@githolon/dsl 0.46.0 → 0.47.0

package/dart/test/test_harness_test.dart

@@ -1,75 +1,103 @@
-// NomosTestHarness: unit coverage for the identity/jwt plumbing, plus the LIVE ephemeral fixture loop
-// (birth a throwaway ws → deploy real law → two client replicas → write on one, converge on the other).
-// The live test needs a `githolon login --agent` session (or NOMOS_PRINCIPAL) and is opt-in via NOMOS_LIVE=1.
+// NomosTestHarness — the EPHEMERAL, FULLY-OFFLINE fixture loop: install real tenant law into a fresh local
+// workspace (no cloud), drive one directive + one read through the REAL githolon over the node runner, and
+// tear down deterministically. This is the headless app-test lane: the same bridge + generated-client surface
+// the app UI uses, under `dart test` / `flutter test`, with no network.
+//
+// Prerequisites (skipped-with-reason when absent, so CI stays green either way): `node` on PATH; the
+// in-repo runner; a warm `~/.holon/runtime` cache (holon.wasm + packages.json — one `githolon` run fills it);
+// and the compiled `examples/guestbook/build/guestbook.deploy.json` (`cd examples/guestbook && npx nomos-compile`).
 @TestOn('vm')
 library;
 
-import 'dart:convert';
 import 'dart:io';
 
 import 'package:nomos_client/nomos_headless.dart';
 import 'package:test/test.dart';
 
-String _repoEntry() =>
+String get _repoEntry =>
     '${Directory.current.path}/../../cloud/web-client/runner/node-entry.mjs';
-
-String _guestbookDeployJson() =>
+String get _guestbookDeployJson =>
     '${Directory.current.path}/../../examples/guestbook/build/guestbook.deploy.json';
