@githolon/dsl 0.3.0 → 0.5.0

package/src/framework/capability.ts

@@ -0,0 +1,215 @@
+// 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.
+
+/**
+ * framework/capability.ts — `capability()`: THE MARKETPLACE DECLARATION
+ * (`architecture/capability_marketplace.md` §4, ruling M2 — the framework-hidden
+ * lane). ONE call declares a typed Order→Receipt capability interface; the dev
+ * sees a typed order call and a typed task row, and the framework supplies
+ * everything else through the SHIPPED `impureCapability()` quartet — so the gate
+ * law (`check_order_receipt`), the kernel recognizer, codegen, and the stable-id
+ * lockfile all see a perfectly ordinary impure capability. Hidden means *not
+ * hand-rolled*, never *not auditable*: the Order and Receipt facts ride the
+ * ledger verbatim.
+ *
+ * ```ts
+ * export const llm = capability("llm.complete", {
+ *   request: { prompt: t.string(), model: t.string(), maxTokens: t.int() },
+ *   receipt: { tokensIn: t.int(), tokensOut: t.int() },
+ * });
+ * // derived, deterministically from the name:
+ * //   aggregate  LlmCompleteTask        order      orderLlmComplete
+ * //   complete   completeLlmComplete    fail/block/deadLetter likewise
+ * //   capability "llm.complete"         (the CapabilityBinding the executor must hold)
+ * ```
+ *
+ * THE RECEIPT-FIELD MECHANISM (stated honestly — the sheet's §4 comment): the
+ * complete Receipt's payload is the framework-FIXED `{requestId, resultRef,
+ * completedAt}`; typed receipt VALUES ride INSIDE `resultRef` as a JSON object,
+ * and the generated `completeResult` ops decode them into the declared typed
+ * fields (per-field zod-validated IN the plan — a malformed executor result is a
+ * typed plan-halt refusal, never a silent partial fold). Receipt fields are
+ * auto-`.optional()` on the aggregate (absent while `requested` — the
+ * read-decode discipline). Large bodies belong in content-addressed
+ * `resultRef`/`resultEvidence` refs, not inline values.
+ *
+ * Naming: the capability name uses the shipped binding grammar
+ * (`^[a-z0-9][a-z0-9._-]{0,63}$` — dots legal; marketplace interfaces are
+ * dot-namespaced by convention) and is carried as the quartet's `capability`
+ * declaration — the `CapabilityBinding` the fulfilling executor must hold
+ * (`architecture/capability_credentials.md`).
+ */
+import { z } from "zod";
+import { instance } from "../aggregate.js";
+import type { Field } from "../fields.js";
+import { set, type PlannedOp } from "../ops.js";
+import { query, type QueryDecl } from "../query.js";
+import {
+  IMPURE_CAPABILITY_ENVELOPE,
+  impureCapability,
+  impureCapabilityAggregate,
+  impureCapabilityInstanceId,
+  type ImpureCapability,
+} from "./impure_capability.js";
+
+/** The shipped CapabilityBinding name grammar (worker + governance law agree). */
+export const CAPABILITY_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+
+/** "llm.complete" → "LlmComplete" — the deterministic id stem. */
+export function capabilityPascal(name: string): string {
+  return name
+    .split(/[._-]+/)
+    .filter(Boolean)
+    .map((part) => part[0]!.toUpperCase() + part.slice(1))
+    .join("");
+}
+
+/** The zod RAW SHAPE derived from request fields (each Field carries its own zod). */
+type RequestShape<Req extends Record<string, Field>> = { [K in keyof Req]: Req[K]["zod"] };
+
+/**
+ * What `capability()` returns: the full shipped quartet (so every existing
+ * consumer — codegen, lowering, the reactor helpers — works unchanged) plus the
+ * marketplace surface: the capability NAME and the request/receipt zod schemas
+ * (the executor side validates provider results against `receiptSchema` BEFORE
+ * building `resultRef`, so a refusal happens host-side first, gate-side always).
+ */
+export interface CapabilityDecl<
+  Req extends Record<string, Field>,
+  Rec extends Record<string, Field>,
+> extends ImpureCapability<string, RequestShape<Req>, Req & Rec> {
+  /** The capability name — the `CapabilityBinding` slot the executor must hold. */
+  readonly name: string;
+  /** The request fields' zod object (what `order<Pascal>`'s params validate as). */
+  readonly requestSchema: z.ZodObject<RequestShape<Req>>;
+  /**
+   * THE EXECUTOR'S SCAN LANE — a declared, indexed query over the task
+   * aggregate keyed on `status` (`<camelPascal>TasksByStatus`). The executor
+   * polls `{status: "requested"}` through the ordinary RPC query lane — no
+   * special scan op, no wasm arm: the projection index IS the work queue.
+   */
+  readonly tasks: QueryDecl;
+  /** The receipt fields' zod object — `{}` when the capability declares none. */
+  readonly receiptSchema: z.ZodObject<{ [K in keyof Rec]: Rec[K]["zod"] }>;
+  /** Build the `resultRef` JSON for a complete Receipt from typed receipt values. */
+  readonly encodeResult: (values: { [K in keyof Rec]: z.infer<Rec[K]["zod"]> }) => string;
+}
+
+/**
+ * Declare a typed marketplace capability. Sugar over {@link impureCapability} —
+ * nothing new on the wire; the one piece of REAL work it adds is the
+ * resultRef-decoding `completeResult` (the receipt-field mechanism above).
+ *
+ * Refusals are COMPILE-TIME loud (thrown at module load, so `nomos-compile`
+ * names them): a malformed name, a request/receipt field shadowing the reserved
+ * envelope, or a field declared on both sides.
+ */
+export function capability<
+  const Name extends string,
+  Req extends Record<string, Field>,
+  Rec extends Record<string, Field> = Record<never, Field>,
+>(name: Name, spec: { request: Req; receipt?: Rec }): CapabilityDecl<Req, Rec> {
+  if (!CAPABILITY_NAME_RE.test(name)) {
+    throw new Error(
+      `capability('${name}'): the name must match ${CAPABILITY_NAME_RE} (lowercase, dot-namespaced — e.g. 'llm.complete'); it doubles as the CapabilityBinding slot the executor must hold`,
+    );
+  }
+  const reserved = new Set(Object.keys(IMPURE_CAPABILITY_ENVELOPE));
+  const receipt = (spec.receipt ?? {}) as Rec;
+  for (const [side, fields] of [
+    ["request", spec.request],
+    ["receipt", receipt],
+  ] as const) {
+    for (const k of Object.keys(fields)) {
+      if (reserved.has(k)) {
+        throw new Error(
+          `capability('${name}'): ${side} field '${k}' shadows the reserved Order→Receipt envelope — rename it (the envelope is framework law: ${[...reserved].join(", ")})`,
+        );
+      }
+    }
+  }
+  for (const k of Object.keys(receipt)) {
+    if (k in spec.request) {
+      throw new Error(
+        `capability('${name}'): '${k}' is declared on BOTH request and receipt — a field has one writer (the order writes requests, the complete Receipt writes receipts); split or rename it`,
+      );
+    }
+  }
+
+  const pascal = capabilityPascal(name);
+  const aggregateId = `${pascal}Task`;
+
+  // Receipt fields fold only when the complete Receipt lands — auto-`.optional()`
+  // so a freshly-ordered task decodes on the generated read type (the same
+  // read-decode discipline the envelope's own optionals follow).
+  const receiptFields = Object.fromEntries(
+    Object.entries(receipt).map(([k, f]) => [k, f.optional()]),
+  ) as Rec;
+  const params = { ...spec.request, ...receiptFields } as Req & Rec;
+  const taskAggregate = impureCapabilityAggregate(aggregateId, params);
+
+  const requestShape = Object.fromEntries(
+    Object.entries(spec.request).map(([k, f]) => [k, f.zod]),
+  ) as RequestShape<Req>;
+  const receiptShape = Object.fromEntries(
+    Object.entries(receipt).map(([k, f]) => [k, f.zod]),
+  ) as { [K in keyof Rec]: Rec[K]["zod"] };
+  const receiptEntries = Object.entries(receipt) as [string, Field][];
+
+  const quartet = impureCapability({
+    aggregateId,
+    orderDirectiveId: `order${pascal}`,
+    completeDirectiveId: `complete${pascal}`,
+    failDirectiveId: `fail${pascal}`,
+    blockDirectiveId: `block${pascal}`,
+    deadLetterDirectiveId: `deadLetter${pascal}`,
+    params,
+    paramsSchema: requestShape,
+    // The loop is dynamic (declared field names), so the per-field `set()` typing
+    // is asserted — the PUBLIC payload types stay fully inferred from the zod shape.
+    writeParams: (taskId, p) =>
+      Object.keys(spec.request).map((k) =>
+        set(instance(taskAggregate, taskId), k as never, (p as Record<string, unknown>)[k] as never),
+      ),
+    // The receipt-field mechanism: typed values ride INSIDE resultRef as JSON;
+    // decode + per-field zod-validate IN the plan (pure function of payload —
+    // deterministic; a malformed executor result is a typed plan-halt refusal).
+    // Absent keys are skipped (partial results are legal — read-decode
+    // discipline), present keys must validate.
+    ...(receiptEntries.length > 0
+      ? {
+          completeResult: (taskId: string, resultRef: string): PlannedOp[] => {
+            const decoded = JSON.parse(resultRef) as Record<string, unknown>;
+            const ops: PlannedOp[] = [];
+            for (const [k, f] of receiptEntries) {
+              if (decoded[k] === undefined) continue;
+              ops.push(set(instance(taskAggregate, taskId), k as never, f.zod.parse(decoded[k]) as never));
+            }
+            return ops;
+          },
+        }
+      : {}),
+    capability: name,
+  });
+
+  const camel = pascal[0]!.toLowerCase() + pascal.slice(1);
+  const tasks = query(`${camel}TasksByStatus`).key("status").returns(taskAggregate);
+
+  return {
+    ...quartet,
+    aggregate: taskAggregate,
+    instanceId: impureCapabilityInstanceId,
+    name,
+    requestSchema: z.object(requestShape),
+    receiptSchema: z.object(receiptShape),
+    encodeResult: (values) => JSON.stringify(z.object(receiptShape).parse(values)),
+    tasks,
+    // The one-export expansion tag (capability_exports.ts): every exports walk
+    // discovers this bundle's aggregate + quartet + scan query without re-exports.
+    __isCapabilityDecl: true,
+  } as CapabilityDecl<Req, Rec>;
+}

