@githolon/dsl 0.3.0 → 0.5.0

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;
@@ -242,7 +259,8 @@ function isCountDecl(v: unknown): v is AnyCount {
     typeof o.on !== "string" && // spatial
     typeof o.fn !== "function" && // derived/combined
     !Array.isArray(o.key) && // query
-    !("field" in o) && // extremum
+    !("field" in o) && // extremum (wire-descriptor shape)
+    !("valueField" in o) && // extremum (the ExtremumDecl/Extremum-builder mark — never a count)
     !("sumField" in o) && // sum (the SumDecl/Sum-builder mark — never a count)
     !("orderBy" in o) && // ordered read
     !("_existsMarker" in o) && // exists
@@ -469,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) {
@@ -491,7 +528,12 @@ 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[] = [];
     let shardingModForDomain: Mod | undefined;
     let shardingLazyExpr: string | undefined;
 
@@ -552,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" &&
@@ -562,6 +604,20 @@ async function main(): Promise<void> {
             typeof (v as { of?: unknown }).of === "string" &&
             typeof (v as { sumField?: unknown }).sumField === "string",
         );
+        // SLICE 8: the derived sharding law's MAINTAINED EXTREMUMS — the estate
+        // min/max over subtotal rows (`nomosEstateExtremumMin/Max`, extremize over
+        // per-shard committed values) — thread through the same explicit lane.
+        const shardingExtrema = (kind: "min" | "max"): AnyExtremum[] =>
+          Object.values(shardingMod).filter(
+            (v): v is AnyExtremum =>
+              !!v && typeof v === "object" &&
+              typeof (v as { id?: unknown }).id === "string" &&
+              typeof (v as { of?: unknown }).of === "string" &&
+              typeof (v as { valueField?: unknown }).valueField === "string" &&
+              (v as { kind?: unknown }).kind === kind,
+          );
+        shardingMins = shardingExtrema("min");
+        shardingMaxes = shardingExtrema("max");
         const specJson = JSON.stringify(spec);
         if (eagerLump) {
           if (!entryImports.some((l) => l.includes("workspace-sharding"))) {
@@ -635,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];
-    const mins = resolveNamed<AnyExtremum>(merged, d.mins, "mins");
-    const maxes = resolveNamed<AnyExtremum>(merged, d.maxes, "maxes");
-    const impureCapabilities = resolveNamed<ImpureCapabilityDecl>(
+    // 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];
+    // `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):
@@ -709,7 +798,7 @@ async function main(): Promise<void> {
           }
         } catch { /* already failed above */ }
       }
-      for (const read of [...(composed.counts ?? []), ...(composed.sums ?? [])]) {
+      for (const read of [...(composed.counts ?? []), ...(composed.sums ?? []), ...(composed.mins ?? []), ...(composed.maxes ?? [])]) {
         const scope = (read as { scope?: unknown }).scope;
         if (scope === undefined) continue;
         const id = (read as { id?: unknown }).id;
@@ -787,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 ?? {})) {
@@ -914,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
@@ -1036,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],
     })),
   };
@@ -1045,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");
@@ -1070,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`,
@@ -1112,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(
@@ -1139,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`);
   }

package/src/directive.ts

@@ -21,6 +21,7 @@ import type { PlannedOp } from "./ops.js";
 import type { Ports } from "./ctx.js";
 import type { CertifiedReadDecl } from "./certified_read.js";
 import type { RelationDecl } from "./relation.js";
+import type { QueryDecl } from "./query.js";
 
 export type ReferentialMarker = "creates" | "mutates" | "ensures" | "archives";
 
