@githolon/dsl 0.45.0 → 0.47.0

package/src/codegen_proof.ts

@@ -98,13 +98,13 @@ function sampleString(zt: z.ZodTypeAny, field: string): string {
 }
 
 /** One sample value for one zod shape. NO FALLBACK: an unhandled shape throws, naming its remedy. */
-function sampleOfZod(zt: z.ZodTypeAny, field: string, where: string): unknown {
+function sampleOfZod(zt: z.ZodTypeAny, field: string, where: string, voIncludeOptional = false): unknown {
   // VALUE OBJECTS FIRST (vo_authoring_end_to_end.md slice C): a declared VO carries its own
   // lawful sample (the author's validated `example`, the blessed geometry sample, or per-field
   // descriptor synthesis) — the raw-zod walk below cannot see constraints like geo's min-2
   // coordinates and would synthesize a value the law itself refuses.
   const vo = voMetaOf(zt);
-  if (vo !== undefined) return voSample(vo);
+  if (vo !== undefined) return voSample(vo, { includeOptional: voIncludeOptional });
   switch (zodKind(zt)) {
     case "string":
       return sampleString(zt, field);
@@ -120,14 +120,14 @@ function sampleOfZod(zt: z.ZodTypeAny, field: string, where: string): unknown {
     }
     case "array": {
       const el = zodArrayElement(zt);
-      return zodKind(el) === "string" ? ["sample-a"] : [sampleOfZod(el, field, where)];
+      return zodKind(el) === "string" ? ["sample-a"] : [sampleOfZod(el, field, where, voIncludeOptional)];
     }
     case "object": {
       const out: Record<string, unknown> = {};
       for (const [name, raw] of Object.entries(zodObjectShape(zt))) {
         const k = zodKind(raw as z.ZodTypeAny);
         if (k === "optional" || k === "default") continue; // optional → omit
-        out[name] = sampleOfZod(raw as z.ZodTypeAny, name, where);
+        out[name] = sampleOfZod(raw as z.ZodTypeAny, name, where, voIncludeOptional);
       }
       return out;
     }
@@ -136,10 +136,10 @@ function sampleOfZod(zt: z.ZodTypeAny, field: string, where: string): unknown {
     case "nullable":
     case "optional":
     case "default":
-      return sampleOfZod(zodDef(zt).innerType!, field, where);
+      return sampleOfZod(zodDef(zt).innerType!, field, where, voIncludeOptional);
     case "union": {
       const first = zodDef(zt).options?.[0];
-      if (first !== undefined) return sampleOfZod(first, field, where);
+      if (first !== undefined) return sampleOfZod(first, field, where, voIncludeOptional);
       throw new Error(`codegen-proof: empty union at field '${field}' of ${where}`);
     }
     default:
@@ -154,7 +154,7 @@ function sampleOfZod(zt: z.ZodTypeAny, field: string, where: string): unknown {
  * optional/defaulted fields omitted, required `…At` strings omitted (auto-stamped
  * by the generated client), everything else sampled by {@link sampleOfZod}.
  */
-export function synthesizePayload(schema: z.ZodTypeAny, where: string): SynthesizedPayload {
+export function synthesizePayload(schema: z.ZodTypeAny, where: string, opts?: { voIncludeOptional?: boolean }): SynthesizedPayload {
   if (zodKind(schema) !== "object") {
     throw new Error(`codegen-proof: ${where} payload is not a zod object — the proof can only synthesize object payloads`);
   }
@@ -166,7 +166,7 @@ export function synthesizePayload(schema: z.ZodTypeAny, where: string): Synthesi
     const k = zodKind(f);
     if (k === "optional" || k === "default") continue; // optional → omit
     if (stamped.has(name)) continue; // `…At` → omit; the client stamps it
-    value[name] = sampleOfZod(f, name, where);
+    value[name] = sampleOfZod(f, name, where, opts?.voIncludeOptional === true);
   }
   return { value, autoStamped };
 }
@@ -598,6 +598,35 @@ export interface BornContextAuthority {
 
 /** Run a directive's plan with a synthesized+probe payload under birth-probe globals and return the drained
  *  field ops (authoring sink + returned ops). `undefined` ⇒ the plan couldn't be probed. */
+/** Run a directive's plan on an EXPLICIT payload under the deterministic probe ports, returning the
+ *  emitted ops (undefined when the plan throws) — the payload-parameterized sibling of {@link probePlanOps}. */
+function probePlanOpsWithPayload(
+  dir: Directive<unknown>,
+  probePayload: Record<string, unknown>,
+  _where: string,
+): FieldOp[] | undefined {
+  let ops: FieldOp[] | undefined;
+  try {
+    withBirthProbeGlobals(() => {
+      __resetAuthoring();
+      __resetReads();
+      __resetBirths();
+      try {
+        const returned = dir.plan(probePayload as never, deterministicPorts({ physical: 1, replica: 1, principal: "principal:probe" }));
+        const drained = [...__drainAuthoring(), ...(Array.isArray(returned) ? returned : [])];
+        ops = drained.filter((o): o is FieldOp => (o as { kind?: string }).kind !== "strike");
+      } finally {
+        __resetAuthoring();
+        __resetReads();
+        __resetBirths();
+      }
+    });
+  } catch {
+    return undefined;
+  }
+  return ops;
+}
+
 function probePlanOps(
   dir: Directive<unknown>,
   where: string,
@@ -1257,6 +1286,8 @@ export function diagnoseRelationBootstrapGap(mod: DomainModule): string | undefi
 interface DiscoveredGenesisStep {
   readonly domain: string;
   readonly directiveId: string;
+  /** The step's dispatch payload — validated at compile against the target directive's schema (births DX). */
+  readonly payload?: unknown;
 }
 
 /** A discovered CHILD-BIRTH leg: a parent `.births()` directive proven end-to-end into the child it births
@@ -1304,6 +1335,12 @@ export interface ChildBirthLeg {
    *  parent workspace (home → estate is the canonical case), the proof runner drives this setup birth first
    *  and then authors the child birth inside the born parent. */
   readonly parentSetup?: ChildBirthParentSetup;
+  /** COMPILE-TIME RECIPE DIAGNOSTICS (births DX): problems found by statically validating each genesis
+   *  step against the composed package (missing child module, unknown seed directive, payload-schema
+   *  mismatch, a plan that returns a non-array — the exact things that otherwise surface at proof time as
+   *  an opaque `born=[]`). WARNINGS, not refusals: the kernel's own gate stays the arbiter; the compile
+   *  summary prints these and the proof runner fails fast on them with the same words. */
+  readonly recipeIssues?: readonly string[];
 }
 
 export interface ChildBirthParentSetup {
@@ -1362,13 +1399,94 @@ export function discoverChildBirthLeg(
   parentDomain: string,
   modules: readonly DomainModule[],
 ): ChildBirthLeg | undefined {
-  if (birthDir.birthsChild !== true) return undefined;
+  const r = discoverChildBirthLegOrReason(birthDir, parentDomain, modules);
+  return r.leg;
+}
+
+/** The engine iterates a plan's return value unconditionally (`wire_encode.ts`: `[...returned]`), so a
+ *  plan returning a builder / undefined ALWAYS halts at the gate with an opaque "value is not iterable".
+ *  This hint turns that into the fix. */
+const PLAN_RETURN_HINT =
+  "a plan must RETURN AN ARRAY of ops — fluent builders (ensure()/create().set(...)) record themselves, so end the plan with `return [];`, or wrap standalone ops in `[ ... ]`";
+
+/** STATIC RECIPE VALIDATION (births DX): check each genesis step against the composed package — the same
+ *  checks the child's own gate will make at birth, surfaced at COMPILE with a fix in the message. The
+ *  bootstrap/nomos `installDomain` steps are kernel-resolved (bytes-by-hash) and skipped. */
+function validateGenesisSteps(
+  chain: readonly DiscoveredGenesisStep[],
+  modules: readonly DomainModule[],
+): string[] {
+  const issues: string[] = [];
+  chain.forEach((s, i) => {
+    const at = `genesis step ${i + 1}`;
+    if (s === null || typeof s !== "object" || typeof s.domain !== "string" || typeof s.directiveId !== "string") {
+      issues.push(`${at} is not a {domain, directiveId, actor, payload} step object`);
+      return;
+    }
+    if (s.directiveId === "installDomain" && (s.domain === "bootstrap" || s.domain === "nomos")) return;
+    const mod = modules.find((m) => (m.domain ?? m.name) === s.domain);
+    if (mod === undefined) {
+      issues.push(
+        `${at} (${s.domain}/${s.directiveId}) targets domain '${s.domain}', which is NOT composed in this package — add its module to nomos.package.mjs \`domains\` (the one-package pattern: the parent must fold the child law so the kernel can resolve its bytes by hash; see bench/scale/fixtures/estate-birth)`,
+      );
+      return;
+    }
+    const dir = (mod.directives as Directive<unknown>[]).find((d) => d?.id === s.directiveId);
+    if (dir === undefined) {
+      issues.push(
+        `${at} (${s.domain}/${s.directiveId}): domain '${s.domain}' has no directive '${s.directiveId}' — it has: ${mod.directives.map((d) => d.id).join(", ")}`,
+      );
+      return;
+    }
+    const parsed = (dir.payloadSchema as z.ZodTypeAny).safeParse(s.payload);
+    if (!parsed.success) {
+      const why = parsed.error.issues.map((iss) => `${iss.path.join(".") || "(payload)"}: ${iss.message}`).join("; ");
+      issues.push(`${at} (${s.domain}/${s.directiveId}): the recipe payload does not satisfy the directive's payload schema — ${why}`);
+      return;
+    }
+    // Run the step's plan on the recipe's own payload (the exact dispatch the child gate replays) and
+    // enforce the ENGINE's return contract: the sealed engine spreads the return value, so a non-array
+    // return is ALWAYS a runtime halt — catch it here, with the fix.
+    try {
+      withBirthProbeGlobals(() => {
+        __resetAuthoring();
+        __resetReads();
+        __resetBirths();
+        try {
+          const returned = dir.plan(s.payload as never, deterministicPorts({ physical: 1, replica: 1, principal: "principal:probe" }));
+          if (!Array.isArray(returned)) {
+            issues.push(
+              `${at} (${s.domain}/${s.directiveId}): the plan returned ${returned === undefined ? "undefined" : `a non-array (${typeof returned})`} — ${PLAN_RETURN_HINT}`,
+            );
+          }
+        } finally {
+          try { __drainAuthoring(); __drainReads(); __drainBirths(); } catch { /* drained */ }
+        }
+      });
+    } catch (e) {
+      issues.push(
+        `${at} (${s.domain}/${s.directiveId}): the plan THREW at the compile probe (${(e as Error)?.message ?? e}) — if it only fails on the sample payload this is a false alarm, but the child gate will replay this exact step at birth`,
+      );
+    }
+  });
+  return issues;
+}
+
+/** {@link discoverChildBirthLeg} with a REASON on the undiscoverable path — so `.births()` without a
+ *  provable leg prints WHY at compile instead of a silent \`proof SKIPPED\`. */
+export function discoverChildBirthLegOrReason(
+  birthDir: Directive<unknown>,
+  parentDomain: string,
+  modules: readonly DomainModule[],
+): { leg?: ChildBirthLeg; reason?: string } {
+  if (birthDir.birthsChild !== true) return {};
+  const who = `${parentDomain}/${birthDir.id}`;
   let recipe: { workspace?: unknown; genesisChain?: unknown } | undefined;
   let synth: SynthesizedPayload;
   try {
     synth = synthesizePayload(birthDir.payloadSchema as z.ZodTypeAny, `${parentDomain}/${birthDir.id}`);
-  } catch {
-    return undefined;
+  } catch (e) {
+    return { reason: `${who}: the payload could not be synthesized for the compile probe (${(e as Error)?.message ?? e}) — the offline proof needs a sampleable payload (strings/numbers/enums; exotic shapes drop the leg)` };
   }
   // The plan needs concrete payload VALUES for every field it reads to build the recipe (frameworkHash /
   // lawHash / owner …). The synthesizer omits `…At` (auto-stamped) + optional fields; fill the auto-stamped
@@ -1389,10 +1507,15 @@ export function discoverChildBirthLeg(
       const drained = __drainBirths();
       recipe = drained[0] as typeof recipe;
     });
-  } catch {
-    return undefined;
+  } catch (e) {
+    return { reason: `${who}: the plan THREW at the compile probe (${(e as Error)?.message ?? e}) — the probe runs it on a synthesized payload to read the birth recipe` };
+  }
+  if (recipe === undefined) {
+    return { reason: `${who}: the plan declared .births() but recorded NO birth — its plan must call birth({ workspace, genesisChain }) (see dsl/src/framework/home.ts birthHome, or bench/scale/fixtures/estate-birth)` };
+  }
+  if (!Array.isArray(recipe.genesisChain)) {
+    return { reason: `${who}: birth() was called without a genesisChain ARRAY — the recipe is { workspace, genesisChain: [ ...steps ] }` };
   }
-  if (recipe === undefined || !Array.isArray(recipe.genesisChain)) return undefined;
   const chain = recipe.genesisChain as DiscoveredGenesisStep[];
   // The child seed = the FIRST genesis step that is neither bootstrap nor nomos installDomain (the leaf's
   // own seed). A platform-shaped recipe (seedGenesis → grantAdmin → birthCloud tail) is out of scope here —
@@ -1401,7 +1524,10 @@ export function discoverChildBirthLeg(
     (s) => s !== null && typeof s === "object" && s.directiveId !== "installDomain"
       && s.domain !== "bootstrap" && s.domain !== "nomos",
   );
-  if (seedStep === undefined) return undefined;
+  if (seedStep === undefined) {
+    return { reason: `${who}: the genesis chain has ONLY install steps (no child seed) — the offline leg proves the LEAF shape [bootstrap/installDomain, nomos/installDomain, <childDomain>/<seedDirective>]; add the child's own seed step (a platform-shaped seedGenesis→grantAdmin→birthCloud tail is proven live, not offline)` };
+  }
+  const recipeIssues = validateGenesisSteps(chain, modules);
   const childDomain = seedStep.domain;
   const childSeedDirectiveId = seedStep.directiveId;
 
@@ -1452,7 +1578,7 @@ export function discoverChildBirthLeg(
   if (frameworkHashField !== undefined) delete birthPayload[frameworkHashField];
   if (lawHashField !== undefined) delete birthPayload[lawHashField];
 
-  return {
+  const leg: ChildBirthLeg = {
     parentDomain,
     birthDirectiveId: birthDir.id,
     birthPayload,
@@ -1466,7 +1592,9 @@ export function discoverChildBirthLeg(
     ...(childSeedAggregateId !== undefined ? { childSeedAggregateId } : {}),
     ...(childSeedInstanceId !== undefined ? { childSeedInstanceId } : {}),
     ...(childQuery !== undefined ? { childQuery } : {}),
+    ...(recipeIssues.length > 0 ? { recipeIssues } : {}),
   };
+  return { leg };
 }
 
 function childBirthsForModule(mod: DomainModule, modules: readonly DomainModule[]): ChildBirthLeg[] {
@@ -1575,6 +1703,27 @@ export interface ProofLegs {
   readonly mintField?: string;
   readonly query?: { readonly id: string; readonly params: Record<string, unknown> };
   readonly count?: { readonly id: string; readonly group: string };
+  /** BIRTHS DX DIAGNOSTICS: present when this domain declares ≥1 `.births()` directive whose child-birth
+   *  leg is either UNDISCOVERABLE (the reason, so the compile summary never silently skips a birth) or
+   *  discoverable-but-suspect (the leg's `recipeIssues`). Printed by the compile summary; the offline
+   *  runner fails fast on recipe issues with the same words. Additive: absent on older files. */
+  readonly birthDiagnostics?: readonly string[];
+  /** SPATIAL MEMBERSHIP (lane-2 read-serving): present when a declared spatial index covers the created
+   *  aggregate AND the plan-probe proved the synthesized payload lands a geometry on the indexed path —
+   *  the offline runner asserts `spatialWithin(id, world)` contains the created row. */
+  readonly spatial?: { readonly id: string };
+  /** EVERY OTHER standalone create (co2 feedback: the proof exercises ALL VO-bearing creates, not just
+   *  the first) — each dispatched + asserted exactly like the primary. Additive: absent on older files. */
+  readonly extraCreates?: readonly {
+    readonly directiveId: string;
+    readonly aggregateId: string;
+    readonly payload: Record<string, unknown>;
+    readonly autoStamped: readonly string[];
+    readonly mintField?: string;
+    readonly query?: { readonly id: string; readonly params: Record<string, unknown> };
+    readonly count?: { readonly id: string; readonly group: string };
+    readonly spatial?: { readonly id: string };
+  }[];
   /** THE CHILD-BIRTH LEG — present iff this domain has a `.births()` directive (it is `child-birth-provable`).
    *  When this domain is itself the BORN child's law (no standalone create), the index also registers the
    *  child domain key pointing at the SAME leg, so `proof --domain <child>` resolves through the parent birth. */
@@ -1603,14 +1752,69 @@ function isStandaloneCreate(d: Directive<unknown> | undefined): boolean {
     && d.requiresRelationGate === undefined;
 }
 
-export function proofLegsForModule(mod: DomainModule): ProofLegs | null {
-  const createDir = (mod.directives as Directive<unknown>[]).find((d) => isStandaloneCreate(d));
-  if (createDir === undefined) return null;
-  const domain = mod.domain ?? mod.name;
+/** Does `v` carry an RFC 7946 geometry object at `segs` (walked into the composite)? */
+function geometryAtPath(v: unknown, segs: readonly string[]): boolean {
+  let cur: unknown = v;
+  for (const s of segs) {
+    if (cur === null || typeof cur !== "object") return false;
+    cur = (cur as Record<string, unknown>)[s];
+  }
+  return (
+    cur !== null && typeof cur === "object" &&
+    typeof (cur as { type?: unknown }).type === "string" &&
+    (cur as { coordinates?: unknown }).coordinates !== undefined
+  );
+}
+
+/** Build ONE standalone-create leg entry (payload + matched query/count + the spatial-membership
+ *  assertion when a declared spatial index covers the type and the plan-probe lands a geometry on
+ *  the indexed path — trying the optionals-included VO sample when the default omits it). */
+function createLegFor(
+  mod: DomainModule,
+  createDir: Directive<unknown>,
+  domain: string,
+): {
+  directiveId: string; aggregateId: string; payload: Record<string, unknown>;
+  autoStamped: readonly string[]; mintField?: string;
+  query?: { id: string; params: Record<string, unknown> };
+  count?: { id: string; group: string };
+  spatial?: { id: string };
+} | null {
   const agg = (mod.aggregates as AggregateHandle[]).find((a) => a.id === createDir.aggregateId);
   if (agg === undefined) return null;
-  const synth = synthesizePayload(createDir.payloadSchema as z.ZodTypeAny, `${domain}/${createDir.id}`);
+  const where = `${domain}/${createDir.id}`;
+  let synth = synthesizePayload(createDir.payloadSchema as z.ZodTypeAny, where);
   const mintField = mintedCreateField(createDir, agg);
+
+  // SPATIAL MEMBERSHIP: probe the plan — does the create set the indexed head field with a geometry
+  // at the declared path? If the default sample omits an optional geometry, retry with the
+  // optionals-included VO sample and adopt IT as the leg's payload (so the proof exercises the
+  // geometry the index needs).
+  let spatial: { id: string } | undefined;
+  const spatials = ((mod.spatials ?? []) as { id: string; of: string; on: string }[]).filter((sp) => sp.of === agg.id);
+  if (spatials.length > 0) {
+    const probeWith = (sy: SynthesizedPayload): FieldOp[] | undefined => {
+      const probePayload: Record<string, unknown> = { ...sy.value };
+      for (const f of sy.autoStamped) probePayload[f] = "2026-01-01T00:00:00Z";
+      const probed = probePlanOpsWithPayload(createDir, probePayload, where);
+      return probed;
+    };
+    const hits = (ops: FieldOp[] | undefined, sp: { on: string }): boolean => {
+      if (ops === undefined) return false;
+      const [head, ...segs] = sp.on.split(".");
+      return ops.some((o) => (o as { kind?: string }).kind === "set" && (o as { field?: string }).field === head && geometryAtPath((o as { value?: unknown }).value, segs));
+    };
+    let ops = probeWith(synth);
+    let matched = spatials.find((sp) => hits(ops, sp));
+    if (matched === undefined) {
+      const richer = synthesizePayload(createDir.payloadSchema as z.ZodTypeAny, where, { voIncludeOptional: true });
+      ops = probeWith(richer);
+      matched = spatials.find((sp) => hits(ops, sp));
+      if (matched !== undefined) synth = richer; // the geometry-bearing sample becomes the leg's payload
+    }
+    if (matched !== undefined) spatial = { id: matched.id };
+  }
+
   const baseValue: Record<string, unknown> = { ...synth.value };
   if (mintField !== undefined) delete baseValue[mintField];
   const query = ((mod.queries ?? []) as QueryDecl[]).find(
@@ -1620,8 +1824,6 @@ export function proofLegsForModule(mod: DomainModule): ProofLegs | null {
     .map((raw) => finishCount(raw))
     .find((c) => c.of === agg.id && (c as { where?: unknown }).where == null && (c.by == null || baseValue[c.by] !== undefined));
   return {
-    domain,
-    legs: ["compile-valid", "standalone-provable"],
     directiveId: createDir.id,
     aggregateId: agg.id,
     payload: baseValue,
@@ -1629,6 +1831,23 @@ export function proofLegsForModule(mod: DomainModule): ProofLegs | null {
     ...(mintField !== undefined ? { mintField } : {}),
     ...(query ? { query: { id: query.id, params: Object.fromEntries(query.key.map((k) => [k, baseValue[k]])) } } : {}),
     ...(count ? { count: { id: count.id, group: count.by != null ? String(baseValue[count.by]) : "" } } : {}),
+    ...(spatial !== undefined ? { spatial } : {}),
+  };
+}
+
+export function proofLegsForModule(mod: DomainModule): ProofLegs | null {
+  const domain = mod.domain ?? mod.name;
+  const creates = (mod.directives as Directive<unknown>[]).filter((d) => isStandaloneCreate(d));
+  const legsBuilt = creates
+    .map((d) => { try { return createLegFor(mod, d, domain); } catch { return null; } })
+    .filter((l): l is NonNullable<typeof l> => l !== null);
+  if (legsBuilt.length === 0) return null;
+  const [primary, ...extras] = legsBuilt;
+  return {
+    domain,
+    legs: ["compile-valid", "standalone-provable"],
+    ...primary!,
+    ...(extras.length > 0 ? { extraCreates: extras } : {}),
   };
 }
 
@@ -1671,9 +1890,20 @@ export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[
   if (childBirthWithSetup !== undefined) legs.push("child-birth-provable");
   if (relationBootstrap !== undefined) legs.push("relation-bootstrap-provable");
 
+  // BIRTHS DX: every `.births()` directive either carries a discoverable leg (whose recipeIssues we
+  // surface) or a REASON it has none — a birth is never silently unprovable.
+  const birthDiagnostics: string[] = [];
+  for (const d of mod.directives as Directive<unknown>[]) {
+    if (d?.birthsChild !== true || typeof d.payloadSchema !== "object") continue;
+    const r = discoverChildBirthLegOrReason(d, domain, modules);
+    if (r.reason !== undefined) birthDiagnostics.push(r.reason);
+    for (const issue of r.leg?.recipeIssues ?? []) birthDiagnostics.push(`${domain}/${d.id}: ${issue}`);
+  }
+
   return {
     domain,
     legs,
+    ...(birthDiagnostics.length > 0 ? { birthDiagnostics } : {}),
     ...(standalone !== null
       ? {
           directiveId: standalone.directiveId,
@@ -1683,6 +1913,8 @@ export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[
           ...(standalone.mintField !== undefined ? { mintField: standalone.mintField } : {}),
           ...(standalone.query !== undefined ? { query: standalone.query } : {}),
           ...(standalone.count !== undefined ? { count: standalone.count } : {}),
+          ...(standalone.spatial !== undefined ? { spatial: standalone.spatial } : {}),
+          ...(standalone.extraCreates !== undefined ? { extraCreates: standalone.extraCreates } : {}),
         }
       : {}),
     ...(childBirthWithSetup !== undefined ? { childBirth: childBirthWithSetup } : {}),

package/src/codegen_ts.ts

@@ -40,6 +40,7 @@ import type { AggregateHandle } from "./aggregate.js";
 import type { Field, ValueObjectDescriptor, ValueObjectFieldDescriptor } from "./fields.js";
 import type { Directive } from "./directive.js";
 import type { DomainModule } from "./codegen_dart.js";
+import type { NomosCompat } from "./compat_manifest.js";
 import type { QueryDecl } from "./query.js";
 import { voMetaOf, collectPayloadValueObjectDescriptors } from "./value_object.js";
 import { finishCount } from "./count.js";
@@ -68,6 +69,9 @@ export const tsHashConstName = (packageName: string): string => `${upperSnake(pa
 /** `tool-library` → `TOOL_LIBRARY_INTERFACE` — the baked structural-interface const (#72). */
 export const interfaceConstName = (packageName: string): string => `${upperSnake(packageName)}_INTERFACE`;
 
+/** `tool-library` → `TOOL_LIBRARY_COMPAT` — the baked client/law compat manifest (§5). */
+export const compatConstName = (packageName: string): string => `${upperSnake(packageName)}_COMPAT`;
+
 // ── zod → TS (the same `_def ?? def` convention as codegen_dart's walker) ─────────
 // The walkers are exported: codegen_proof.ts synthesizes SAMPLE payloads from the
 // same zod shapes this file derives TYPES from — one introspection, two emitters.
@@ -379,6 +383,9 @@ export interface TsClientOptions {
    *  (read shapes, sid-keyed), keyed by domain. Baked in so `connect()` can negotiate
    *  shape-compatibility against the workspace's installed offer — NOT by hash. */
   readonly interface?: Record<string, unknown>;
+  /** The CLIENT/LAW COMPAT MANIFEST (§5) — baked in so the factory can hand it to the
+   *  holon's connect-time classifier (DIAGNOSIS only, never a gate). */
+  readonly compat?: NomosCompat;
 }
 
 /** TRUE when any module declares a PACKED workspace taxonomy (the routed-holon shape).
@@ -422,6 +429,16 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           ``,
         ]
       : []),
+    ...(opts.compat !== undefined
+      ? [
+          `/** The CLIENT/LAW COMPAT MANIFEST (§5): the law hash + structural interface hash + generator`,
+          ` *  provenance this client was generated against. A DIAGNOSIS surface — the factory hands it to`,
+          ` *  the holon's connect-time classifier, which logs a warning on a law-hash mismatch. It NEVER`,
+          ` *  gates: a hash mismatch with a compatible SHAPE is normal during law evolution (#72). */`,
+          `export const ${compatConstName(opts.packageName)} = ${JSON.stringify(opts.compat)} as const;`,
+          ``,
+        ]
+      : []),
     `/** One projection row: the aggregate's wire type, its id, and the folded fields. */`,
     `export interface Row<T> { type: string; id: string; data: T }`,
     ``,
@@ -438,6 +455,9 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `  watchById(aggregateId: string, cb: (rows: unknown) => void, opts?: { intervalMs?: number }): () => void;`,
     `  /** Declared-count / declared-sum O(1) reads (maintained by the read engine). */`,
     `  count(countId: string, groupKey?: string): Promise<number>;`,
+  `  /** THE SPATIAL READ (R*Tree probe): rows intersecting the bbox — same row shape as query().`,
+  `   *  OPTIONAL member: structural binding tolerates a pre-spatial holon (the accessor then throws at call). */`,
+  `  spatialWithin?(spatialId: string, bbox: { minLng: number; minLat: number; maxLng: number; maxLat: number }): Promise<unknown>;`,
     `  sum(sumId: string, groupKey?: string): Promise<number>;`,
     ...(anyPackedTaxonomy(modules)
       ? [
@@ -450,6 +470,10 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `  deadLetters(): Promise<{ id?: string; oid: string; source: string; error: string; domain?: string | null; directiveId?: string | null; at: string }[]>;`,
     `  retryDeadLetter(id: string): Promise<{ ok: boolean; head?: string; alreadyOnMain?: boolean; error?: string }>;`,
     `  discardDeadLetter(id: string): Promise<{ ok: boolean; removed: number }>;`,
+    `  /** THE CONNECT-TIME COMPAT CLASSIFIER (§5) — OPTIONAL: a holon from @githolon/client's connect()`,
+    `   *  attaches it (implemented by \`checkCompat\`); the generated factory hands over this client's baked`,
+    `   *  compat manifest so a law-hash mismatch logs a warning. DIAGNOSIS only — never throws, never gates. */`,
+    `  checkCompat?(compat: { lawHash: string; interfaceHash: string; packageName: string }): void;`,
     `}`,
     ``,
     `/** AUTHORITY IS UNFORGEABLE-BY-CONSTRUCTION: a GATED directive (one carrying a \`.requires(relation)\` write`,
@@ -824,6 +848,12 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       }
     }
 
+    for (const sp of (mod.spatials ?? []) as { id: string; of: string; on: string }[]) {
+      methods.push(
+        `    /** Declared spatial index \`${sp.id}\` — rows of \`${sp.of}\` whose \`${sp.on}\` geometry intersects the bbox (R*Tree probe). */`,
+        `    ${lcFirst(camel(sp.id))}: (bbox: { minLng: number; minLat: number; maxLng: number; maxLat: number }) => (holon.spatialWithin ?? (() => { throw new Error("this holon predates spatial reads — upgrade @githolon/client"); }))(${JSON.stringify(sp.id)}, bbox) as Promise<Row<${sp.of}Data>[]>,`,
+      );
+    }
     for (const q of (mod.queries ?? []) as QueryDecl[]) {
       const agg = aggByType.get(q.returns);
       const params = q.key
@@ -890,6 +920,9 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       `export function ${tsClientFactoryName(domain)}(holon: NomosHolon, opts: { domainHash?: string; actor?: string } = {}) {`,
       `  const domainHash = opts.domainHash ?? ${hashConst};`,
       `  const actor = opts.actor;`,
+      ...(opts.compat !== undefined
+        ? [`  holon.checkCompat?.(${compatConstName(opts.packageName)});`]
+        : []),
       `  return {`,
       `    domain: ${JSON.stringify(domain)} as const,`,
       `    domainHash,`,

package/src/compat_manifest.ts

@@ -0,0 +1,20 @@
+// The CLIENT/LAW COMPATIBILITY MANIFEST (§5, architecture/plug_and_play_dx.md).
+//
+// A DIAGNOSIS surface, NEVER a gate. Clients fit workspaces by STRUCTURAL INTERFACE
+// (stable-id subtyping, #72), not by law-hash pin — the hash pin was a bug we removed.
+// This block is baked into the generated TS + Dart clients and mirrored into the deploy
+// JSON so a connect() can classify: lawHash-equal (silent) vs lawHash-differs-shape-compat
+// (proceed, log) vs structurally-incompatible (warn). It is FRONTEND-ONLY — emitted like
+// the dart codegen hints, it does NOT enter the USD IR / package bytes / domainHash.
+export interface NomosCompat {
+  /** The package name (`cfg.name`). */
+  readonly packageName: string;
+  /** The deploy domainHash — sha256 of the package bytes (`policy:{hash}`). */
+  readonly lawHash: string;
+  /** sha256 over the CANONICAL serialization of the package structural interface. */
+  readonly interfaceHash: string;
+  /** Per domain key → its admission-identity hash (absent for identity-excluded domains). */
+  readonly domains: Record<string, { readonly identityHash?: string }>;
+  /** The generator provenance — the `@githolon/dsl` version + this manifest's schema. */
+  readonly generator: { readonly dsl: string; readonly schema: number };
+}