@githolon/dsl 0.54.1 → 0.55.0

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

package/src/zod_lazy.ts

@@ -0,0 +1,45 @@
+/**
+ * Dependency-free helpers for RECURSIVE `z.lazy` payload schemas, shared by BOTH codegen walkers
+ * (codegen_ts + codegen_dart) WITHOUT coupling them. Keeping these here (rather than in codegen_ts)
+ * avoids a codegen_ts↔codegen_dart import cycle that would otherwise drag codegen_ts's heavy
+ * transitive deps (workspace_routing → node:crypto) into the tenant ENGINE bundle (esbuild
+ * neutral-platform, no node builtins). This module imports NOTHING but zod's type.
+ */
+import type { z } from "zod";
+
+function lazyDef(zt: z.ZodTypeAny): { type?: unknown; getter?: () => z.ZodTypeAny } {
+  const raw = zt as unknown as { _def?: { type?: unknown; getter?: () => z.ZodTypeAny }; def?: { type?: unknown; getter?: () => z.ZodTypeAny } };
+  return raw._def ?? raw.def ?? {};
+}
+
+/**
+ * Resolve a `z.lazy(() => …)` ONE level to its inner schema (zod v4 exposes the deferred getter on
+ * `_def.getter`). A non-lazy schema is returned unchanged. Recursive `z.lazy` schemas (a `TreeNode`
+ * that references itself) are common for tree/JSON payloads; every schema WALKER unwraps here and
+ * carries a VISITED / registry keyed on the lazy object's IDENTITY so a self-reference is a
+ * detectable knot, never an infinite descent.
+ */
+export function zodUnwrapLazy(zt: z.ZodTypeAny): z.ZodTypeAny {
+  const def = lazyDef(zt);
+  if (def.type === "lazy" && typeof def.getter === "function") return def.getter();
+  return zt;
+}
+
+const capFirst = (s: string): string => (s.length === 0 ? s : s[0]!.toUpperCase() + s.slice(1));
+const camelize = (s: string): string => s.replace(/[_\s-]+(\w)/g, (_m, c: string) => c.toUpperCase());
+
+/**
+ * A PascalCase type name from a payload path (`saveTree.root` → `SaveTreeRoot`), array markers
+ * dropped. The SAME base the TS and Dart recursive-type synthesizers use so a recursive type's
+ * TS alias and Dart class agree in the common case.
+ */
+export function recursiveTypeBaseName(path: string): string {
+  return (
+    path
+      .replace(/\[\]/g, "")
+      .split(/[.]/)
+      .filter(Boolean)
+      .map((s) => capFirst(camelize(s)))
+      .join("") || "Recursive"
+  );
+}