@githolon/dsl 0.4.0 → 0.5.1

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,24 @@ 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, minted ids, the whole lifecycle on the same engine plane the cloud
+ * edge runs — use the CLI, NOT this function:
+ *   • `githolon dev --once` — ONE compile → law-live-locally → proof cycle, then
+ *     exit (the CI/smoke lane for lifecycle + id-mint tests — a non-zero exit
+ *     names the jam). `githolon dev` (no flag) is the same on a watch loop.
+ *   • `githolon proof` — the generated proof's offline legs on a local holon.
+ * Those mint ids, run the gate, and fold — exactly what this function does NOT.
  */
 export function executeDirectiveToIntent<P>(
   directive: Directive<P>,