@githolon/dsl 0.48.1 → 0.49.0

package/dart/lib/src/test_harness.dart

@@ -66,7 +66,11 @@ class NomosTestHarness {
   /// [runtimeDir] — the runtime cache (default `~/.holon/runtime`); must hold `holon.wasm` + `packages.json`.
   /// [nodeEntry] — path to `node-entry.mjs`; when omitted it is resolved from [resolveFrom] via
   /// `require.resolve('@githolon/client/runner/node-entry.mjs')`.
-  /// [installHelper] — path to `offline-install.mjs`; defaults to the file beside [nodeEntry].
+  /// [installHelper] — the offline law-install lane. An EXISTING `.mjs` file is run as a node script (the
+  /// in-repo `offline-install.mjs`, the default when it exists beside [nodeEntry]); anything else is a
+  /// githolon COMMAND LINE whose `harness-install` subcommand is driven (the default `npx githolon` when the
+  /// in-repo helper is absent — a published tenant needs nothing but `githolon`). E.g. force the subcommand
+  /// with `installHelper: 'node /abs/cli/dist/cli.mjs'`.
   /// [registerTearDown] — pass the test framework's `addTearDown` to auto-[dispose] when the test ends
   /// (feature-detecting `package:test` from a library is not clean in Dart, so this is explicit and safe).
   /// [autoTearDown] — when true (default) and [registerTearDown] is given, registers [dispose] as a teardown.
@@ -90,8 +94,18 @@ class NomosTestHarness {
     }
     final entry = nodeEntry ??
         await _resolveEntry(node, resolveFrom ?? Directory.current.path);
-    final helper = installHelper ??
-        '${File(entry).parent.path}/offline-install.mjs';
+    // THE INSTALL LANE. [installHelper] is the one seam (PACKAGING NOTE above): either the in-repo
+    // `offline-install.mjs` node script, OR the published `githolon harness-install` subcommand (the CLI
+    // bundles the engine + this exact install sequence, so a published tenant needs nothing but `githolon`).
+    //  • an EXISTING `.mjs` file  ⇒ run it as a node script (the in-repo default when present);
+    //  • anything else            ⇒ treat it as a githolon COMMAND LINE and drive `harness-install`
+    //    (default `npx githolon` when the in-repo helper is absent; the test forces this lane by passing
+    //    e.g. `installHelper: 'node /abs/cli/dist/cli.mjs'`).
+    final resolvedHelper =
+        installHelper ?? '${File(entry).parent.path}/offline-install.mjs';
+    final useInRepoScript =
+        resolvedHelper.endsWith('.mjs') && File(resolvedHelper).existsSync();
+    final githolonCmd = installHelper == null ? 'npx githolon' : resolvedHelper;
 
     // A FRESH temp dir per harness — the snapshot + any transient runner state live here and nowhere else,
     // so dispose() leaves nothing behind.
@@ -102,7 +116,9 @@ class NomosTestHarness {
       final snapshot = '${workdir.path}/snapshot.bin';
       await _runInstall(
           node: node,
-          helper: helper,
+          useInRepoScript: useInRepoScript,
+          inRepoScript: resolvedHelper,
+          githolonCmd: githolonCmd,
           deployJsonPaths: deployJsonPaths,
           workspace: workspace,
           snapshot: snapshot,
@@ -182,29 +198,45 @@ class NomosTestHarness {
 
   static Future<void> _runInstall({
     required String node,
-    required String helper,
+    required bool useInRepoScript,
+    required String inRepoScript,
+    required String githolonCmd,
     required List<String> deployJsonPaths,
     required String workspace,
     required String snapshot,
     String? runtimeDir,
     void Function(String line)? onDiagnostic,
   }) async {
-    if (!File(helper).existsSync()) {
-      throw NomosTestHarnessException(
-          'offline-install helper not found at $helper — pass installHelper: explicitly '
-          '(it ships beside node-entry.mjs)');
-    }
-    final r = await Process.run(node, [
-      helper,
+    // Both lanes take the SAME flags (--deploy/--workspace/--out/--runtime) and print the SAME one-line JSON
+    // contract; only the leading command differs (node <script> vs `<githolon...> harness-install`).
+    final common = <String>[
       '--deploy', deployJsonPaths.join(','),
       '--workspace', workspace,
       '--out', snapshot,
       if (runtimeDir != null) ...['--runtime', runtimeDir],
-    ]);
+    ];
+    final String executable;
+    final List<String> args;
+    if (useInRepoScript) {
+      executable = node;
+      args = [inRepoScript, ...common];
+    } else {
+      // `githolonCmd` is a command line (e.g. `npx githolon` or `node /abs/cli.mjs`) — split into tokens.
+      final tokens =
+          githolonCmd.trim().split(RegExp(r'\s+')).where((t) => t.isNotEmpty).toList();
+      if (tokens.isEmpty) {
+        throw NomosTestHarnessException(
+            'no install helper resolved — pass installHelper: (an offline-install.mjs path, or a githolon command)');
+      }
+      executable = tokens.first;
+      args = [...tokens.skip(1), 'harness-install', ...common];
+    }
+    final tag = useInRepoScript ? 'offline-install' : 'harness-install';
+    final r = await Process.run(executable, args);
     final err = (r.stderr as String).trim();
     if (err.isNotEmpty) {
       for (final line in err.split('\n')) {
-        (onDiagnostic ?? stderr.writeln)('[offline-install] $line');
+        (onDiagnostic ?? stderr.writeln)('[$tag] $line');
       }
     }
     if (r.exitCode != 0) {

package/dart/test/test_harness_test.dart

@@ -20,6 +20,9 @@ String get _guestbookDeployJson =>
     '${Directory.current.path}/../../examples/guestbook/build/guestbook.deploy.json';
 String get _runtimeDir =>
     '${Platform.environment['HOME'] ?? ''}/.holon/runtime';
+// The built CLI bin — drives the `githolon harness-install` SUBCOMMAND lane (the published-harness path).
+String get _cliDist =>
+    '${Directory.current.path}/../../cli/dist/cli.mjs';
 
 /// 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.
@@ -100,4 +103,43 @@ void main() {
     await expectLater(
         harness.bridge.query('entriesByAuthor', {'author': 'x'}), throwsA(anything));
   }, timeout: const Timeout(Duration(minutes: 2)));
+
+  test('OFFLINE: the `githolon harness-install` SUBCOMMAND lane installs law and drives a read', () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+    if (!File(_cliDist).existsSync()) {
+      markTestSkipped('build the CLI first: cd cli && npm run build (needs dist/cli.mjs)');
+      return;
+    }
+    // FORCE the published subcommand lane via the installHelper seam: a githolon command line (here the
+    // in-repo built bin) whose `harness-install` subcommand does the offline install a published tenant gets.
+    final harness = await NomosTestHarness.ephemeral(
+      deployJsonPaths: [_guestbookDeployJson],
+      nodeEntry: _repoEntry,
+      runtimeDir: _runtimeDir,
+      installHelper: 'node $_cliDist', // NOT an existing .mjs file ⇒ the subcommand lane
+      registerTearDown: addTearDown,
+    );
+
+    final outcome = await harness.bridge.offerCreates(
+      domain: 'guestbook',
+      directiveId: 'signGuestbook',
+      payload: {
+        'author': 'subcommand',
+        'message': 'installed via githolon harness-install',
+        'mood': 'happy',
+        'signedAt': DateTime.now().toUtc().toIso8601String(),
+      },
+    );
+    expect(outcome.created, hasLength(1));
+    final rows = await harness.bridge.query('entriesByAuthor', {'author': 'subcommand'});
+    expect(rows, hasLength(1));
+    expect((rows.first['data'] as Map)['message'], 'installed via githolon harness-install');
+    expect((rows.first['data'] as Map)['moodEmoji'], '😊'); // the law's plan ran through the subcommand-built snapshot
+
+    stdout.writeln('subcommand harness green: ws=${harness.workspace}');
+  }, timeout: const Timeout(Duration(minutes: 2)));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.48.1",
+  "version": "0.49.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/build_package.ts

@@ -68,6 +68,7 @@ import { emitUsd } from "./usd.js";
 import { expandCapabilityExports } from "./capability_exports.js";
 import { RelationTuple } from "./framework/relations.js";
 import { parentAttestedBirthMarker } from "./births.js";
+import { discoverUnsanctionedEnsures, sanctioningEnsureDirective } from "./secondary_ensure.js";
 
 // ─────────────────────────────────────────────────────────────────────────────────
 // composeDomainModule — the named-keys `module(...)`
@@ -185,6 +186,24 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
       if (!byId.has(a.id)) byId.set(a.id, a);
     }
   }
+  // SECONDARY-CREATE AUTO-DECLARE (secondary_ensure.ts — the id-mint-gate DX): a plan may `ensure(B, "det:id")`
+  // a SECOND aggregate at a deterministic id of a type its directive does NOT declare `.ensures()` for. The
+  // id-mint gate refuses such an id unless the certified manifest carries an `Ensure → B` declaration. Plan-
+  // probe the directives, and for every ensured type NO directive already declares, inject a NO-OP sanctioning
+  // `.ensures(B)` directive (modelled on `nomosBirthRecordEnsure`) so the manifest opens the declared-ensures
+  // lane. Best-effort + era-safe: a domain with no (unsanctioned) secondary ensure synthesizes nothing and is
+  // byte-identical; a domain that DOES could not have deployed before without the author hand-writing this.
+  const autoDeclaredEnsures: string[] = [];
+  for (const ty of discoverUnsanctionedEnsures(directives, spec.domain ?? spec.name)) {
+    const agg = byId.get(ty);
+    // Only sanction a type whose handle this domain actually carries (its schema must be present for the
+    // upsert to fold); a probe pointing at a foreign/unknown type is left to the runtime gate (no schema).
+    if (agg === undefined) continue;
+    const dir = sanctioningEnsureDirective(agg);
+    if (directives.some((d) => d.id === dir.id)) continue;
+    directives.push(dir);
+    autoDeclaredEnsures.push(ty);
+  }
   const aggregates = [...byId.values()];
   const directiveIds = new Set(directives.map((d) => d.id));
   for (const task of spec.impureCapabilities ?? []) {
@@ -330,6 +349,8 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
     domain: spec.domain ?? spec.name,
     aggregates,
     directives,
+    // Diagnostic metadata for the compile summary — NOT law (not hashed). Omit-when-empty.
+    ...(autoDeclaredEnsures.length > 0 ? { autoDeclaredEnsures } : {}),
     ...(queries.length > 0 ? { queries } : {}),
     ...(counts.length > 0 ? { counts } : {}),
     ...(spatials.length > 0 ? { spatials } : {}),
@@ -878,7 +899,29 @@ export function hexUtf8(text: string): string {
  * domainHash the deploy names is sha256 over the WHOLE returned string (trailing
  * newline included) exactly as committed.
  */
-export function packageUsda(usdJson: string, javascript: string): string {
+export function packageUsda(usdJson: string, javascript: string, opts: { compact?: boolean } = {}): string {
+  // THE COMPACT ERA (opt-in, 2026-07-04): base64 blob fields (`*B64`, 1.33× text) instead of hex
+  // (2×). Requires every consumer to carry the decode arm (kernel domain_package.rs extract_blob +
+  // the JS parsers) — shipped ahead of this emit, so `compact: true` is the tenant's explicit
+  // choice once their stack is current. Hex stays the default emit until a future major; hex
+  // packages parse FOREVER (the era rule). sha256(the returned string) is the domainHash either
+  // way — a compact recompile is ONE named hash move (batched with minify + locale-strip).
+  if (opts.compact) {
+    return `#usda 1.0
+(
+    customData = {
+        string nomos:format = "${NOMOS_DOMAIN_PACKAGE_FORMAT}"
+    }
+)
+
+def "NomosDomainPackage"
+{
+    custom string nomos:usdJsonB64 = "${Buffer.from(usdJson, "utf8").toString("base64")}"
+    custom string nomos:executable:language = "javascript"
+    custom string nomos:executable:javascriptB64 = "${Buffer.from(javascript, "utf8").toString("base64")}"
+}
+`;
+  }
   return `#usda 1.0
 (
     customData = {

package/src/codegen_dart.ts

@@ -2985,6 +2985,14 @@ export interface DomainModule {
   domain?: string;
   aggregates: AggregateHandle[];
   directives: AnyDirective[];
+  /**
+   * SECONDARY-CREATE AUTO-DECLARE (secondary_ensure.ts) — the aggregate TYPES whose deterministic
+   * secondary `ensure(...)` `composeDomainModule` plan-probed and SANCTIONED by injecting a no-op
+   * `.ensures(Type)` directive into {@link directives}. Diagnostic metadata for the compile summary
+   * ONLY — NOT law, NOT hashed (the manifest reads named fields; this one is not among them). Absent
+   * when the domain has no unsanctioned secondary ensure (the common case).
+   */
+  autoDeclaredEnsures?: string[];
   /**
    * STABLE-ID CONTINUITY (#58 — names are labels, identity is minted). When present
    * (attached by `nomos-compile` from the PRIOR build's identity manifests), the

package/src/codegen_proof.ts

@@ -659,6 +659,33 @@ function probePlanOps(
   return { ops, synth, probePayload };
 }
 
+/**
+ * Compile-side plan-probe of a directive's SECONDARY deterministic ENSURES — the aggregate TYPES its
+ * plan introduces via `ensure(Agg, "det:id")` (an `ensures`-marked op at a dev-chosen deterministic id),
+ * beyond whatever its PRIMARY referential marker declares. This is the discovery half of the "secondary
+ * create auto-declare" DX (`secondary_ensure.ts`): the kernel's id-mint gate admits an Ensure-introduced
+ * typed id ONLY when the certified manifest declares `Ensure → Type`, so `composeDomainModule` sanctions
+ * each discovered type with a no-op ensures directive.
+ *
+ * BEST-EFFORT (the reliability caveat): runs the plan ONCE under a synthesized payload + the deterministic
+ * probe ports. A plan that can't be probed (unsynthesizable payload / throws) or that ensures CONDITIONALLY
+ * on a payload shape the synthesis didn't hit yields fewer (or no) types — in which case the runtime
+ * id-mint gate still refuses the un-sanctioned ensure exactly as before (NO regression, NO weakening: the
+ * courtesy simply didn't fire). Returns the sorted set of ensured types (INCLUDING the directive's own
+ * primary target if it marks `ensures`; the caller subtracts the domain-wide declared set).
+ */
+export function probeEnsuredTypes(dir: Directive<unknown>, where: string): string[] {
+  const probed = probePlanOps(dir, where);
+  if (probed === undefined) return [];
+  const out = new Set<string>();
+  for (const o of probed.ops) {
+    if ((o as { marker?: string }).marker !== "ensures") continue;
+    const ty = o.aggregateType;
+    if (typeof ty === "string" && ty.length > 0) out.add(ty);
+  }
+  return [...out].sort();
+}
+
 /** The `status` of a `subjects` setEntry leaf (`writeTuple`/`removeTuple` lowers a JSON `{status, …}` leaf).
  *  `"active"` = a POSITIVE grant; `"revoked"` = a REVOKE. `undefined` ⇒ not a parseable subject leaf. */
 function subjectLeafStatus(op: FieldOp): string | undefined {

package/src/compile_package_main.ts

@@ -212,6 +212,18 @@ interface PackageConfig {
    * `docs/usd_layered_composition.md`).
    */
   readonly layered?: boolean;
+  /**
+   * THE COMPACT PACKAGE ERA (opt-in; also `--compact` / NOMOS_COMPACT=1). ONE batched,
+   * NAMED domainHash move that shrinks the package ~4x (guestbook 1.48MB → ~0.35MB):
+   *   • minified engine lump (esbuild minify — string literals, and so refusal codes, unchanged);
+   *   • zod locales stripped to `en` only (the locale barrel is 35% of every lump and is
+   *     namespace-re-exported so tree-shaking can't drop it; `en` keeps error messages
+   *     byte-identical to today's default);
+   *   • base64 blob fields (`*B64`, 1.33x text) instead of hex (2x).
+   * REQUIRES the whole consuming stack (cloud kernel + clients) at ≥ the release that shipped
+   * the decode arms. Default stays off until a future major; hex packages parse forever.
+   */
+  readonly compact?: boolean;
 }
 
 function fail(msg: string): never {
@@ -608,6 +620,7 @@ function emitDart(
 async function main(): Promise<void> {
   const argv = process.argv.slice(2);
   const layeredFlag = argv.includes("--layered");
+  const compactFlag = argv.includes("--compact") || process.env["NOMOS_COMPACT"] === "1";
   // §"Shipped (1–4)" follow-up: `githolon compile --analyze` (or NOMOS_ANALYZE=1) runs
   // `dart analyze` on the generated Dart package after emission and fails the compile on red.
   const analyzeFlag = argv.includes("--analyze") || process.env.NOMOS_ANALYZE === "1";
@@ -1346,12 +1359,44 @@ async function main(): Promise<void> {
   // JS shim with the platform-native binary, which only an exec can run.
   const esbuildBin = path.join(path.dirname(esbuildPkgJson), esbuildBinRel ?? "bin/esbuild");
 
-  const javascript =
-    execFileSync(
+  const compact = compactFlag || cfg.compact === true;
+  let javascript: string;
+  if (compact) {
+    // COMPACT LUMP (see PackageConfig.compact): the programmatic esbuild API (same pinned
+    // package as the binary) so a resolve-plugin can stub zod's locale barrel to en-only —
+    // the CLI binary has no plugin surface. Same bundle options + minify; deterministic
+    // (pinned esbuild version, deterministic minifier).
+    const esbuildMod = (await import(pathToFileURL(path.join(path.dirname(esbuildPkgJson), "lib", "main.js")).href)) as typeof import("esbuild");
+    const localeStripToEn = {
+      name: "nomos-zod-locales-en-only",
+      setup(build: import("esbuild").PluginBuild) {
+        build.onResolve({ filter: /locales\/index\.js$/ }, (args) => {
+          const resolved = path.resolve(args.resolveDir, args.path);
+          if (!/[\/\\]zod[\/\\]/.test(resolved)) return null; // only zod's own barrel
+          return { path: resolved, namespace: "nomos-zod-locales-en" };
+        });
+        build.onLoad({ filter: /.*/, namespace: "nomos-zod-locales-en" }, (args) => ({
+          // en ONLY: the default error map — messages stay byte-identical to today's default,
+          // so typed refusal payloads (which carry codes + en text) replay unchanged.
+          contents: 'export { default as en } from "./en.js";',
+          resolveDir: path.dirname(args.path),
+          loader: "js" as const,
+        }));
+      },
+    };
+    const built = await esbuildMod.build({
+      entryPoints: [entryPath], bundle: true, format: "iife", target: "es2020",
+      platform: "neutral", charset: "utf8", minify: true, write: false,
+      absWorkingDir: cfgDir, plugins: [localeStripToEn], logLevel: "silent",
+    });
+    javascript = built.outputFiles![0]!.text.trimEnd() + "\n";
+  } else {
+    javascript = execFileSync(
       esbuildBin,
       [entryPath, "--bundle", "--format=iife", "--target=es2020", "--platform=neutral", "--charset=utf8"],
       { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], cwd: cfgDir, maxBuffer: 256 * 1024 * 1024 },
     ).trimEnd() + "\n";
+  }
   if (!/globalThis\.plan\s*=/.test(javascript) && !/globalThis\["plan"\]\s*=/.test(javascript)) {
     fail(`bundled engine entry does not assign globalThis.plan — refusing to package`);
   }
@@ -1462,7 +1507,7 @@ async function main(): Promise<void> {
 
   // ── 2. USD IR + the package envelope ──
   const usdJson = emitUsdJsonForModules(domainModules);
-  const text = packageUsda(usdJson, javascript);
+  const text = packageUsda(usdJson, javascript, { compact });
   const pkgPath = path.join(outDir, `${cfg.name}.package.usda`);
   writeFileSync(pkgPath, text, "utf8");
   const domainHash = sha256HexUtf8(text);
@@ -1732,6 +1777,14 @@ async function main(): Promise<void> {
       domainModules.reduce((n, m) => n + (pick(m)?.length ?? 0), 0);
     console.log(`  reads      ${sum((m) => m.queries)} quer(y/ies), ${sum((m) => m.counts)} count(s), ${sum((m) => m.sums)} sum(s) — declared (routed via the openapi)`);
   }
+  // SECONDARY-CREATE AUTO-DECLARE (secondary_ensure.ts): surface every type the compiler sanctioned
+  // from a plan's deterministic secondary `ensure(...)` — the id-mint-gate DX made visible (the author
+  // wrote `ensure(B, …)`; the compiler declared `Ensure → B` so the deterministic id admits).
+  for (const m of domainModules) {
+    for (const ty of m.autoDeclaredEnsures ?? []) {
+      console.log(`  ensure     auto-declared Ensure→${ty} in '${m.domain ?? m.name}' from a plan's secondary ensure(...) (id-mint gate opened)`);
+    }
+  }
   console.log(`  identity   ${Object.keys(identity.manifests).length} domain(s) (carried in the package IR + nomos.stable-ids.json; no sidecar files)${identity.excluded.length ? ` — ${identity.excluded.length} EXCLUDED (palette gap)` : ""}`);
   for (const [dom, h] of Object.entries(identity.hashes)) console.log(`             ${dom.padEnd(20)} ${h}`);
   for (const ex of identity.excluded) console.log(`             EXCLUDED ${ex.domain}: ${ex.reason}`);

package/src/fields.ts

@@ -404,6 +404,18 @@ export const t = {
   position(): Field<string, "position"> {
     return makeField<string, "position">("position", z.string(), LastPosition);
   },
+  /**
+   * An ARRAY of a value object (or any zod) as a VALUE-OBJECT-SHAPE / directive-PAYLOAD
+   * element — the ergonomic sugar for `z.array(SomeVo.zod)`. Accepts a VO handle
+   * (`t.array(DrawingGeoControlPoint)`), a Field, or a raw zod, and returns the branded
+   * `z.array(...)` so the nested VO's descriptor tree threads (vo_first_class.md slice 1).
+   * NOTE: this returns a ZOD SCHEMA — a shape/payload element — NOT a `t.*` aggregate field
+   * (an array of VOs is stored as one wholesale-replace json leaf; place it via a value object).
+   */
+  array(inner: { readonly zod: z.ZodTypeAny } | z.ZodTypeAny): z.ZodArray<z.ZodTypeAny> {
+    const el = (inner as { zod?: z.ZodTypeAny }).zod ?? (inner as z.ZodTypeAny);
+    return z.array(el);
+  },
   /** Enum via `as const` literal union — value typos squeal at compile time. */
   enum<const E extends readonly [string, ...string[]]>(values: E): Field<E[number], "enum"> {
     return makeField<E[number], "enum">(

package/src/secondary_ensure.ts

@@ -0,0 +1,86 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded
+// QuickJS engine}.  If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * SECONDARY-CREATE AUTO-DECLARE (the co2-dev id-mint-gate DX).
+ *
+ * A directive carries ONE referential marker for its PRIMARY aggregate (`.creates(A)` /
+ * `.ensures(A)` / …). But a plan may ALSO introduce a SECOND aggregate at a caller-chosen
+ * DETERMINISTIC id — `ensure(B, "b:singleton")` — of a type the directive does NOT declare
+ * `.ensures()` for. The kernel's id-mint gate admits an Ensure-introduced typed id ONLY through
+ * the sanctioned declared-ensures lane: the CERTIFIED manifest must carry a directive whose marker
+ * is `Ensure` targeting that type (exactly how `birth_meter_ensure.ts` sanctions `NomosBirthRecord`).
+ * With no such declaration the deterministic id is REFUSED ("[id-mint gate]") — correct BY DESIGN
+ * (an unsanctioned dev-chosen id can't be forged) but an opaque footgun for the author.
+ *
+ * This module closes the footgun WITHOUT weakening the gate: `composeDomainModule` PLAN-PROBES each
+ * directive (the same probe machinery `codegen_proof.ts` uses), discovers the secondary types its
+ * plan ensures, and — for any type NO directive in the domain already declares `.ensures()` for —
+ * injects a NO-OP sanctioning `.ensures(Type)` directive (a {@link sanctioningEnsureDirective},
+ * modelled on `nomosBirthRecordEnsure`). The manifest/USD then carries the `Ensure → Type`
+ * declaration the id-mint gate reads, so the deterministic id is admitted. The synthesized directive
+ * is DELIBERATELY USELESS TO DISPATCH (its plan writes nothing); its only load-bearing property is
+ * its manifest presence.
+ *
+ * ERA-SAFE: a domain whose plans do NO secondary ensures is returned untouched (byte-identical). A
+ * domain that DOES gains the sanction — and such a domain could not have deployed before this without
+ * the author hand-writing the declaration, so no already-shippable manifest hash silently drifts.
+ *
+ * BEST-EFFORT (graceful degradation): the probe runs each plan ONCE under a synthesized payload. A
+ * plan that ensures CONDITIONALLY on a payload shape the synthesis didn't hit (or that can't be
+ * probed) simply gets no auto-sanction — and the runtime id-mint gate refuses the ensure exactly as
+ * before (no regression, no forged-id hole). Auto-declare only ever ADDS a sanction the author's own
+ * plan already proves it intends; it never blocks a valid deploy.
+ */
+import { z } from "zod";
+import { directive } from "./directive.js";
+import type { Directive } from "./directive.js";
+import type { AggregateHandle } from "./aggregate.js";
+import { probeEnsuredTypes } from "./codegen_proof.js";
+
+/** The synthesized directive id sanctioning `Ensure → <aggId>`. Derived purely from the aggregate id
+ *  so recompiles are stable; non-id chars are flattened so the id stays route-safe. */
+export function sanctioningEnsureDirectiveId(aggId: string): string {
+  return `nomosEnsure_${aggId.replace(/[^A-Za-z0-9_]/g, "_")}`;
+}
+
+/**
+ * A no-op sanctioning `.ensures(agg)` directive — the twin of `nomosBirthRecordEnsure`, parameterized
+ * by an arbitrary aggregate. Its plan emits ZERO ops (it cannot forge a row); its ONLY purpose is the
+ * `Ensure → agg` marker the certified manifest carries so the id-mint gate opens the declared-ensures
+ * lane for a plan's secondary deterministic `ensure(agg, …)`.
+ */
+export function sanctioningEnsureDirective(agg: AggregateHandle): Directive<unknown> {
+  return directive(sanctioningEnsureDirectiveId(agg.id))
+    .ensures(agg)
+    .payload(z.object({}).strict())
+    .plan(() => []) as unknown as Directive<unknown>;
+}
+
+/**
+ * Discover the secondary-ensured types a domain's directives introduce that NO directive already
+ * declares `.ensures()` for — the SORTED gap set the compose seam must sanction. Pure discovery:
+ * probes every directive, unions the ensured types, subtracts the domain-wide DECLARED-ensures set.
+ */
+export function discoverUnsanctionedEnsures(
+  directives: readonly Directive<unknown>[],
+  domain: string,
+): string[] {
+  // Types some directive already DECLARES as its primary `.ensures(...)` target — already sanctioned.
+  const declared = new Set<string>();
+  for (const d of directives) {
+    if ((d as { marker?: string }).marker === "ensures") declared.add(d.aggregateId);
+  }
+  const gap = new Set<string>();
+  for (const d of directives) {
+    // A `.births()` directive's genesis-recipe plan runs under a different probe surface; its meter
+    // record is sanctioned by `birth_meter_ensure.ts`, so leave it to that lane (avoid double probing).
+    if ((d as { birthsChild?: boolean }).birthsChild === true) continue;
+    for (const ty of probeEnsuredTypes(d, `${domain}/${d.id}`)) {
+      if (!declared.has(ty)) gap.add(ty);
+    }
+  }
+  return [...gap].sort();
+}

package/src/value_object.ts

@@ -52,6 +52,7 @@
  */
 import { z } from "zod";
 
+import type { Driver } from "./drivers.js";
 import {
   valueObjectField,
   type Field,
@@ -129,6 +130,17 @@ export interface ValueObject<T = unknown> {
    * whole), `.optional()`, `.encrypted()` (under the existing `requires(cap)` rules).
    */
   field(): Field<T, "json">;
+  /**
+   * SUGAR for `.field().merge(driver)` — lower this VO DIRECTLY to an aggregate field with
+   * the chosen merge driver: `location: SiteLocation.merge(Lww).optional()`. A VO field is
+   * ONE Lww-class json leaf replaced WHOLESALE, so only the Lww-class family
+   * (`Lww` / `LwwCausal` / `LwwBy`) is accepted — any other driver throws (field-level merge
+   * composition of a VO's subfields is a later slice; model those as aggregate fields / a
+   * `t.map(...)`). The returned `Field` chains the usual modifiers (`.optional()`,
+   * `.encrypted()`, …), so `SiteLocation.merge(Lww).optional()` == `SiteLocation.field()
+   * .merge(Lww).optional()` byte-for-byte.
+   */
+  merge(driver: Driver): Field<T, "json">;
   /** Phantom to keep T load-bearing for inference. */
   readonly _t?: T;
 }
@@ -255,12 +267,48 @@ export function idOfMetaOf(zt: z.ZodTypeAny): string | undefined {
   return undefined;
 }
 
+/** Thread a nested VO's own descriptor + transitive dependencies into `deps` (divergent
+ *  same-name shapes throw — one name, one shape), then return its ref field descriptor. This
+ *  is what makes `z.array(SomeVo.zod)` / a raw `SomeVo.zod` entry plug-and-play: the VO brand
+ *  rides the `.zod`, so the descriptor TREE is threaded rather than lost (vo_first_class.md
+ *  slice 0). */
+function takeVoField(
+  meta: ValueObjectFieldMeta,
+  deps: Map<string, ValueObjectDescriptor>,
+): ValueObjectFieldDescriptor {
+  for (const d of [meta.descriptor, ...meta.dependencies]) {
+    const existing = deps.get(d.name);
+    if (existing !== undefined && JSON.stringify(existing) !== JSON.stringify(d)) {
+      throw new Error(
+        `valueObject: two DIVERGENT value objects share the name '${d.name}' — one name, one shape. ` +
+          `Rename one of them (the descriptor is identity-bearing).`,
+      );
+    }
+    deps.set(d.name, d);
+  }
+  return meta.geometry !== undefined
+    ? { type: "geometry", ref: meta.name, geometry: meta.geometry }
+    : { type: "object", ref: meta.name };
+}
+
 /**
  * Describe one CONSTRAINED zod schema as a descriptor field (NO FALLBACK — an
  * out-of-set shape throws with the field's path so the author fixes the declaration,
- * never ships an undescribed structure).
+ * never ships an undescribed structure). `deps` collects every nested VO the schema
+ * references BY BRAND (`z.array(SomeVo.zod)`, a raw `SomeVo.zod`) so its descriptor rides
+ * alongside — the caller unions it into the VO's `dependencies`.
  */
-function describeZod(voName: string, path: string, schema: z.ZodTypeAny): ValueObjectFieldDescriptor {
+function describeZod(
+  voName: string,
+  path: string,
+  schema: z.ZodTypeAny,
+  deps: Map<string, ValueObjectDescriptor>,
+): ValueObjectFieldDescriptor {
+  // A VO referenced through its RAW zod (its own brand, no optional wrapper) — emit the
+  // ref + thread its descriptor tree. (Optional wrappers are handled by the switch below,
+  // which recurses to the branded inner schema.)
+  const ownBrand = (schema as unknown as Record<symbol, unknown>)[NOMOS_VO_BRAND];
+  if (ownBrand !== undefined) return takeVoField(ownBrand as ValueObjectFieldMeta, deps);
   switch (zodKind(schema)) {
     case "string":
       return { type: "string" };
@@ -285,7 +333,7 @@ function describeZod(voName: string, path: string, schema: z.ZodTypeAny): ValueO
       return { type: "literal", value: v };
     }
     case "array": {
-      const items = describeZod(voName, `${path}[]`, zodArrayElement(schema));
+      const items = describeZod(voName, `${path}[]`, zodArrayElement(schema), deps);
       if (items.optional === true) {
         throw new Error(
           `valueObject '${voName}': field '${path}' is an array of optionals — not expressible in the v1 set.`,
@@ -295,7 +343,7 @@ function describeZod(voName: string, path: string, schema: z.ZodTypeAny): ValueO
     }
     case "optional":
     case "default": {
-      const inner = describeZod(voName, path, zodDef(schema).innerType!);
+      const inner = describeZod(voName, path, zodDef(schema).innerType!, deps);
       return { ...inner, optional: true };
     }
     default:
@@ -452,7 +500,29 @@ function makeValueObject<T>(
     field(): Field<T, "json"> {
       return valueObjectField(zodSchema, meta);
     },
+    merge(driver: Driver): Field<T, "json"> {
+      const k = driver.kind;
+      if (k !== "Lww" && k !== "LwwCausal" && k !== "LwwBy") {
+        throw new Error(
+          `valueObject '${name}': .merge(${k}) is not a valid value-object field merge — a VO is ONE ` +
+            `Lww-class json leaf replaced WHOLESALE, so only Lww / LwwCausal / LwwBy apply. Field-level ` +
+            `merge composition of a VO's subfields is a later slice; model independently-merging subfields ` +
+            `as aggregate fields or a t.map(...).`,
+        );
+      }
+      return valueObjectField(zodSchema, meta).merge(driver);
+    },
   };
+  // THE HANDLE IS A FIRST-CLASS ZOD SCHEMA (vo_first_class.md slice 1): delegate zod's
+  // internals so the raw HANDLE composes DIRECTLY where a zod is expected — `z.array(Vo)`,
+  // `z.object({ f: Vo })`, a directive payload — with NO `.zod` peeling. Non-enumerable (never
+  // serialized, domainHash-inert) and stamped with the VO brand so describeZod / voMetaOf resolve
+  // the handle exactly like its `.zod`.
+  const inner = zodSchema as unknown as { _zod?: unknown; _def?: unknown; def?: unknown };
+  Object.defineProperty(vo, "_zod", { get: () => inner._zod, enumerable: false });
+  Object.defineProperty(vo, "_def", { get: () => inner._def, enumerable: false });
+  Object.defineProperty(vo, "def", { get: () => inner.def, enumerable: false });
+  Object.defineProperty(vo, NOMOS_VO_BRAND, { value: meta, enumerable: false });
   return vo;
 }
 
@@ -495,7 +565,7 @@ export function valueObject<const Name extends string, S extends Record<string,
           : { type: "object", ref: entry.name };
       collectDescriptors(entry, deps);
     } else {
-      fields[key] = describeZod(name, key, entry);
+      fields[key] = describeZod(name, key, entry, deps);
       zodShape[key] = entry;
     }
   }
@@ -584,7 +654,7 @@ export function variant<const Name extends string, Arms extends Record<string, U
             : { type: "object", ref: entry.name };
           collectDescriptors(entry, deps);
         } else {
-          fields[fieldKey] = describeZod(name, `${key}.${fieldKey}`, entry);
+          fields[fieldKey] = describeZod(name, `${key}.${fieldKey}`, entry, deps);
           zodShape[fieldKey] = entry;
         }
       }