@githolon/dsl 0.54.2 → 0.55.1

package/src/codegen_dart.ts

@@ -35,6 +35,7 @@ import type { AggregateHandle } from "./aggregate.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import type { RelationTypeDecl } from "./relation_schema.js";
 import type { Field, FieldKind, ValueObjectDescriptor, ValueObjectFieldDescriptor } from "./fields.js";
+import { admitsNull, nullMetaOf, nullDocLine } from "./null_meta.js";
 import type { Directive } from "./directive.js";
 import { executeDirectiveToIntent } from "./wire_encode.js";
 import { deterministicPorts } from "./ctx.js";
@@ -81,6 +82,13 @@ export interface PayloadFieldSpec {
    * only emits ops for present fields). Required fields are always emitted.
    */
   optional: boolean;
+  /**
+   * NULL SEMANTICS (null_semantics.md): the payload field ADMITS a domain `null` (its zod is
+   * `.nullable()`, a `t.nullable(...)`/`t.clearable(...)` sink). It generates as the sealed
+   * tri-state [NomosSlot] so the call site says OMITTED / EXPLICIT-NULL / PRESENT explicitly —
+   * `toPayloadJson` then omits, writes a real `null`, or writes the value accordingly.
+   * `false`/absent for a plain field (byte-identical to a pre-feature payload). */
+  nullAdmits?: boolean;
 }
 
 type ZodInternalDef = {
@@ -239,11 +247,19 @@ export function introspectPayload(
     // when null — mirroring the engine's Zod, which only sees present fields).
     let zt = ztRaw as z.ZodTypeAny;
     let optional = false;
-    while (isOptionalOrDefault(zt)) {
-      optional = true;
+    let nullAdmits = false;
+    // Unwrap optional/default (omission) AND nullable (a domain `null`) in ANY order — a payload
+    // field may be `.nullable()`, `.optional()`, or both. A nullable field carries the tri-state slot.
+    while (isOptionalOrDefault(zt) || zodTypeName(zt) === "ZodNullable") {
+      if (zodTypeName(zt) === "ZodNullable") nullAdmits = true;
+      else optional = true;
       zt = zodInnerType(zt);
     }
-    out.push({ ...introspectField(name, zt, enumDartTypes, lazyNames), optional });
+    out.push({
+      ...introspectField(name, zt, enumDartTypes, lazyNames),
+      optional,
+      ...(nullAdmits ? { nullAdmits: true } : {}),
+    });
   }
   return out;
 }
@@ -453,6 +469,15 @@ interface AggFieldSpec {
    * only the generated read-model type. `undefined` for a non-json field.
    */
   jsonShape?: "object";
+  /**
+   * NULL SEMANTICS (null_semantics.md): the field ADMITS a domain `null` (declared
+   * `t.nullable(...)` / `t.clearable(...)`), so its read-model + payload surface is the
+   * sealed tri-state [NomosSlot] (Omitted / ExplicitNull / Present) instead of a plain
+   * `T?` — so the app edge can't collapse omission and explicit-null. `false`/absent for a
+   * `forbid` field (byte-identical to a pre-feature field). */
+  nullAdmits?: boolean;
+  /** The law-documentation `reason` for a null-admitting field (surfaces in the Dart doc comment). */
+  nullReason?: string;
 }
 
 export interface DartImport {
@@ -805,11 +830,16 @@ function aggregateFieldSpecs(
       // BIRTH-PRESENCE LAW (`.fromBirth()`): the gate refuses any event that leaves the field
       // absent, so the read model may type it NON-NULLABLE — the one lawful exception to the
       // partial-fold nullability doctrine (absence is unrepresentable by law, not convention).
-      const spec: AggFieldSpec = isCollectionKind(base.kind)
+      const baseSpec: AggFieldSpec = isCollectionKind(base.kind)
         ? base
         : f.isFromBirth === true
           ? { ...base, optional: false }
           : { ...base, optional: true };
+      // NULL SEMANTICS (null_semantics.md): a null-admitting scalar carries the tri-state slot.
+      const nmeta = nullMetaOf(f);
+      const spec: AggFieldSpec = admitsNull(f)
+        ? { ...baseSpec, nullAdmits: true, ...(nmeta.nullReason !== undefined ? { nullReason: nmeta.nullReason } : {}) }
+        : baseSpec;
       if (used.has(spec.name)) {
         throw new Error(
           `aggregate '${agg.id}' field '${spec.wireName}' maps to duplicate Dart field '${spec.name}'`,
@@ -1134,19 +1164,27 @@ function emitAggregate(
     `  /// indexed/by-id accessor matched on (e.g. the siteId). Empty string only when`,
     `  /// the aggregate is built from a bare \`data\` map with no row id (e.g. a unit test).`,
     `  final ${idType} aggregateId;`,
-    ...specs.map(
-      (s) => `  final ${s.dartType}${s.optional ? "?" : ""} ${s.name};`,
-    ),
+    ...specs.flatMap((s) => {
+      const doc = s.nullReason !== undefined ? [`  /// null semantic: ${s.nullReason}`] : [];
+      // NULL SEMANTICS: a null-admitting field is the sealed tri-state slot (Omitted / ExplicitNull /
+      // Present) — omission and explicit-null never collapse. Others keep the plain `T?`.
+      return s.nullAdmits === true
+        ? [...doc, `  final NomosSlot<${stripNullable(s.dartType)}> ${s.name};`]
+        : [`  final ${s.dartType}${s.optional ? "?" : ""} ${s.name};`];
+    }),
   ].join("\n");
   const ctorParams = [
     `    this.aggregateId = const ${idType}.fromRow(''),`,
     ...specs.map(
       // A required scalar stays `required`; an optional scalar OR a collection is not
       // `required` (an absent optional scalar is null; an absent collection is empty).
+      // A null-admitting slot defaults to Omitted.
       (s) =>
-        s.optional || isCollectionKind(s.kind)
-          ? `    ${collectionDefaultParam(s)}`
-          : `    required this.${s.name},`,
+        s.nullAdmits === true
+          ? `    this.${s.name} = const NomosSlot.omitted(),`
+          : s.optional || isCollectionKind(s.kind)
+            ? `    ${collectionDefaultParam(s)}`
+            : `    required this.${s.name},`,
     ),
   ].join("\n");
 
@@ -1158,7 +1196,11 @@ function emitAggregate(
   // threaded from the row id (GAP 2) — defaulting to '' for a bare-map call.
   const parseLines = [
     `      aggregateId: ${aggregateIdFromRowExpr(agg.id, "id")},`,
-    ...specs.map((s) => `      ${s.name}: ${parseField(s, className)},`),
+    ...specs.map((s) =>
+      s.nullAdmits === true
+        ? `      ${s.name}: NomosSlot.decode<${stripNullable(s.dartType)}>(data, '${s.wireName}', ${slotDecodeCallback(s, "aggregate")}),`
+        : `      ${s.name}: ${parseField(s, className)},`,
+    ),
   ].join("\n");
 
   // `==`/`hashCode` include the id (two rows with the same data but different ids are
@@ -1953,6 +1995,53 @@ function parseField(s: AggFieldSpec, aggregate: string): string {
   }
 }
 
+/**
+ * The `(v) => …` DECODE CALLBACK for a null-admitting field's [NomosSlot] (null_semantics.md).
+ * [NomosSlot.decode] pre-handles the OMITTED (key absent) + EXPLICIT-NULL (value `null`) cases,
+ * so this callback ONLY sees a real PRESENT value `v` (never null) and turns it into the typed
+ * Dart value — mirroring [parseField]'s present-branch per kind, but over a raw leaf `v`. */
+function slotDecodeCallback(s: AggFieldSpec, mode: "aggregate" | "readModel"): string {
+  switch (s.kind) {
+    case "ref":
+      return s.refIdClass !== undefined
+        ? `(v) => ${s.refIdClass}.fromRow(v as String)`
+        : `(v) => v as String`;
+    case "position":
+    case "string":
+      return s.valueClass !== undefined
+        ? `(v) => ${s.valueClass}.fromRow(v as String)`
+        : `(v) => v as String`;
+    case "json":
+      if (s.voClass !== undefined) {
+        return `(v) => ${s.voClass}.fromProjected((v as Map).cast<String, Object?>())`;
+      }
+      // The AGGREGATE class types every `json` leaf as `String` (re-stringify a parsed container via
+      // `jsonEncode`); the READ MODEL types a `t.jsonObject()` leaf as `Map<String, Object?>` (strict
+      // object) and a plain `t.json()` leaf as the permissive `Object?` (kept as-is).
+      if (mode === "aggregate") return `(v) => v is String ? v : jsonEncode(v)`;
+      return s.jsonShape === "object" ? `(v) => (v as Map).cast<String, Object?>()` : `(v) => v`;
+    case "bool":
+      return `(v) => v as bool`;
+    case "counter":
+    case "int":
+      return `(v) => (v as num).toInt()`;
+    case "enum":
+      return `(v) => ${s.dartType}.fromWire(v as String)`;
+    case "evidence":
+      return `(v) => EvidenceRef.fromProjected((v as Map).cast<String, Object?>())`;
+    // Collections never admit null (the law bans nullable on a set/map) — unreachable.
+    case "set":
+    case "map":
+      return `(v) => v`;
+  }
+}
+
+/** Strip a trailing `?` so a nullable-typed base (`Object?`) becomes the slot's inner
+ *  non-null type (`NomosSlot<Object>` — the slot owns nullability via ExplicitNull). */
+function stripNullable(t: string): string {
+  return t.endsWith("?") ? t.slice(0, -1) : t;
+}
+
 // ---- generated read model class --------------------------------------------
 //
 // A typed read model class generated from aggregate DSL field declarations. It
@@ -2145,9 +2234,12 @@ function emitReadModel(
     `  /// The kernel aggregate id (the \`{type,id,data}\` row's \`id\`, e.g. the siteId).`,
     `  /// Empty string only when built from a bare \`data\` map with no row id (a unit test).`,
     `  final ${idType} aggregateId;`,
-    ...specs.map(
-      (s) => `  final ${readModelDartType(s)}${readModelNullableSuffix(s)} ${s.name};`,
-    ),
+    ...specs.flatMap((s) => {
+      const doc = s.nullReason !== undefined ? [`  /// null semantic: ${s.nullReason}`] : [];
+      return s.nullAdmits === true
+        ? [...doc, `  final NomosSlot<${stripNullable(readModelDartType(s))}> ${s.name};`]
+        : [`  final ${readModelDartType(s)}${readModelNullableSuffix(s)} ${s.name};`];
+    }),
     ...deriveds.map(
       (d) =>
         `  /// Engine-projected DERIVED read field (pure fn of the folded fields; NOT kernel state).\n  final ${projectionReturnDartType(d.returns)} ${d.id};`,
@@ -2162,9 +2254,12 @@ function emitReadModel(
     ...specs.map((s) =>
       // A required field is `required`; an optional scalar, a collection, OR a
       // permissive json leaf (already nullable `Object?`) takes its default/null.
-      s.optional || isCollectionKind(s.kind) || isPermissiveJsonLeaf(s)
-        ? `    ${readModelDefaultParam(s)}`
-        : `    required this.${s.name},`,
+      // A null-admitting slot defaults to Omitted.
+      s.nullAdmits === true
+        ? `    this.${s.name} = const NomosSlot.omitted(),`
+        : s.optional || isCollectionKind(s.kind) || isPermissiveJsonLeaf(s)
+          ? `    ${readModelDefaultParam(s)}`
+          : `    required this.${s.name},`,
     ),
     // Derived/combined fields are always nullable (null until the engine pass runs).
     ...deriveds.map((d) => `    this.${d.id},`),
@@ -2173,7 +2268,11 @@ function emitReadModel(
 
   const parseLines = [
     `      aggregateId: ${aggregateIdFromRowExpr(agg.id, "id")},`,
-    ...specs.map((s) => `      ${s.name}: ${parseReadModelField(s, wireType)},`),
+    ...specs.map((s) =>
+      s.nullAdmits === true
+        ? `      ${s.name}: NomosSlot.decode<${stripNullable(readModelDartType(s))}>(data, '${s.wireName}', ${slotDecodeCallback(s, "readModel")}),`
+        : `      ${s.name}: ${parseReadModelField(s, wireType)},`,
+    ),
     // Derived/combined fields decode from the engine-produced bare JSON leaf.
     ...deriveds.map((d) => `      ${d.id}: ${parseProjectionReturnField(d.id, d.returns)},`),
     ...combineds.map((c) => `      ${c.id}: ${parseProjectionReturnField(c.id, c.returns)},`),
@@ -2225,10 +2324,20 @@ function emitDirective(
   // Field decls: optional payload fields are nullable Dart fields (omitted from the
   // payload JSON when null); required fields are non-null + `required` in the ctor.
   const fieldDecls = specs
-    .map((s) => `  final ${s.dartType}${s.optional ? "?" : ""} ${s.name};`)
+    .map((s) =>
+      s.nullAdmits === true
+        ? `  final NomosSlot<${stripNullable(s.dartType)}> ${s.name};`
+        : `  final ${s.dartType}${s.optional ? "?" : ""} ${s.name};`,
+    )
     .join("\n");
   const ctorParams = specs
-    .map((s) => `    ${s.optional ? "" : "required "}this.${s.name},`)
+    .map((s) =>
+      // A null-admitting slot defaults to Omitted (the call site chooses Present/ExplicitNull);
+      // an optional field defaults to null; a required field is `required`.
+      s.nullAdmits === true
+        ? `    this.${s.name} = const NomosSlot.omitted(),`
+        : `    ${s.optional ? "" : "required "}this.${s.name},`,
+    )
     .join("\n");
   // Zero-field payload (e.g. a `.births()` sanctioning directive with an empty
   // object schema): `const X({});` / a dangling blank field block is INVALID Dart —
@@ -2243,14 +2352,21 @@ function emitDirective(
   // fields are written only when present (mirrors the engine's Zod: ops are emitted
   // only for present fields).
   const requiredEntries = specs
-    .filter((s) => !s.optional)
+    .filter((s) => !s.optional && s.nullAdmits !== true)
     .map((s) => `    '${s.name}': ${toJsonExpr(s, s.name)},`);
   const optionalLines = specs
-    .filter((s) => s.optional)
+    .filter((s) => s.optional && s.nullAdmits !== true)
     .map(
       (s) =>
         `    if (${s.name} != null) '${s.name}': ${toJsonExpr(s, `${s.name}!`)},`,
     );
+  // NULL SEMANTICS: a null-admitting field writes through its slot — Omitted writes nothing,
+  // ExplicitNull writes a real `null`, Present writes the encoded value (null_semantics.md).
+  const slotSpecs = specs.filter((s) => s.nullAdmits === true);
+  const slotWriteLines = slotSpecs.map(
+    (s) => `    ${s.name}.writeTo(data, '${s.name}', (v) => ${toJsonExpr(s, "v")});`,
+  );
+  const hasSlots = slotSpecs.length > 0;
 
   const docFirst = directiveDoc(d);
 
@@ -2284,12 +2400,25 @@ function emitDirective(
     ``,
     `  /// Serialise this payload to the intent DATA JSON (the shape the`,
     `  /// domain Zod schema validates inside the engine). Optional fields are`,
-    `  /// omitted when null.`,
+    `  /// omitted when null; a null-admitting field writes through its tri-state slot.`,
     `  @override`,
-    `  Map<String, Object?> toPayloadJson() => <String, Object?>{`,
-    ...requiredEntries,
-    ...optionalLines,
-    `  };`,
+    ...(hasSlots
+      ? [
+          `  Map<String, Object?> toPayloadJson() {`,
+          `    final data = <String, Object?>{`,
+          ...requiredEntries,
+          ...optionalLines,
+          `    };`,
+          ...slotWriteLines,
+          `    return data;`,
+          `  }`,
+        ]
+      : [
+          `  Map<String, Object?> toPayloadJson() => <String, Object?>{`,
+          ...requiredEntries,
+          ...optionalLines,
+          `  };`,
+        ]),
     `}`,
   ].join("\n");
 }
@@ -3591,6 +3720,13 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
   ].join("\n\n");
   // The symbols whose Dart surface this file EMITS (framework-shared ones live in the shared file).
   const localAggregates = mod.aggregates.filter((a) => !skipAggregateIds.has(a.id));
+  // A nullable plain-`t.json()` read-model field's slot decode re-stringifies a parsed container via
+  // `jsonEncode` — the ONE case the generated file needs `dart:convert` (null_semantics.md).
+  const needsJsonConvert = localAggregates.some((a) =>
+    Object.values(a.fields as Record<string, Field>).some(
+      (f) => admitsNull(f) && f.kind === "json" && f.valueObject === undefined,
+    ),
+  );
   const localDirectives = mod.directives.filter((d) => !skipDirectiveIds.has(d.id));
   const localQueries = (mod.queries ?? []).filter((q) => !skipQueryIds.has(q.id));
   // Enums are collected from the LOCALLY-emitted symbols only — a framework directive/aggregate's
@@ -3798,6 +3934,8 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
     `// ignore_for_file: unnecessary_this, prefer_const_constructors, constant_identifier_names`,
     `// ignore_for_file: unused_import`,
     ``,
+    // A nullable plain-`t.json()` read-model slot decode re-stringifies via `jsonEncode`.
+    ...(needsJsonConvert ? [`import 'dart:convert';`] : []),
     // The generated tenant domains live in the `co2_nomos_domains` package and depend
     // on the framework `nomos_client` package by its PUBLIC package: URI — NOT a relative
     // `../wire.dart` path into the framework (which broke when the generated dir moved

package/src/codegen_openapi.ts

@@ -38,6 +38,8 @@ import { hasManyIndexes } from "./query.js";
 import { finishCount } from "./count.js";
 import { finishSum } from "./sum.js";
 import { finishExtremum } from "./extremum.js";
+import { nullDocLine } from "./null_meta.js";
+import type { Field } from "./fields.js";
 
 type AnyDirective = Directive<unknown>;
 
@@ -56,13 +58,30 @@ export interface OpenApiFragmentOptions {
 }
 
 /** Lower a directive's payload zod to JSON Schema; a non-representable schema falls back to a
- *  permissive object rather than failing the whole compile (the engine still validates the real zod). */
-function payloadJsonSchema(d: AnyDirective): unknown {
+ *  permissive object rather than failing the whole compile (the engine still validates the real zod).
+ *  NULL SEMANTICS (null_semantics.md): a payload property that maps by name to a null-admitting field
+ *  on the directive's target aggregate carries that field's documented `reason` as its `description`,
+ *  so every consumer of the spec knows what a `null` MEANS here. */
+function payloadJsonSchema(d: AnyDirective, module: DomainModule): unknown {
+  let schema: unknown;
   try {
-    return z.toJSONSchema((d as { payloadSchema: z.ZodTypeAny }).payloadSchema, { io: "input" });
+    schema = z.toJSONSchema((d as { payloadSchema: z.ZodTypeAny }).payloadSchema, { io: "input" });
   } catch {
     return { type: "object", additionalProperties: true };
   }
+  const aggId = (d as { aggregateId?: string }).aggregateId;
+  const agg = aggId !== undefined ? module.aggregates.find((a) => a.id === aggId) : undefined;
+  const props = (schema as { properties?: Record<string, Record<string, unknown>> })?.properties;
+  if (agg !== undefined && props !== undefined && typeof props === "object") {
+    for (const [name, prop] of Object.entries(props)) {
+      const field = (agg.fields as Record<string, Field> | undefined)?.[name];
+      const doc = field !== undefined ? nullDocLine(field) : undefined;
+      if (doc !== undefined && prop !== null && typeof prop === "object") {
+        prop.description = prop.description !== undefined ? `${String(prop.description)} — ${doc}` : doc;
+      }
+    }
+  }
+  return schema;
 }
 
 /** The domain key the engine resolves intents against (the `author` registry key). */
@@ -111,7 +130,7 @@ export function generateOpenApiFragment(
       },
       requestBody: {
         required: true,
-        content: { "application/json": { schema: payloadJsonSchema(dir) } },
+        content: { "application/json": { schema: payloadJsonSchema(dir, module) } },
       },
       responses: {
         "200": { description: "admitted — the sealed intent head" },

package/src/codegen_proof.ts

@@ -44,6 +44,7 @@ import type { FieldOp } from "./ops.js";
 import type { RelationTypeDecl, Rewrite } from "./relation_schema.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import { finishCount } from "./count.js";
+import { clearDirectiveId } from "./clear_directive.js";
 import { voMetaOf, voSample } from "./value_object.js";
 import { mintedCreateField } from "./workspace_routing.js";
 import { deterministicPorts } from "./ctx.js";
@@ -66,6 +67,27 @@ import {
 /** Shared empty visited-set for the lazy-recursion guard (no allocation on the common path). */
 const EMPTY_LAZY_VISITED: ReadonlySet<z.ZodTypeAny> = new Set();
 
+/**
+ * The top-level payload fields that ADMIT a domain `null` (their zod is `.nullable()`, a
+ * `t.nullable(...)`/`t.clearable(...)` sink — null_semantics.md). The proof drives the NULL ARM for
+ * each (the value arm is the normal synthesized sample) so the law is provably total over `null`.
+ * A nullable wrapped in optional/default still counts (unwrapped in ANY order). Empty for a
+ * null-free payload — no extra leg, byte-identical proof. */
+export function nullablePayloadFields(schema: z.ZodTypeAny): string[] {
+  if (zodKind(schema) !== "object") return [];
+  const out: string[] = [];
+  for (const [name, raw] of Object.entries(zodObjectShape(schema))) {
+    let f = raw as z.ZodTypeAny;
+    let admits = false;
+    while (zodKind(f) === "optional" || zodKind(f) === "default" || zodKind(f) === "nullable") {
+      if (zodKind(f) === "nullable") admits = true;
+      f = zodDef(f).innerType!;
+    }
+    if (admits) out.push(name);
+  }
+  return out;
+}
+
 const camel = (s: string) => s.replace(/[_\s-]+(\w)/g, (_m, c: string) => c.toUpperCase());
 const lcFirst = (s: string) => (s.length ? s[0]!.toLowerCase() + s.slice(1) : s);
 
@@ -2620,6 +2642,58 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
     );
   }
 
+  // NULL SEMANTICS BOTH-ARM PROOF (null_semantics.md): the primary dispatch above already proved the
+  // VALUE arm (a nullable field synthesizes to a sampled value); here we prove the NULL arm — the law
+  // ADMITS an explicit `null` for each nullable field, so it is provably total over null. Each create
+  // arm mints a fresh id. Empty for a null-free payload (byte-identical proof).
+  const nullArms = nullablePayloadFields(createDir.payloadSchema as z.ZodTypeAny);
+  for (const field of nullArms) {
+    const armMint = mintField !== undefined ? `, ${JSON.stringify(mintField)}: await holon.mint(${JSON.stringify(agg.id)})` : "";
+    out.push(
+      `// ${n()}. NULL-ARM PROOF — \`${field}\` is nullable: the law must ADMIT an explicit null (both arms proven).`,
+      `try {`,
+      `  await app.${createDir.id}({ ...${JSON.stringify(baseValue)}${armMint}, ${JSON.stringify(field)}: null });`,
+      `  ok(${JSON.stringify(`null-arm — ${domain}/${createDir.id} admitted with \`${field}\`=null (the law handles the explicit-null arm)`)});`,
+      `} catch (e) {`,
+      `  fail(\`null-arm ${field}=null was REFUSED — a nullable field's null arm must be admitted: \${(e as Error).message}\`);`,
+      `}`,
+      ``,
+    );
+  }
+
+  // CLEAR-LANE PROOF (null_semantics.md): a `t.clearable(...)` field's compose-injected clear directive
+  // (`clearDirectiveId(agg, field)`) LOWERS to a Set of json null — dispatch it on the created instance
+  // and read the field back as null (ExplicitNull). Only UN-GATED clear directives (the proof binds no
+  // actor); a gated clear needs authority the negative/positive gate legs already cover. Empty for a
+  // clearable-free aggregate (byte-identical proof).
+  const clearLegs = Object.entries(agg.fields as Record<string, Field>)
+    .filter(([, f]) => f.isClearable === true)
+    .map(([field]) => ({ field, dirId: clearDirectiveId(agg.id, field) }))
+    .filter(({ dirId }) => {
+      const cd = (mod.directives as Directive<unknown>[]).find((d) => d.id === dirId);
+      return cd !== undefined && (cd as { requiresRelationGate?: unknown }).requiresRelationGate === undefined;
+    });
+  for (const { field, dirId } of clearLegs) {
+    out.push(
+      `// ${n()}. CLEAR-LANE PROOF — \`${field}\` is clearable: \`${dirId}\` lowers to Set(json null); after it,`,
+      `//    the field reads back null (ExplicitNull), never omitted.`,
+      `try {`,
+      `  await app.${dirId}({ id: createdId });`,
+      `} catch (e) {`,
+      `  fail(\`clear-lane ${dirId} was REFUSED — an un-gated clear of a clearable field must be admitted: \${(e as Error).message}\`);`,
+      `}`,
+      `{`,
+      `  const clearedRows = await holon.queryById(createdId) as { data?: Record<string, unknown> }[];`,
+      `  const clearedRow = clearedRows[0];`,
+      `  if (clearedRow !== undefined && clearedRow.data !== undefined && clearedRow.data[${JSON.stringify(field)}] != null) {`,
+      `    fail(\`clear-lane ${field}: expected null after clear, got \${JSON.stringify(clearedRow.data[${JSON.stringify(field)}])}\`);`,
+      `  }`,
+      `  ok(${JSON.stringify(`clear-lane — ${domain}/${dirId} admitted; \`${field}\` reads back null (ExplicitNull)`)});`,
+      `}`,
+      ``,
+    );
+  }
+
   out.push(
     `globalThis.fetch = realFetch;`,
     `ok("offline proof ENFORCED — fetch was trapped: local write/read touched no network");`,

package/src/codegen_ts.ts

@@ -50,6 +50,7 @@ import type { DerivedDecl } from "./derived.js";
 import type { CombinedDecl } from "./combined.js";
 import { resolveWorkspaceTypes, type ResolvedWorkspaceType, type WorkspaceTypeDecl } from "./workspace_type.js";
 import { deriveClientMintPlan, type ClientMintPlanEntry } from "./workspace_routing.js";
+import { admitsNull, nullDocLine } from "./null_meta.js";
 
 const cap = (s: string) => (s.length ? s[0]!.toUpperCase() + s.slice(1) : s);
 const camel = (s: string) => s.replace(/[_\s-]+(\w)/g, (_m, c: string) => c.toUpperCase());
@@ -468,6 +469,14 @@ function tsTypeOfPayload(
 // ── DSL Field → read-model TS type (the projection's decode surface) ──────────────
 
 function tsTypeOfField(field: Field): string {
+  const base = tsBaseTypeOfField(field);
+  // NULL SEMANTICS (null_semantics.md): a `nullable`/`explicit-empty` field ADMITS a domain `null`,
+  // so its read-model type carries the `| null` arm (distinct from the `?` partial-fold absence a
+  // non-null-admitting field gets). A `forbid` json/VO field NEVER gets the null arm.
+  return admitsNull(field) ? `${base} | null` : base;
+}
+
+function tsBaseTypeOfField(field: Field): string {
   switch (field.kind) {
     case "string":
       return "string";
@@ -1140,6 +1149,8 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     out.push(`export interface ${typeId}Data {`);
     for (const [name, field] of Object.entries(agg.fields)) {
       const required = (field as Field).isFromBirth === true;
+      const doc = nullDocLine(field);
+      if (doc !== undefined) out.push(`  /** ${doc} */`);
       out.push(`  ${name}${required ? "" : "?"}: ${tsTypeOfField(field as Field)};`);
     }
     for (const extra of extrasByType.get(typeId) ?? []) out.push(extra);

package/src/compile_package_main.ts

@@ -379,6 +379,10 @@ const DART_SUPPORT_SRC = [
   "offer.dart",
   "subscriptions.dart",
   "provider.dart",
+  // The tri-state slot (NomosSlot<T>) for `nullable`/`clearable` fields (null_semantics.md) — the
+  // barrel re-exports it and generated read-model/payload classes reference it, so it must vendor.
+  // Zero external pub deps (pure Dart).
+  "null_slot.dart",
   // Runtime aggregate-meta support types (NomosAggregateMeta/NomosFieldMeta) — the generated
   // per-domain registry consts reference them through the barrel.
   "aggregate_meta.dart",