@githolon/dsl 0.20.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/compile_engine.ts

@@ -444,6 +444,11 @@ export function makeEngineReport(
     payload?: Record<string, unknown>;
   };
   priorState?: Record<string, unknown>;
+  capturedPorts?: {
+    principal?: string;
+    principal_verified?: boolean;
+    reads?: readonly { query_id?: string; queryId?: string; args?: Record<string, string>; result?: unknown }[];
+  };
 }) => string {
   return (job) => {
     const intent = job.intent ?? {};
@@ -543,7 +548,19 @@ export function makeEngineReport(
         );
       }
       const snapshots = (job.priorState ?? {}) as Record<string, Record<string, unknown>>;
-      const verdict = decl.assert(snapshots);
+      // Mirror engine_entry.planWorkspaceInvariantAssert: surface intent + captured author identity +
+      // the committed captured reads (#58 — the captured-read invariant gate), normalising the kernel's
+      // snake_case `query_id` to the DSL `queryId` so the law body is wire-shape agnostic. A #266 body
+      // that ignores ctx is byte-identical.
+      const assertIntent = (intent.payload ?? {}) as Record<string, unknown>;
+      const principal = (job.capturedPorts?.principal ?? "") as string;
+      const principalVerified = job.capturedPorts?.principal_verified === true;
+      const reads = (job.capturedPorts?.reads ?? []).map((r) => ({
+        queryId: (r.queryId ?? r.query_id ?? "") as string,
+        args: (r.args ?? {}) as Record<string, string>,
+        result: r.result,
+      }));
+      const verdict = decl.assert(snapshots, { intent: assertIntent, principal, principalVerified, reads });
       return JSON.stringify(verdict);
     }
 

package/src/engine_entry.ts

