@githolon/dsl 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.4.0",
+  "version": "0.5.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",
@@ -17,6 +17,7 @@
   "exports": {
     ".": "./src/index.ts",
     "./manifest": "./src/manifest.ts",
+    "./stable-ids": "./src/stable_ids.ts",
     "./compose": "./src/compose.ts",
     "./usd": "./src/usd.ts",
     "./usd-layers": "./src/usd_layers.ts",

package/src/build_package.ts

@@ -54,6 +54,7 @@ import type { WorkspaceTypeDecl } from "./workspace_type.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import { domainHash, emitManifestBytes } from "./manifest.js";
 import { emitUsd } from "./usd.js";
+import { expandCapabilityExports } from "./capability_exports.js";
 
 // ─────────────────────────────────────────────────────────────────────────────────
 // composeDomainModule — the named-keys `module(...)`
@@ -134,6 +135,9 @@ export interface DomainModuleSpec {
 export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
   let merged: Mod = {};
   for (const m of spec.modules) merged = { ...merged, ...m };
+  // `capability()` bundles expand into discoverable entries (the package plane's
+  // merge point) — the quartet validation below then passes without re-exports.
+  merged = expandCapabilityExports(merged);
 
   const byId = new Map<string, AggregateHandle>();
   for (const a of [...aggregatesOf(merged), ...(spec.extraAggregates ?? [])]) byId.set(a.id, a);

package/src/capability_exports.ts

@@ -0,0 +1,55 @@
+// 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} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * capability_exports.ts — the ONE-EXPORT expansion for `capability()` bundles
+ * (`architecture/capability_marketplace.md` §4, ruling M2 — "the domain dev
+ * declares ONE thing").
+ *
+ * Every module-exports walk in the house scans TOP-LEVEL exports by shape
+ * (aggregates, directives, queries…). A `capability()` declaration is one
+ * export holding a task aggregate + the five lifecycle directives as
+ * properties — invisible to those walks. This helper, applied at each plane's
+ * merge point (the engine lump's `mergeModules`, the package composer's merge,
+ * the compile CLI's merge), ADDS the bundle's pieces to the exports bag under
+ * synthetic names (`<export>$aggregate`, `<export>$order`, …) so every
+ * existing shape-walk discovers them with ZERO new walk semantics. The
+ * original bundle export stays (config-named lanes still resolve it); the
+ * walks ignore its unmatched shape exactly as before.
+ *
+ * ZERO imports on purpose: this file is bundled into the sealed engine lump
+ * (engine_entry.ts) — it must drag nothing with it.
+ */
+
+/** Duck-type guard: a `capability()` return (the tag is set by the factory). */
+export function isCapabilityDecl(v: unknown): v is Record<string, unknown> {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    (v as { __isCapabilityDecl?: boolean }).__isCapabilityDecl === true
+  );
+}
+
+const PIECES = ["aggregate", "order", "complete", "fail", "block", "deadLetter", "tasks"] as const;
+
+/**
+ * Expand every `capability()` bundle in an exports bag into discoverable
+ * top-level entries. Pure; returns the SAME object when nothing expands (the
+ * common case stays allocation-free and referentially stable).
+ */
+export function expandCapabilityExports<M extends Record<string, unknown>>(mod: M): M {
+  let out: Record<string, unknown> | null = null;
+  for (const [k, v] of Object.entries(mod)) {
+    if (!isCapabilityDecl(v)) continue;
+    out ??= { ...mod };
+    for (const piece of PIECES) {
+      const member = (v as Record<string, unknown>)[piece];
+      if (member !== undefined) out[`${k}$${piece}`] = member;
+    }
+  }
+  return (out ?? mod) as M;
+}

package/src/codegen_dart.ts

@@ -2322,6 +2322,15 @@ export interface DomainModule {
   domain?: string;
   aggregates: AggregateHandle[];
   directives: AnyDirective[];
+  /**
+   * STABLE-ID CONTINUITY (#58 — names are labels, identity is minted). When present
+   * (attached by `nomos-compile` from the PRIOR build's identity manifests), the
+   * canonical manifest's `stableIds` block carries these sids/lineages forward instead
+   * of minting at first appearance — a renamed entity keeps its identity. Keyed by
+   * CURRENT names (the compiler resolves renames BEFORE attaching). Absent ⇒ every
+   * sid mints deterministically at first appearance.
+   */
+  stableIdContinuity?: import("./stable_ids_types.js").StableIds;
   /**
    * The domain's NAMED, INDEXED read declarations (read-side closure step 1).
    * ADDITIVE + OPTIONAL: a domain that declares no query omits this entirely and is

package/src/codegen_proof.ts

@@ -41,6 +41,7 @@ import type { Directive } from "./directive.js";
 import type { DomainModule } from "./codegen_dart.js";
 import type { QueryDecl } from "./query.js";
 import { finishCount } from "./count.js";
+import { mintedCreateField } from "./workspace_routing.js";
 import {
   autoStampFields,
   tsClientFactoryName,
@@ -211,10 +212,21 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
   }
   const synth = synthesizePayload(createDir.payloadSchema as z.ZodTypeAny, `${domain}/${createDir.id}`);
 
+  // THE MINTED-ID RULE (the gate's `check_create_ids`): a `.creates` payload field
+  // that IS the target's own id must be KERNEL-MINTED — a hand-written sample id
+  // refuses typed at admission (`NotMinted`). The marker-driven trace names the
+  // field (never name-guessed); the generated proof MINTS it at runtime
+  // (`holon.mint`) instead of synthesizing a sample, so the proof admits
+  // everywhere the law does.
+  const mintField = mintedCreateField(createDir, agg);
+  const baseValue: Record<string, unknown> = { ...synth.value };
+  if (mintField !== undefined) delete baseValue[mintField];
+
   // The first declared query that can READ BACK the create: returns the created
-  // aggregate and every key field has a synthesized payload value to probe with.
+  // aggregate and every key field has a synthesized payload value to probe with
+  // (a query keyed on the MINTED field is skipped — its value exists only at runtime).
   const query = ((mod.queries ?? []) as QueryDecl[]).find(
-    (q) => q.returns === agg.id && q.key.length > 0 && q.key.every((k) => !k.includes(".") && synth.value[k] !== undefined),
+    (q) => q.returns === agg.id && q.key.length > 0 && q.key.every((k) => !k.includes(".") && baseValue[k] !== undefined),
   );
 
   // The first declared count the create moves: counts the created aggregate,
@@ -226,7 +238,7 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
       (c) =>
         c.of === agg.id &&
         (c as { where?: unknown }).where == null &&
-        (c.by == null || synth.value[c.by] !== undefined),
+        (c.by == null || baseValue[c.by] !== undefined),
     );
 
   const concurrency = findConcurrencyLeg(mod.directives as Directive<unknown>[], agg);
@@ -239,10 +251,27 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
       .replace(/^-+|-+$/g, "")
       .slice(0, 24) || "domain";
 
-  const payloadLit = JSON.stringify(synth.value);
-  const queryParams = query ? JSON.stringify(Object.fromEntries(query.key.map((k) => [k, synth.value[k]]))) : "";
+  const payloadLit =
+    mintField !== undefined
+      ? `{ ...${JSON.stringify(baseValue)}, ${JSON.stringify(mintField)}: __minted }`
+      : JSON.stringify(baseValue);
+  const queryParamsObj = query ? Object.fromEntries(query.key.map((k) => [k, baseValue[k]])) : undefined;
+  const queryParams = queryParamsObj ? JSON.stringify(queryParamsObj) : "";
   const listAccessor = `list${agg.id}s`;
 
+  // THE MACHINE-READABLE LEGS (parsed by `githolon`'s offline proof runner —
+  // cli/src/proof_offline.ts — instead of regex-scraping the generated source).
+  const legsMarker = JSON.stringify({
+    domain,
+    directiveId: createDir.id,
+    aggregateId: agg.id,
+    payload: baseValue,
+    autoStamped: synth.autoStamped,
+    ...(mintField !== undefined ? { mintField } : {}),
+    ...(query && queryParamsObj ? { query: { id: query.id, params: queryParamsObj } } : {}),
+    ...(count ? { count: { id: count.id, group: count.by != null ? String(baseValue[count.by]) : "" } } : {}),
+  });
+
   let step = 0;
   const n = () => ++step;
   const out: string[] = [];
@@ -256,6 +285,7 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
     `//`,
     `// The flow mirrors the scaffold's test/e2e.mts (docs/ in a scaffolded app explains`,
     `// every call — start at docs/01-mental-model.md). Regenerated on every compile; do not edit.`,
+    `// @nomos-proof-legs ${legsMarker}`,
     `import { readFileSync } from "node:fs";`,
     `import { connect } from "@githolon/client";`,
     `import { ${factory}, ${hashConst} } from "./${opts.packageName}.client.ts";`,
@@ -266,18 +296,25 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
     `// IDENTITY NOTE: this proof uses the bare x-nomos-principal lane so it is`,
     `// SELF-CONTAINED (a throwaway workspace, no stored credentials). Real apps use`,
     `// \`githolon login --agent\` (a VERIFIED identity) + \`githolon ws create/deploy\`.`,
-    `const fail: (m: string) => never = (m) => { console.error("✗ " + m); process.exit(1); };`,
+    `const fail: (m: string) => never = (m) => { throw new Error(m); };`,
     `const ok = (m: string) => console.log("✓ " + m);`,
     ``,
     `const deploy = JSON.parse(readFileSync(new URL(${JSON.stringify(`./${opts.packageName}.deploy.json`)}, import.meta.url), "utf8"));`,
     ``,
+    `// CLEANUP CONTRACT: the throwaway workspace is RETIRED on every exit (green or`,
+    `// jammed) — a proof never leaves orphans. PROOF_KEEP=1 (githolon proof --live --keep)`,
+    `// keeps it and prints the FULL secret once, with the persist command.`,
+    `let SECRET = "";`,
+    `let runError: unknown = null;`,
+    `try {`,
+    ``,
     `// ${n()}. a throwaway workspace (the ONE-TIME secret comes back on create)`,
     `let r = await fetch(\`\${CLOUD}/v1/workspaces/\${WS}\`, { method: "POST", headers: { "x-nomos-principal": "githolon-proof" } });`,
     `let d = await r.json();`,
     `if (!d.ok) fail(\`create workspace: \${JSON.stringify(d)}\`);`,
-    `const SECRET: string = d.workspaceSecret;`,
+    `SECRET = d.workspaceSecret;`,
     `if (!SECRET?.startsWith("nws_v1_")) fail(\`no workspaceSecret returned: \${JSON.stringify(d)}\`);`,
-    `ok(\`workspace \${WS} created — secret \${SECRET.slice(0, 10)}…\`);`,
+    `ok(\`workspace \${WS} created (one-time secret held for cleanup — PROOF_KEEP=1 keeps the workspace and prints it)\`);`,
     ``,
     `// ${n()}. deploy YOUR compiled law (build/${opts.packageName}.deploy.json) WITH the secret`,
     `r = await fetch(\`\${CLOUD}/v1/workspaces/\${WS}/domains\`, { method: "POST", headers: { "content-type": "application/json", authorization: \`Bearer \${SECRET}\` }, body: JSON.stringify(deploy) });`,
@@ -297,8 +334,16 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
     `const realFetch = globalThis.fetch;`,
     `globalThis.fetch = (() => { throw new Error("OFFLINE PROOF VIOLATED: local authoring touched the network"); }) as typeof fetch;`,
     ``,
+    ...(mintField !== undefined
+      ? [
+          `// the target's own id is KERNEL-MINTED (never hand-written — the gate's`,
+          `// check_create_ids refuses sample ids typed): the local wasm mints, the id`,
+          `// rides the payload, replay reads the capture.`,
+          `const __minted = await holon.mint(${JSON.stringify(agg.id)});`,
+        ]
+      : []),
     `await app.${createDir.id}(${payloadLit});`,
-    `ok("dispatch ${domain}/${createDir.id} — offline write under the pulled law (payload synthesized from YOUR schema)");`,
+    `ok("dispatch ${domain}/${createDir.id} — offline write under the pulled law (payload synthesized from YOUR schema${mintField !== undefined ? `; \`${mintField}\` kernel-minted` : ``})");`,
     ``,
   );
 
@@ -326,7 +371,7 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
 
   if (count) {
     const accessor = lcFirst(camel(count.id));
-    const callArg = count.by != null ? JSON.stringify(String(synth.value[count.by])) : "";
+    const callArg = count.by != null ? JSON.stringify(String(baseValue[count.by])) : "";
     out.push(
       `// ${n()}. the first declared count — the maintained O(1) tally, locally`,
       `const localCount = await app.${accessor}(${callArg});`,
@@ -370,7 +415,7 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
   if (count) {
     out.push(
       `// ${n()}. the EDGE maintains the same count (same wasm, same law)`,
-      `d = await (await fetch(\`\${CLOUD}/v1/workspaces/\${WS}/counts/${count.id}${count.by != null ? `?group=\${encodeURIComponent(${JSON.stringify(String(synth.value[count.by]))})}` : ``}\`)).json();`,
+      `d = await (await fetch(\`\${CLOUD}/v1/workspaces/\${WS}/counts/${count.id}${count.by != null ? `?group=\${encodeURIComponent(${JSON.stringify(String(baseValue[count.by]))})}` : ``}\`)).json();`,
       `if (!(d.ok && d.count === 1)) fail(\`cloud count ${count.id}: \${JSON.stringify(d)}\`);`,
       `ok("cloud count ${count.id} = 1 — the O(1) maintained read, at the edge too");`,
       ``,
@@ -424,6 +469,22 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
     ``,
     `console.log(\`\\nALL GREEN — generated proof for "${opts.packageName}": deploy → offline write → local reads → admission → cloud reads${concurrency ? ` → AddWins merge` : ``} → convergence (\${WS})\`);`,
     ``,
+    `} catch (e) {`,
+    `  runError = e;`,
+    `  console.error("✗ " + ((e as Error)?.message ?? e));`,
+    `} finally {`,
+    `  // THE CLEANUP CONTRACT: never an orphaned cloud workspace. Retired on every`,
+    `  // exit path; PROOF_KEEP=1 keeps it and prints the FULL secret exactly once.`,
+    `  if (SECRET && process.env.PROOF_KEEP === "1") {`,
+    `    console.log(\`workspace \${WS} KEPT — secret \${SECRET}\`);`,
+    `    console.log(\`  persist it: githolon secret set \${WS} <the secret above>   (then: githolon ws retire \${WS} when done)\`);`,
+    `  } else if (SECRET) {`,
+    `    const rr = await fetch(\`\${CLOUD}/v1/workspaces/\${WS}/retire\`, { method: "POST", headers: { authorization: \`Bearer \${SECRET}\` } }).then((x) => x.json()).catch(() => ({}));`,
+    `    console.log(\`  retired \${WS}: \${(rr as { ok?: boolean }).ok === true}\`);`,
+    `  }`,
+    `  process.exit(runError ? 1 : 0);`,
+    `}`,
+    ``,
   );
 
   return out.join("\n");

package/src/compile_package_main.ts

@@ -21,10 +21,10 @@
  * Per domain: `key` is the engine dispatch key AND the identity-manifest name
  * (`name` overrides the latter); `modules` is the ORDERED module list (later wins on
  * a name collision — the framework `identity` union pattern). Read-side declarations
- * (queries / counts / spatials / deriveds / combineds) are AUTO-DISCOVERED from the
- * merged module exports by SHAPE (both individual decls and exported arrays of them,
- * deduped); anything undiscoverable can be passed explicitly as EXPORT NAMES, e.g.
- * `{ sums: ["GUESTBOOK_SUMS"], extraAggregates: ["SomeFrameworkHandle"] }`.
+ * (queries / counts / sums / spatials / deriveds / combineds) are AUTO-DISCOVERED
+ * from the merged module exports by SHAPE (both individual decls and exported arrays
+ * of them, deduped); anything undiscoverable can be passed explicitly as EXPORT
+ * NAMES, e.g. `{ mins: ["LOWEST_BIDS"], extraAggregates: ["SomeFrameworkHandle"] }`.
  * Reports: `{ reports: { my_report_v1: "./report/my_report.ts#myReportV1" } }`.
  *
  * It emits into `outDir` (default `<config dir>/build`):
@@ -49,6 +49,7 @@
  * `globalThis.plan`.
  */
 import { execFileSync } from "node:child_process";
+import { expandCapabilityExports, isCapabilityDecl } from "./capability_exports.js";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
@@ -93,6 +94,14 @@ import {
   layeredRootUsda,
   type LayeredModuleInput,
 } from "./usd_layers.js";
+import { domainManifest } from "./manifest.js";
+import type { WireSchema } from "./wire.js";
+import {
+  deriveStableIdContinuity,
+  stableIdsFromManifestJson,
+  type InferredRename,
+  type StableIds,
+} from "./stable_ids.js";
 import type { UsdLayer } from "./usd.js";
 import { generateTsClient, tsClientFactoryName } from "./codegen_ts.js";
 import { generateTsProof } from "./codegen_proof.js";
@@ -106,8 +115,9 @@ interface DomainConfig {
   // Explicit EXPORT-NAME escape hatches (resolved on the merged module exports):
   readonly queries?: readonly string[];
   readonly counts?: readonly string[];
+  /** Escape hatch only since #57 — exported SumDecls auto-discover like queries/counts. */
   readonly sums?: readonly string[];
-  /** Maintained MIN/MAX reads (#47) — export names, config-named like sums. */
+  /** Maintained MIN/MAX reads (#47) — export names (config-named; not yet auto-discovered). */
   readonly mins?: readonly string[];
   readonly maxes?: readonly string[];
   readonly spatials?: readonly string[];
@@ -232,6 +242,13 @@ function isCombinedDecl(v: unknown): v is CombinedDecl {
   );
 }
 
+/** A sum decl/builder — the `{id, of, sumField}` mark (counts/extremums never carry `sumField`). */
+function isSumDecl(v: unknown): v is AnySum {
+  if (!v || typeof v !== "object") return false;
+  const o = v as Record<string, unknown>;
+  return typeof o.id === "string" && typeof o.of === "string" && typeof o.sumField === "string";
+}
+
 /** A count decl/builder — `{id, of}` with NONE of the other decl families' marks. */
 function isCountDecl(v: unknown): v is AnyCount {
   if (!v || typeof v !== "object") return false;
@@ -470,6 +487,25 @@ async function main(): Promise<void> {
   const layered = layeredFlag || cfg.layered === true;
   const layeredDomains: { key: string; inputs: LayeredModuleInput[] }[] = [];
   let importSeq = 0;
+  /**
+   * THE CAPABILITY LOWERING (capability_marketplace.md §4 — the deploy-warning
+   * prerequisite + the executor's task→capability→domain map). Rides the
+   * UNHASHED deploy sidecar only (a top-level deploy-body key, like
+   * `dispositions`) — never the read manifest the wasm parses, never any
+   * hash-bearing artifact: declaring a capability moves no identity hash, and
+   * capability-free deploy bodies stay byte-identical (omit-when-empty).
+   */
+  const capabilityLowerings: {
+    capability: string;
+    domain: string;
+    aggregateId: string;
+    order: string;
+    complete: string;
+    fail: string;
+    block: string;
+    deadLetter: string;
+    tasksQueryId: string | null;
+  }[] = [];
 
   for (const d of cfg.domains) {
     if (typeof d.key !== "string" || !Array.isArray(d.modules) || d.modules.length === 0) {
@@ -492,6 +528,9 @@ async function main(): Promise<void> {
     }
     let merged: Mod = {};
     for (const m of mods) merged = { ...merged, ...m };
+    // `capability()` bundles expand into discoverable entries (the CLI plane's
+    // merge point) — queries/sums/sid-minting/manifests all see the pieces.
+    merged = expandCapabilityExports(merged);
     let shardingSums: AnySum[] = [];
     let shardingMins: AnyExtremum[] = [];
     let shardingMaxes: AnyExtremum[] = [];
@@ -555,9 +594,9 @@ async function main(): Promise<void> {
         merged = { ...merged, ...shardingMod };
         shardingModForDomain = shardingMod;
         // The derived sharding law's MAINTAINED SUMS (`nomosEstateSummary` — the §5.1
-        // estate total over subtotal rows) must reach the read manifest + identity:
-        // sums are config-named (never auto-discovered — hash stability for existing
-        // packages), so the appended module's sums thread through explicitly here.
+        // estate total over subtotal rows) must reach the read manifest + identity.
+        // (Sums auto-discover since #57; this explicit thread predates that and stays
+        // as belt-and-braces — the reference-dedupe below collapses the overlap.)
         shardingSums = Object.values(shardingMod).filter(
           (v): v is AnySum =>
             !!v && typeof v === "object" &&
@@ -652,14 +691,47 @@ async function main(): Promise<void> {
       ...discover<WorkspaceInvariantDecl>(merged, isWorkspaceInvariantDecl),
       ...resolveNamed<WorkspaceInvariantDecl>(merged, d.workspaceInvariants, "workspaceInvariants"),
     ];
-    const sums = [...resolveNamed<AnySum>(merged, d.sums, "sums"), ...shardingSums];
+    // Sums are AUTO-DISCOVERED like queries/counts (#57 — an exported SumDecl used to be
+    // SILENTLY DROPPED unless config-named; the config lane stays as the escape hatch).
+    // Reference-dedupe: a sum that is BOTH exported and config-named is the same object.
+    const sums = [
+      ...new Set([
+        ...discover<AnySum>(merged, isSumDecl),
+        ...resolveNamed<AnySum>(merged, d.sums, "sums"),
+        ...shardingSums,
+      ]),
+    ];
     const mins = [...resolveNamed<AnyExtremum>(merged, d.mins, "mins"), ...shardingMins];
     const maxes = [...resolveNamed<AnyExtremum>(merged, d.maxes, "maxes"), ...shardingMaxes];
-    const impureCapabilities = resolveNamed<ImpureCapabilityDecl>(
+    // `capability()` declarations AUTO-DISCOVER (the marketplace lane, M2 —
+    // "declare ONE thing"); the config-named lane stays for hand-rolled
+    // impureCapability quartets. Deduped by task-aggregate id (a config-named
+    // capability() counts once).
+    const discoveredCapabilities = Object.values(merged).filter(isCapabilityDecl) as unknown as ImpureCapabilityDecl[];
+    const namedCapabilities = resolveNamed<ImpureCapabilityDecl>(
       merged,
       d.impureCapabilities,
       "impureCapabilities",
     );
+    const capByAggregate = new Map<string, ImpureCapabilityDecl>();
+    for (const c of [...discoveredCapabilities, ...namedCapabilities]) capByAggregate.set(c.aggregate.id, c);
+    const impureCapabilities = [...capByAggregate.values()];
+    for (const c of impureCapabilities) {
+      const meta = c as unknown as { name?: unknown; capability?: unknown; tasks?: { id?: unknown } };
+      const cap = typeof meta.name === "string" ? meta.name : typeof meta.capability === "string" ? meta.capability : null;
+      if (cap === null) continue; // a binding-free quartet lowers nothing (omit-when-absent)
+      capabilityLowerings.push({
+        capability: cap,
+        domain: d.key,
+        aggregateId: c.aggregate.id,
+        order: c.order.id,
+        complete: c.complete.id,
+        fail: c.fail.id,
+        block: c.block.id,
+        deadLetter: c.deadLetter.id,
+        tasksQueryId: typeof meta.tasks?.id === "string" ? meta.tasks.id : null,
+      });
+    }
     const extraAggregates = resolveNamed<AggregateHandle>(merged, d.extraAggregates, "extraAggregates");
 
     // Dart-codegen hints (frontend-only — never law; see DomainConfig):
@@ -804,6 +876,96 @@ async function main(): Promise<void> {
     }
   }
 
+  // ── STABLE-ID CONTINUITY (#58 — names are labels, identity is minted) ──
+  // Derive each composed domain's stable ids from the PRIOR compile: the committed
+  // `nomos.stable-ids.json` lockfile beside the config (the durable source — survives
+  // a clean clone), else the previous build's identity manifests. Match by name;
+  // exactly ONE disappeared + ONE appeared name of the same kind/shape is an inferred
+  // RENAME (sid carried, lineage recorded, printed below); anything else mints fresh
+  // at first appearance (a leftover disappearance is THE EVOLVE GATE's typed question
+  // at deploy — answered in the upgrade intent's disposition). The resolved continuity
+  // is attached to the module so the canonical manifest + USD-IR carry it.
+  interface StableIdLock {
+    v: 1;
+    domains: Record<string, { stableIds: StableIds; schemas: Record<string, WireSchema> }>;
+  }
+  const lockPath = path.join(cfgDir, "nomos.stable-ids.json");
+  const priorLock: StableIdLock | undefined = existsSync(lockPath)
+    ? (JSON.parse(readFileSync(lockPath, "utf8")) as StableIdLock)
+    : undefined;
+  const priorBuildManifestsPath = path.join(outDir, "domain_identity_manifests.json");
+  const priorBuildManifests: Record<string, string> | undefined = existsSync(priorBuildManifestsPath)
+    ? (JSON.parse(readFileSync(priorBuildManifestsPath, "utf8")) as Record<string, string>)
+    : undefined;
+  const inferredRenames: { domain: string; renames: InferredRename[] }[] = [];
+  const nextLock: StableIdLock = { v: 1, domains: {} };
+  for (const mod of domainModules) {
+    const identityName = mod.name;
+    // The CURRENT canonical aggregate schemas (a pre-continuity manifest pass —
+    // aggregates/schemas do not depend on continuity).
+    let currentAggs: { id: string; schema: WireSchema; kinds?: Record<string, string> }[];
+    try {
+      const preManifest = domainManifest(mod);
+      currentAggs = preManifest.aggregates.map((a) => ({
+        id: a.id,
+        schema: a.schema,
+        // The CURRENT field kinds (off the pre-continuity stableIds emission) — the
+        // pair rule's kind axis ("rename + add a field" in one release still infers).
+        kinds: Object.fromEntries(
+          Object.entries(preManifest.stableIds?.aggregates[a.id]?.fields ?? {}).map(
+            ([f, v]) => [f, v.kind ?? ""] as [string, string],
+          ),
+        ),
+      }));
+    } catch {
+      // A palette-gap domain has no canonical identity (recorded-and-excluded later);
+      // it carries no stable ids either.
+      continue;
+    }
+    // Continuity source: the lockfile first (durable, committed), else the prior build.
+    let prior: StableIds | undefined;
+    let priorSchemas: Record<string, WireSchema> | undefined;
+    const locked = priorLock?.domains[identityName];
+    if (locked !== undefined) {
+      prior = locked.stableIds;
+      priorSchemas = locked.schemas;
+    } else if (priorBuildManifests?.[identityName] !== undefined) {
+      prior = stableIdsFromManifestJson(priorBuildManifests[identityName]!);
+      try {
+        const parsed = JSON.parse(priorBuildManifests[identityName]!) as {
+          aggregates?: { id: string; schema: WireSchema }[];
+        };
+        priorSchemas = Object.fromEntries((parsed.aggregates ?? []).map((a) => [a.id, a.schema]));
+      } catch {
+        priorSchemas = undefined;
+      }
+    }
+    const { continuity, inferred } = deriveStableIdContinuity(
+      identityName,
+      currentAggs,
+      prior,
+      priorSchemas,
+    );
+    mod.stableIdContinuity = continuity;
+    // The layered emission's per-module layers must carry the SAME sids (the flatten
+    // homomorphism is byte-asserted), so the continuity rides every layer input too.
+    for (const ld of layeredDomains) {
+      if (ld.key === (mod.domain ?? mod.name)) {
+        for (const inp of ld.inputs) inp.module.stableIdContinuity = continuity;
+      }
+    }
+    if (inferred.length > 0) inferredRenames.push({ domain: identityName, renames: inferred });
+    // The lockfile records the EMITTED surface (sids + lineage + kinds — the next
+    // compile's pair rule reads the kinds), not the bare continuity.
+    nextLock.domains[identityName] = {
+      stableIds: domainManifest(mod).stableIds ?? continuity,
+      schemas: Object.fromEntries(currentAggs.map((a) => [a.id, a.schema])),
+    };
+  }
+  // Persist the lockfile (commit it with the law: it is how a rename keeps its
+  // identity across clean clones). Deterministic — re-compiles rewrite the same bytes.
+  writeFileSync(lockPath, JSON.stringify(nextLock, null, 2) + "\n", "utf8");
+
   // ── reports ──
   const entryReports: string[] = [];
   for (const [reportId, ref] of Object.entries(cfg.reports ?? {})) {
@@ -931,6 +1093,54 @@ async function main(): Promise<void> {
     fail(`bundled engine entry does not assign globalThis.plan — refusing to package`);
   }
 
+  // ── 1a. THE CAPTURED-READ GATE (#57, lifted-when-declared since #58) ──
+  // `read()` (the captured-read lane) is served by the sealed engine ONLY for law
+  // that DECLARES it: a directive whose plan reads must declare each query with
+  // `.reads(theQuery)`, which lands the `nomosReadGate` key in the law's USD-IR (the
+  // era key — the gate serves/captures/CAS-verifies reads only under it). A lump that
+  // references read() while NO directive declares a captured-read query would still
+  // halt at first dispatch (the engine provides no nomos.read for it), so THAT
+  // compile refuses fail-closed. The marker is a string that lives ONLY inside
+  // `read()`'s body (dsl/src/read.ts — keep them byte-identical) and is tree-shaken
+  // out of read-free lumps.
+  const CAPTURED_READ_LUMP_MARKER = "nomos.read is not provided by this host";
+  const declaresCapturedReads = domainModules.some((m) =>
+    m.directives.some(
+      (d) => ((d as { declaredQueryReads?: unknown[] }).declaredQueryReads ?? []).length > 0,
+    ),
+  );
+  if (javascript.includes(CAPTURED_READ_LUMP_MARKER) && !declaresCapturedReads) {
+    fail(
+      `this law references read() — the CAPTURED-READ lane — but NO directive declares a ` +
+        `captured-read query, so the sealed engine would provide no nomos.read and every ` +
+        `dispatch of a read()-calling plan would halt at runtime. The compile refuses fail-closed.\n` +
+        `  remedy: declare the read on the directive whose plan calls it — ` +
+        `.reads(theQueryDecl) (the same QueryDecl the read() call passes). The law then ` +
+        `opts into the captured-read gate: reads are served live at author, captured onto ` +
+        `the intent, replayed at verify, and CAS-checked at every gate.\n` +
+        `  alternative: commit the premise in the payload instead — the CALLER reads (a ` +
+        `typed query/count off the holon) and the payload carries the result as a stamped fact.`,
+    );
+  }
+  // The symmetric validation: every DECLARED captured-read query must return a known
+  // aggregate of its domain (fail-closed — a read recipe over an unknown type can
+  // never be derived at the gate).
+  for (const m of domainModules) {
+    const aggIds = new Set(m.aggregates.map((a) => a.id));
+    for (const d of m.directives) {
+      for (const q of (d as { declaredQueryReads?: { id: string; returns: string }[] })
+        .declaredQueryReads ?? []) {
+        if (!aggIds.has(q.returns)) {
+          fail(
+            `domain '${m.domain ?? m.name}': directive '${d.id}' declares captured read ` +
+              `'${q.id}' returning '${q.returns}', which is not an aggregate of this domain — ` +
+              `captured reads are same-workspace, same-domain declared reads.`,
+          );
+        }
+      }
+    }
+  }
+
   // ── 1b. THE FROZEN-SANDBOX BOOT PROBE (lazy boot only, fail-closed) ──
   // The sealed engine freezes globalThis after the lump's top level; a lazy
   // domain's module init runs LATER, inside the dispatch. Any module that writes
@@ -1053,6 +1263,7 @@ async function main(): Promise<void> {
       directives: m.directives.map((d) => d.id),
       queries: (m.queries ?? []).map((q) => q.id),
       counts: (m.counts ?? []).map((c) => c.id),
+      sums: (m.sums ?? []).map((s) => s.id),
       identityHash: identity.hashes[m.domain ?? m.name],
     })),
   };
@@ -1062,6 +1273,10 @@ async function main(): Promise<void> {
     readManifest,
     identityManifests: identity.manifests,
     identityHashes: identity.hashes,
+    // The capability lowering (unhashed sidecar; omit-when-empty — see the
+    // collector's doc above). The worker stages it on the manifest overlay:
+    // the deploy-time binding warning + the executor's scan map read it there.
+    ...(capabilityLowerings.length > 0 ? { capabilities: capabilityLowerings } : {}),
   };
   const deployPath = path.join(outDir, `${cfg.name}.deploy.json`);
   writeFileSync(deployPath, JSON.stringify(deployBody) + "\n", "utf8");
@@ -1087,7 +1302,7 @@ async function main(): Promise<void> {
       `domain '${d.domain}'${d.identityHash ? `  (identity ${d.identityHash.slice(0, 12)}…)` : "  (EXCLUDED from identity manifest)"}`,
       `  aggregates: ${d.aggregates.join(", ") || "—"}`,
       `  directives: ${d.directives.join(", ") || "—"}`,
-      `  queries: ${d.queries.join(", ") || "—"}   counts: ${d.counts.join(", ") || "—"}`,
+      `  queries: ${d.queries.join(", ") || "—"}   counts: ${d.counts.join(", ") || "—"}   sums: ${d.sums.join(", ") || "—"}`,
     ]),
     `deploy: POST ${cfg.name}.deploy.json to /v1/workspaces/<ws>/domains (or: githolon deploy <ws>)`,
     `typed client: ${cfg.name}.client.ts — ${tsClientFactoryName(domainModules[0]?.domain ?? domainModules[0]?.name ?? cfg.name)}(holon), law hash baked in`,
@@ -1129,10 +1344,21 @@ async function main(): Promise<void> {
       `  layered    ${rel(layeredRootPath)} (${layeredFileCount} module layer(s) in build/layers/ — flatten-verified byte-identical to the canonical IR)`,
     );
   }
-  console.log(`  read       ${rel(readPath)} (${Object.keys(readManifest.aggregateFieldKinds).length} aggregate(s), ${readManifest.queries.length} quer(y/ies), ${readManifest.counts.length} count(s))`);
+  console.log(`  read       ${rel(readPath)} (${Object.keys(readManifest.aggregateFieldKinds).length} aggregate(s), ${readManifest.queries.length} quer(y/ies), ${readManifest.counts.length} count(s), ${readManifest.sums?.length ?? 0} sum(s))`);
   console.log(`  identity   ${rel(manifestsPath)} (${Object.keys(identity.manifests).length} domain(s)${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}`);
+  // STABLE IDS (#58): the minted/carried identity surface + every INFERRED rename —
+  // the silent lane made visible (if an inference is wrong — you meant remove+add —
+  // split the edit into two compiles, or answer the evolve gate with a disposition).
+  console.log(`  stable-ids ${rel(lockPath)} (committed lockfile — identity across renames)`);
+  for (const { domain, renames } of inferredRenames) {
+    for (const r of renames) {
+      console.log(
+        `             INFERRED RENAME [${domain}] ${r.from} -> ${r.to} (stable id ${r.sid} carried; a rename is metadata — same identity, new label)`,
+      );
+    }
+  }
   for (const m of domainModules) {
     if (m.workspaceTypes !== undefined && m.workspaceTypes.length > 0) {
       console.log(
@@ -1156,7 +1382,9 @@ async function main(): Promise<void> {
   console.log(`  # raw lane: curl -X POST -H 'content-type: application/json' -H 'Authorization: Bearer <workspaceSecret>' \\`);
   console.log(`  #   --data-binary @${rel(deployPath)} https://nomos.captainapp.co.uk/v1/workspaces/<ws>/domains`);
   if (proofPath !== undefined) {
-    console.log(`prove it: npx githolon proof   # GENERATED from your law — offline write -> sync -> admission -> cloud reads, live`);
+    console.log(`prove it OFFLINE first: npx githolon proof        # the generated proof's offline legs on a LOCAL holon (no cloud workspace)`);
+    console.log(`  inner loop:           npx githolon dev          # watch -> recompile -> law live locally -> offline proof, on every save`);
+    console.log(`  then the cloud loop:  npx githolon proof --live # throwaway workspace, retired on exit (--keep keeps it)`);
   } else {
     console.log(`prove it: npm run e2e   # offline write -> sync -> admission -> cloud query, live`);
   }