@githolon/dsl 0.54.2 → 0.55.0

package/src/fields.ts

@@ -35,6 +35,66 @@ export type JsonValue =
   | JsonValue[]
   | { readonly [k: string]: JsonValue };
 
+/**
+ * NULL SEMANTICS (`architecture/null_semantics.md`). JSON's one `null` collapses three distinct
+ * law meanings; a field NAMES which it admits before the law lets a null through:
+ *  - `"forbid"`         — null is refused anywhere (the `t.json()` default; the explicit spelling
+ *                          is `t.json({ null: "forbid" })`).
+ *  - `"explicit-empty"` — nulls are admitted as a documented domain value (`t.json({ null:
+ *                          "explicit-empty", reason })`); `nullReason` records why.
+ *  - `"nullable"`       — null IS a real domain value on this field (`t.nullable(X, { reason })`);
+ *                          `nullReason` records why (rides docs/openapi).
+ * The EXPLICIT-CLEAR semantic is ORTHOGONAL, carried by the separate `isClearable` flag (`t.clearable(X)`
+ * + `.clear(field)` / the generated `clearX(...)` lane, lowered to a Set of json `null`) — a field can be
+ * BOTH clearable and nullable. FRONTEND/IR-ONLY metadata: neither ever enters the kernel wire `Schema`
+ * (driver-only — see `encodeKernelSchema`), so a field's domainHash is UNCHANGED. Codegen reads
+ * `nullSemantic`/`nullReason`/`isClearable` to shape the tri-state client surface; the runtime enforcement
+ * is the payload zod (no-null refine) + the encode-path null guard (`wire_encode.ts`).
+ */
+export type NullSemantic = "forbid" | "explicit-empty" | "nullable";
+
+/** The null semantics that ADMIT a null value on a field (everything else refuses null). NOTE: a
+ *  `isClearable` field ALSO admits null (a cleared field reads back as json null) — use {@link admitsNull}
+ *  to combine both axes. */
+export const NULL_ADMITTING: ReadonlySet<NullSemantic> = new Set<NullSemantic>(["explicit-empty", "nullable"]);
+
+/** True iff a field admits a null VALUE — either a null-admitting `nullSemantic` OR `isClearable`
+ *  (a cleared field reads back as json null → ExplicitNull, so the read type must be tri-state). This
+ *  is the ONE predicate the encode guard, the check twins, and codegen's tri-state trigger share. */
+export function admitsNull(field: { readonly nullSemantic?: NullSemantic; readonly isClearable?: true }): boolean {
+  return field.isClearable === true || (field.nullSemantic !== undefined && NULL_ADMITTING.has(field.nullSemantic));
+}
+
+/**
+ * A recursive JSON schema that REFUSES `null` at every depth (`architecture/null_semantics.md`).
+ * The PAYLOAD helper for a `t.json()`-shaped field: declare a directive payload field with it and a
+ * null anywhere refuses at `.parse()` (the lump gate). Deterministic (a fixed `z.lazy` union — no
+ * clock/rng), so it validates byte-identically on every peer. `null` is simply not a member of any
+ * arm. (The aggregate FIELD zod stays `z.string()` — type-level, hash-stable; the no-null LAW on the
+ * write path is the encode-path guard in `wire_encode.ts`.) */
+export const jsonNoNullSchema: z.ZodType<JsonValue> = z.lazy(() =>
+  z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.array(jsonNoNullSchema),
+    z.record(z.string(), jsonNoNullSchema),
+  ]),
+) as unknown as z.ZodType<JsonValue>;
+
+/** A recursive JSON schema that ADMITS `null` at every depth — the `t.json({ null: "explicit-empty" })`
+ *  field zod (nulls are a declared domain value). Same deterministic `z.lazy` union, plus a `z.null()` arm. */
+export const jsonWithNullSchema: z.ZodType<JsonValue> = z.lazy(() =>
+  z.union([
+    z.null(),
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.array(jsonWithNullSchema),
+    z.record(z.string(), jsonWithNullSchema),
+  ]),
+) as unknown as z.ZodType<JsonValue>;
+
 export type FieldKind =
   | "string"
   | "int"