@@ -606,7 +606,11 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
   function planWorkspaceInvariantAssert(job: {
     intent?: { workspaceInvariant?: { id?: string }; payload?: unknown };
     priorState?: Record<string, unknown>;
-    capturedPorts?: { principal?: string; principal_verified?: boolean };
+    capturedPorts?: {
+      principal?: string;
+      principal_verified?: boolean;
+      reads?: readonly { query_id?: string; queryId?: string; args?: Record<string, string>; result?: unknown }[];
+    };
   }): string {
     const id = job.intent?.workspaceInvariant?.id;
     if (typeof id !== "string") {
@@ -623,7 +627,17 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
     const principal = (job.capturedPorts?.principal ?? "") as string;
     // VA-core (Phase 3): the kernel-DERIVED author-verified flag — threaded like `principal`.
     const principalVerified = job.capturedPorts?.principal_verified === true;
-    return JSON.stringify(decl.assert(snapshots, { intent, principal, principalVerified }));
+    // THE CAPTURED READS (#58 — the captured-read invariant gate): surface the committed
+    // `captured_ports.reads` the executor ships in the assert dispatch so a count/aggregate predicate
+    // (WorkspaceQuota) can judge over the row LIST a captured read returned. The wire field is the kernel's
+    // `CapturedRead` (snake_case `query_id`); normalize to the DSL `queryId` so the law body is wire-shape
+    // agnostic. Empty/absent ⇒ `[]` (every pre-#58 / #266 body ignores it — additive, byte-identical).
+    const reads = (job.capturedPorts?.reads ?? []).map((r) => ({
+      queryId: (r.queryId ?? r.query_id ?? "") as string,
+      args: (r.args ?? {}) as Record<string, string>,
+      result: r.result,
+    }));
+    return JSON.stringify(decl.assert(snapshots, { intent, principal, principalVerified, reads }));
   }
 
   function planDerive(job: {

package/src/framework/genesis.ts

@@ -81,10 +81,15 @@ export const seedGenesis = directive("seedGenesis")
   .payload(
     z.object({
       principal: z.string().min(1),
-      // EMPTY ⇒ a CONTROL-PLANE genesis: records the founding principal (arming the kernel's genesis
-      // bootstrap clause for the founding admin grant) WITHOUT a self-id, so the workspace stays
-      // UNWARRANTED (host-stamped authorship, like root) — deploys/governance/child births keep working
-      // unsigned. NON-EMPTY ⇒ a TENANT (signed-author) self-id (the source binding author signatures cover).
+      // `seedGenesis` is GENERIC over the warrant: it records whatever self-id the genesis recipe hands it.
+      //   EMPTY ⇒ the workspace stays UNWARRANTED (host-stamped authorship) — the LEGACY/compat lane: a
+      //     pre-VA chain or a recipe that explicitly opted out (`requiresWarrant: false`) replays byte-identical.
+      //   NON-EMPTY ⇒ WARRANTED: the self-id is the source binding author signatures cover, so the kernel
+      //     enforces SIGNED control-plane authorship on every lane (author / receive / verify_chain).
+      // THE WARRANT-FLIP (THE GOVERNANCE DEFAULT, 2026-06-27): `buildGenesisChain` now seeds a NON-EMPTY
+      // self-id (the workspace name) by default for every governance/platform birth — control-plane authority
+      // is born warranted unless the recipe explicitly opts out. The choice lives in the recipe builder, not
+      // here; this directive just writes the warrant it is given. Era: the regime is per-workspace, at genesis.
       workspaceId: z.string(),
       bornAt: z.string().min(1),
     }),

package/src/framework/workspace_invariant.ts

@@ -69,6 +69,22 @@ export function refAs(name: string, aggregateType: string, id: string): Invarian
   return { name, aggregate: aggregateType, id };
 }
 
+/**
+ * ONE captured write-path read the predicate may consume (#58 — the captured-read lane). The SAME
+ * `{queryId, args, result}` the directive's plan recorded onto `captured_ports.reads` (via `read(query,
+ * args)` + `.reads(theQuery)` on the directive), CAS-re-derived + byte-compared at the pre-apply position
+ * on every lane (author / edge admission / verify_chain). So a captured read the assert reads is a
+ * COMMITTED, peer-identical fact — the gate's count-style judgement input (e.g. the WorkspaceQuota
+ * invariant counts the workspaces a `workspacesByPrincipal` captured read returned). `result` is the
+ * canonical row array `[{id, data}]` `derive_captured_read` produces. The executor ships these into the
+ * assert dispatch on EVERY lane via the same `captured_ports` it hands the gate (no kernel/adapter change).
+ */
+export interface InvariantCapturedRead {
+  readonly queryId: string;
+  readonly args: Record<string, string>;
+  readonly result: unknown;
+}
+
 /** Derive the BOUNDED declared read-set from the intent payload. Pure — no IO, no live read.
  * `ctx.principal` is the captured, authenticated AUTHOR identity (e.g. `key:<keyHash>` / a verified uid)
  * — the same value on every replaying peer — so an invariant can gate by WHO authored (law-gated authz). */
@@ -101,6 +117,18 @@ export type WorkspaceInvariantAssert = (
     principal?: string;
     /** VA-core (Phase 3): the kernel-DERIVED author-verified flag — see {@link WorkspaceInvariantReads}. */
     principalVerified?: boolean;
+    /**
+     * THE CAPTURED READS (#58 — the captured-read invariant gate). The committed `captured_ports.reads`
+     * the directive's plan recorded — present iff the directive DECLARES reads (`.reads(theQuery)`) and
+     * its plan called `read(query, args)`. Each is CAS-re-derived + byte-compared at the pre-apply
+     * position on every lane, so a count/aggregate judgement over them is a function of the COMMITTED,
+     * peer-identical pre-apply state — never a forgeable client claim. This is how a count-style gate
+     * (e.g. WorkspaceQuota: `liveWorkspaces < allowance`) judges O(#rows) WITHOUT a new kernel primitive:
+     * the `workspaceInvariant.reads` ref-set resolves single instances by id (it cannot ENUMERATE), so a
+     * cardinality predicate reads the row LIST off a captured read instead. Empty when the directive
+     * declares no reads (every pre-#58 / #266 body ignores it — additive, byte-identical).
+     */
+    reads?: readonly InvariantCapturedRead[];
   },
 ) => WorkspaceInvariantVerdict;
 

package/src/framework/workspaces.ts

@@ -73,7 +73,8 @@ import { Lww } from "../drivers.js";
 import { t } from "../fields.js";
 import { set, withMarker } from "../ops.js";
 import { query } from "../query.js";
-import { workspaceInvariant, refAs } from "./workspace_invariant.js";
+import { read } from "../read.js";
+import { workspaceInvariant, refAs, type WorkspaceInvariantVerdict } from "./workspace_invariant.js";
 import { writeTuple, removeTuple, RelationTuple, relationTupleInstanceId } from "./relations.js";
 import { relationType, self, user, key } from "../relation_schema.js";
 import { GENESIS_WARRANT_ID } from "./genesis.js";
@@ -458,13 +459,21 @@ export function buildGenesisChain(p: {
   frameworkHash?: string;
   lawHash?: string;
   /**
-   * THE WARRANT-FLIP (VA-1, architecture/identity_keys.md). When TRUE — set iff the genesis recipe
-   * declares an AuthProvider (an IdP vouches for this subtree's principals) — `seedGenesis` records a
-   * REAL `workspaceId` (the workspace name as the unique self-id), so the chain is born WARRANTED:
-   * `verify_captured_principal` enforces signed authorship on all lanes (author / receive / verify_chain).
-   * FALSE (the default, the legacy lane) keeps `workspaceId: ""` so the workspace stays unwarranted
-   * (host-stamped authorship, like root) — pre-VA / non-AuthProvider births replay byte-identically.
-   * NO flag-day: the era is per-workspace, decided at genesis by whether the recipe carries an AuthProvider.
+   * THE WARRANT-FLIP (VA-1, architecture/identity_keys.md). Controls whether `seedGenesis` records a REAL
+   * `workspaceId` (the workspace name as the unique self-id) so the chain is born WARRANTED — meaning
+   * `verify_captured_principal` enforces SIGNED control-plane authorship on every lane (author / edge
+   * receive / verify_chain). An empty `workspaceId` keeps the workspace UNWARRANTED (host-stamped authorship,
+   * the legacy lane), so a control-plane offer (grantAdmin etc.) is taken at its word — the forge that was
+   * open on unwarranted root/co2.
+   *
+   * THE GOVERNANCE DEFAULT (THE WARRANT-FLIP, 2026-06-27): `buildGenesisChain` only ever runs for a
+   * PLATFORM/GOVERNANCE birth (every call sits inside the `if (p.foundingAdminHash)` guard — a genesis that
+   * carries control-plane authority: grantAdmin/grantCreation). Control-plane authority is EXACTLY what the
+   * signed-author regime protects, so a governance birth is born WARRANTED by DEFAULT (`requiresWarrant`
+   * undefined/true ⇒ warranted). The ONLY escape is an explicit `requiresWarrant === false`, retained as an
+   * era-safe compat hatch (a pre-VA chain re-built byte-identical). NO flag-day: the era is per-workspace,
+   * decided at genesis — existing UNWARRANTED chains keep replaying; only newly-born/re-born governance
+   * chains arm the signature requirement.
    */
   requiresWarrant?: boolean;
 }): string {
@@ -495,15 +504,106 @@ export function buildGenesisChain(p: {
   });
   return JSON.stringify([
     ...installSteps,
-    // THE WARRANT-FLIP (VA-1): a REAL self-id iff the recipe declares an AuthProvider (born warranted ⇒
-    // signed authorship enforced on every lane); "" keeps the legacy host-stamped lane (byte-identical).
-    { domain: "workspaces", directiveId: "seedGenesis", actor: founder, payload: { principal: founder, workspaceId: p.requiresWarrant ? p.name : "", bornAt: p.bornAt } },
+    // THE WARRANT-FLIP (THE GOVERNANCE DEFAULT): a governance birth is born WARRANTED by default — a REAL
+    // self-id (the workspace name) so signed control-plane authorship is enforced on every lane. The ONLY
+    // way to stay on the legacy host-stamped lane ("" self-id, byte-identical to a pre-VA chain) is an
+    // EXPLICIT `requiresWarrant === false` (the era-safe compat hatch). `p.requiresWarrant !== false`
+    // ⇒ warranted whenever the flag is undefined OR true.
+    { domain: "workspaces", directiveId: "seedGenesis", actor: founder, payload: { principal: founder, workspaceId: p.requiresWarrant !== false ? p.name : "", bornAt: p.bornAt } },
     { domain: "workspaces", directiveId: "grantAdmin", actor: founder, payload: { keyHash: p.foundingAdminHash, label: `founding admin (born for ${p.principal})`, grantedBy: p.principal, grantedAt: p.requestedAt } },
     // No `role` — it was a vestigial node-class label (collapsed with `kind`); birthCloud ignores it now.
     { domain: "workspaces", directiveId: "birthCloud", actor: "", payload: { principal: p.principal, name: p.name, tier: p.tier, bornAt: p.requestedAt, bornUnder } },
   ]);
 }
 
+// ── THE QUOTA-GATE QUERIES (declared HERE — used by the WorkspaceQuota captured-read invariant) ────────
+// The captured-read invariant lane (#58) needs these QueryDecls at the directive's CONSTRUCTION (the
+// `.reads(...)` call below), which runs at module load BEFORE the read-section further down — so the
+// three the WorkspaceQuota gate consults are declared up here (the rest stay in the read section). They
+// are STILL auto-discovered by shape (export name = wire id), so the read manifest/openapi route them
+// exactly as before; only their definition POSITION moved. The quota gate counts a principal's live
+// (non-retired/-reclaimed) CloudWorkspaces against its allowance (a QuotaGrant else the CloudPolicy default).
+
+/** One principal's workspaces — the WorkspaceQuota gate counts the live (non-retired/-reclaimed) ones. */
+export const workspacesByPrincipal = query("workspacesByPrincipal")
+  .key("principal")
+  .returns(CloudWorkspace);
+
+/** THE QUOTA LAW singleton (`scope: "cloud"`) — defaults for allowance + byte cap. */
+export const cloudPolicy = query("cloudPolicy").key("scope").returns(CloudPolicy);
+
+/** A principal's quota grants — the LATEST one is the allowance in force (overrides the CloudPolicy default). */
+export const quotaByPrincipal = query("quotaByPrincipal")
+  .key("principal")
+  .returns(QuotaGrant);
+
+/** THE DEFAULT WORKSPACE ALLOWANCE — the CLAUDE.md / CloudPolicy figure when no grant + no policy row. */
+export const DEFAULT_MAX_WORKSPACES_PER_PRINCIPAL = 50;
+
+/** A captured-read row as `derive_captured_read` shapes it: `{id, data:{field:value}}`. */
+type QuotaRow = { id?: string; data?: Record<string, unknown> };
+
+/**
+ * CAPTURE the three quota reads on the write path (the plan side of the WorkspaceQuota gate). Called by
+ * both `createWorkspace` and `birthChild` so the captured set is IDENTICAL + UNCONDITIONAL (a stable,
+ * byte-deterministic capture on every lane). It returns nothing — the values ride `captured_ports.reads`
+ * and the verdict is the invariant's ({@link quotaVerdict}); this just commits the premise.
+ */
+function countQuotaReads(principal: string): void {
+  read(workspacesByPrincipal, { principal });
+  read(quotaByPrincipal, { principal });
+  read(cloudPolicy, { scope: "cloud" });
+}
+
+/**
+ * THE WORKSPACE-QUOTA VERDICT — the PURE predicate the {@link workspaceQuota} invariant runs over the
+ * COMMITTED captured reads (the same `{queryId,args,result}` the plan recorded, CAS-re-derived on every
+ * lane). Counts the principal's LIVE (non-retired/-reclaimed) CloudWorkspaces and compares against its
+ * allowance (the latest QuotaGrant.maxWorkspaces if any, else CloudPolicy.maxWorkspacesPerPrincipal, else
+ * the {@link DEFAULT_MAX_WORKSPACES_PER_PRINCIPAL} floor). The NEW workspace is NOT yet in the pre-apply
+ * state, so `liveCount < allowance` (strict) is the correct test: the principal may hold AT MOST
+ * `allowance`, so a fresh birth is admitted iff it already holds fewer. A principal-less call (should be
+ * impossible after S3) fails CLOSED. The verdict is a pure function of the captured reads ⇒ identical on
+ * author, edge admission, and verify_chain.
+ */
+function quotaVerdict(
+  reads: readonly { queryId: string; args: Record<string, string>; result: unknown }[],
+  principal: string,
+): WorkspaceInvariantVerdict {
+  if (!principal) return { reject: "quota-missing-principal" };
+  const rowsOf = (queryId: string): QuotaRow[] => {
+    const hit = reads.find((r) => r.queryId === queryId && r.args.principal === principal);
+    return Array.isArray(hit?.result) ? (hit!.result as QuotaRow[]) : [];
+  };
+  // LIVE = not retired, not reclaimed (the WORKSPACE_STATUSES lifecycle). The captured read already
+  // excludes archived rows; status is a plain Lww string in `data`.
+  const liveCount = rowsOf(workspacesByPrincipal.id).filter((row) => {
+    const status = (row.data?.status ?? "") as string;
+    return status !== "retired" && status !== "reclaimed";
+  }).length;
+  // ALLOWANCE: the LATEST QuotaGrant for the principal (max grantedAt) wins; else the CloudPolicy default;
+  // else the hard floor. `derive_captured_read` decodes t.int() as a JSON number.
+  const grants = rowsOf(quotaByPrincipal.id);
+  let allowance: number | undefined;
+  let latestGrantedAt = -Infinity;
+  for (const g of grants) {
+    const at = Number(g.data?.grantedAt ?? -Infinity);
+    const max = Number(g.data?.maxWorkspaces ?? NaN);
+    if (Number.isFinite(at) && at > latestGrantedAt && Number.isFinite(max)) {
+      latestGrantedAt = at;
+      allowance = max;
+    }
+  }
+  if (allowance === undefined) {
+    const policyHit = reads.find((r) => r.queryId === cloudPolicy.id && r.args.scope === "cloud");
+    const policyRows = Array.isArray(policyHit?.result) ? (policyHit!.result as QuotaRow[]) : [];
+    const max = Number(policyRows[0]?.data?.maxWorkspacesPerPrincipal ?? NaN);
+    if (Number.isFinite(max)) allowance = max;
+  }
+  if (allowance === undefined) allowance = DEFAULT_MAX_WORKSPACES_PER_PRINCIPAL;
+  return liveCount < allowance ? { accept: true } : { reject: "workspace-quota-exceeded" };
+}
+
 /**
  * createWorkspace — record the lawful REQUEST for a workspace. Nomos MINTS the
  * `CloudWorkspace` id (the payload carries none); the record is born
@@ -523,17 +623,30 @@ export const createWorkspace = directive("createWorkspace")
       tier: z.enum(WORKSPACE_TIERS).default("edge"),
       /** Parent CloudWorkspace aggregate id; `""` (default) = root. */
       parent: z.string().default(""),
-      /** The auth-provider principal uid the request claimed; `""` = unclaimed. */
-      principal: z.string().default(""),
+      /** The auth-provider principal uid the request claimed. REQUIRED (S3 — no anonymous nodes):
+       *  every birth bottoms out in a principal, so the kernel REFUSES an empty-principal birth at
+       *  the typed payload gate (the host `if(!principal) 401` was the only enforcer; now it is LAW).
+       *  Era-safe: pre-change chains only ever recorded born-with-principal records (the host gate
+       *  already blocked anonymous births), and replay resolves each intent under the law that sealed
+       *  it (per-position era), so old intents never re-validate against this schema. */
+      principal: z.string().min(1),
       requestedBy: z.string().min(1),
       requestedAt: epochMs,
     }),
   )
   .plan((p) => {
+    // THE WORKSPACE-QUOTA CAPTURED READS (#58 / S2): consult the principal's live-workspace count + its
+    // allowance on the write path. Each read is CAS-re-derived + byte-compared at the pre-apply position
+    // on every lane, so the WorkspaceQuota invariant judges over the COMMITTED, peer-identical state (never
+    // a forged client claim). The plan only CAPTURES them (the verdict is the invariant's job); the values
+    // ride `captured_ports.reads`. The captured set must be STABLE across author + replay — always read all
+    // three (an unconditional capture is byte-deterministic; a data-dependent one would not be).
+    countQuotaReads(p.principal);
     // No genesis ⇒ a plain lineage record (no foundingAdminHash) — never drained; materialized by boot-on-touch.
     planBirthRecord(p);
     return [];
   })
