@githolon/dsl 0.48.1 → 0.50.0

package/src/compile_package_main.ts

@@ -121,6 +121,7 @@ import { generateTsClient, tsClientFactoryName } from "./codegen_ts.js";
 import { generateOpenApiFragment, mergeOpenApiFragments } from "./codegen_openapi.js";
 import { domainInterface, type DomainInterface } from "./shape_compat.js";
 import { generateTsProof, proofLegsIndex } from "./codegen_proof.js";
+import { checkDomainModules, formatFindings, hasRefusal } from "./law_check.js";
 import type { NomosCompat } from "./compat_manifest.js";
 
 const DSL_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -212,6 +213,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 +621,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 +1360,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 +1508,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 +1778,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}`);
@@ -1763,6 +1817,24 @@ async function main(): Promise<void> {
   for (const w of birthWarnings) {
     console.log(`  ⚠ births   ${w}`);
   }
+  // ── THE AUTHOR-TIME GATE (architecture/author_time_gate.md) — the static twins of the kernel
+  //    gate's refusal vocabulary, unified into ONE report. `githolon check` runs the same pass;
+  //    compile runs it implicitly and REFUSES on any refuse-level finding (a statically-provable
+  //    runtime refusal shipped as law). Warns/notes are printed but never block the compile.
+  const checkFindings = checkDomainModules(domainModules);
+  if (checkFindings.length > 0) {
+    console.log(`  check      ${checkFindings.length} finding(s) (githolon check):`);
+    for (const line of formatFindings(checkFindings)) {
+      const mark = line.includes("REFUSE") ? "✗" : line.includes("WARN") ? "⚠" : "•";
+      console.log(`             ${mark} ${line}`);
+    }
+    if (hasRefusal(checkFindings)) {
+      // Emit the artifacts (already written) but REFUSE the compile: a refuse-level finding is a
+      // statically-provable runtime gate refusal — shipping it as law would fail at first dispatch.
+      console.error(`  ✗ check    REFUSED — fix the refuse-level finding(s) above (or run \`githolon check\`)`);
+      process.exitCode = 1;
+    }
+  }
   if (dartOut !== undefined) {
     const supportText =
       dartSupportImport === "vendored" ? "vendored nomos_client support" : "package nomos_client imports";

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/law_check.ts

@@ -0,0 +1,375 @@
+// 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.
+
+/**
+ * THE AUTHOR-TIME GATE — `githolon check` (architecture/author_time_gate.md, slice 1).
+ *
+ * Every DX bug the tenant teams reported was the same disease: the kernel gate refused
+ * something at RUNTIME that was STATICALLY VISIBLE at compile. The cure is to pre-fire
+ * the refusal at author time, with the FIX inside the message. This module is the
+ * unified surface: it runs the STATIC TWINS of the gate's refusal vocabulary over the
+ * composed domain modules and returns typed {@link Finding}s.
+ *
+ * Three verdict levels:
+ *   - **refuse** — the fault is PAYLOAD-INDEPENDENT (return shape, schema/driver mismatch),
+ *     so the runtime gate WILL refuse it. `githolon check` exits non-zero; `compile` refuses.
+ *   - **warn** — the probe SAW something suspicious but can't PROVE it (a plan that threw on
+ *     the one synthesized sample — a conditional/payload-dependent path). Names the payload.
+ *   - **note** — an auto-repair was applied (e.g. the auto-declared secondary ensure).
+ *
+ * FALSE-POSITIVE DISCIPLINE (the hard rule, from the design doc): the probe runs ONE
+ * synthesized payload — a conditional branch it doesn't take proves nothing. A twin may
+ * REFUSE only when the fault is payload-independent; everything else is a WARN naming the
+ * payload that exhibited it. The runtime gate remains the arbiter; `check` never claims
+ * completeness, only that what it flags is real.
+ */
+import type { z } from "zod";
+
+import type { AggregateHandle } from "./aggregate.js";
+import type { Directive } from "./directive.js";
+import type { DomainModule } from "./codegen_dart.js";
+import type { Field } from "./fields.js";
+import type { FieldOp, PlannedOp } from "./ops.js";
+import { deterministicPorts } from "./ctx.js";
+import { synthesizePayload, withBirthProbeGlobals, type SynthesizedPayload } from "./codegen_proof.js";
+import { __drainAuthoring, __resetAuthoring } from "./authoring.js";
+import { __drainReads, __resetReads } from "./read.js";
+import { __drainBirths, __resetBirths } from "./births.js";
+import { proofLegsIndex } from "./codegen_proof.js";
+import { autoStampFields, zodKind, zodObjectShape } from "./codegen_ts.js";
+
+/** One author-time finding — the gate refusal pre-fired at compile, or a courtesy note. */
+export interface Finding {
+  /** The domain key the directive lives in. */
+  readonly domain: string;
+  /** The directive the finding is about (absent for a domain-wide note). */
+  readonly directiveId?: string;
+  /** `refuse` — provably refuses at the gate · `warn` — suspicious, can't prove · `note` — auto-repair. */
+  readonly level: "refuse" | "warn" | "note";
+  /** What is wrong (or, for a note, what was auto-repaired). */
+  readonly what: string;
+  /** How to fix it (or, for a note, how the repair keeps the law valid). */
+  readonly fix: string;
+}
+
+/** Payload field names the FRAMEWORK consumes off the intent (never the plan) — excluded from the
+ *  unread-payload-field warn so a birth/timestamp convention field is never falsely flagged as dead.
+ *  Sources: `autoStampFields` (the `…At` clock convention) + `birthMeterSubject`/`birthMeterBornAt`. */
+const FRAMEWORK_CONSUMED_PAYLOAD_FIELDS: ReadonlySet<string> = new Set([
+  "principal",
+  "owner",
+  "ownerSubject",
+  "bornAt",
+  "requestedAt",
+]);
+
+/** The outcome of running one directive's plan on its synthesized sample under the probe globals. */
+interface ProbeResult {
+  readonly synth: SynthesizedPayload;
+  /** The stamped-and-filled sample the plan was run with (what a WARN names). */
+  readonly probePayload: Record<string, unknown>;
+  /** The plan's RETURN value (whatever it was — checked for array-ness by the return twin). */
+  readonly returned: unknown;
+  /** True when the plan THREW on the sample (payload-dependent — everything degrades to a WARN). */
+  readonly threw: boolean;
+  readonly error?: unknown;
+  /** The FIELD ops the plan emitted (authoring sink + returned ops), when it didn't throw. */
+  readonly ops: FieldOp[];
+  /** The top-level payload keys the plan actually READ (via the tracking proxy). */
+  readonly readFields: ReadonlySet<string>;
+}
+
+/** Run a directive's plan ONCE on a tracking-proxy sample under the birth-probe globals, capturing the
+ *  return value, whether it threw, the emitted field ops, and which payload fields it read. `undefined`
+ *  ⇒ the payload is unsynthesizable (an exotic zod shape) — the directive can't be probed at all. */
+function probeDirective(dir: Directive<unknown>, where: string): ProbeResult | undefined {
+  let synth: SynthesizedPayload;
+  try {
+    synth = synthesizePayload(dir.payloadSchema as z.ZodTypeAny, where);
+  } catch {
+    return undefined;
+  }
+  // Build the sample: required non-stamped fields from the synth, plus the auto-stamped `…At` fields
+  // filled with a fixed ISO stamp (the client stamps them at dispatch; the plan may read them here).
+  const probePayload: Record<string, unknown> = { ...synth.value };
+  for (const f of synth.autoStamped) probePayload[f] = "2026-01-01T00:00:00Z";
+
+  const shapeKeys = new Set(Object.keys(safeShape(dir.payloadSchema as z.ZodTypeAny)));
+  const readFields = new Set<string>();
+  const tracked = new Proxy(probePayload, {
+    get(target, prop, recv) {
+      if (typeof prop === "string" && shapeKeys.has(prop)) readFields.add(prop);
+      return Reflect.get(target, prop, recv);
+    },
+  });
+
+  let returned: unknown;
+  let threw = false;
+  let error: unknown;
+  let ops: FieldOp[] = [];
+  withBirthProbeGlobals(() => {
+    __resetAuthoring();
+    __resetReads();
+    __resetBirths();
+    try {
+      returned = dir.plan(tracked as never, deterministicPorts({ physical: 1, replica: 1, principal: "principal:probe" }));
+      const drained: PlannedOp[] = [...__drainAuthoring(), ...(Array.isArray(returned) ? returned : [])];
+      ops = drained.filter((o): o is FieldOp => (o as { kind?: string }).kind !== "strike");
+    } catch (e) {
+      threw = true;
+      error = e;
+    } finally {
+      // Drain the sinks on every path so a throwing probe never leaks state into the next.
+      try { __drainAuthoring(); } catch { /* drained */ }
+      try { __drainReads(); } catch { /* drained */ }
+      try { __drainBirths(); } catch { /* drained */ }
+    }
+  });
+  return { synth, probePayload, returned, threw, error, ops, readFields };
+}
+
+/** `zodObjectShape` with a swallow — a non-object payload yields `{}` (the return twin handles it). */
+function safeShape(schema: z.ZodTypeAny): Record<string, z.ZodTypeAny> {
+  try {
+    if (zodKind(schema) !== "object") return {};
+    return zodObjectShape(schema);
+  } catch {
+    return {};
+  }
+}
+
+/** The REQUIRED top-level payload fields (optional/defaulted omitted — an unread optional proves nothing). */
+function requiredPayloadFields(schema: z.ZodTypeAny): string[] {
+  const out: string[] = [];
+  for (const [name, f] of Object.entries(safeShape(schema))) {
+    const k = zodKind(f);
+    if (k === "optional" || k === "default") continue;
+    out.push(name);
+  }
+  return out;
+}
+
+/** A short, safe render of the sample payload a WARN names (bounded so a huge payload doesn't flood). */
+function samplePayloadText(payload: Record<string, unknown>): string {
+  let s: string;
+  try {
+    s = JSON.stringify(payload);
+  } catch {
+    s = "<unserializable>";
+  }
+  return s.length > 200 ? `${s.slice(0, 197)}…` : s;
+}
+
+// ── TWIN A — the UNIVERSAL plan-return probe ──────────────────────────────────────
+// The engine assembles a plan's output with `[...returned]` (wire_encode.ts). A plan whose
+// `plan` returns a NON-ITERABLE (undefined — a forgotten `return`; a builder — a forgotten
+// `return []` after `create(...).set(...)`; a plain object) throws "not iterable" at the FIRST
+// dispatch on every peer. This is payload-INDEPENDENT (the return TYPE is fixed) ⇒ REFUSE.
+// A plan that THREW on the sample is payload-DEPENDENT (can't prove) ⇒ WARN naming the sample.
+function planReturnFindings(domain: string, dir: Directive<unknown>, probe: ProbeResult): Finding[] {
+  if (probe.threw) {
+    return [
+      {
+        domain,
+        directiveId: dir.id,
+        level: "warn",
+        what: `the plan THREW on the synthesized sample (${(probe.error as Error)?.message ?? String(probe.error)}) — can't prove the return shape`,
+        fix: `run it on the sample ${samplePayloadText(probe.probePayload)} — if the throw is real, the runtime gate refuses; if it's a payload-dependent branch, ignore`,
+      },
+    ];
+  }
+  if (!Array.isArray(probe.returned)) {
+    const got =
+      probe.returned === undefined
+        ? "undefined (a missing `return`)"
+        : typeof probe.returned === "object" && probe.returned !== null
+          ? "an object/builder (a forgotten `return []`)"
+          : `a ${typeof probe.returned}`;
+    return [
+      {
+        domain,
+        directiveId: dir.id,
+        level: "refuse",
+        what: `the plan returns ${got}, not an array of ops — the engine assembles plan output with [...returned] and would throw "not iterable" at the first dispatch`,
+        fix: `return an array of ops — the fluent surface (create/set/add) records ops as a side-effect, so end the plan with \`return [];\` (or return the typed ops directly)`,
+      },
+    ];
+  }
+  return [];
+}
+
+// ── TWIN B — the UNREAD-PAYLOAD-FIELD warn ────────────────────────────────────────
+// A REQUIRED payload field the plan never reads on the sample path is usually a bug (dead field
+// or missing logic). WARN only (a conditional read the sample didn't reach proves nothing), and
+// only for a plan that ran cleanly (a throwing plan read nothing — twin A already flagged it).
+// Framework-consumed convention fields (auto-stamped `…At`, birth subject/time) are excluded.
+function unreadPayloadFindings(domain: string, dir: Directive<unknown>, probe: ProbeResult): Finding[] {
+  if (probe.threw) return [];
+  const stamped = new Set(autoStampFields(dir.payloadSchema as z.ZodTypeAny));
+  // The GATE reads some payload fields the PLAN never does: `.requires(rel, { objectFrom })` derives
+  // the gate object from a named payload id field (per-record authz). Excluding it keeps a real
+  // gate-consumed field from being flagged dead (the todo-pro `shareTodo.listId` case).
+  const gateConsumed = new Set<string>();
+  const objectFromField = (dir as { requiresRelationGate?: { objectFrom?: { idField?: string } } })
+    .requiresRelationGate?.objectFrom?.idField;
+  if (typeof objectFromField === "string") gateConsumed.add(objectFromField);
+  const out: Finding[] = [];
+  for (const f of requiredPayloadFields(dir.payloadSchema as z.ZodTypeAny)) {
+    if (probe.readFields.has(f)) continue;
+    if (stamped.has(f)) continue; // the client stamps it; the plan needn't read it
+    if (FRAMEWORK_CONSUMED_PAYLOAD_FIELDS.has(f)) continue; // the meter reads it off the intent
+    if (gateConsumed.has(f)) continue; // the authz gate derives its object from it
+    out.push({
+      domain,
+      directiveId: dir.id,
+      level: "warn",
+      what: `payload field '${f}' is never read by the plan (on the sampled path) — dead field or missing logic?`,
+      fix: `read it in the plan (e.g. \`.set("${f}", p.${f})\`), make it \`.optional()\` if it is genuinely optional, or drop it from the payload`,
+    });
+  }
+  return out;
+}
+
+// ── TWIN C — the OP-VS-SCHEMA / driver twin ───────────────────────────────────────
+// Walk the probed ops against the target aggregate's schema. An op on a field the aggregate
+// does NOT declare is a hard mismatch (REFUSE, naming the real fields). A `set` on an additive
+// set (AddWins/RemoveWins) OVERWRITES the CRDT instead of merging — REFUSE naming addToSet/
+// removeFromSet. A `setEntry` on a non-map field is likewise a driver mismatch. Conservative:
+// only ops targeting an aggregate THIS domain declares are judged (a foreign/framework tuple is
+// left to the runtime gate); every refusal here is a combination the engine provably rejects.
+function opVsSchemaFindings(
+  domain: string,
+  dir: Directive<unknown>,
+  probe: ProbeResult,
+  aggById: ReadonlyMap<string, AggregateHandle>,
+): Finding[] {
+  if (probe.threw) return [];
+  const out: Finding[] = [];
+  const seen = new Set<string>(); // dedupe identical (agg, field, kind) findings
+  for (const op of probe.ops) {
+    const aggId = op.aggregateType;
+    if (typeof aggId !== "string") continue;
+    const agg = aggById.get(aggId);
+    if (agg === undefined) continue; // foreign / framework aggregate — the runtime gate arbitrates
+    const key = `${aggId}.${op.field}.${op.kind}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const field = agg.fields[op.field] as Field | undefined;
+    if (field === undefined) {
+      const real = Object.keys(agg.fields).sort();
+      out.push({
+        domain,
+        directiveId: dir.id,
+        level: "refuse",
+        what: `the plan writes '${op.field}' on '${aggId}', which is not a declared field of that aggregate`,
+        fix: `write one of ${aggId}'s fields — ${real.length ? real.join(", ") : "(none)"} — or add '${op.field}' to the aggregate`,
+      });
+      continue;
+    }
+    const driverKind = (field.driver as { kind?: string }).kind;
+    if (op.kind === "set" && driverKind === "AddWins") {
+      out.push({
+        domain,
+        directiveId: dir.id,
+        level: "refuse",
+        what: `the plan \`set\`s '${op.field}' on '${aggId}', an AddWins set — set() OVERWRITES the merge (concurrent adds would be lost)`,
+        fix: `use \`addToSet(instance(${aggId}, id), "${op.field}", values)\` — the additive write that commutes`,
+      });
+    } else if (op.kind === "set" && driverKind === "RemoveWins") {
+      out.push({
+        domain,
+        directiveId: dir.id,
+        level: "refuse",
+        what: `the plan \`set\`s '${op.field}' on '${aggId}', a RemoveWins set — set() OVERWRITES the 2P-set CRDT`,
+        fix: `use \`addToSet(...)\` / \`removeFromSet(instance(${aggId}, id), "${op.field}", values)\` — the additive/tombstone writes`,
+      });
+    } else if (op.kind === "setEntry" && field.kind !== "map") {
+      out.push({
+        domain,
+        directiveId: dir.id,
+        level: "refuse",
+        what: `the plan \`setEntry\`s '${op.field}' on '${aggId}', a '${field.kind}' field — setEntry targets a map (MapOf) field only`,
+        fix: `write a t.map(...) field with setEntry, or use \`set(...)\` for the '${field.kind}' field '${op.field}'`,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * Run every author-time twin over the composed domain modules and return the findings, ordered
+ * refuse → warn → note (stable within a level, by domain/directive appearance). This is the ONE
+ * entry `githolon check` and `compile`'s summary both call.
+ */
+export function checkDomainModules(modules: readonly DomainModule[]): Finding[] {
+  const findings: Finding[] = [];
+
+  for (const mod of modules) {
+    const domain = mod.domain ?? mod.name;
+    const aggById = new Map<string, AggregateHandle>();
+    for (const a of mod.aggregates) aggById.set(a.id, a);
+
+    // The NOTE twin (unify): the auto-declared secondary ensures composeDomainModule injected.
+    for (const ty of mod.autoDeclaredEnsures ?? []) {
+      findings.push({
+        domain,
+        level: "note",
+        what: `auto-declared Ensure→${ty} from a plan's secondary ensure(...) — the id-mint gate was opened for it`,
+        fix: `no action needed; to make it explicit, export a directive that \`.ensures(${ty})\``,
+      });
+    }
+
+    for (const dir of mod.directives as Directive<unknown>[]) {
+      const where = `${domain}/${dir.id}`;
+      const probe = probeDirective(dir, where);
+      if (probe === undefined) continue; // unsynthesizable payload — proven by hand, not by check
+      findings.push(...planReturnFindings(domain, dir, probe));
+      findings.push(...unreadPayloadFindings(domain, dir, probe));
+      findings.push(...opVsSchemaFindings(domain, dir, probe, aggById));
+    }
+  }
+
+  // The BIRTH-RECIPE twin (unify): fold the scattered `.births()` recipe diagnostics into the
+  // one report as WARNs (a discoverable-but-suspect recipe — missing seed, uncomposed child domain).
+  try {
+    const idx = proofLegsIndex(modules as DomainModule[]);
+    if (idx !== null) {
+      for (const [domain, legs] of Object.entries(idx.domains)) {
+        for (const diag of legs.birthDiagnostics ?? []) {
+          findings.push({
+            domain,
+            level: "warn",
+            what: `birth recipe: ${diag}`,
+            fix: `see architecture/g3_kernel_fulfils_birth.md / the births DX — the recipe must install both framework + child law and seed genesis`,
+          });
+        }
+      }
+    }
+  } catch {
+    /* birth discovery is best-effort — its absence never blocks the check */
+  }
+
+  const rank = { refuse: 0, warn: 1, note: 2 } as const;
+  return findings
+    .map((f, i) => ({ f, i }))
+    .sort((a, b) => rank[a.f.level] - rank[b.f.level] || a.i - b.i)
+    .map(({ f }) => f);
+}
+
+/** Does the finding set carry a hard refusal (⇒ `githolon check` exits non-zero, `compile` refuses)? */
+export function hasRefusal(findings: readonly Finding[]): boolean {
+  return findings.some((f) => f.level === "refuse");
+}
+
+/** Format one finding as the unified report line: `<domain>/<directive>: <LEVEL> — <what> — fix: <fix>`. */
+export function formatFinding(f: Finding): string {
+  const subject = f.directiveId !== undefined ? `${f.domain}/${f.directiveId}` : f.domain;
+  return `${subject}: ${f.level.toUpperCase()} — ${f.what} — fix: ${f.fix}`;
+}
+
+/** The full `check` report body (one line per finding), ordered refuse → warn → note. */
+export function formatFindings(findings: readonly Finding[]): string[] {
+  return findings.map(formatFinding);
+}

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();
+}