docs: standardize NULL terminology across UI, docs, and code comments

Replace inconsistent phrases like "no default (null)", "no default",
and "with no default" with explicit "NULL" or "default is NULL"
throughout UI text, doc comments, inline comments, and documentation.
Also improve default value UX in AttributeDefinitionForm (NULL badge,
type-specific placeholders, icon clear button) and reorder search/filter
controls on AttributeDefinitionsPage.

Author: jumpbetweenrows

admin-ui/src/components/AttributeDefinitionForm.tsx

@@ -29,6 +29,13 @@ interface Props {
 const VALUE_TYPES: ValueType[] = ['string', 'integer', 'boolean', 'list']
 const ENTITY_TYPES = SUPPORTED_ENTITY_TYPES
 
+const DEFAULT_PLACEHOLDER: Record<ValueType, string> = {
+  string: 'Type a value…',
+  integer: 'Type an integer…',
+  boolean: '', // boolean uses a select, not a text input
+  list: 'JSON array, e.g., ["default"]',
+}
+
 const inputCls =
   'w-full border border-gray-300 rounded-lg px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-blue-500'
 
@@ -186,39 +193,41 @@ export function AttributeDefinitionForm({
             onChange={(e) => setDefaultValue(e.target.value)}
             className={inputCls}
           >
-            <option value="">No default (null)</option>
+            <option value="">NULL</option>
             <option value="true">true</option>
             <option value="false">false</option>
           </select>
         ) : (
-          <div className="flex items-center gap-2">
+          <div className="relative">
             <input
               type={valueType === 'integer' ? 'number' : 'text'}
               value={defaultValue}
               onChange={(e) => setDefaultValue(e.target.value)}
-              placeholder={
-                valueType === 'list'
-                  ? 'No default (null) — or JSON array, e.g., ["default"]'
-                  : 'No default (null)'
-              }
-              className={`${inputCls} flex-1`}
+              placeholder={DEFAULT_PLACEHOLDER[valueType]}
+              className={`${inputCls} ${defaultValue ? 'pr-8' : 'pr-16'}`}
             />
-            {defaultValue && (
+            {defaultValue ? (
               <button
                 type="button"
                 onClick={() => setDefaultValue('')}
-                className="text-gray-400 hover:text-red-500 text-sm px-1"
+                className="absolute right-2 top-1/2 -translate-y-1/2 text-gray-400 hover:text-red-500 transition-colors"
                 title="Clear to null"
               >
-                &times;
+                <svg className="h-4 w-4" fill="currentColor" viewBox="0 0 20 20">
+                  <path fillRule="evenodd" d="M10 18a8 8 0 1 0 0-16 8 8 0 0 0 0 16ZM8.28 7.22a.75.75 0 0 0-1.06 1.06L8.94 10l-1.72 1.72a.75.75 0 1 0 1.06 1.06L10 11.06l1.72 1.72a.75.75 0 1 0 1.06-1.06L11.06 10l1.72-1.72a.75.75 0 0 0-1.06-1.06L10 8.94 8.28 7.22Z" clipRule="evenodd" />
+                </svg>
               </button>
+            ) : (
+              <span className="absolute right-2 top-1/2 -translate-y-1/2 pointer-events-none font-mono text-xs bg-orange-100 text-orange-700 px-1.5 py-0.5 rounded">
+                NULL
+              </span>
             )}
           </div>
         )}
         <p className="text-xs text-gray-400 mt-1">
           {defaultValue
             ? `Users without this attribute will be treated as having the value "${defaultValue}" when policies are evaluated. This value is applied by the proxy at query time — it is not stored on the user.`
-            : 'When null: users without this attribute will have NULL substituted in policy expressions. In SQL, comparisons with NULL (e.g., tenant = NULL) evaluate to NULL, which is treated as false — so equality filters return zero rows. This is applied by the proxy at query time, not stored on the user.'}
+            : 'The default is NULL. Users without this attribute will have NULL substituted in policy expressions. In SQL, comparisons with NULL (e.g., tenant = NULL) evaluate to NULL, which is treated as false — so equality filters return zero rows. This is applied by the proxy at query time, not stored on the user.'}
         </p>
       </div>
 

admin-ui/src/components/DecisionFunctionModal.tsx

@@ -61,7 +61,7 @@ function buildCtxCompletions(evaluateContext: EvaluateContext, configStr: string
   for (const def of attrDefs) {
     const typeLabel = def.value_type === 'list' ? 'string[]' : def.value_type
     const defaultHint =
-      def.default_value != null ? `default: ${def.default_value}` : 'default: null'
+      def.default_value != null ? `default: ${def.default_value}` : 'default: NULL'
     items.push({
       label: `ctx.session.user.${def.key}`,
       type: 'variable' as const,
@@ -727,7 +727,7 @@ export function DecisionFunctionModal({
 
           <p className="text-xs text-gray-400 -mt-3">
             Custom user attributes (e.g. <code className="bg-gray-100 px-1 rounded">ctx.session.user.clearance</code>) are <code className="bg-gray-100 px-1 rounded">null</code> when
-            not set on a user or when their default is null. Use defensive checks
+            not set on a user and the attribute&apos;s default is NULL. Use defensive checks
             like <code className="bg-gray-100 px-1 rounded">{'if (ctx.session.user.clearance == null)'}</code> before
             numeric comparisons, since <code className="bg-gray-100 px-1 rounded">null &gt;= 0</code> is <code className="bg-gray-100 px-1 rounded">true</code> in JavaScript.
           </p>

admin-ui/src/components/UserAttributeEditor.tsx

@@ -171,7 +171,7 @@ function AddAttributeDropdown({
                 {d.display_name} ({d.value_type})
                 {d.default_value != null
                   ? ` — default: ${d.default_value}`
-                  : ' — no default (null)'}
+                  : ' — default: NULL'}
               </option>
             ))}
           </select>

admin-ui/src/pages/AttributeDefinitionsPage.tsx

@@ -99,13 +99,6 @@ export function AttributeDefinitionsPage() {
       </div>
 
       <div className="flex items-center gap-3 mb-4">
-        <input
-          type="search"
-          value={search}
-          onChange={(e) => { setSearch(e.target.value); setPage(1) }}
-          placeholder="Search by key or display name…"
-          className="border border-gray-300 rounded-lg px-3 py-1.5 text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 w-64"
-        />
         <label className="text-sm text-gray-600 flex items-center gap-2">
           Entity type:
           <select
@@ -122,6 +115,13 @@ export function AttributeDefinitionsPage() {
             <option value="">All</option>
           </select>
         </label>
+        <input
+          type="search"
+          value={search}
+          onChange={(e) => { setSearch(e.target.value); setPage(1) }}
+          placeholder="Search by key or display name…"
+          className="border border-gray-300 rounded-lg px-3 py-1.5 text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 w-64"
+        />
       </div>
 
       {deleteError && (

docs/permission-system.md

@@ -320,15 +320,15 @@ Reserved keys for `entity_type = "user"`: `username`, `id`, `user_id`, `roles` 
 
 When a user lacks an attribute that is referenced by a policy, the proxy resolves the value using the attribute definition's `default_value`:
 
-| User has attribute? | `default_value` set? | Template variable result | Decision function context |
+| User has attribute? | `default_value` | Template variable result | Decision function context |
 |---|---|---|---|
 | Yes | (irrelevant) | User's actual value (typed literal) | User's actual value (typed JSON) |
-| No | Yes (`"acme"`) | `default_value` as typed literal | `default_value` as typed JSON |
-| No | No (null) | SQL `NULL` literal | JSON `null` |
+| No | Non-NULL (e.g. `"acme"`) | `default_value` as typed literal | `default_value` as typed JSON |
+| No | NULL (default) | SQL `NULL` literal | JSON `null` |
 
 **SQL NULL semantics**: In SQL, comparisons with NULL (e.g., `column = NULL`) evaluate to NULL (three-valued logic), which is treated as false in WHERE clauses — so the user sees zero rows. This is standard SQL behavior consistent across DataFusion (which evaluates the filter in-process) and upstream databases like PostgreSQL (if the filter is pushed down). This applies to equality (`=`, `!=`), `IN`, and comparison operators (`>`, `<`). NULL is also handled naturally by `COALESCE` expressions. Note: `IS NULL` would match, so avoid writing filter expressions that use `IS NULL` with user attributes unless that behavior is intentional.
 
-**Decision function null semantics**: Missing attributes with no default appear as `null` (not `undefined`). Equality checks work correctly (`null === "acme"` → `false`). However, numeric comparisons have a JS quirk: `null >= 0` is `true` because `null` coerces to `0`. Always guard numeric comparisons with a null check: `if (ctx.session.user.clearance == null) return { fire: true, reason: "missing clearance" }`.
+**Decision function null semantics**: Missing attributes whose default is NULL appear as `null` (not `undefined`). Equality checks work correctly (`null === "acme"` → `false`). However, numeric comparisons have a JS quirk: `null >= 0` is `true` because `null` coerces to `0`. Always guard numeric comparisons with a null check: `if (ctx.session.user.clearance == null) return { fire: true, reason: "missing clearance" }`.
 
 **Undefined attributes**: If a policy references `{user.foo}` but no attribute definition named `foo` exists at all, the query fails with an error. This catches typos and stale policies referencing deleted attributes.
 
@@ -400,7 +400,7 @@ curl -X POST ... \
 
 See [Template variables](#template-variables) above. `{user.KEY}` references produce typed literals based on the attribute definition's `value_type`.
 
-**Missing attributes**: if a user does not have an attribute set, the proxy resolves the value from the attribute definition's `default_value`. If a default is set, it is substituted as a typed literal. If no default is set (null), SQL `NULL` is substituted — comparisons with `NULL` evaluate to `NULL` (three-valued logic), which is treated as false in WHERE clauses, so the user sees zero rows. If the attribute has no definition at all, the query fails with an error. See [Missing attribute behavior](#missing-attribute-behavior) for the full resolution table.
+**Missing attributes**: if a user does not have an attribute set, the proxy resolves the value from the attribute definition's `default_value`. If a default is set, it is substituted as a typed literal. If the default is NULL, SQL `NULL` is substituted — comparisons with `NULL` evaluate to `NULL` (three-valued logic), which is treated as false in WHERE clauses, so the user sees zero rows. If the attribute has no definition at all, the query fails with an error. See [Missing attribute behavior](#missing-attribute-behavior) for the full resolution table.
 
 ### Using attributes in decision functions
 
@@ -434,7 +434,7 @@ User attributes are available as first-class fields on `ctx.session.user` with c
 
 Note: integer and boolean attributes appear as native JSON types in the decision function context (not strings). List attributes appear as JSON arrays of strings.
 
-**Missing attributes in decision context**: attributes the user lacks are resolved via `default_value` from the attribute definition. If a default is set, the typed value appears on `ctx.session.user` as if the user had that attribute. If no default is set, the field is `null` (not `undefined`). Use `== null` checks before numeric comparisons, since `null >= 0` is `true` in JavaScript. See [Missing attribute behavior](#missing-attribute-behavior) for the full resolution table.
+**Missing attributes in decision context**: attributes the user lacks are resolved via `default_value` from the attribute definition. If a default is set, the typed value appears on `ctx.session.user` as if the user had that attribute. If the default is NULL, the field is `null` (not `undefined`). Use `== null` checks before numeric comparisons, since `null >= 0` is `true` in JavaScript. See [Missing attribute behavior](#missing-attribute-behavior) for the full resolution table.
 
 ### Cache behavior
 

docs/security-vectors.md

@@ -864,7 +864,7 @@ Note: `tenant` is no longer a reserved key — it is a regular custom attribute.
 
 **Bug**: `mangle_vars()` used `unwrap_or("")` for missing attributes with no error or warning. Decision function context omitted missing attributes entirely (`undefined` in JS), causing `undefined >= 0` to silently evaluate to `false` in numeric comparisons.
 
-**Defense**: `resolve_user_attribute_defaults()` merges user attributes with definition defaults. Missing attributes with a `default_value` get that value substituted (typed literal in SQL, typed JSON in decision context). Missing attributes with no default get SQL `NULL` (zero rows for equality) and JSON `null` (distinguishable from `undefined`). References to completely undefined attributes (no definition) return an error. The centralized helper is used in all three paths: `mangle_vars` (row filters + masks), query-level decision context (`handle_query`), and visibility-level decision context (`build_typed_json_attributes`).
+**Defense**: `resolve_user_attribute_defaults()` merges user attributes with definition defaults. Missing attributes with a `default_value` get that value substituted (typed literal in SQL, typed JSON in decision context). Missing attributes whose default is NULL get SQL `NULL` (zero rows for equality) and JSON `null` (distinguishable from `undefined`). References to completely undefined attributes (no definition) return an error. The centralized helper is used in all three paths: `mangle_vars` (row filters + masks), query-level decision context (`handle_query`), and visibility-level decision context (`build_typed_json_attributes`).
 
 **Test**: Unit: `test_mangle_vars_missing_attr_with_default`, `test_mangle_vars_missing_attr_null_default`, `test_mangle_vars_missing_attr_no_definition`, `test_mangle_vars_missing_attr_default_integer`, `test_mangle_vars_missing_attr_default_list`, `test_mangle_vars_present_attr_ignores_default`, `test_resolve_user_attribute_defaults`. Integration: `row_filter_missing_attr_uses_default`, `row_filter_missing_attr_null_default`, `row_filter_attr_present_ignores_default`, `column_mask_missing_attr_uses_default`, `column_mask_missing_attr_null_default`, `decision_fn_missing_attr_uses_default`.
 

proxy/CLAUDE.md

@@ -138,9 +138,9 @@ Custom key-value attributes on users, governed by a schema-first attribute defin
 
 **Template variables**: `{user.KEY}` in filter/mask expressions. Built-in fields (`{user.username}`, `{user.id}`) take priority via `match` arms in `UserVars::get()`, preventing attribute override attacks. Custom attributes (including `tenant`) fall through to the resolved attribute map (user values + definition defaults via `resolve_user_attribute_defaults()`).
 
-**Missing attribute resolution**: When a user lacks an attribute referenced by a policy, the proxy resolves it from the attribute definition's `default_value`. If set, the default is used as a typed literal. If null, SQL `NULL` is substituted (comparisons with NULL evaluate to NULL → treated as false in WHERE → zero rows). If no definition exists, the query errors. This is handled centrally by `resolve_user_attribute_defaults()` in `hooks/policy.rs`, used in all three paths: template variables, query-level decision context, and visibility-level decision context (`build_typed_json_attributes` in `engine/mod.rs`).
+**Missing attribute resolution**: When a user lacks an attribute referenced by a policy, the proxy resolves it from the attribute definition's `default_value`. If a non-NULL default is set, it is used as a typed literal. If the default is NULL (the default), SQL `NULL` is substituted (comparisons with NULL evaluate to NULL → treated as false in WHERE → zero rows). If no definition exists, the query errors. This is handled centrally by `resolve_user_attribute_defaults()` in `hooks/policy.rs`, used in all three paths: template variables, query-level decision context, and visibility-level decision context (`build_typed_json_attributes` in `engine/mod.rs`).
 
-**Decision function context**: Custom attributes are flattened as first-class fields on `ctx.session.user` (e.g., `ctx.session.user.region`, `ctx.session.user.tenant`) with typed JSON values. Missing attributes with a `default_value` appear as their typed default; missing with no default appear as `null` (not `undefined`). Built-in fields (`id`, `username`, `roles`) always take priority. `ctx.session.time.now` is an ISO 8601 / RFC 3339 timestamp of the evaluation time (not session start).
+**Decision function context**: Custom attributes are flattened as first-class fields on `ctx.session.user` (e.g., `ctx.session.user.region`, `ctx.session.user.tenant`) with typed JSON values. Missing attributes with a `default_value` appear as their typed default; missing attributes whose default is NULL appear as `null` (not `undefined`). Built-in fields (`id`, `username`, `roles`) always take priority. `ctx.session.time.now` is an ISO 8601 / RFC 3339 timestamp of the evaluation time (not session start).
 
 **Save-time expression validation**: `validate_expression()` in `hooks/policy.rs` dry-run parses filter/mask expressions at policy create/update time and returns 422 if the syntax is unsupported. Called from `validate_definition()` in `dto.rs`.
 

proxy/src/hooks/policy.rs

@@ -87,7 +87,7 @@ pub struct AttrDefInfo {
 
 /// Merge user's actual attributes with defaults from attribute definitions.
 /// Missing attributes with a default_value get that value inserted.
-/// Missing attributes with no default get a null sentinel (value_type="null").
+/// Missing attributes whose default is NULL get a null sentinel (value_type="null").
 pub fn resolve_user_attribute_defaults(
     user_attrs: &HashMap<String, TypedAttribute>,
     attr_defs: &HashMap<String, AttrDefInfo>,
@@ -180,7 +180,7 @@ struct VarMapping {
 ///
 /// Uses `resolve_user_attribute_defaults` to merge user attributes with definition defaults
 /// before substitution. Missing attributes with a default produce typed literals; missing
-/// attributes with no default produce SQL NULL; references to undefined attributes error.
+/// attributes with a NULL default produce SQL NULL; references to undefined attributes error.
 fn mangle_vars(template: &str, vars: &UserVars) -> Result<(String, Vec<VarMapping>), String> {
     let mut result = template.to_string();
     let mut mappings = Vec::new();
@@ -4850,7 +4850,7 @@ Javy.IO.writeSync(1, new TextEncoder().encode(JSON.stringify(result)));
         // Missing + default → uses default
         assert_eq!(resolved["clearance"].value, "0");
         assert_eq!(resolved["clearance"].value_type, "integer");
-        // Missing + no default → null sentinel
+        // Missing + NULL default → null sentinel
         assert_eq!(resolved["region"].value_type, "null");
     }
 

proxy/tests/policy_enforcement.rs

@@ -7821,7 +7821,7 @@ async fn row_filter_missing_attr_uses_default() {
     assert_eq!(rows[1][1], "acme");
 }
 
-/// Row filter: user lacks attribute, no default_value → SQL NULL → zero rows.
+/// Row filter: user lacks attribute, default is NULL → SQL NULL → zero rows.
 #[tokio::test]
 async fn row_filter_missing_attr_null_default() {
     let _pg = require_postgres!();
@@ -7992,7 +7992,7 @@ async fn column_mask_missing_attr_uses_default() {
     assert_eq!(rows[1][1], "B***_guest");
 }
 
-/// Column mask: user lacks attribute, no default → mask uses NULL.
+/// Column mask: user lacks attribute, default is NULL → mask uses NULL.
 #[tokio::test]
 async fn column_mask_missing_attr_null_default() {
     let _pg = require_postgres!();
@@ -8011,7 +8011,7 @@ async fn column_mask_missing_attr_null_default() {
     let ds_id = server.create_datasource("ds_cmdef02", "open").await;
     server.discover(ds_id, &[schema]).await;
 
-    // Attribute definition with no default → NULL
+    // Attribute definition with NULL default
     server
         .create_attribute_definition("label", "user", "string", None)
         .await;
@@ -8081,7 +8081,7 @@ async fn decision_fn_missing_attr_uses_default() {
     let _user_id = server.create_user("gina", "GinaPass12!", ds_id).await;
 
     // Decision function: fire only if clearance === 0 (the default)
-    // If the user had no attribute and no default injection, ctx.session.user.clearance
+    // If the user had no attribute and the default were not injected, ctx.session.user.clearance
     // would be undefined → undefined === 0 is false → filter would NOT fire → all rows visible.
     let decision_fn_id = create_decision_fn(
         &server,