+  .reads(workspacesByPrincipal, quotaByPrincipal, cloudPolicy) // arm the captured-read invariant gate (S2)
   .requires("creator"); // posture-gated creation: only a #creator holder may request a workspace
 
 /**
@@ -733,8 +846,13 @@ export const birthChild = directive("birthChild")
     z
       .object({
         name: z.string().min(1),
-        /** The auth-provider principal uid the request claimed; `""` = unclaimed (a plain leaf may be). */
-        principal: z.string().default(""),
+        /** The auth-provider principal uid the request claimed. REQUIRED (S3 — no anonymous nodes):
+         *  THE WORLD RESTS ON A BIRTH UID, so a birth with no principal is refused at the typed
+         *  payload gate (the host `if(!principal) 401` was the only enforcer; now it is LAW, judged
+         *  on every lane — author / edge admission / verify_chain). Era-safe: pre-change chains only
+         *  ever recorded born-with-principal records, and replay resolves each intent under the law
+         *  that sealed it (per-position era), so old intents never re-validate against this schema. */
+        principal: z.string().min(1),
         /** Parent CloudWorkspace aggregate id; `""` (default) = root. */
         parent: z.string().default(""),
         /** Hosting tier; defaults to the edge DO (a genesis/platform birth typically passes `heavy`). */