package/src/framework/impure_capability.ts

@@ -136,9 +136,10 @@ export const IMPURE_CAPABILITY_ENVELOPE = {
   // GENERIC, written by every impureCapability Receipt (complete OR fail), so the read
   // projection answers "is Order O closed, by which Receipt, with what result" in O(1)
   // off the `(closesOrder, order_id)` index — never a ledger scan. Absent while
-  // `requested` (a fresh order has no closing receipt). Wire-identical to the Rust
-  // reactor's `closesOrder` op (`git-holon::reactor::receipt_intent`,
-  // `kernel::manifest_view::IMPURE_CAPABILITY_RECEIPT_FIELDS`).
+  // `requested` (a fresh order has no closing receipt). The kernel supplies its
+  // framework-fixed Lww driver (`kernel::manifest_view::IMPURE_CAPABILITY_RECEIPT_FIELDS`)
+  // and the gate enforces the lifecycle around it (`nomos_executor::check_order_receipt` —
+  // admit step 5.5: OrphanReceipt / ReceiptOnTerminalOrder, terminal-once as law).
   closesOrder: t.string().merge(Lww).optional(),
 } as const;
 
@@ -348,6 +349,18 @@ export interface ImpureCapability<
   readonly block: RequirableDirective<z.infer<typeof blockSchema>>;
   readonly deadLetter: RequirableDirective<z.infer<typeof deadLetterSchema>>;
   readonly instanceId: (requestId: string) => string;