@@ -70,6 +71,18 @@ export interface Directive<P = unknown> {
    * (read ⊆ declared) is a SEPARATE later step; here it only DECLARES.
    */
   readonly declaredReads: string[];
+  /**
+   * The directive's DECLARED CAPTURED-READ queries (#58 — the captured-read lane):
+   * the O(1) DSL-defined queries its `plan` may `read()` on the write path. Each is a
+   * declared, indexed {@link QueryDecl}; the gate serves `nomos.read` LIVE from the
+   * pre-apply committed state at author, replays the captured result at verify, and
+   * RE-DERIVES it at the pre-apply position for the read-conflict (CAS-as-law) check.
+   * Same-workspace only, size-bounded. Defaults to `[]` (no captured reads — the
+   * engine then provides no `nomos.read`, exactly the pre-#58 posture). OPTIONAL +
+   * ADDITIVE (a hand-built directive object without it is a read-free directive);
+   * OMITTED from the canonical manifest when empty (hash-stable for read-free directives).
+   */
+  readonly declaredQueryReads?: QueryDecl[];
   /**
    * The directive's DECLARED emit boundary: the event types its `plan` may EMIT,
    * each with an optional `max` bound. Part of the domain identity. Defaults to `{}`
@@ -130,13 +143,18 @@ export interface RequirableDirective<P> extends Directive<P> {
    */
   requires(capability?: string, scopeFrom?: ScopeFrom<P>): RequirableDirective<P>;
   /**
-   * Declare the directive's READ boundary: the ref types its `plan` may read. Callable
-   * MULTIPLE times to accumulate; results are deduped + sorted on the directive's
-   * `declaredReads`. Purely additive — a directive that never calls this declares no
-   * reads (`[]`) and is byte-identical in the canonical manifest to before this existed.
-   * Returns a NEW requirable directive (non-destructive).
+   * Declare the directive's READ boundary. TWO argument kinds, one declaration site:
+   *   * a STRING declares a ref TYPE its `plan` may read (the original boundary —
+   *     deduped + sorted on `declaredReads`);
+   *   * a {@link QueryDecl} declares a CAPTURED-READ query (#58): an O(1) DSL query
+   *     its `plan` may `read()` on the write path — served live at author from the
+   *     pre-apply state, captured onto the intent, replayed + CAS-re-derived at every
+   *     later gate (deduped by query id on `declaredQueryReads`).
+   * Callable MULTIPLE times to accumulate. Purely additive — a directive that never
+   * calls this declares no reads and is byte-identical in the canonical manifest to
+   * before this existed. Returns a NEW requirable directive (non-destructive).
    */
-  reads(...refTypes: string[]): RequirableDirective<P>;
+  reads(...reads: (string | QueryDecl)[]): RequirableDirective<P>;
   /**
    * Declare ONE entry of the directive's EMIT boundary: an `eventType` its `plan` may
    * emit, with an optional `max` count bound. Callable MULTIPLE times to accumulate
@@ -239,6 +257,7 @@ class DirectivePlanStep<Id extends string, P> {
       payloadSchema: this.payloadSchema,
       plan: fn,
       declaredReads: [],
+      declaredQueryReads: [],
       declaredEmits: {},
       declaredCertifiedReads: {},
       declaredRelations: [],
@@ -263,11 +282,17 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
         ...(scopeFrom !== undefined ? { scopeFrom } : {}),
       });
     },
-    reads(...refTypes: string[]): RequirableDirective<P> {
-      // Accumulate onto any prior reads, dedup, sort — order is incidental to the
-      // declared boundary; only the SET of read ref types is the contract.
+    reads(...reads: (string | QueryDecl)[]): RequirableDirective<P> {
+      // Split by argument kind: strings are the ref-type boundary; QueryDecls are the
+      // captured-read lane (#58). Both accumulate, dedup (ref types by value, queries
+      // by id — later decl wins), sort — only the SET is the contract.
+      const refTypes = reads.filter((r): r is string => typeof r === "string");
+      const queryDecls = reads.filter((r): r is QueryDecl => typeof r !== "string");
       const merged = [...new Set([...base.declaredReads, ...refTypes])].sort();
-      return makeRequirable({ ...base, declaredReads: merged });
+      const byId = new Map<string, QueryDecl>((base.declaredQueryReads ?? []).map((q) => [q.id, q]));
+      for (const q of queryDecls) byId.set(q.id, q);
+      const mergedQueries = [...byId.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+      return makeRequirable({ ...base, declaredReads: merged, declaredQueryReads: mergedQueries });
     },
     emits(eventType: string, opts?: { max?: number }): RequirableDirective<P> {
       // Accumulate one event type onto any prior emits; a `max` bound is recorded only

package/src/engine_entry.ts

@@ -52,6 +52,7 @@
  * tenant package for the long-form rationale of each branch.
  */
 import { executeDirectiveToIntent } from "./wire_encode.js";
+import { expandCapabilityExports } from "./capability_exports.js";
 import type { Directive } from "./directive.js";
 import type { AggregateHandle, AggregateInvariantFn, AggregateInvariantVerdict } from "./aggregate.js";
 import type { Ports } from "./ctx.js";
@@ -200,7 +201,10 @@ function combinedsOf(mod: DomainModuleExports): CombinedDecl[] {
 function mergeModules(mods: readonly DomainModuleExports[]): DomainModuleExports {
   let merged: DomainModuleExports = {};
   for (const m of mods) merged = { ...merged, ...m };
-  return merged;
+  // `capability()` bundles expand into discoverable entries here — the engine
+  // plane's ONE merge point, so the registry sees the task aggregate + quartet
+  // without per-piece re-exports (capability_exports.ts).
+  return expandCapabilityExports(merged);
 }
 
 /**