@@ -769,11 +887,18 @@ export const birthChild = directive("birthChild")
       }),
   )
   .plan((p) => {
+    // THE WORKSPACE-QUOTA CAPTURED READS (#58 / S2) — same unconditional capture as createWorkspace, so the
+    // WorkspaceQuota invariant counts this principal's live workspaces against its allowance on every lane.
+    countQuotaReads(p.principal);
     const rec = planBirthRecord(p, p.foundingAdminHash ? { foundingAdminHash: p.foundingAdminHash, pool: p.pool } : undefined);
     // LAW AUTHORS THE GENESIS RECIPE (P1): a genesis birth carries its child's [installDomain×2 →]
     // seedGenesis→grantAdmin→birthCloud chain. (refine guarantees principal + bornAt here.)
     if (p.foundingAdminHash) {
-      const genesisChain = buildGenesisChain({ name: p.name, principal: p.principal, parent: p.parent, tier: p.tier, foundingAdminHash: p.foundingAdminHash, bornAt: p.bornAt as string, requestedAt: p.requestedAt, ...(p.frameworkHash ? { frameworkHash: p.frameworkHash } : {}), ...(p.lawHash ? { lawHash: p.lawHash } : {}), ...(p.requiresWarrant ? { requiresWarrant: true } : {}) });
+      // THE GOVERNANCE DEFAULT (THE WARRANT-FLIP): a governance birth is warranted unless the request
+      // EXPLICITLY opts out (`requiresWarrant === false`). Thread the flag through ONLY when the request set
+      // it — undefined falls to buildGenesisChain's warranted default; an explicit `false` rides the compat
+      // hatch (an era-safe legacy re-build).
+      const genesisChain = buildGenesisChain({ name: p.name, principal: p.principal, parent: p.parent, tier: p.tier, foundingAdminHash: p.foundingAdminHash, bornAt: p.bornAt as string, requestedAt: p.requestedAt, ...(p.frameworkHash ? { frameworkHash: p.frameworkHash } : {}), ...(p.lawHash ? { lawHash: p.lawHash } : {}), ...(p.requiresWarrant !== undefined ? { requiresWarrant: p.requiresWarrant } : {}) });
       // THE GENESIS RECIPE IS ALSO A LINEAGE/AUDIT FACT on the parent's chain (the parent records what it
       // ORDERED — law naming law, legitimate). The kernel does NOT read this field to detect the birth.
       rec.set("genesisChain", genesisChain);
@@ -786,6 +911,7 @@ export const birthChild = directive("birthChild")
     }
     return [];
   })