@@ -184,6 +244,28 @@ export interface Field<T = unknown, K extends FieldKind = FieldKind> {
    * Scalar Lww-class kinds only; mutually exclusive with `.optional()`. Flag named
    * `isFromBirth` — the `fromBirth()` METHOD sets it (the isOptional/isEncrypted convention). */
   readonly isFromBirth?: true;
+  /**
+   * NULL SEMANTICS (`architecture/null_semantics.md`): what `null` MEANS on this field. Set by the
+   * `t.json(...)` null option and the `t.optional`/`t.clearable`/`t.nullable` wrappers. `undefined`
+   * ⇒ the field carries no null declaration (a scalar/collection whose null-ness never arises); a
+   * `json` field with no wrapper defaults to `"forbid"` at construction. FRONTEND/IR-ONLY — never in
+   * the kernel wire `Schema` (driver-only), so it changes NO hash. See {@link NullSemantic}.
+   */
+  readonly nullSemantic?: NullSemantic;
+  /** The REQUIRED reason string for `nullable`/`explicit-empty` (law documentation — rides docs/openapi).
+   *  Present iff `nullSemantic` is `"nullable"` or `"explicit-empty"`. */
+  readonly nullReason?: string;
+  /** EXPLICIT-CLEAR (`architecture/null_semantics.md`): set by `t.clearable(...)`. The field admits an
+   *  explicit-clear write (`clear(handle, "field")` / `.clear("field")` / the generated `clearX(...)`
+   *  lane), lowered to a Set of json `null`. ORTHOGONAL to `nullSemantic` (a field may be both). A
+   *  cleared field reads back as json null, so codegen surfaces it tri-state (see {@link admitsNull}).
+   *  FRONTEND/IR-ONLY — no hash change. */
+  readonly isClearable?: true;
+  /** The AUTHZ relation the GENERATED clear directive requires (`t.clearable(field, { requires })`). When
+   *  set, the compose-seam-injected `clear<Agg><Field>` directive carries `.requires(relation)`; when
+   *  absent the clear lane is ungated (and `law_check` WARNs if sibling writes ARE gated). Compose/codegen
+   *  metadata — the REAL law is the generated directive's `requiresRelationGate` (hashed there, not here). */
+  readonly clearRequires?: string;
   /** For `t.ref` cross-workspace edges: the foreign workspace id, if any. */
   readonly refWorkspace?: string;
   /** For `t.ref` (the target) AND `t.hasMany` (the child type): the related aggregate's wire id. */
@@ -295,6 +377,15 @@ export interface Field<T = unknown, K extends FieldKind = FieldKind> {
   /** Declare BIRTH-PRESENCE LAW: aggregate() synthesizes a gate invariant requiring this field
    * present on every event touching the type; read models type it NON-NULLABLE. */
   fromBirth(): Field<T, K>;
+  /**
+   * INTERNAL (the `t.optional`/`t.clearable`/`t.nullable` wrappers call this): tag this field's null
+   * semantic (+ optional reason). Threaded through merge/optional like every other flag. Not for
+   * direct authoring — reach it via the wrappers, which validate driver/kind eligibility.
+   */
+  withNull(semantic: NullSemantic, reason?: string): Field<T, K>;
+  /** INTERNAL (`t.clearable` calls this): mark this field EXPLICIT-CLEARABLE (sets {@link Field.isClearable}
+   *  + optional {@link Field.clearRequires}). Threaded through merge/optional like every other flag. */
+  clearable(requires?: string): Field<T, K> & { readonly isClearable: true };
   /** Phantom to keep T load-bearing for inference. */
   readonly _t?: T;
 }
@@ -316,6 +407,10 @@ function makeField<T, K extends FieldKind = FieldKind>(
     encrypted?: true;
     meta?: true;
     facet?: FieldFacet;
+    nullSemantic?: NullSemantic;
+    nullReason?: string;
+    isClearable?: true;
+    clearRequires?: string;
   } = {},
 ): Field<T, K> {
   const isOptional = extra.isOptional ?? false;
@@ -335,6 +430,10 @@ function makeField<T, K extends FieldKind = FieldKind>(
     ...(extra.encrypted ? { isEncrypted: true as const } : {}),
     ...(extra.meta ? { isMeta: true as const } : {}),
     ...(extra.fromBirth ? { isFromBirth: true as const } : {}),
+    ...(extra.nullSemantic !== undefined ? { nullSemantic: extra.nullSemantic } : {}),
+    ...(extra.nullReason !== undefined ? { nullReason: extra.nullReason } : {}),
+    ...(extra.isClearable ? { isClearable: true as const } : {}),
+    ...(extra.clearRequires !== undefined ? { clearRequires: extra.clearRequires } : {}),
     merge(d: Driver) {
       return makeField<T, K>(kind, zod, d, extra);
     },
@@ -364,6 +463,22 @@ function makeField<T, K extends FieldKind = FieldKind>(
       }
       return makeField<T, K>(kind, zod, driver, { ...extra, fromBirth: true });
     },
+    withNull(semantic: NullSemantic, reason?: string): Field<T, K> {
+      // Threaded through merge/optional like every other flag (it rides `extra`). Reason is carried
+      // only for the semantics that document one; the wrappers validate eligibility before calling.
+      return makeField<T, K>(kind, zod, driver, {
+        ...extra,
+        nullSemantic: semantic,
+        ...(reason !== undefined ? { nullReason: reason } : {}),
+      });
+    },
+    clearable(requires?: string): Field<T, K> & { readonly isClearable: true } {
+      return makeField<T, K>(kind, zod, driver, {
+        ...extra,
+        isClearable: true,
+        ...(requires !== undefined ? { clearRequires: requires } : {}),
+      }) as Field<T, K> & { readonly isClearable: true };
+    },
     encrypted(): Field<T, K> {
       // Carry the flag through merge/optional (extra is threaded), so `.merge(Lww).encrypted()`
       // and `.encrypted().merge(Lww)` agree. The wire schema is UNCHANGED (driver-only) — the
@@ -411,6 +526,42 @@ export const publicField = <T, K extends FieldKind>(field: Field<T, K>): Field<T
 /** Infer the authored value type of a Field. */
 export type FieldValue<F> = F extends Field<infer T> ? T : never;
 
+/** The kinds a `clearable`/`nullable` null semantic may ride: VALUE LEAVES only. A collection/CRDT
+ *  (`set`/`map`/`counter`/`position`/`hasMany`) clears/empties through its own additive op, never a null. */
+const NULL_ELIGIBLE_KINDS: ReadonlySet<FieldKind> = new Set<FieldKind>([
+  "string",
+  "int",
+  "bool",
+  "enum",
+  "json",
+  "ref",
+  "evidence",
+]);
+
+/** Guard the `t.clearable`/`t.nullable` wrappers: the field must be a value leaf with an Lww-class
+ *  driver (the value is replaced/cleared WHOLESALE). Throws with the fix inside the message. */
+function assertNullEligible(field: Field<unknown, FieldKind>, wrapper: "clearable" | "nullable"): void {
+  if (!NULL_ELIGIBLE_KINDS.has(field.kind)) {
+    throw new Error(
+      `t.${wrapper}(...) is not available on a '${field.kind}' field — a collection/CRDT clears through ` +
+        `its own additive op (removeFromSet / decrement), never a null. Value leaves only ` +
+        `(${[...NULL_ELIGIBLE_KINDS].join("/")}).`,
+    );
+  }
+  const dk = (field.driver as { kind?: string }).kind;
+  if (dk !== "Lww" && dk !== "LwwCausal" && dk !== "LwwBy") {
+    throw new Error(
+      `t.${wrapper}(...) needs an Lww-class field (Lww / LwwCausal / LwwBy) — a null/clear replaces the ` +
+        `value WHOLESALE, which a '${dk}' merge cannot express. Declare the field Lww-class first.`,
+    );
+  }
+  if (field.isFromBirth === true) {
+    throw new Error(
+      `t.${wrapper}(...) contradicts .fromBirth() — a birth-present field is NON-NULLABLE by law; drop one.`,
+    );
+  }
+}
+
 export const t = {
   string(): Field<string, "string"> {
     return makeField("string", z.string(), Lww);
@@ -491,11 +642,76 @@ export const t = {
    * JSON leaf — the kernel `Value` is Str|Int only), so the v1-free projection surfaces
    * it as a permissive `Object?`. Use `t.jsonObject()` when the leaf is ALWAYS an OBJECT
    * value-object (e.g. a `location`) to get a strict `Map<String,Object?>` read type. */
-  json(): Field<JsonValue, "json"> {
-    // AUTHORING type is the structured JsonValue (the kernel stores Value::Json), so a plan may
-    // set()/setEntry() a real object/array/scalar. The runtime wire + zod are UNCHANGED (a `Str`
-    // leaf at op time — no hash change); only the accepted TS value widens (a `string` stays valid).
-    return makeField<string, "json">("json", z.string(), Lww) as unknown as Field<JsonValue, "json">;
+  json(opts?: { null?: "forbid" | "explicit-empty"; reason?: string }): Field<JsonValue, "json"> {
+    // NULL SEMANTICS (`architecture/null_semantics.md`): `t.json()` EXCLUDES null at every depth by
+    // default. The FIELD zod stays `z.string()` (TYPE-LEVEL only — the wire is a `Value::Json` leaf,
+    // identical bytes/hash to before), and the no-null LAW is enforced two ways: the encode-path null
+    // guard (`wire_encode.ts`) refuses a plan-injected null in the lump on every peer, and a payload
+    // declared with the exported {@link jsonNoNullSchema} refuses a null at `.parse()`. `{ null:
+    // "explicit-empty", reason }` admits nulls as a documented domain value (reason REQUIRED — a
+    // meaning-free null is the whole footgun); the `nullSemantic` metadata is FRONTEND/IR-ONLY (codegen
+    // shapes the tri-state client surface from it) and never enters the hashed IR.
+    const mode = opts?.null ?? "forbid";
+    if (mode === "explicit-empty") {
+      if (typeof opts?.reason !== "string" || opts.reason.trim() === "") {
+        throw new Error(
+          `t.json({ null: "explicit-empty" }) requires a non-empty \`reason\` — the reason is law ` +
+            `documentation (it rides docs/openapi so every consumer knows what a null MEANS here). ` +
+            `Give a reason, or use the default t.json() which forbids null.`,
+        );
+      }
+      return makeField<string, "json">("json", z.string(), Lww, {
+        nullSemantic: "explicit-empty",
+        nullReason: opts.reason,
+      }) as unknown as Field<JsonValue, "json">;
+    }
+    return makeField<string, "json">("json", z.string(), Lww, {
+      nullSemantic: "forbid",
+    }) as unknown as Field<JsonValue, "json">;
+  },
+  /**
+   * `t.optional(field)` — the OMISSION semantic: a folded aggregate may LACK this field (absent =
+   * not supplied / inherit). The wrapper spelling of `field.optional()` (`architecture/null_semantics.md`);
+   * null NEVER arrives for an optional field — the law forbids it — so the generated client stays an
+   * idiomatic `T?` (absence only). Chainable-equivalent to `.optional()`.
+   */
+  optional<T, K extends FieldKind>(field: Field<T, K>): Field<T | undefined, K> {
+    return field.optional();
+  },
+  /**
+   * `t.clearable(field)` — the EXPLICIT-CLEAR semantic (`architecture/null_semantics.md`): the field
+   * admits an explicit-clear write (`.clear("field")` / the generated `clearX(...)` lane), lowered to a
+   * Set of json `null`. Value leaves only (Lww-class scalar / json / value-object — a collection/CRDT
+   * clears by its own additive op, never by null), else a compile-time throw. Codegen emits the clear lane.
+   */
+  clearable<T, K extends FieldKind>(
+    field: Field<T, K>,
+    opts?: { requires?: string },
+  ): Field<T, K> & { readonly isClearable: true } {
+    assertNullEligible(field, "clearable");
+    return field.clearable(opts?.requires);
+  },
+  /**
+   * `t.nullable(field, { reason })` — null IS a real domain value on this field (`architecture/
+   * null_semantics.md`): e.g. external-import fidelity. `reason` is REQUIRED (a meaning-free null is the
+   * footgun this feature removes) and rides docs/openapi. Value leaves only (Lww-class), else a throw.
+   * The field's zod is widened to admit null; the generated client gets the tri-state `| null` arm.
+   */
+  nullable<T, K extends FieldKind>(
+    field: Field<T, K>,
+    opts: { reason: string },
+  ): Field<T | null, K> & { readonly nullSemantic: "nullable" } {
+    if (typeof opts?.reason !== "string" || opts.reason.trim() === "") {
+      throw new Error(
+        `t.nullable(field, { reason }) requires a non-empty \`reason\` — null is a real value here, and ` +
+          `the reason is law documentation (it rides docs/openapi). Give a reason, or use t.optional(...) ` +
+          `for omission / t.clearable(...) for explicit clearing.`,
+      );
+    }
+    assertNullEligible(field, "nullable");
+    return field.withNull("nullable", opts.reason) as unknown as Field<T | null, K> & {
+      readonly nullSemantic: "nullable";
+    };
   },
   /** A JSON-OBJECT value-object leaf: an arbitrary JSON-string leaf (identical wire +
    * driver to `t.json()` — a `Str` at op time, so NO hash change) whose decoded value is

package/src/index.ts

@@ -31,6 +31,11 @@ export {
   type FieldValue,
   type FieldKind,
   type JsonValue,
+  type NullSemantic,
+  NULL_ADMITTING,
+  admitsNull,
+  jsonNoNullSchema,
+  jsonWithNullSchema,
   type EvidenceRefValue,
   evidenceRefSchema,
   // FIELD FACETS (the endorse model — security_model.md): authority/standing/attribution gate
@@ -94,6 +99,7 @@ export {
 } from "./drivers.js";
 export {
   set,
+  clear,
   addToSet,
   setEntry,
   increment,
@@ -106,6 +112,10 @@ export {
   type PlannedEventMarker,
   type StrikeOp,
 } from "./ops.js";
+// GENERATED CLEAR LANE (null_semantics.md): `clearDirectiveId(aggId, field)` is the id convention
+// (`clear<Agg><Field>`) the codegen agent's `clearX()` client methods bind to; the directives
+// themselves are compose-injected (`withClearDirectives`) so they ride every plane's module surface.
+export { clearDirectiveId, makeClearDirective, withClearDirectives } from "./clear_directive.js";
 export {
   directive,
   recordObject,

package/src/law_check.ts

@@ -30,7 +30,7 @@ import { z } from "zod";
 import type { AggregateHandle } from "./aggregate.js";
 import type { Directive } from "./directive.js";
 import type { DomainModule } from "./codegen_dart.js";
-import type { Field, ValueObjectDescriptor, ValueObjectFieldDescriptor } from "./fields.js";
+import { admitsNull, type Field, type ValueObjectDescriptor, type ValueObjectFieldDescriptor } from "./fields.js";
 import type { FieldOp, PlannedOp } from "./ops.js";
 import { deterministicPorts } from "./ctx.js";
 import { synthesizePayload, withBirthProbeGlobals, type SynthesizedPayload } from "./codegen_proof.js";
@@ -43,6 +43,7 @@ import { finishCount } from "./count.js";
 import { finishSum } from "./sum.js";
 import { finishExtremum } from "./extremum.js";
 import { finishExists } from "./exists.js";
+import { clearDirectiveId } from "./clear_directive.js";
 
 /** One author-time finding — the gate refusal pre-fired at compile, or a courtesy note. */
 export interface Finding {
@@ -656,6 +657,183 @@ function dottedQueryKeyFindings(mod: DomainModule, aggById: ReadonlyMap<string,
   return out;
 }
 
+// ── TWIN N (null_semantics.md) — the NULL-SEMANTICS twins ──────────────────────────
+// JSON's one `null` collapses three law meanings, so the DSL makes the author NAME which a field
+// admits before a null is lawful (t.optional / t.clearable / t.nullable / t.json({null})). These
+// twins pre-fire the three refusals the gate would raise: (a) a payload field that ADMITS null with
+// no null-admitting receiver; (b) a null-admitting field used where a null is structurally illegal
+// (authority gate, identity ref, spatial index, read key); (c) a plan op writing literal null into a
+// field that never declared null a meaning. All PAYLOAD-INDEPENDENT (pure declarations) ⇒ REFUSE.
+
+/** The verbatim null-semantics guidance (`null_semantics.md`) — the `fix` on twin N-a/N-c. */
+const NULL_GUIDANCE =
+  'Use optional for omission, clearable(...) for explicit clearing, or nullable(..., reason: "...") for an explicit empty/import value.';
+
+/** Minimal zod `_def`/`def` accessor (the `_def ?? def` convention, node-builtin-free). */
+function zDef(zt: z.ZodTypeAny): { type?: string; innerType?: z.ZodTypeAny; options?: readonly z.ZodTypeAny[]; value?: unknown } {
+  const raw = zt as unknown as { _def?: Record<string, unknown>; def?: Record<string, unknown> };
+  return (raw._def ?? raw.def ?? {}) as { type?: string; innerType?: z.ZodTypeAny; options?: readonly z.ZodTypeAny[]; value?: unknown };
+}
+
+/** True iff a payload schema ADMITS a `null` value (a `.nullable()` wrap, `z.null()`/`z.literal(null)`,
+ *  or a union with a null arm) — the static signal twin N-a keys on. Bounded recursion. */
+function zodAdmitsNull(schema: z.ZodTypeAny | undefined, depth = 0): boolean {
+  if (schema === undefined || depth > 16) return false;
+  const k = zodKind(schema);
+  if (k === "null" || k === "nullable") return true;
+  if (k === "literal") return zDef(schema).value === null;
+  if (k === "optional" || k === "default") return zodAdmitsNull(zDef(schema).innerType, depth + 1);
+  if (k === "union") return (zDef(schema).options ?? []).some((o) => zodAdmitsNull(o, depth + 1));
+  return false;
+}
+
+/** The set of a domain's aggregate fields (by name) whose null semantic ADMITS a null — the receivers
+ *  that legitimately take a null-bearing payload field. Name-keyed (the `.set("x", p.x)` convention). */
+function nullAdmittingFieldNames(aggById: ReadonlyMap<string, AggregateHandle>): ReadonlySet<string> {
+  const out = new Set<string>();
+  for (const agg of aggById.values()) {
+    for (const [name, f] of Object.entries(agg.fields)) {
+      if (admitsNull(f as Field)) out.add(name);
+    }
+  }
+  return out;
+}
+
+// TWIN N-a — a directive PAYLOAD field admits null with no null-admitting receiver.
+function nullPayloadFindings(
+  domain: string,
+  dir: Directive<unknown>,
+  aggById: ReadonlyMap<string, AggregateHandle>,
+): Finding[] {
+  const receivers = nullAdmittingFieldNames(aggById);
+  const out: Finding[] = [];
+  for (const [name, f] of Object.entries(safeShape(dir.payloadSchema as z.ZodTypeAny))) {
+    if (!zodAdmitsNull(f)) continue;
+    if (receivers.has(name)) continue; // a field of the same name declared nullable/clearable — lawful
+    out.push({
+      domain,
+      directiveId: dir.id,
+      level: "refuse",
+      what: `payload field '${name}' admits null, but null has no law-level meaning`,
+      fix: NULL_GUIDANCE,
+    });
+  }
+  return out;
+}
+
+// TWIN N-c — a plan op writes literal null into a field that never declared null a meaning.
+function nullWriteFindings(
+  domain: string,
+  dir: Directive<unknown>,
+  probe: ProbeResult,
+  aggById: ReadonlyMap<string, AggregateHandle>,
+): Finding[] {
+  if (probe.threw) return [];
+  const out: Finding[] = [];
+  const seen = new Set<string>();
+  for (const op of probe.ops) {
+    if (op.kind !== "set" || op.value !== null) continue;
+    const field =
+      op.targetField ??
+      (typeof op.aggregateType === "string"
+        ? (aggById.get(op.aggregateType)?.fields[op.field] as Field | undefined)
+        : (aggById.get(op.aggregateId)?.fields[op.field] as Field | undefined));
+    if (field === undefined) continue; // foreign/framework target — runtime gate arbitrates
+    if (admitsNull(field)) continue; // clearable/nullable — lawful
+    const key = `${op.aggregateType ?? op.aggregateId}.${op.field}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({
+      domain,
+      directiveId: dir.id,
+      level: "refuse",
+      what: `the plan writes null into '${op.field}' on '${op.aggregateType ?? op.aggregateId}', which never declared null a meaning`,
+      fix: `declare the field t.clearable(...) and use clear(handle, "${op.field}"), or t.nullable(..., { reason }). ${NULL_GUIDANCE}`,
+    });
+  }
+  return out;
+}
+
+// TWIN N-b — a null-admitting field used where a null is structurally ILLEGAL.
+function nullBanFindings(mod: DomainModule, aggById: ReadonlyMap<string, AggregateHandle>): Finding[] {
+  const domain = mod.domain ?? mod.name;
+  const out: Finding[] = [];
+  const seen = new Set<string>();
+  const admits = (aggId: string, fieldName: string): Field | undefined => {
+    const f = aggById.get(aggId)?.fields[fieldName] as Field | undefined;
+    return f !== undefined && admitsNull(f) ? f : undefined;
+  };
+  const ban = (aggId: string, fieldName: string, rule: string, fix: string): void => {
+    if (admits(aggId, fieldName) === undefined) return;
+    const key = `${rule}:${aggId}.${fieldName}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    out.push({
+      domain,
+      level: "refuse",
+      what: `'${aggId}.${fieldName}' is a null-admitting field (nullable/clearable/explicit-empty) used as ${rule} — a null there is structurally illegal`,
+      fix,
+    });
+  };
+
+  // Facet gates (authority/standing) + identity refs — a null in these breaks the very thing they decide.
+  for (const agg of mod.aggregates) {
+    for (const [name, f0] of Object.entries(agg.fields)) {
+      const f = f0 as Field;
+      if (admits(agg.id, name) === undefined) continue;
+      if (f.facet === "authority" || f.facet === "standing") {
+        ban(agg.id, name, "an authority/standing gate", "drop the null semantic — an authority sink must always resolve to a subject.");
+      }
+      if (f.kind === "ref") {
+        ban(agg.id, name, "an identity reference", "an identity ref must always point somewhere — model absence with a separate presence flag, not a null ref.");
+      }
+    }
+  }
+  // Read keys / group-bys / spatial indexes — a null key row is a silent dead index.
+  for (const q of mod.queries ?? []) for (const k of q.key) if (!k.includes(".")) ban(q.returns, k, `the query '${q.id}' key`, "key on a non-null field — a null key never indexes.");
+  const banBy = (of: string, by: string | undefined, id: string, noun: string): void => {
+    if (by !== undefined && !by.includes(".")) ban(of, by, `the ${noun} '${id}' group-by`, "group by a non-null field — a null group is a silent dead bucket.");
+  };
+  for (const c of mod.counts ?? []) { const d = finishCount(c); banBy(d.of, d.by, d.id, "count"); }
+  for (const s of mod.sums ?? []) { const d = finishSum(s); banBy(d.of, d.by, d.id, "sum"); }
+  for (const m of mod.mins ?? []) { const d = finishExtremum(m); banBy(d.of, d.by, d.id, "min"); }
+  for (const m of mod.maxes ?? []) { const d = finishExtremum(m); banBy(d.of, d.by, d.id, "max"); }
+  for (const e of mod.exists_ ?? []) { const d = finishExists(e); banBy(d.of, d.by, d.id, "exists"); }
+  for (const sp of mod.spatials ?? []) if (!sp.on.includes(".")) ban(sp.of, sp.on, `the spatial index '${sp.id}'`, "a spatial field must always carry a geometry — a null point is not indexable.");
+  return out;
+}
+
+// TWIN N-d (null_semantics.md) — an UNGATED generated clear lane beside GATED sibling writes.
+// A `t.clearable(field)` mints a `clear<Agg><Field>` WRITE directive. If it is ungated (no
+// `requires:`) while OTHER writes on the same aggregate ARE `.requires`-gated, the clear lane is an
+// accidental authz hole (you can null a field you can't otherwise write). WARN (not refuse — an
+// ungated clear may be intentional; name the fix). The generated directive carries the real gate;
+// this twin reads the field's `clearRequires` metadata to see whether the author declared one.
+function nullClearAuthorityFindings(mod: DomainModule, aggById: ReadonlyMap<string, AggregateHandle>): Finding[] {
+  const domain = mod.domain ?? mod.name;
+  // Aggregate ids that carry at least one `.requires`-gated directive (the authz axis).
+  const gatedAggs = new Set<string>();
+  for (const d of mod.directives as Directive<unknown>[]) {
+    if ((d as { requiresRelationGate?: unknown }).requiresRelationGate !== undefined) gatedAggs.add(d.aggregateId);
+  }
+  const out: Finding[] = [];
+  for (const agg of mod.aggregates) {
+    if (!gatedAggs.has(agg.id)) continue; // no gated sibling → an ungated clear is not a relative hole
+    for (const [name, f0] of Object.entries(agg.fields)) {
+      const f = f0 as Field;
+      if (f.isClearable !== true || f.clearRequires !== undefined) continue; // gated clear → fine
+      out.push({
+        domain,
+        directiveId: clearDirectiveId(agg.id, name),
+        level: "warn",
+        what: `the generated clear lane for '${agg.id}.${name}' is UNGATED, but sibling writes on '${agg.id}' are .requires-gated — a clear is a write, so this can null a field you otherwise can't write`,
+        fix: `pass an authority to t.clearable("${name}", { requires: "<relation>" }), or gate it deliberately if an open clear is intended`,
+      });
+    }
+  }
+  return out;
+}
+
 // ── TWIN 3 (slice 2) — INVARIANT SAMPLE-PROBE (aggregate + workspace invariants) ────
 // An aggregate invariant (`aggregate(id, fields, { invariant })`) runs on every touching event; a
 // workspaceInvariant(id).on(dir).reads(...).assert(...) runs at the gate. We probe each like a plan:
@@ -856,12 +1034,16 @@ export function checkDomainModules(
       findings.push(...unreadPayloadFindings(domain, dir, probe));
       findings.push(...opVsSchemaFindings(domain, dir, probe, aggById));
       findings.push(...deletedAmbientFindings(domain, dir, probe));
+      findings.push(...nullPayloadFindings(domain, dir, aggById));
+      findings.push(...nullWriteFindings(domain, dir, probe, aggById));
     }
 
     // Slice-2/slice-3 twins over the whole module: invariant sample-probes + encryption grouping.
     findings.push(...invariantFindings(mod, aggById));
     findings.push(...encryptionGroupingFindings(mod, aggById));
     findings.push(...dottedQueryKeyFindings(mod, aggById));
+    findings.push(...nullBanFindings(mod, aggById));
+    findings.push(...nullClearAuthorityFindings(mod, aggById));
   }
 
   // The BIRTH-RECIPE twin (unify): fold the scattered `.births()` recipe diagnostics into the

package/src/null_meta.ts

@@ -0,0 +1,65 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded QuickJS engine}.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * NULL-SEMANTICS METADATA CONSUMPTION (architecture/null_semantics.md — the codegen half).
+ *
+ * The DSL half (`fields.ts`/`ops.ts`/`law_check.ts`) TAGS a field with its null semantic:
+ * `nullSemantic` (`"forbid"` default · `"explicit-empty"` · `"nullable"`), the required
+ * `nullReason` documentation for the null-admitting semantics, and `isClearable` for the
+ * explicit-clear lane. This module is the ONE reader of those props for the 5 codegen surfaces
+ * (TS/Dart clients, the Dart bridge client, proof synthesis, openapi) — so a shape change lands
+ * in one place, and the read is a structural cast (the props are additive/optional on `Field`,
+ * so a field carrying none is byte-identical to a pre-feature field).
+ */
+
+import { admitsNull } from "./fields.js";
+
+// THE null-admission predicate is the DSL half's canonical `admitsNull` (fields.ts) — it treats a
+// `nullSemantic` of `explicit-empty`/`nullable` AND `isClearable` alike (a cleared field reads back as
+// json null → ExplicitNull), so the encode guard, the check twins, and codegen's tri-state trigger all
+// share ONE definition. Re-exported so the 5 codegen surfaces import it from here with the doc helpers.
+export { admitsNull };
+
+/** The three named null semantics (`forbid` is the default when the field carries none). */
+export type NullSemantic = "forbid" | "explicit-empty" | "nullable";
+
+/** The null-semantics view of a field — a structural read of the DSL-tagged props. */
+export interface NullMeta {
+  readonly nullSemantic: NullSemantic;
+  /** The law-documentation reason (required by the DSL for the null-admitting semantics). */
+  readonly nullReason?: string;
+  /** The field declares an explicit-CLEAR lane (`t.clearable(...)`). */
+  readonly clearable: boolean;
+}
+
+/** The structural shape the DSL half writes onto a null-aware field (all optional/additive). */
+interface NullTaggedField {
+  readonly nullSemantic?: NullSemantic;
+  readonly nullReason?: string;
+  readonly isClearable?: true;
+}
+
+/** Read a field's (or any tagged value object descriptor's) null-semantics view. A field carrying
+ *  none reads as the `forbid` default with no reason and non-clearable — the era-safe zero. */
+export function nullMetaOf(field: unknown): NullMeta {
+  const f = (field ?? {}) as NullTaggedField;
+  const nullSemantic: NullSemantic = f.nullSemantic ?? "forbid";
+  return {
+    nullSemantic,
+    ...(f.nullReason !== undefined ? { nullReason: f.nullReason } : {}),
+    clearable: f.isClearable === true,
+  };
+}
+
+/** The human doc line for a null-admitting field, e.g. `null semantic: external import fidelity`.
+ *  Surfaces in generated openapi field descriptions + TS/Dart doc comments. `undefined` when the
+ *  field forbids null (nothing to say) or carries no reason. */
+export function nullDocLine(field: unknown): string | undefined {
+  const m = nullMetaOf(field);
+  if (m.nullSemantic === "forbid") return undefined;
+  const which = m.nullSemantic === "nullable" ? "nullable" : "explicit-empty";
+  return m.nullReason !== undefined ? `null semantic (${which}): ${m.nullReason}` : `null semantic: ${which}`;
+}

package/src/ops.ts

@@ -182,6 +182,38 @@ export function set<
   return { ...addressOf(agg), ...targetFieldOf(agg, field), field, kind: "set", value };
 }
 
+/**
+ * `clear(handle, "field")` — the EXPLICIT-CLEAR write (`architecture/null_semantics.md`) on a
+ * `t.clearable(...)` (or `t.nullable(...)`) field: it writes json `null`, lowering to a plain `Set`
+ * of `Value::Json(null)` (no new wire op — the kernel already stores a json null fine; the DSL null
+ * semantic is what makes it LAWFUL). NEVER hand-write `.set("field", null)` for this — `clear` names
+ * the intent and the encode-path guard admits its null because the target field declared it clearable.
+ * REFUSES at author time (and the type level collapses the field name) if the target field is NOT
+ * null-admitting.
+ */
+export function clear<
+  A extends Target,
+  K extends {
+    [P in keyof Fields<A>]: Fields<A>[P] extends { readonly isClearable: true }
+      ? P
+      : Fields<A>[P] extends { readonly nullSemantic: "nullable" }
+        ? P
+        : never;
+  }[keyof Fields<A>] &
+    string,
+>(agg: A, field: K): FieldOp {
+  const f = (agg as { fields?: Record<string, Field> }).fields?.[field] as
+    | { isClearable?: true; nullSemantic?: string }
+    | undefined;
+  if (f !== undefined && f.isClearable !== true && f.nullSemantic !== "nullable") {
+    throw new Error(
+      `clear('${field}'): '${field}' is not a clearable/nullable field — declare it t.clearable(...) ` +
+        `(explicit clear) or t.nullable(..., { reason }) (null is a real value) before clearing it.`,
+    );
+  }
+  return { ...addressOf(agg), ...targetFieldOf(agg, field), field, kind: "set", value: null };
+}
+
 /** Return the same field op with an explicit per-aggregate event marker. */
 export function withMarker(op: FieldOp, marker: PlannedEventMarker): FieldOp {
   return { ...op, marker };