@githolon/dsl 0.4.0 → 0.5.0

package/src/manifest.ts

@@ -48,6 +48,14 @@ import {
   canonicalTaxonomyFragment,
   type CanonicalDirectiveRoute,
 } from "./workspace_routing.js";
+import {
+  mintAggregateSid,
+  mintDomainSid,
+  mintFieldSid,
+  type StableAggregateId,
+  type StableFieldId,
+  type StableIds,
+} from "./stable_ids.js";
 
 /** One captured `[fieldName, zodKind]` payload field, with optionality. */
 export interface CanonicalPayloadField {
@@ -126,6 +134,15 @@ export interface CanonicalDirective {
    * before this key existed (pinned golden hashes stay UNCHANGED).
    */
   readonly certifiedReads?: CanonicalCertifiedRead[];
+  /**
+   * The directive's DECLARED CAPTURED-READ queries (#58 — the captured-read lane):
+   * the O(1) DSL queries its `plan` may `read()` on the write path, each carried as
+   * `{queryId, key, returns}` (the read RECIPE is the contract — a different key or
+   * returns-type is a different read, so it moves the hash). SORTED by queryId.
+   * OMITTED ENTIRELY when the directive declares none — a captured-read-free
+   * directive is byte-identical in the manifest to before this key existed.
+   */
+  readonly capturedReads?: CanonicalCapturedRead[];
   /**
    * The directive's DECLARED required HOST CAPABILITY ports (`TARGET_deps.dot` cluster_ports;
    * the HOST/PORT axis, invariant 3): the capability ports the host must PROVIDE for the
@@ -178,6 +195,15 @@ export interface CanonicalRelationEvidence {
   readonly kind: string;
 }
 
+/** One DECLARED captured-read query (#58) — the write-path `read()` recipe in the
+ * manifest: the query id, its index key (DECLARED order — index column order), and the
+ * aggregate TYPE it returns. */
+export interface CanonicalCapturedRead {
+  readonly queryId: string;
+  readonly key: string[];
+  readonly returns: string;
+}
+
 /** One captured DECLARED CertifiedRead — the profiled write-path read identity in the manifest.
  * `queryId` is the gate's required-read key; `sql`/`multiRow`/`uniqueTieBreakers` are the recipe
  * + shape the admission re-run + the profile pin (a recipe change moves the domain hash). */
@@ -378,6 +404,18 @@ export interface CanonicalManifest {
   readonly domain: string;
   readonly aggregates: CanonicalAggregate[];
   readonly directives: CanonicalDirective[];
+  /**
+   * STABLE IDENTIFIERS (#58 — the foundation: names are LABELS, identity is MINTED by
+   * the compiler at first appearance, never dev-assigned). Carries `{stableId, name}`
+   * for the domain, every aggregate, and every field — keyed by CURRENT name, each
+   * entry holding its `sid` plus the label lineage `was` (prior names, oldest first;
+   * compiler-derived from continuity, never dev-written). ALWAYS EMITTED by the post-
+   * #58 compiler — this key MOVES every enforcement-era identity hash (named and
+   * expected; inert-era artifacts already built stay byte-identical untouched). The
+   * EVOLVE GATE diffs old vs new law BY SID; the projection folds via the sid lineage
+   * so a renamed entity's old-era data coheres under the new label.
+   */
+  readonly stableIds?: StableIds;
   /**
    * The domain's WORKSPACE INVARIANTS (#266), SORTED by id, PRESENCE ONLY (id + `on`).
    * OMITTED ENTIRELY when the domain declares none — so an invariant-free domain is
@@ -636,6 +674,23 @@ function canonicalEmits(
  * NAME (the `reads:{}` key) is incidental to identity (it is `decide`'s ergonomics), so it is
  * NOT captured — only the `query_id` + recipe.
  */
+/**
+ * Canonicalize a directive's DECLARED captured-read queries (#58) into a manifest
+ * fragment. OMIT-WHEN-EMPTY: returns `{}` (no `capturedReads` key) when the directive
+ * declares none — the omission keeps read-free hashes unchanged. When non-empty,
+ * returns a `capturedReads` array SORTED by queryId, each carrying the read recipe
+ * `{queryId, key, returns}` (key in DECLARED order — index column order).
+ */
+function canonicalCapturedReads(
+  declared: QueryDecl[],
+): { capturedReads?: CanonicalCapturedRead[] } {
+  if (declared.length === 0) return {};
+  const capturedReads: CanonicalCapturedRead[] = declared
+    .map((q) => ({ queryId: q.id, key: [...q.key], returns: q.returns }))
+    .sort((a, b) => (a.queryId < b.queryId ? -1 : a.queryId > b.queryId ? 1 : 0));
+  return { capturedReads };
+}
+
 function canonicalCertifiedReads(
   declared: Record<string, CertifiedReadDecl>,
 ): { certifiedReads?: CanonicalCertifiedRead[] } {
@@ -888,6 +943,50 @@ function canonicalOrderedReads(
   return { orderedReads: items };
 }
 
+/**
+ * The domain's STABLE-ID surface (#58): continuity-carried when the compiler attached
+ * `mod.stableIdContinuity` (renames resolved, sids + lineage carried), deterministic
+ * first-appearance minting otherwise — so the manifest stays a pure function of the
+ * module (+ its attached continuity). Any aggregate/field the continuity does not
+ * cover (a genuinely new appearance) mints fresh.
+ */
+function stableIdsForModule(
+  mod: DomainModule,
+  aggregates: CanonicalAggregate[],
+): StableIds {
+  const continuity = mod.stableIdContinuity;
+  const domainSid = continuity?.domain ?? mintDomainSid(mod.name);
+  // The CURRENT field KINDS off the live handles (the retype arm's identity input —
+  // a `t.string()` → `t.int()` retype moves `kind` while the driver stays Lww).
+  const handlesById = new Map(mod.aggregates.map((a) => [a.id, a]));
+  const out: Record<string, StableAggregateId> = {};
+  for (const agg of aggregates) {
+    const prior = continuity?.aggregates[agg.id];
+    const aggSid = prior?.sid ?? mintAggregateSid(domainSid, agg.id);
+    const handleFields = (handlesById.get(agg.id)?.fields ?? {}) as Record<
+      string,
+      { kind?: string } | undefined
+    >;
+    const fields: Record<string, StableFieldId> = {};
+    for (const fieldName of Object.keys(agg.schema).sort()) {
+      const pf = prior?.fields[fieldName];
+      const kind = handleFields[fieldName]?.kind;
+      fields[fieldName] = {
+        sid: pf?.sid ?? mintFieldSid(aggSid, fieldName),
+        ...(pf?.was !== undefined && pf.was.length > 0 ? { was: pf.was } : {}),
+        // The CURRENT kind, always from the live module (continuity never supplies it).
+        ...(kind !== undefined ? { kind } : {}),
+      };
+    }
+    out[agg.id] = {
+      sid: aggSid,
+      ...(prior?.was !== undefined && prior.was.length > 0 ? { was: prior.was } : {}),
+      fields,
+    };
+  }
+  return { v: 1, domain: domainSid, aggregates: out };
+}
+
 /**
  * Build the canonical semantic manifest for a domain module — purely from the
  * in-memory DSL objects. No file reads, no bundle, no esbuild: the manifest is a
@@ -919,6 +1018,7 @@ export function domainManifest(mod: DomainModule): CanonicalManifest {
       // Omit-when-empty: a directive declaring NO boundary contributes neither key,
       // so its canonical manifest is byte-identical to before the boundary existed.
       ...canonicalReads(d.declaredReads),
+      ...canonicalCapturedReads(d.declaredQueryReads ?? []),
       ...canonicalEmits(d.declaredEmits),
       ...canonicalCertifiedReads(d.declaredCertifiedReads),
       ...canonicalRelations(d.declaredRelations),
@@ -939,6 +1039,9 @@ export function domainManifest(mod: DomainModule): CanonicalManifest {
     domain: mod.name,
     aggregates,
     directives,
+    // STABLE IDS (#58): always emitted by this compiler — the one deliberate
+    // hash-mover (enforcement-era identity hashes move; named + expected).
+    stableIds: stableIdsForModule(mod, aggregates),
     ...canonicalWorkspaceInvariants(mod.workspaceInvariants),
     ...canonicalQueries(mod.queries),
     ...canonicalCounts(allCounts.length > 0 ? allCounts : undefined),

package/src/read.ts

@@ -46,9 +46,38 @@ function host(): NomosRead {
  * result}` into the intent's read footprint — so the read is replayable and the write's premise is
  * committed. `query` is a declared, indexed {@link QueryDecl} (e.g. a `t.hasMany` inverse from
  * `hasManyIndexes`); `args` are its index-key values.
+ *
+ * DEPLOYABLE SINCE #58 — WHEN DECLARED: the sealed wasm engine provides `nomos.read` for law that
+ * DECLARES the captured-read lane — the directive whose plan reads must declare each query with
+ * `.reads(theQuery)` (which lands the `nomosReadGate` key in the law's USD-IR). The engine then
+ * serves the read LIVE from the PRE-APPLY committed state at author, captures `{queryId, args,
+ * result}` into the intent's `captured_ports.reads`, replays the capture at verify, and the one
+ * gate RE-DERIVES each captured read at the pre-apply position and byte-compares — a typed
+ * read-conflict refusal on drift (CAS as law). Undeclared `read()` in law with NO declared
+ * captured-read query still REFUSES TO PACKAGE (`nomos-compile` greps the bundled lump for
+ * {@link CAPTURED_READ_LUMP_MARKER}, which lives ONLY in this function's body and is tree-shaken
+ * away with it) — and an inert host (no `nomos.read`) still halts with the named error below.
  */
 export function read<T = unknown>(query: QueryDecl, args: Record<string, string>): T {
+  const h = host() as { read?: unknown } | undefined;
+  if (typeof h?.read !== "function") {
+    // The string below IS the compile gate's marker — keep it byte-identical to
+    // CAPTURED_READ_LUMP_MARKER (compile_package_main.ts greps the bundled lump for it).
+    throw new Error(
+      `read('${query.id}'): nomos.read is not provided by this host — the engine serves ` +
+        `captured reads only for law that DECLARES them: add .reads(${query.id}'s QueryDecl) ` +
+        `to the directive and recompile (#58).`,
+    );
+  }
   const result = host().read(query.id, args) as T;
   footprint.push({ queryId: query.id, args, result });
   return result;
 }
+
+/**
+ * The compile gate's lump sentinel — the EXACT substring of the refusal `read()` throws above.
+ * It exists in a bundled engine lump iff `read` itself survived tree-shaking, i.e. iff some
+ * domain module actually references the captured-read lane. `nomos-compile` greps the lump for
+ * it and refuses to package (fail-closed: better a named compile refusal than a runtime halt).
+ */
+export const CAPTURED_READ_LUMP_MARKER = "nomos.read is not provided by this host";

package/src/stable_ids.ts

@@ -0,0 +1,226 @@
+// 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.
+
+/**
+ * STABLE IDENTIFIERS (#58) — names are LABELS; identity is MINTED by the compiler at
+ * FIRST APPEARANCE and never dev-assigned.
+ *
+ * Every aggregate, every field, and the domain itself carry a compiler-minted stable
+ * id (`sid`). The sid is the entity's IDENTITY across law upgrades: the evolve gate
+ * diffs old vs new law BY SID (a rename — same sid, new label — is metadata and
+ * admits silently; a true removal/retype is a typed refusal unless the upgrade intent
+ * carries a disposition), and the projection folds via the sid lineage so a renamed
+ * aggregate's old-era rows cohere under the new label automatically.
+ *
+ * MINTING (first appearance, deterministic): a sid is the first 16 hex chars of
+ * sha256 over a versioned scope string — so a clean checkout re-mints the SAME id
+ * for the same first appearance (no lockfile needed for the common case):
+ *
+ *   domain     sid("domain:<domainName>")
+ *   aggregate  sid("aggregate:<domainSid>:<aggName>")
+ *   field      sid("field:<aggSid>:<fieldName>")
+ *
+ * Note the NESTING: field sids mint under the AGGREGATE SID (not its name), so a
+ * renamed aggregate's fields keep their identities for free.
+ *
+ * CONTINUITY (across compiles): `nomos-compile` reads the PRIOR build's identity
+ * manifests / the committed `nomos.stable-ids.json` lockfile and derives a continuity
+ * table per domain — match by name first; then the UNAMBIGUOUS-PAIR rule: exactly ONE
+ * disappeared name + exactly ONE same-shaped appeared name is an inferred RENAME (the
+ * sid is carried, the old label recorded in `was`, and the compile summary prints the
+ * inference). Anything still unmatched is left for THE EVOLVE GATE's typed question
+ * at deploy — the dev answers in the upgrade intent's disposition
+ * ({retired | retyped | rebinds}).
+ *
+ * `was` is the LABEL LINEAGE: every label this sid previously wore, oldest first.
+ * It is compiler-derived (never dev-written) and HASH-BEARING (it is law): the
+ * projection reads it to fold old-era field/type labels into the current ones.
+ *
+ * BUILD-TIME ONLY (imports `node:crypto`): reached via `@githolon/dsl/stable-ids` /
+ * `@githolon/dsl/manifest`, never the runtime barrel. The pure TYPE surface lives in
+ * `stable_ids_types.ts` so the runtime type graph stays node-free.
+ */
+import { createHash } from "node:crypto";
+import type { WireSchema } from "./wire.js";
+import type { StableAggregateId, StableFieldId, StableIds } from "./stable_ids_types.js";
+
+export type { StableAggregateId, StableFieldId, StableIds } from "./stable_ids_types.js";
+
+/** Mint one stable id: first 16 hex chars of sha256 over the versioned scope. */
+export function mintStableId(scope: string): string {
+  return createHash("sha256").update(`nomos-sid:v1:${scope}`, "utf8").digest("hex").slice(0, 16);
+}
+
+export function mintDomainSid(domainName: string): string {
+  return mintStableId(`domain:${domainName}`);
+}
+
+export function mintAggregateSid(domainSid: string, aggName: string): string {
+  return mintStableId(`aggregate:${domainSid}:${aggName}`);
+}
+
+export function mintFieldSid(aggSid: string, fieldName: string): string {
+  return mintStableId(`field:${aggSid}:${fieldName}`);
+}
+
+/** One inferred rename, printed by the compile summary (visibility for the silent lane). */
+export interface InferredRename {
+  /** `"<Agg>"` for an aggregate rename, `"<Agg>.<field>"` for a field rename. */
+  readonly what: string;
+  readonly from: string;
+  readonly to: string;
+  readonly sid: string;
+}
+
+/**
+ * Derive the stable-id CONTINUITY for one domain from its PRIOR manifest's stableIds
+ * (the chain/build holds v's sids) against the CURRENT compile's names.
+ *
+ *   1. match by NAME — same name carries its sid + lineage forward;
+ *   2. the UNAMBIGUOUS-PAIR rule — exactly one disappeared + one appeared name of the
+ *      same kind AND shape (aggregate: same field-name set; field: same driver AND
+ *      same read kind, with exactly ONE matching appearance) is an inferred RENAME:
+ *      the sid is carried, `was` extended;
+ *   3. anything else mints fresh at first appearance (a leftover disappearance is the
+ *      EVOLVE GATE's question at deploy — never silently resolved here).
+ *
+ * Returns the continuity keyed by CURRENT names (exactly the shape `domainManifest`
+ * consumes) plus the inferred renames for the compile summary.
+ */
+export function deriveStableIdContinuity(
+  domainName: string,
+  currentAggregates: { id: string; schema: WireSchema; kinds?: Record<string, string> }[],
+  prior: StableIds | undefined,
+  /** The prior canonical manifest's aggregate schemas (keyed by PRIOR name) — when
+   * supplied, tightens the field-pair rule to same-driver only. */
+  priorSchemas?: Record<string, WireSchema>,
+): { continuity: StableIds; inferred: InferredRename[] } {
+  const inferred: InferredRename[] = [];
+  const domainSid = prior?.domain ?? mintDomainSid(domainName);
+
+  const priorAggs = prior?.aggregates ?? {};
+  const currentNames = new Set(currentAggregates.map((a) => a.id));
+
+  // Pass 1 — name matches.
+  const resolved: Record<
+    string,
+    { sid: string; was?: string[]; priorFields?: Record<string, StableFieldId>; priorSchema?: WireSchema }
+  > = {};
+  for (const agg of currentAggregates) {
+    const p = priorAggs[agg.id];
+    if (p !== undefined) {
+      resolved[agg.id] = {
+        sid: p.sid,
+        ...(p.was !== undefined ? { was: p.was } : {}),
+        priorFields: p.fields,
+        ...(priorSchemas?.[agg.id] !== undefined ? { priorSchema: priorSchemas[agg.id] } : {}),
+      };
+    }
+  }
+
+  // Pass 2 — the unambiguous aggregate pair (one disappeared, one appeared, same shape).
+  const disappeared = Object.keys(priorAggs).filter((n) => !currentNames.has(n));
+  const appeared = currentAggregates.filter((a) => resolved[a.id] === undefined);
+  if (disappeared.length === 1 && appeared.length === 1) {
+    const oldName = disappeared[0]!;
+    const oldAgg = priorAggs[oldName]!;
+    const newAgg = appeared[0]!;
+    // Shape gate: the renamed aggregate must keep its field-name set (a rename is a
+    // LABEL move, not a remodel) — a remodel goes to the evolve gate's typed question.
+    const oldFields = Object.keys(oldAgg.fields).sort().join(" ");
+    const newFields = Object.keys(newAgg.schema).sort().join(" ");
+    if (oldFields === newFields) {
+      resolved[newAgg.id] = {
+        sid: oldAgg.sid,
+        was: [...(oldAgg.was ?? []), oldName],
+        priorFields: oldAgg.fields,
+        ...(priorSchemas?.[oldName] !== undefined ? { priorSchema: priorSchemas[oldName] } : {}),
+      };
+      inferred.push({ what: newAgg.id, from: oldName, to: newAgg.id, sid: oldAgg.sid });
+    }
+  }
+
+  // Per-aggregate field continuity (name match + the unambiguous field pair).
+  const aggregates: Record<string, StableAggregateId> = {};
+  for (const agg of currentAggregates) {
+    const r = resolved[agg.id];
+    const aggSid = r?.sid ?? mintAggregateSid(domainSid, agg.id);
+    const priorFields = r?.priorFields ?? {};
+    const fieldNames = Object.keys(agg.schema);
+    const fields: Record<string, StableFieldId> = {};
+    for (const f of fieldNames) {
+      const pf = priorFields[f];
+      if (pf !== undefined) {
+        fields[f] = { sid: pf.sid, ...(pf.was !== undefined ? { was: pf.was } : {}) };
+      }
+    }
+    const fDisappeared = Object.keys(priorFields).filter((n) => !fieldNames.includes(n));
+    const fAppeared = fieldNames.filter((n) => fields[n] === undefined);
+    if (fDisappeared.length === 1 && fAppeared.length >= 1) {
+      const oldF = fDisappeared[0]!;
+      // Shape gate for a field rename: the DRIVER (merge law) AND the KIND (read
+      // type) must be unchanged — a rename is a LABEL move. Among the appeared
+      // names, the pair binds IFF EXACTLY ONE matches the disappeared field's
+      // shape (so "rename + add a field" in one release still infers; two
+      // same-shaped appearances stay ambiguous — the evolve gate asks).
+      const priorDriver = priorFieldDriver(r, oldF);
+      const priorKind = priorFields[oldF]?.kind;
+      const candidates = fAppeared.filter((newF) => {
+        const driverOk =
+          priorDriver === undefined || priorDriver === JSON.stringify(agg.schema[newF]);
+        const newKind = agg.kinds?.[newF];
+        const kindOk = priorKind === undefined || newKind === undefined || priorKind === newKind;
+        return driverOk && kindOk;
+      });
+      if (candidates.length === 1) {
+        const newF = candidates[0]!;
+        const pf = priorFields[oldF]!;
+        fields[newF] = { sid: pf.sid, was: [...(pf.was ?? []), oldF] };
+        inferred.push({ what: `${agg.id}.${newF}`, from: oldF, to: newF, sid: pf.sid });
+      }
+    }
+    for (const f of fieldNames) {
+      if (fields[f] === undefined) fields[f] = { sid: mintFieldSid(aggSid, f) };
+    }
+    aggregates[agg.id] = {
+      sid: aggSid,
+      ...(r?.was !== undefined ? { was: r.was } : {}),
+      fields,
+    };
+  }
+
+  return { continuity: { v: 1, domain: domainSid, aggregates }, inferred };
+}
+
+/** The prior driver snapshot for a field, when the caller threaded the prior canonical
+ * manifest's schemas through `priorSchemas` (the stableIds block itself carries no
+ * drivers). Returns `undefined` (pair allowed on name-cardinality alone) when no
+ * snapshot is available. */
+function priorFieldDriver(
+  resolved: { priorSchema?: WireSchema } | undefined,
+  oldField: string,
+): string | undefined {
+  const schema = resolved?.priorSchema;
+  if (schema === undefined) return undefined;
+  const d = schema[oldField];
+  return d === undefined ? undefined : JSON.stringify(d);
+}
+
+/** Parse the `stableIds` block out of one PRIOR canonical-manifest JSON string —
+ * tolerant (absent/era-old manifests return `undefined`, never a throw). */
+export function stableIdsFromManifestJson(manifestJson: string): StableIds | undefined {
+  try {
+    const parsed = JSON.parse(manifestJson) as { stableIds?: StableIds };
+    const s = parsed.stableIds;
+    if (s && s.v === 1 && typeof s.domain === "string" && s.aggregates && typeof s.aggregates === "object") {
+      return s;
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/stable_ids_types.ts

@@ -0,0 +1,40 @@
+// 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.
+
+/**
+ * STABLE-ID TYPES (#58) — the pure type surface of `stable_ids.ts`, split out so the
+ * RUNTIME type graph (DomainModule's optional `stableIdContinuity`) never drags
+ * `node:crypto` into a tenant scaffold's typecheck (scaffolds compile without
+ * `@types/node`). The minting/derivation machinery lives in `stable_ids.ts`
+ * (build-time only — `nomos-compile` + `@githolon/dsl/manifest`).
+ */
+
+/** One field's stable identity: the minted sid + the labels it previously wore. */
+export interface StableFieldId {
+  readonly sid: string;
+  /** Prior labels of this sid, oldest first. OMITTED when the label never changed. */
+  readonly was?: string[];
+  /** The field's READ KIND (`string`/`int`/`json`/…): the retype arm of the evolve
+   * gate diffs it per sid (a driver change alone misses `t.string()` → `t.int()`).
+   * Always set at emission; continuity input may omit it (the current module is the
+   * source of the CURRENT kind). */
+  readonly kind?: string;
+}
+
+/** One aggregate's stable identity: sid + label lineage + per-field sids (keyed by CURRENT field name). */
+export interface StableAggregateId {
+  readonly sid: string;
+  readonly was?: string[];
+  readonly fields: Record<string, StableFieldId>;
+}
+
+/** A domain's full stable-id surface — the `stableIds` canonical-manifest key / `nomosStableIds` USD key. */
+export interface StableIds {
+  readonly v: 1;
+  /** The domain's own minted sid. */
+  readonly domain: string;
+  /** Aggregates keyed by CURRENT name (the label). */
+  readonly aggregates: Record<string, StableAggregateId>;
+}

package/src/usd.ts

@@ -188,6 +188,31 @@ export interface UsdLayer {
     /** Declared workspace invariants `{id, on}` the gate executes, sorted by id. */
     readonly workspaceInvariants?: { id: string; on: string }[];
   };
+  /**
+   * STABLE IDENTIFIERS (#58 — names are labels, identity is minted). The layer's
+   * domain/aggregate/field sids + label lineages, carried verbatim from the canonical
+   * manifest's `stableIds`. ALWAYS present on post-#58-compiled law (the one
+   * deliberate hash-mover); ABSENT on every bundle compiled before — the era key the
+   * EVOLVE GATE and the projection's sid-lineage fold switch on. A law-upgrade deploy
+   * whose old AND new packages both carry this key is DIFFED BY SID at the one gate.
+   */
+  readonly nomosStableIds?: import("./stable_ids_types.js").StableIds;
+  /**
+   * THE CAPTURED-READ GATE DECLARATION (#58). Present IFF ≥1 directive of this layer
+   * declares a captured-read query (`.reads(someQuery)`): the law's EXPLICIT opt-in
+   * to `nomos.read` at the one gate — the engine serves declared reads LIVE from the
+   * pre-apply state at author, replays the captured footprint at verify, and the gate
+   * RE-DERIVES each captured read at the pre-apply position (typed read-conflict on
+   * drift — CAS as law). OMITTED for read-free law (byte-identical hash — the exact
+   * `nomosInvariantGate` era discipline; bundles without the key behave as before).
+   */
+  readonly nomosReadGate?: {
+    readonly v: 1;
+    /** Every declared read query's recipe, keyed by query id. */
+    readonly queries: Record<string, { key: string[]; returns: string }>;
+    /** directive id → the SORTED query ids its plan may read. */
+    readonly directives: Record<string, string[]>;
+  };
 }
 
 /** The reserved variant name declaring a set's DEFAULT (USD has a default variant). */
@@ -267,12 +292,41 @@ export function emitUsd(
       const wsInvariants = [...(l.module.workspaceInvariants ?? [])]
         .map((w) => ({ id: w.id, on: w.on }))
         .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+      // THE CAPTURED-READ GATE DECLARATION (#58): collected from the canonical
+      // manifest's per-directive `capturedReads` (omit-when-empty — read-free law's
+      // USD is byte-identical apart from the always-on stableIds key).
+      const rgQueries = new Map<string, { key: string[]; returns: string }>();
+      const rgDirectives = new Map<string, string[]>();
+      for (const d of manifest.directives) {
+        if (d.capturedReads === undefined || d.capturedReads.length === 0) continue;
+        rgDirectives.set(d.id, d.capturedReads.map((r) => r.queryId));
+        for (const r of d.capturedReads) {
+          rgQueries.set(r.queryId, { key: [...r.key], returns: r.returns });
+        }
+      }
+      // SORTED-KEY records (byte-determinism — the layered flatten must reproduce
+      // these bytes exactly; see usd_layers.ts).
+      const readGateQueries: Record<string, { key: string[]; returns: string }> = {};
+      for (const k of [...rgQueries.keys()].sort()) readGateQueries[k] = rgQueries.get(k)!;
+      const readGateDirectives: Record<string, string[]> = {};
+      for (const k of [...rgDirectives.keys()].sort()) readGateDirectives[k] = rgDirectives.get(k)!;
       return {
         path: l.path,
         prims: encodeModuleToPrims(l.path, l.module),
         ...(manifest.queries !== undefined ? { queries: manifest.queries } : {}),
         ...(manifest.deriveds !== undefined ? { deriveds: manifest.deriveds } : {}),
         ...(manifest.combineds !== undefined ? { combineds: manifest.combineds } : {}),
+        // STABLE IDS (#58): every post-#58 compile carries them (the era key).
+        ...(manifest.stableIds !== undefined ? { nomosStableIds: manifest.stableIds } : {}),
+        ...(Object.keys(readGateDirectives).length > 0
+          ? {
+              nomosReadGate: {
+                v: 1 as const,
+                queries: readGateQueries,
+                directives: readGateDirectives,
+              },
+            }
+          : {}),
         ...(invariantAggregates.length > 0 || wsInvariants.length > 0
           ? {
               nomosInvariantGate: {

package/src/usd_layers.ts

@@ -340,6 +340,14 @@ export function usdaLayerText(
     `    {`,
     `        custom string nomos:kind = "domain"`,
     `        custom string nomos:domain = ${usdaString(domain)}`,
+    // STABLE IDS + the captured-read gate (#58): layer-level law keys, hex-carried
+    // so the .usda round-trips byte-faithfully to the IR layer.
+    ...(layer.nomosStableIds !== undefined
+      ? [`        custom string nomos:stableIdsHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosStableIds)))}`]
+      : []),
+    ...(layer.nomosReadGate !== undefined
+      ? [`        custom string nomos:readGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosReadGate)))}`]
+      : []),
     ``,
     ...body,
     `    }`,
@@ -456,12 +464,52 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
     const queries = foldById<UsdQuery>(stack.map((l) => l.queries));
     const deriveds = foldById<UsdDerived>(stack.map((l) => l.deriveds));
     const combineds = foldById<UsdCombined>(stack.map((l) => l.combineds));
+    // STABLE IDS (#58): fold per-module stableIds — domain sid from the latest
+    // declaring layer (they coincide by construction: one domain, one mint scope),
+    // aggregates merged later-wins per CURRENT name, SORTED keys (byte-determinism
+    // against the composed emission's sorted-aggregate insertion order).
+    let stableIds: UsdLayer["nomosStableIds"];
+    {
+      const aggs = new Map<string, NonNullable<UsdLayer["nomosStableIds"]>["aggregates"][string]>();
+      let domainSid: string | undefined;
+      for (const l of stack) {
+        if (l.nomosStableIds === undefined) continue;
+        domainSid = l.nomosStableIds.domain;
+        for (const [name, a] of Object.entries(l.nomosStableIds.aggregates)) aggs.set(name, a);
+      }
+      if (domainSid !== undefined) {
+        const aggregates: NonNullable<UsdLayer["nomosStableIds"]>["aggregates"] = {};
+        for (const k of [...aggs.keys()].sort()) aggregates[k] = aggs.get(k)!;
+        stableIds = { v: 1, domain: domainSid, aggregates };
+      }
+    }
+    // The captured-read gate (#58): queries + per-directive read sets merged
+    // later-wins, SORTED keys (matching the composed emission).
+    let readGate: UsdLayer["nomosReadGate"];
+    {
+      const q = new Map<string, { key: string[]; returns: string }>();
+      const d = new Map<string, string[]>();
+      for (const l of stack) {
+        if (l.nomosReadGate === undefined) continue;
+        for (const [id, spec] of Object.entries(l.nomosReadGate.queries)) q.set(id, spec);
+        for (const [id, reads] of Object.entries(l.nomosReadGate.directives)) d.set(id, reads);
+      }
+      if (d.size > 0) {
+        const queriesRec: Record<string, { key: string[]; returns: string }> = {};
+        for (const k of [...q.keys()].sort()) queriesRec[k] = q.get(k)!;
+        const directivesRec: Record<string, string[]> = {};
+        for (const k of [...d.keys()].sort()) directivesRec[k] = d.get(k)!;
+        readGate = { v: 1, queries: queriesRec, directives: directivesRec };
+      }
+    }
     return {
       path,
       prims: [...prims.keys()].sort().map((p) => prims.get(p)!),
       ...(queries !== undefined ? { queries } : {}),
       ...(deriveds !== undefined ? { deriveds } : {}),
       ...(combineds !== undefined ? { combineds } : {}),
+      ...(stableIds !== undefined ? { nomosStableIds: stableIds } : {}),
+      ...(readGate !== undefined ? { nomosReadGate: readGate } : {}),
     };
   });
 
@@ -579,9 +627,21 @@ function attrStringArray(prim: ParsedPrim, name: string): string[] {
 export function parseUsdaDocument(text: string): UsdDocument {
   const prims = parseUsdaPrims(text);
   const domainByScope = new Map<string, string>();
+  const stableIdsByDomain = new Map<string, UsdLayer["nomosStableIds"]>();
+  const readGateByDomain = new Map<string, UsdLayer["nomosReadGate"]>();
   for (const p of prims) {
     if (p.attrs.get("nomos:kind") === "domain") {
-      domainByScope.set(p.path, attrString(p, "nomos:domain"));
+      const domain = attrString(p, "nomos:domain");
+      domainByScope.set(p.path, domain);
+      // STABLE IDS + the captured-read gate (#58): the hex-carried layer-level keys.
+      const sidHex = p.attrs.get("nomos:stableIdsHex");
+      if (typeof sidHex === "string") {
+        stableIdsByDomain.set(domain, JSON.parse(unhexUtf8(sidHex)) as UsdLayer["nomosStableIds"]);
+      }
+      const rgHex = p.attrs.get("nomos:readGateHex");
+      if (typeof rgHex === "string") {
+        readGateByDomain.set(domain, JSON.parse(unhexUtf8(rgHex)) as UsdLayer["nomosReadGate"]);
+      }
     }
   }
 
@@ -669,12 +729,16 @@ export function parseUsdaDocument(text: string): UsdDocument {
   const layers: UsdLayer[] = [...buckets.keys()]
     .map((domain) => {
       const b = buckets.get(domain)!;
+      const sids = stableIdsByDomain.get(domain);
+      const rg = readGateByDomain.get(domain);
       return {
         path: `/Nomos/${domain}`,
         prims: [...b.prims].sort(byPath),
         ...(b.queries.length > 0 ? { queries: [...b.queries].sort(byId) } : {}),
         ...(b.deriveds.length > 0 ? { deriveds: [...b.deriveds].sort(byId) } : {}),
         ...(b.combineds.length > 0 ? { combineds: [...b.combineds].sort(byId) } : {}),
+        ...(sids !== undefined ? { nomosStableIds: sids } : {}),
+        ...(rg !== undefined ? { nomosReadGate: rg } : {}),
       };
     })
     .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));

package/src/wire_encode.ts

@@ -128,6 +128,21 @@ function encodeKernelFieldOp(op: FieldOp, field: Field | undefined): WireFieldOp
  *
  * `agg` is the directive's declared target handle, used to resolve field kinds
  * when encoding values; ops emitted to sibling aggregates encode by value-kind.
+ *
+ * ⚠️ THIS IS PLAN LOWERING ONLY — NOT A DOMAIN TEST HARNESS. It runs your
+ * directive's `plan()` and encodes the resulting ops into the wire Intent shape.
+ * It does NOT touch the kernel: it does not admit through the gate (no
+ * invariants, no minted-id check, no terminal-once, no captured reads), it does
+ * not fold state, and it requires a hand-provided `ctx` (`deterministicPorts`)
+ * with a stub `nomos.mint`. Use it to ASSERT THE BYTES a plan lowers to (the
+ * `impure_capability`/`capability` lowering tests are the canonical use), never
+ * to test domain LIFECYCLE.
+ *
+ * For a KERNEL-BACKED local harness — admission through the real gate, folds,
+ * reads, the whole lifecycle on the same engine plane the cloud edge runs — use
+ * the CLI: `githolon proof` (the generated proof's offline legs on a local
+ * holon) and `githolon dev` (the watch→recompile→law-live→proof inner loop).
+ * Those mint ids, run the gate, and fold — exactly what this function does NOT.
  */
 export function executeDirectiveToIntent<P>(
   directive: Directive<P>,