@githolon/dsl 0.4.0 → 0.5.0

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);
 }
 
 /**

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,