+  /**
+   * The CAPABILITY CREDENTIAL this task's provider must hold to fulfil Orders
+   * (`architecture/capability_credentials.md`): the law name of a
+   * `CapabilityBinding` — e.g. `"openai"`, `"cf-analytics"` — bound per
+   * workspace via the bind lane (`githolon capability bind <ws> <name>`). The
+   * provider HOST resolves `(workspace, capability)` → the credential VALUE
+   * from its own store, fail-closed against the law fact (active, unexpired);
+   * the value never rides an intent and never appears here. DECLARATION
+   * METADATA only — absent (the default) changes nothing on the wire, so
+   * credential-free domains stay byte-identical.
+   */
+  readonly capability?: string;
 }
 
 /**
@@ -429,6 +442,12 @@ export function impureCapability<
    * the Rust reactor's `result_fields` (`HandlerSuccess::with_result_field`).
    */
   completeResult?: (taskInstanceId: string, resultRef: string) => PlannedOp[];
+  /**
+   * OPTIONAL: the capability-credential name the provider host must hold a
+   * law-state `CapabilityBinding` for (see {@link ImpureCapability.capability}).
+   * Omit-when-absent — declaring nothing changes nothing on the wire.
+   */
+  capability?: string;
 }): ImpureCapability<Id, ParamsShape, F> {
   const taskAggregate = impureCapabilityAggregate(spec.aggregateId, spec.params);
 
@@ -489,6 +508,9 @@ export function impureCapability<
     block,
     deadLetter,
     instanceId: impureCapabilityInstanceId,
+    // Omit-when-absent (hash discipline): a capability-free declaration carries
+    // NO key at all, so its bundled source — and the package hash — is unchanged.
+    ...(spec.capability !== undefined ? { capability: spec.capability } : {}),
   };
 }
 