+  .reads(workspacesByPrincipal, quotaByPrincipal, cloudPolicy) // arm the WorkspaceQuota captured-read gate (S2)
   .births() // BIRTH IS A DECLARED KERNEL PRIMITIVE (G3): emits the `nomosBirthGate` era key; the kernel folds the carried recipe
   .requires("creator"); // THE ONE birth authority — a #creator may birth a leaf OR a platform (tier collapsed)
 
@@ -1248,18 +1374,9 @@ export const workspacesByParent = query("workspacesByParent")
   .key("parent")
   .returns(CloudWorkspace);
 
-/** One principal's workspaces — the quota gate counts the non-retired ones. */
-export const workspacesByPrincipal = query("workspacesByPrincipal")
-  .key("principal")
-  .returns(CloudWorkspace);
-
-/** THE QUOTA LAW singleton (`scope: "cloud"`) — defaults for allowance + byte cap. */
-export const cloudPolicy = query("cloudPolicy").key("scope").returns(CloudPolicy);
-
-/** A principal's quota grants — the LATEST one is the allowance in force. */
-export const quotaByPrincipal = query("quotaByPrincipal")
-  .key("principal")
-  .returns(QuotaGrant);
+// workspacesByPrincipal / cloudPolicy / quotaByPrincipal — DECLARED ABOVE (before createWorkspace), so the
+// WorkspaceQuota captured-read invariant can reference them at directive construction. (Auto-discovered by
+// shape regardless of position; they route into the read manifest/openapi exactly as the others here do.)
 
 /** "May this principal create platforms?" — invite-only; active grant = yes. */
 export const platformGrantByPrincipal = query("platformGrantByPrincipal")