+String get _runtimeDir =>
+    '${Platform.environment['HOME'] ?? ''}/.holon/runtime';
+
+/// The prerequisite that isn't installable in-test (a warm runtime cache + the compiled fixture). Returns a
+/// skip reason, or null when everything the harness needs is present.
+String? _missingPrereq() {
+  if (!File(_repoEntry).existsSync()) return 'in-repo runner not found at $_repoEntry';
+  if (!File(_guestbookDeployJson).existsSync()) {
+    return 'compile the fixture first: cd examples/guestbook && npx nomos-compile';
+  }
+  if (!File('$_runtimeDir/holon.wasm').existsSync() ||
+      !File('$_runtimeDir/packages.json').existsSync()) {
+    return 'warm ~/.holon/runtime first (run any `githolon` command once to cache the runtime)';
+  }
+  return null;
+}
 
 void main() {
-  test('ephemeral without any identity refuses with a named remedy', () async {
-    // isolate from a real ~/.holon by pointing HOME at an empty dir
-    // (can't re-env the current isolate — so only run when no creds file exists).
-    final home = Platform.environment['HOME'] ?? '';
-    if (File('$home/.holon/credentials.json').existsSync()) {
-      markTestSkipped('a githolon session exists — the fallback would find it');
-      return;
-    }
+  test('ephemeral rejects an empty deploy list with a named remedy', () async {
     await expectLater(
-      NomosTestHarness.ephemeral(),
+      NomosTestHarness.ephemeral(deployJsonPaths: const []),
       throwsA(isA<NomosTestHarnessException>()),
     );
   });
 
-  test(
-    'LIVE: ephemeral fixture — birth, deploy law, write on one replica, read it on another',
-    skip: Platform.environment['NOMOS_LIVE'] != '1'
-        ? 'set NOMOS_LIVE=1 (needs a githolon login --agent session)'
-        : null,
-    () async {
-      final harness = await NomosTestHarness.ephemeral(
-        deployJsonPaths: [_guestbookDeployJson()],
-        nodeEntry: _repoEntry(),
-      );
-      try {
-        final writer = await harness.connect(clientId: 'writer');
-        final reader = await harness.connect(clientId: 'reader');
-        final minted = await writer.mintId('Fixture');
-        expect(minted, startsWith('Fixture_'));
-        final outcome = await writer.offerCreates(
-            domain: 'guestbook',
-            directiveId: 'signGuestbook',
-            payload: {
-              'author': 'harness',
-              'message': 'ephemeral fixture green',
-              'mood': 'delighted',
-              'signedAt': DateTime.now().toUtc().toIso8601String(),
-            });
-        expect(outcome.created, hasLength(1));
-        expect(outcome.created.single.type, 'guestbook.GuestbookEntry');
-        await writer.sync(admit: true);
-        await reader.sync(admit: false);
-        final rows = await reader.query('entriesByAuthor', {'author': 'harness'});
-        expect(rows, hasLength(1));
-        expect(rows.first['id'], outcome.created.single.id);
-        expect(
-            (rows.first['data'] as Map)['message'], 'ephemeral fixture green');
-        stdout.writeln(
-            'live harness green: ws=${harness.workspace} rows=${jsonEncode(rows.first['data'])}');
-      } finally {
-        await harness.dispose();
-      }
-    },
-    timeout: const Timeout(Duration(minutes: 5)),
-  );
+  test('OFFLINE: install real law, write one directive, read it back, dispose', () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+    final harness = await NomosTestHarness.ephemeral(
+      deployJsonPaths: [_guestbookDeployJson],
+      nodeEntry: _repoEntry,
+      runtimeDir: _runtimeDir,
+      registerTearDown: addTearDown, // deterministic auto-dispose even if an expect() throws
+    );
+
+    // Drive the REAL law: a create directive + a declared query — the same ops a generated client emits.
+    final outcome = await harness.bridge.offerCreates(
+      domain: 'guestbook',
+      directiveId: 'signGuestbook',
+      payload: {
+        'author': 'harness',
+        'message': 'offline fixture green',
+        'mood': 'happy',
+        'signedAt': DateTime.now().toUtc().toIso8601String(),
+      },
+    );
+    expect(outcome.created, hasLength(1));
+    expect(outcome.created.single.type, 'guestbook.GuestbookEntry');
+
+    final rows = await harness.bridge.query('entriesByAuthor', {'author': 'harness'});
+    expect(rows, hasLength(1));
+    expect(rows.first['id'], outcome.created.single.id);
+    expect((rows.first['data'] as Map)['message'], 'offline fixture green');
+    expect((rows.first['data'] as Map)['moodEmoji'], '😊'); // proves the law's plan ran, not a stub
+
+    stdout.writeln('offline harness green: ws=${harness.workspace}');
+  }, timeout: const Timeout(Duration(minutes: 2)));
+
+  test('OFFLINE: dispose is idempotent and removes the temp dir', () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+    final harness = await NomosTestHarness.ephemeral(
+      deployJsonPaths: [_guestbookDeployJson],
+      nodeEntry: _repoEntry,
+      runtimeDir: _runtimeDir,
+      autoTearDown: false, // drive dispose explicitly to assert its determinism
+    );
+    // A read proves the holon is live before teardown.
+    expect(await harness.bridge.query('entriesByAuthor', {'author': 'nobody'}), isEmpty);
+
+    await harness.dispose();
+    await harness.dispose(); // idempotent: the second call is a no-op, never throws
+    // The bridge is dead after dispose — a call fails rather than silently reaching a leaked runner.
+    await expectLater(
+        harness.bridge.query('entriesByAuthor', {'author': 'x'}), throwsA(anything));
+  }, timeout: const Timeout(Duration(minutes: 2)));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.46.0",
+  "version": "0.47.0",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/codegen_dart_client.ts

@@ -60,6 +60,9 @@ export const dartHashConstName = (fileBase: string): string => `${lcFirst(camel(
 /** `todo-nomos` → `todoNomosInterfaceJson` — the baked structural-interface JSON const (#72). */
 export const interfaceConstNameDart = (fileBase: string): string => `${lcFirst(camel(fileBase))}InterfaceJson`;
 
+/** `todo-nomos` → `todoNomosCompatJson` — the baked client/law compat manifest JSON const (§5). */
+export const compatConstNameDart = (fileBase: string): string => `${lcFirst(camel(fileBase))}CompatJson`;
+
 /** Emit a Dart RAW triple-quoted string literal of an object's JSON (the interface is JSON-only
  *  data — no `'`/`$`/backslash escaping concerns under `r'''…'''`; JSON never contains `'''`). */
 function dartRawJson(value: unknown): string {
@@ -97,6 +100,9 @@ export interface DartBridgeClientOptions {
    *  (read shapes, sid-keyed). Baked in as JSON so the app can negotiate shape-compatibility
    *  against the workspace's installed offer, NOT by law hash. */
   readonly interface?: unknown;
+  /** The CLIENT/LAW COMPAT MANIFEST (§5) — the law hash + interface hash + generator provenance
+   *  this client was generated against. Baked in as JSON (DIAGNOSIS only, never a gate). */
+  readonly compat?: unknown;
   /** Where the bridge/runtime support types are imported from. */
   readonly supportImport?: "vendored" | "package";
   /**
@@ -314,6 +320,15 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
           ``,
         ]
       : []),
+    ...(opts.compat !== undefined
+      ? [
+          `/// The CLIENT/LAW COMPAT MANIFEST (§5) as JSON — the law hash, structural interface hash, and`,
+          `/// generator provenance this client was generated against. A DIAGNOSIS surface for connect-time`,
+          `/// classification (silent / shape-compatible / incompatible); it NEVER gates.`,
+          `const String ${compatConstNameDart(mod.name)} = ${dartRawJson(opts.compat)};`,
+          ``,
+        ]
+      : []),
     `/// Typed async client for the \`${domain}\` domain, bound to a connected [NomosBridge].`,
     `///`,
     `/// Pass \`actor\` (the verified principal uid) to author AS that user — the bridge's \`offerDirective\` op`,

package/src/codegen_proof.ts

@@ -1286,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
@@ -1333,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 {
@@ -1391,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
@@ -1418,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 —
@@ -1430,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;
 
@@ -1481,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,
@@ -1495,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[] {
@@ -1604,6 +1703,11 @@ 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. */
@@ -1786,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,

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,8 +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(). */`,
-  `  spatialWithin(spatialId: string, bbox: { minLng: number; minLat: number; maxLng: number; maxLat: number }): Promise<unknown>;`,
+  `  /** 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)
       ? [
@@ -452,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`,
@@ -829,7 +851,7 @@ 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(${JSON.stringify(sp.id)}, bbox) as Promise<Row<${sp.of}Data>[]>,`,
+        `    ${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[]) {
@@ -898,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 };
+}