package/src/framework/workspaces.ts

@@ -1,3 +1,7 @@
+// governance-law revision: capability bindings 2026-06-12 (facts about authority on the
+// ledger, authority itself host-side — architecture/capability_credentials.md). Carries
+// the founding-key-rotation re-entry forward (genesis re-seeds idempotently by hash).
+export const GOVERNANCE_REVISION = "2026-06-12-capability-bindings"; // hash-bearing: re-enters root genesis idempotently
 // 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
@@ -203,6 +207,15 @@ export const CloudPolicy = aggregate("CloudPolicy", {
   maxWorkspacesPerPrincipal: t.int().merge(Lww),
   /** Cumulative pushed-bytes cap per workspace ledger (bytes). */
   workspaceByteCap: t.int().merge(Lww),
+  /**
+   * The workspace-CREATION posture dial (cloud_sovereignty.md S6) —
+   * `"open"` (anyone creates), `"invite"` (an active CreationGrant key
+   * required), or `"closed"` (admins only). OPTIONAL: absent keeps the
+   * implicit posture the cloud has always had (zero active CreationGrants ⇒
+   * open, any ⇒ invite-governed) — pre-dial chains and policies behave
+   * exactly as before.
+   */
+  creationPosture: t.string().merge(Lww).optional(),
   /** Who last set the policy (attribution). */
   setBy: t.string().merge(Lww),
   /** Epoch-ms the policy was last set (caller-stamped). */
@@ -245,6 +258,47 @@ export const PlatformGrant = aggregate("PlatformGrant", {
   status: t.enum(GRANT_STATUSES).merge(Lww),
 });
 
+/**
+ * CapabilityBinding — A FACT ABOUT AUTHORITY, never authority itself (the
+ * doctrine: `architecture/capability_credentials.md`). A workspace's impure
+ * capabilities (analytics tokens, provider API keys, upload credentials) need
+ * credentials — and credentials are constitutionally incompatible with a
+ * replicated chain (every peer would hold them forever; git never forgets;
+ * revocation cannot recall bytes). So the LEDGER records only the binding fact:
+ * WHICH workspace bound WHICH capability under WHICH credential digest
+ * (`keyHash` — the AdminGrant discipline, again), with what scope/expiry, by
+ * whom, at which `epoch`. The credential VALUE lives at exactly ONE
+ * credential-holding host (the workspace DO's storage, keyed
+ * `(workspace, capability)`), is never passed host-to-host, and is unusable
+ * the moment the law flips this record — the executing host checks the law
+ * fail-closed before every use.
+ *
+ * EPOCHS ARE PROVENANCE: a rotation revokes the active record and creates the
+ * next one (`epoch + 1`, fresh `keyHash`) — so every Receipt fact a provider
+ * stamps can name the binding epoch that produced it, and "which credential
+ * produced which facts" is answerable forever from law-state alone.
+ */
+export const CapabilityBinding = aggregate("CapabilityBinding", {
+  /** The bound workspace's CloudWorkspace AGGREGATE id (root-custody lineage). */
+  workspaceId: t.string().merge(Lww),
+  /** The capability's law name (e.g. "cf-analytics", "openai", "gcs-upload"). */
+  capability: t.string().merge(Lww),
+  /** sha256 hex of the credential VALUE — the value itself NEVER lands here. */
+  keyHash: t.string().merge(Lww),
+  /** Monotone per (workspace, capability): 1, 2, … — rotation provenance. */
+  epoch: t.int().merge(Lww),
+  /** OPTIONAL narrowing label ("read-only", an account tag, …); absent = whole capability. */
+  scope: t.string().merge(Lww).optional(),
+  /** OPTIONAL epoch-ms expiry; absent = until revoked. Expired = fail-closed at the host. */
+  expiresAt: t.int().merge(Lww).optional(),
+  /** Who bound it (attribution, on the ledger forever). */
+  boundBy: t.string().merge(Lww),
+  /** Epoch-ms the binding was authored (caller-stamped). */
+  boundAt: t.int().merge(Lww),
+  /** `active` | `revoked` — the law's kill switch for the credential's USE. */
+  status: t.enum(GRANT_STATUSES).merge(Lww),
+});
+
 // --- workspace directives ---------------------------------------------------------
 
 /**
@@ -607,6 +661,66 @@ export const releaseHostname = directive("releaseHostname")
     return [set(c, "status", "released" as const)];
   });
 
+/**
+ * bindCapability — record the FACT that a workspace holds a capability
+ * credential (worker-authored after the value is stored host-side; the value
+ * itself takes the other road — DO storage — and NEVER this one). The payload's
+ * only credential-shaped field is `keyHash`, regex-pinned to sha256 hex: a raw
+ * secret value structurally cannot enter this directive. `scope`/`expiresAt`
+ * are omit-when-absent — a scope-free, expiry-free binding writes neither field.
+ */
+export const bindCapability = directive("bindCapability")
+  .creates(CapabilityBinding)
+  .payload(
+    z.object({
+      workspaceId: z.string().min(1),
+      /** Lowercase capability name — a law identifier, not free text. */
+      capability: z.string().regex(/^[a-z0-9][a-z0-9._-]{0,63}$/, "expected a lowercase capability name ([a-z0-9._-], max 64)"),
+      keyHash: sha256Hex,
+      epoch: z.number().int().positive(),
+      scope: z.string().min(1).optional(),
+      expiresAt: epochMs.optional(),
+      boundBy: z.string().min(1),
+      boundAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    const b = create(CapabilityBinding)
+      .set("workspaceId", p.workspaceId)
+      .set("capability", p.capability)
+      .set("keyHash", p.keyHash)
+      .set("epoch", p.epoch)
+      .set("boundBy", p.boundBy)
+      .set("boundAt", p.boundAt)
+      .set("status", "active" as const);
+    // Omit-when-absent: optional facts fold only when the payload carries them.
+    if (p.scope !== undefined) b.set("scope", p.scope);
+    if (p.expiresAt !== undefined) b.set("expiresAt", p.expiresAt);
+    return [];
+  });
+
+/**
+ * revokeCapability — flip a CapabilityBinding to `revoked`. The credential
+ * stops being USABLE at fold time (the executing host checks this record,
+ * fail-closed, before resolving the value); the record (who bound it, when,
+ * who killed it — the revoker rides the intent) stays on the ledger — audit is
+ * structural. Rotation = revoke + bind at `epoch + 1`; unbind = revoke + the
+ * host deletes the stored value.
+ */
+export const revokeCapability = directive("revokeCapability")
+  .mutates(CapabilityBinding)
+  .payload(
+    z.object({
+      bindingId: z.string().min(1),
+      revokedBy: z.string().min(1),
+      revokedAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    const b = instance(CapabilityBinding, p.bindingId);
+    return [set(b, "status", "revoked" as const)];
+  });
+
 /**
  * setCloudPolicy — set (or amend) THE QUOTA LAW. An Ensure on the law-state
  * singleton: the first author births it, later authors amend it in place —
@@ -618,6 +732,10 @@ export const setCloudPolicy = directive("setCloudPolicy")
     z.object({
       maxWorkspacesPerPrincipal: z.number().int().positive(),
       workspaceByteCap: z.number().int().positive(),
+      // The creation-posture dial (cloud_sovereignty.md S6). Optional:
+      // omitted leaves the field untouched (a partial amend never silently
+      // resets the door).
+      creationPosture: z.enum(["open", "invite", "closed"]).optional(),
       setBy: z.string().min(1),
       setAt: epochMs,
     }),
@@ -628,6 +746,7 @@ export const setCloudPolicy = directive("setCloudPolicy")
       withMarker(set(pol, "scope", "cloud"), "ensures"),
       set(pol, "maxWorkspacesPerPrincipal", p.maxWorkspacesPerPrincipal),
       set(pol, "workspaceByteCap", p.workspaceByteCap),
+      ...(p.creationPosture !== undefined ? [set(pol, "creationPosture", p.creationPosture)] : []),
       set(pol, "setBy", p.setBy),
       set(pol, "setAt", p.setAt),
     ];
@@ -815,3 +934,13 @@ export const hostnameClaimByHostname = query("hostnameClaimByHostname")
 export const hostnameClaimsByWorkspace = query("hostnameClaimsByWorkspace")
   .key("workspaceId")
   .returns(HostnameClaim);
+
+/** A workspace's capability bindings — the executor's fail-closed law probe AND the audit list. */
+export const capabilityBindingsByWorkspace = query("capabilityBindingsByWorkspace")
+  .key("workspaceId")
+  .returns(CapabilityBinding);
+
+/** Provenance: which binding (workspace, capability, epoch) a credential digest belongs to. */
+export const capabilityBindingByKeyHash = query("capabilityBindingByKeyHash")
+  .key("keyHash")
+  .returns(CapabilityBinding);

package/src/index.ts

@@ -66,6 +66,9 @@ export { create, existing, type AggregateRef } from "./authoring.js";
 // THE CAPTURED READ — a plan reads O(1) DSL queries via `read(query, args)`; the result is committed as
 // the intent's read footprint (deterministic replay + stale-premise detection). The dev calls typed DSL
 // queries; the library routes them here. The host capability is `nomos.read` (twin of `nomos.rng`).
+// NOT YET DEPLOYABLE (#57): the sealed wasm engine does not provide `nomos.read` yet, so
+// `nomos-compile` REFUSES law that references read() (a named compile error, never a runtime halt).
+// The captured-reads wave (task #58) wires the capability in and lifts the refusal.
 export { read } from "./read.js";
 export {
   query,
@@ -216,6 +219,12 @@ export {
   type TaskOutcome,
   type TaskReceipt,
 } from "./framework/impure_capability.js";
+export {
+  capability,
+  capabilityPascal,
+  CAPABILITY_NAME_RE,
+  type CapabilityDecl,
+} from "./framework/capability.js";
 export {
   DOMAIN_INSTALLATION_PHASES,
   PolicyBundle,

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). */
@@ -334,6 +360,12 @@ export interface CanonicalExtremum {
   readonly where?: CanonicalPred;
   /** The group-by field. OMITTED for a grand-total extremum. */
   readonly by?: string;
+  /** THE ESTATE SCOPE (sharding §5, slice 8) — see {@link CanonicalCount.scope}:
+   *  per-shard extremums ride the §5.2 delta lane as gate-adjudicated coordinator
+   *  subtotals (extremize-on-monotone; retractions re-derive). OMITTED for
+   *  home-scope extremums, so an unscoped declaration is byte-identical to before
+   *  this key existed (golden hashes UNCHANGED). */
+  readonly scope?: string;
 }
 
 /**
@@ -372,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
@@ -630,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[] } {
@@ -841,14 +902,17 @@ function canonicalExtrema(
 ): { mins?: CanonicalExtremum[] } | { maxes?: CanonicalExtremum[] } {
   if (declared === undefined || declared.length === 0) return {};
   const items: CanonicalExtremum[] = [...declared]
-    .map(finishExtremum)
-    .map((e) => ({
+    .map((raw) => ({ finished: finishExtremum(raw), scope: (raw as { scope?: unknown }).scope }))
+    .map(({ finished: e, scope }) => ({
       id: e.id,
       kind: e.kind,
       of: e.of,
       valueField: e.valueField,
       ...(e.where !== undefined ? { where: e.where } : {}),
       ...(e.by !== undefined ? { by: e.by } : {}),
+      // OMIT-WHEN-ABSENT (the canonicalSums discipline): a home-scope extremum is
+      // byte-identical to before the scope key existed — hash-stable by default.
+      ...(typeof scope === "string" ? { scope } : {}),
     }))
     .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
   return { [keyName]: items };
@@ -879,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
@@ -910,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),
@@ -930,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),