@githolon/dsl 0.54.2 → 0.55.1

package/src/wire_encode.ts

@@ -31,7 +31,7 @@ import {
   planBirthRecordOps,
 } from "./birth_meter.js";
 import type { AggregateHandle } from "./aggregate.js";
-import type { Field, EvidenceRefValue } from "./fields.js";
+import { admitsNull, type Field, type EvidenceRefValue } from "./fields.js";
 import type { Directive, ReferentialMarker } from "./directive.js";
 import type { PlannedOp, FieldOp } from "./ops.js";
 import { deterministicPorts, type Ports } from "./ctx.js";
@@ -77,6 +77,15 @@ export function encodeKernelSchema(agg: AggregateHandle): WireSchema {
   return out;
 }
 
+/** Recursively true iff `value` is (or contains, at any depth) a json `null` — the no-null check the
+ *  encode-path null gate runs on a forbid `t.json()` field. Bounded by the value's own structure. */
+function jsonHasNull(value: unknown): boolean {
+  if (value === null) return true;
+  if (Array.isArray(value)) return value.some(jsonHasNull);
+  if (typeof value === "object") return Object.values(value as Record<string, unknown>).some(jsonHasNull);
+  return false;
+}
+
 /** A shape description for a value that failed to encode (diagnostics only). */
 function describeShape(value: unknown): string {
   if (value === null) return "null";
@@ -93,6 +102,21 @@ function encodeKernelValue(field: Field | undefined, value: unknown, op?: FieldO
   // string): the authored {hash, mediaType, byteLength, storageClass} maps to the
   // kernel's snake_case serde shape + the `Git`/`External` unit-variant. Checked BEFORE
   // the scalar fallthroughs (an evidence value is an object, never a Str/Int).
+  // NULL SEMANTICS (`architecture/null_semantics.md`) — the LUMP null gate, top-level null. A null
+  // value is lawful ONLY on a field that declared a null-admitting semantic (nullable / explicit-empty
+  // / clearable via `clear(...)`); it lowers to `Value::Json(null)` regardless of the field's kind (a
+  // cleared string clears to json null). A null on a forbid field is a typed refusal HERE (the encode
+  // runs in the sealed engine on every peer) — the runtime twin of the check-time refusal. Era-safe: a
+  // pre-null-semantics package froze its old lump (no `nullSemantic`), so this only tightens new law.
+  if (value === null && field !== undefined) {
+    if (admitsNull(field)) return { Json: null };
+    const aggName = op?.aggregateType ?? op?.aggregateId ?? "?";
+    throw new Error(
+      `${aggName}.${op?.field ?? field.kind}: writes null, but null has no law-level meaning here. ` +
+        `Use t.clearable(...) + clear(...) for explicit clearing, or t.nullable(..., { reason }) / ` +
+        `t.json({ null: "explicit-empty", reason }) for a real empty value.`,
+    );
+  }
   if (field?.kind === "evidence") {
     const v = value as EvidenceRefValue;
     return {
@@ -109,7 +133,23 @@ function encodeKernelValue(field: Field | undefined, value: unknown, op?: FieldO
   // value — object, array, string, number, boolean, null — commits as one consistent value kind
   // (the kernel canonicalises it at the boundary). This is the new-era encoding; a package compiled
   // before this change froze the old `{ Str: JSON.stringify(value) }` lump and replays unchanged.
-  if (field?.kind === "json") return { Json: value };
+  if (field?.kind === "json") {
+    // NULL SEMANTICS (`architecture/null_semantics.md`) — the LUMP null gate. A `t.json()` field forbids
+    // null at every depth unless it declared a null-admitting semantic (nullable / explicit-empty /
+    // clearable via `clear(...)`). A plan-injected null on a forbid field is a typed refusal HERE (the
+    // encode runs inside the sealed engine on every peer), the runtime twin of the check-time refusal.
+    // Era-safe: a pre-null-semantics package froze its old lump and never carries a `nullSemantic`, so
+    // this branch only tightens NEWLY compiled law (the field defaults to "forbid" at construction).
+    if (!admitsNull(field) && jsonHasNull(value)) {
+      const aggName = op?.aggregateType ?? op?.aggregateId ?? "?";
+      throw new Error(
+        `${aggName}.${op?.field ?? field.kind}: json field carries a null, but null has no law-level ` +
+          `meaning here. Use t.clearable(...) + clear(...) for explicit clearing, or ` +
+          `t.nullable(..., { reason }) / t.json({ null: "explicit-empty", reason }) for a real empty value.`,
+      );
+    }
+    return { Json: value };
+  }
   // A `t.map(t.json())` / `t.map(VO.field())` ENTRY value is a json leaf too. Its wire DRIVER is
   // `MapOf(Lww)` (whose leaves are ordinary kernel `Value`s), so a json-valued entry lowers to the SAME
   // first-class `Value::Json` a top-level json field does — the map entry round-trips as its OBJECT, not a