@@ -1416,3 +1533,45 @@ export const reclaimRequiresRetired = workspaceInvariant("ReclaimRequiresRetired
     const rec = ws as { status?: string } | undefined;
     return rec?.status === "retired" ? { accept: true } : { reject: "reclaim-requires-retired" };
   });
+
+// ── THE WORKSPACE-QUOTA GATE (S2 — THE QUOTA LAW, ENFORCED) ────────────────────────────────────────────
+// The CloudPolicy/QuotaGrant law-state used to be enforced by NOBODY — `createWorkspace`/`birthChild` were
+// gated only by `.requires("creator")`, so a single #creator could mint unbounded workspaces. NOW the
+// COUNT quota is REAL law at the gate: each birth directive CAPTURES (via the #58 captured-read lane,
+// `countQuotaReads`) the principal's live-workspace list + its allowance, and THIS invariant counts them
+// and refuses once the principal already holds its allowance. It rides the #41 captured-read invariant
+// gate — O(#workspaces-for-the-principal), no new kernel primitive: the standard `workspaceInvariant.reads`
+// ref-set resolves single instances by id (it CANNOT enumerate), so the cardinality predicate reads the row
+// LIST off the captured reads in `ctx.reads` instead (the snapshot ref-set is empty — nothing to resolve by
+// id). The captured reads are CAS-re-derived + byte-compared at the pre-apply position on every lane
+// (author / edge admission / verify_chain), so the count the gate judges is the COMMITTED, peer-identical
+// pre-apply count — a forged/stale client claim is a typed read-conflict refusal BEFORE this even runs.
+//
+// HONEST SCOPE: this is the COUNT quota only (live workspaces per principal). The BYTE cap
+// (`workspaceByteCap` / cumulative pushed bytes) is a CUSTODY fact, NOT chain state — it is metered by the
+// transport rate-limit lane, never by a kernel cap, and this invariant does NOT pretend to enforce it.
+//
+// ERA-SAFE: the era is the bundle. Both the captured-read lane (`nomosReadGate`, emitted iff a directive
+// declares `.reads(...)`) and the invariant (`nomosInvariantGate`, emitted iff the package declares ≥1
+// invariant — which governance already does) are PER-INSTALL era keys; every chain sealed under pre-S2 law
+// carries NEITHER for these directives, so it replays BYTE-GREEN (no captured reads to re-derive, no
+// WorkspaceQuota invariant to fire). The verdict is a pure function of the captured reads ⇒ identical on
+// every replaying peer.
+
+/** createWorkspace: the principal must hold FEWER than its allowance of live workspaces (count quota). */
+export const workspaceQuotaCreate = workspaceInvariant("WorkspaceQuota")
+  .on("createWorkspace")
+  // The snapshot ref-set is EMPTY — the count comes from the captured reads (ctx.reads), which the standard
+  // ref-resolution cannot produce (it resolves single instances by id, never an enumeration).
+  .reads(() => [])
+  .assert((_snapshots, ctx) =>
+    quotaVerdict(ctx?.reads ?? [], String((ctx?.intent ?? {}).principal ?? "")),
+  );
+
+/** birthChild: the SAME count quota (a leaf or platform birth draws on the principal's allowance). */
+export const workspaceQuotaBirth = workspaceInvariant("WorkspaceQuotaBirth")
+  .on("birthChild")
+  .reads(() => [])
+  .assert((_snapshots, ctx) =>
+    quotaVerdict(ctx?.reads ?? [], String((ctx?.intent ?? {}).principal ?? "")),
+  );

package/src/index.ts

@@ -386,6 +386,7 @@ export {
   type WorkspaceInvariantReads,
   type WorkspaceInvariantAssert,
   type InvariantRef,
+  type InvariantCapturedRead,
 } from "./framework/workspace_invariant.js";
 // NATIVE ZANZIBAR RELATION SCHEMA (P1) — the userset-rewrite law as pure data.
 export {