@githolon/dsl 0.19.0 → 0.21.0

package/dart/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.20.0
+- Authority-aware: `NomosBridge.offerDirective(domain, directiveId, payload, {actor, domainHash})` — generated
+  clients route every offer through THE ONE encoder (`encodeIntentOfferBytes` in @githolon/client); no
+  per-client envelope encoding. New typed `MissingOfferAuthority` — a `.requires(...)` directive authored
+  with no actor throws BEFORE submit (an actorless gated offer cannot be generated). Lockstep jump to 0.20.0.
+
 ## 0.17.0
 - Lockstep bump with the birth-primitive release (see `@githolon/dsl` 0.17.0): birth is one law primitive
   (`birthChild`), the platform-creator tier collapsed onto `#creator`, `grantCreation` takes a user or key

package/dart/lib/src/errors.dart

@@ -77,3 +77,22 @@ class LawHashUnavailable extends NomosBridgeError {
   LawHashUnavailable({required this.workspace, String? message})
       : super(message ?? 'could not resolve the current law hash for "$workspace" — the cloud reported no installed law for the home');
 }
+
+/// AUTHORITY IS UNFORGEABLE-BY-CONSTRUCTION: a GATED directive (one carrying a `.requires(relation)` write
+/// gate in its law) authored with NO `actor` cannot produce an offer — the generated client throws THIS
+/// BEFORE any submit, so an actorless gated offer is impossible to GENERATE (never merely refused at the
+/// kernel gate). REMEDY: construct the generated client with an `actor` (the verified principal — under a
+/// home scope this is the subject; the bridge owns signing). Secrets NEVER appear here — only the identity.
+class MissingOfferAuthority extends NomosBridgeError {
+  /// The domain of the gated directive.
+  final String domain;
+
+  /// The gated directive id that could not be offered without an authority.
+  final String directiveId;
+
+  /// The relation the law requires the author to hold (e.g. `admin`).
+  final String requires;
+  MissingOfferAuthority({required this.domain, required this.directiveId, required this.requires, String? message})
+      : super(message ??
+            '$domain/$directiveId requires the "$requires" relation — construct the client with an actor (the verified principal) to author it; a gated offer cannot be made without an authority');
+}

package/dart/lib/src/webview_bridge.dart

@@ -176,6 +176,28 @@ class NomosBridge {
     return r['head'].toString();
   }
 
+  /// THE ONE ENCODER offer: hand the holon a PLANNED directive (domain/directiveId/payload) + the verified
+  /// [actor]; the runner's `offerDirective` op encodes the v2 envelope via the SINGLE codec (index.mjs
+  /// `encodeIntentOfferBytes`, with `security.actor` included iff [actor] is set). The generated Dart client
+  /// calls THIS — it never hand-builds offer bytes, so there is exactly ONE copy of the wire format. Returns
+  /// the new local head; durable on [sync]. ([offer] with opaque bytes stays for back-compat carriers.)
+  Future<String> offerDirective({
+    required String domain,
+    required String directiveId,
+    required Object? payload,
+    String? actor,
+    String? domainHash,
+  }) async {
+    final r = _asMap(await _call('offerDirective', {
+      'domain': domain,
+      'directiveId': directiveId,
+      'payload': payload,
+      if (actor != null) 'actor': actor,
+      if (domainHash != null) 'domainHash': domainHash,
+    }));
+    return r['head'].toString();
+  }
+
   /// Mint an ed25519 DEVICE KEY in-kernel → `{secret, public}` (base64). The SECRET stays on this device
   /// (persist it in secure storage); pass it to [connect] as `authorSecret` (or per-offer `signWith`) so the
   /// holon SIGNS each intent. The PUBLIC half is what gets enrolled so the gate re-verifies the signature on

package/dart/pubspec.yaml

@@ -11,7 +11,7 @@ description: >-
   Nomos 2 Dart frontend types — the hand-written kernel wire types plus the
   code-generated per-domain aggregate + directive-payload types. (De)serializes
   the EXACT serde JSON the Rust kernel + projection produce/consume.
-version: 0.18.0
+version: 0.20.0
 
 environment:
   sdk: ^3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.19.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/codegen_dart_client.ts

@@ -123,15 +123,39 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     const payloadClass = `${cap(d.id)}Payload`;
     const stamps = autoStampFields((d as unknown as { payloadSchema: z.ZodTypeAny }).payloadSchema);
     const method = safeMethod(d.id);
+    // THE AUTHORITY GATE (codegen-time): a directive carrying `.requires(relation)` is GATED — its method
+    // throws MissingOfferAuthority when `actor` is null/empty, BEFORE any submit, so an actorless gated
+    // offer is impossible to GENERATE (the war: the gate is structural, not just kernel-side). Secrets never
+    // appear — only the actor identity (the bridge owns signing).
+    const gate = (d as { requiresRelationGate?: { relation: string } }).requiresRelationGate;
+    const gateGuard = gate !== undefined
+      ? `    if (actor == null || actor!.trim().isEmpty) throw MissingOfferAuthority(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, requires: ${dartStr(gate.relation)});`
+      : "";
+    const gateDoc = gate !== undefined
+      ? `  /// GATED: needs an \`actor\` (the \`${gate.relation}\` relation) — throws MissingOfferAuthority otherwise.`
+      : "";
     if (stamps.length > 0) {
       methods.push(
         `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head.`,
         `  /// Omitted ${stamps.map((s) => `\`${s}\``).join(" / ")} auto-stamp(s) ISO now() at offer.`,
+        ...(gateDoc ? [gateDoc] : []),
         `  Future<String> ${method}(${payloadClass} payload) {`,
+        ...(gateGuard ? [gateGuard] : []),
         `    final data = payload.toPayloadJson();`,
         `    final now = DateTime.now().toUtc().toIso8601String();`,
         ...stamps.map((s) => `    data.putIfAbsent(${dartStr(s)}, () => now);`),
-        `    return bridge.offer(intentBytes: _encodeIntentOffer(${dartStr(domain)}, ${dartStr(d.id)}, data, domainHash));`,
+        `    return bridge.offerDirective(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: data, actor: actor, domainHash: domainHash);`,
+        `  }`,
+        ``,
+      );
+    } else if (gateGuard) {
+      // A gated directive with no `…At` sugar still needs a block body for the throw guard.
+      methods.push(
+        `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head.`,
+        gateDoc,
+        `  Future<String> ${method}(${payloadClass} payload) {`,
+        gateGuard,
+        `    return bridge.offerDirective(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: payload.toPayloadJson(), actor: actor, domainHash: domainHash);`,
         `  }`,
         ``,
       );
@@ -139,7 +163,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       methods.push(
         `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head.`,
         `  Future<String> ${method}(${payloadClass} payload) =>`,
-        `      bridge.offer(intentBytes: _encodeIntentOffer(${dartStr(domain)}, ${dartStr(d.id)}, payload.toPayloadJson(), domainHash));`,
+        `      bridge.offerDirective(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: payload.toPayloadJson(), actor: actor, domainHash: domainHash);`,
         ``,
       );
     }
@@ -216,14 +240,15 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     `//   final app = ${className}(bridge);`,
     `//   await app.${dirs[0] ? safeMethod(dirs[0].id) : "someDirective"}(/* typed payload */);`,
     ``,
-    `import 'dart:convert';`,
-    ``,
+    // `dart:convert` is needed ONLY for the interface block's `jsonDecode` — the offer lane no longer encodes
+    // any envelope (it routes through `bridge.offerDirective` → THE ONE ENCODER). Omit it when no interface.
+    ...(opts.interface !== undefined ? [`import 'dart:convert';`, ``] : []),
     `import '${supportImport}';`,
     `import '${mod.name}.dart';`,
     `// Re-export the sibling types (read models + payloads + the bridge runtime) so ONE import of this`,
     `// client file gives an app the whole typed surface.`,
     `export '${mod.name}.dart';`,
-    `export '${supportImport}' show NomosBridge, BridgeTransport, NomosBridgeError, kWebviewBridgeVersion;`,
+    `export '${supportImport}' show NomosBridge, BridgeTransport, NomosBridgeError, MissingOfferAuthority, kWebviewBridgeVersion;`,
     ``,
     `/// sha256 of the deployed \`.package.usda\` — the installed law this client offers under.`,
     `const String ${hashConst} = ${dartStr(opts.domainHash)};`,
@@ -238,22 +263,22 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
           ``,
         ]
       : []),
-    `String _encodeIntentOffer(String domain, String directiveId, Object? payload, String domainHash) =>`,
-    `    base64Encode(utf8.encode(jsonEncode({`,
-    `      'v': 2,`,
-    `      'intent': {`,
-    `        'domain': domain,`,
-    `        'directiveId': directiveId,`,
-    `        'payload': payload,`,
-    `        'domainHash': domainHash,`,
-    `      },`,
-    `    })));`,
-    ``,
     `/// Typed async client for the \`${domain}\` domain, bound to a connected [NomosBridge].`,
+    `///`,
+    `/// Pass \`actor\` (the verified principal uid) to author AS that user — the bridge's \`offerDirective\` op`,
+    `/// carries it through THE ONE ENCODER (\`encodeIntentOfferBytes\` in @githolon/client) as \`security.actor\`,`,
+    `/// so the kernel seals it as the captured principal and the ReBAC \`.requires(...)\` gate judges the real`,
+    `/// author. A GATED directive (one whose law declares \`.requires(relation)\`) authored with no actor throws`,
+    `/// [MissingOfferAuthority] BEFORE any submit — an actorless gated offer can't be constructed. The bridge`,
+    `/// owns SIGNING (a device secret on \`connect\`); only the actor IDENTITY is passed here, never a secret.`,
     `class ${className} {`,
     `  final NomosBridge bridge;`,
     `  final String domainHash;`,
-    `  ${className}(this.bridge, {this.domainHash = ${hashConst}});`,
+    ``,
+    `  /// The verified principal uid every offer is authored as (sealed as \`security.actor\` by the one encoder).`,
+    `  /// Null ⇒ open (un-gated) authoring; a gated directive then throws [MissingOfferAuthority].`,
+    `  final String? actor;`,
+    `  ${className}(this.bridge, {this.domainHash = ${hashConst}, this.actor});`,
     ``,
     ...(opts.interface !== undefined
       ? [

package/src/codegen_proof.ts

@@ -183,6 +183,136 @@ function findConcurrencyLeg(
   return undefined;
 }
 
+// ── authority-conformance discovery (the ONE-ENCODER + gate proof — actorless gated offer is impossible) ──
+
+/** A discovered AUTHORITY-CONFORMANCE leg: a GATED directive (one carrying `.requires(relation)`) the proof
+ *  can drive locally to prove (a) authored WITH an actor, the produced offer envelope carries `security.actor`
+ *  (the one encoder threaded the actor through), and (b) authored WITHOUT an actor, the generated client
+ *  THROWS MissingOfferAuthority before any submit (an actorless gated offer is impossible to GENERATE). */
+export interface AuthorityConformanceLeg {
+  /** The gated directive's domain (the generated factory + its `domain` field). */
+  readonly domain: string;
+  /** The gated directive id (the generated client method). */
+  readonly directiveId: string;
+  /** The relation the law requires the author to hold (e.g. `admin`) — the MissingOfferAuthority `requires`. */
+  readonly relation: string;
+  /** The synthesized payload the proof drives the gated directive with (auto-stamped `…At` omitted). */
+  readonly payload: Record<string, unknown>;
+  /** Required `…At` fields the runtime stamps at dispatch (mirrors the create leg). */
+  readonly autoStamped: readonly string[];
+  /** When the gated directive is a `.creates` whose own id is kernel-minted, the field to mint at runtime. */
+  readonly mintField?: string;
+}
+
+/** Discover the AUTHORITY-CONFORMANCE leg: the first GATED directive (`.requires(relation)` ⇒
+ *  `requiresRelationGate`) whose payload the synthesizer can sample. A birth / attestation-authorized
+ *  directive is skipped (their authority is a carried cert / signed quote, not an `actor` block — a different
+ *  lane). `undefined` ⇒ this package has no gated directive (the leg becomes a documented no-op). */
+export function discoverAuthorityConformanceLeg(mod: DomainModule): AuthorityConformanceLeg | undefined {
+  const domain = mod.domain ?? mod.name;
+  const gated = (mod.directives as Directive<unknown>[]).find(
+    (d) =>
+      d?.requiresRelationGate !== undefined &&
+      typeof d.payloadSchema === "object" &&
+      d.birthsChild !== true &&
+      d.attestationAuthorizedGate === undefined,
+  );
+  if (gated === undefined) return undefined;
+  let synth: SynthesizedPayload;
+  try {
+    synth = synthesizePayload(gated.payloadSchema as z.ZodTypeAny, `${domain}/${gated.id}`);
+  } catch {
+    return undefined; // an exotic payload the synthesizer can't sample → no conformance leg (still gated at the kernel)
+  }
+  const agg = (mod.aggregates as AggregateHandle[]).find((a) => a.id === gated.aggregateId);
+  const mintField = agg !== undefined ? mintedCreateField(gated, agg) : undefined;
+  const payload: Record<string, unknown> = { ...synth.value };
+  if (mintField !== undefined) delete payload[mintField];
+  return {
+    domain,
+    directiveId: gated.id,
+    relation: gated.requiresRelationGate!.relation,
+    payload,
+    autoStamped: synth.autoStamped,
+    ...(mintField !== undefined ? { mintField } : {}),
+  };
+}
+
+/**
+ * THE AUTHORITY-CONFORMANCE LEG (the one-encoder + gate proof). On the real LOCAL holon, with fetch trapped:
+ *   (a) bind the generated client WITH an actor + drive the gated directive. SPY on `holon.offerDirective` to
+ *       capture the (domain, directiveId, payload, opts) the client passes, RE-ENCODE that through the v2
+ *       envelope shape (the SAME `{ v:2, intent, security:{actor} }` the one encoder emits) and DECODE it back
+ *       to assert `security.actor` IS the bound actor — the produced offer envelope carries the principal.
+ *   (b) bind a SECOND client WITHOUT an actor + call the gated directive — assert it THROWS
+ *       MissingOfferAuthority LOCALLY (before any offerDirective/submit fires; the spy stays untouched).
+ * Emits nothing when the package has no gated directive (a documented no-op note).
+ */
+function authorityConformanceLegLines(
+  leg: AuthorityConformanceLeg | undefined,
+  factory: string,
+  n: () => number,
+): string[] {
+  if (leg === undefined) {
+    return [
+      `// ${n()}. authority-conformance leg: this law has no gated (\`.requires(...)\`) directive, so there is`,
+      `//    nothing to prove about actorless-gated-offer refusal (an un-gated domain authors openly).`,
+      `console.log("– authority-conformance leg SKIPPED — no .requires(...) directive (add one to prove the one-encoder threads security.actor + an actorless gated offer can't be generated)");`,
+      ``,
+    ];
+  }
+  const payloadEntries = leg.mintField !== undefined
+    ? `{ ...${JSON.stringify(leg.payload)}, ${JSON.stringify(leg.mintField)}: await holon.mint("conformance") }`
+    : JSON.stringify(leg.payload);
+  return [
+    `// ${n()}. AUTHORITY CONFORMANCE (THE ONE ENCODER + the gate): \`${leg.domain}/${leg.directiveId}\` is GATED`,
+    `//    (\`.requires("${leg.relation}")\`). (a) WITH an actor the produced offer envelope must carry`,
+    `//    security.actor; (b) WITHOUT one the generated client THROWS MissingOfferAuthority before any submit.`,
+    `{`,
+    `  const realFetch2 = globalThis.fetch;`,
+    `  globalThis.fetch = (() => { throw new Error("OFFLINE PROOF VIOLATED: authority-conformance touched the network"); }) as typeof fetch;`,
+    `  try {`,
+    `    // (a) SPY on offerDirective: capture what the generated client passes, re-encode the v2 envelope it`,
+    `    //     would produce (the one-encoder shape), decode it back, and assert security.actor IS the actor.`,
+    `    const ACTOR = "user:proof-conformance";`,
+    `    let captured: { domain: string; directiveId: string; payload: unknown; opts?: { domainHash?: string; actor?: string } } | undefined;`,
+    `    const realOffer: typeof holon.offerDirective = holon.offerDirective.bind(holon);`,
+    `    holon.offerDirective = (domain, directiveId, payload, opts) => {`,
+    `      captured = { domain, directiveId, payload, opts };`,
+    `      return realOffer(domain, directiveId, payload, opts);`,
+    `    };`,
+    `    try {`,
+    `      await ${factory}(holon, { actor: ACTOR }).${leg.directiveId}(${payloadEntries});`,
+    `    } finally {`,
+    `      holon.offerDirective = realOffer;`,
+    `    }`,
+    `    if (!captured) fail("authority-conformance: the gated directive did not reach holon.offerDirective");`,
+    `    const actorOnOffer = captured!.opts?.actor;`,
+    `    if (actorOnOffer !== ACTOR) fail(\`authority-conformance: the offer did not carry the actor (got \${JSON.stringify(actorOnOffer)})\`);`,
+    `    // Decode the bytes THE ONE ENCODER actually emits from these args (NOT a hand-rolled copy) — so this`,
+    `    // leg catches encoder DRIFT (a dropped/renamed/whitespace-normalized security.actor), not merely that`,
+    `    // the actor reached offerDirective. The v2 wire format lives in exactly one place: encodeIntentOfferBytes.`,
+    `    const decoded = JSON.parse(new TextDecoder().decode(encodeIntentOfferBytes({ domain: captured!.domain, directiveId: captured!.directiveId, payload: captured!.payload, domainHash: captured!.opts?.domainHash, actor: actorOnOffer })));`,
+    `    if (decoded?.security?.actor !== ACTOR) fail(\`authority-conformance: THE ONE ENCODER dropped security.actor (\${JSON.stringify(decoded?.security)})\`);`,
+    `    ok(\`authority conformance (a) — \${${JSON.stringify(`${leg.domain}/${leg.directiveId}`)}} authored WITH an actor carries security.actor through THE ONE ENCODER\`);`,
+    ``,
+    `    // (b) the SAME directive with NO actor: the generated client refuses to BUILD the offer — it throws`,
+    `    //     MissingOfferAuthority locally, BEFORE any submit (an actorless gated offer is impossible to make).`,
+    `    let threw: Error | undefined;`,
+    `    try {`,
+    `      await ${factory}(holon).${leg.directiveId}(${payloadEntries});`,
+    `    } catch (e) { threw = e as Error; }`,
+    `    if (threw === undefined) fail("authority-conformance: the gated directive with NO actor did NOT throw — an actorless gated offer must be impossible to generate");`,
+    `    if (threw.name !== "MissingOfferAuthority") fail(\`authority-conformance: expected MissingOfferAuthority, got \${threw.name}: \${threw.message}\`);`,
+    `    ok(\`authority conformance (b) — \${${JSON.stringify(`${leg.domain}/${leg.directiveId}`)}} with NO actor throws MissingOfferAuthority before any submit (gated offer impossible to generate)\`);`,
+    `  } finally {`,
+    `    globalThis.fetch = realFetch2;`,
+    `  }`,
+    `}`,
+    ``,
+  ];
+}
+
 // ── child-birth discovery (the G3 `.births()` lane — prove a parent birth end-to-end into the child) ──────
 
 /** ONE step of a discovered birth recipe's genesis chain (the subset codegen reads). */
@@ -733,7 +863,7 @@ function generateBirthOnlyProof(
     `// Regenerated on every compile; do not edit.`,
     `// @nomos-proof-legs ${legsMarker}`,
     `import { readFileSync } from "node:fs";`,
-    `import { connect } from "@githolon/client";`,
+    `import { connect, encodeIntentOfferBytes } from "@githolon/client";`,
     `import { ${factory}, ${hashConst} } from "./${opts.packageName}.client.ts";`,
     `void connect; void ${factory};`,
     ``,
@@ -823,6 +953,11 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
 
   const concurrency = findConcurrencyLeg(mod.directives as Directive<unknown>[], agg);
 
+  // THE AUTHORITY-CONFORMANCE LEG (the one-encoder + gate proof): the first gated (`.requires(...)`) directive
+  // in the primary domain, proven locally — actor threads through the one encoder; an actorless gated offer
+  // throws MissingOfferAuthority. `undefined` ⇒ a documented no-op (the domain authors openly).
+  const conformance = discoverAuthorityConformanceLeg(mod);
+
   // Workspace-name slug: any package name → a safe, recognizable ws prefix.
   const slug =
     opts.packageName
@@ -865,7 +1000,7 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
     `// every call — start at docs/01-mental-model.md). Regenerated on every compile; do not edit.`,
     `// @nomos-proof-legs ${legsMarker}`,
     `import { readFileSync } from "node:fs";`,
-    `import { connect } from "@githolon/client";`,
+    `import { connect, encodeIntentOfferBytes } from "@githolon/client";`,
     `import { ${factory}, ${hashConst} } from "./${opts.packageName}.client.ts";`,
     ``,
     `const CLOUD = (process.env.NOMOS_CLOUD || "https://nomos.captainapp.co.uk").replace(/\\/+$/, "");`,
@@ -1009,6 +1144,11 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
     );
   }
 
+  // THE AUTHORITY-CONFORMANCE LEG (the one-encoder + gate proof): runs on the LOCAL holon (fetch re-trapped),
+  // proving the generated client threads security.actor through THE ONE ENCODER and that an actorless gated
+  // offer is impossible to GENERATE (throws MissingOfferAuthority before any submit). No-op when un-gated.
+  out.push(...authorityConformanceLegLines(conformance, factory, n));
+
   // THE CHILD-BIRTH LEG (G3, gap 2): when the primary domain has a `.births()` directive, prove the birth
   // END-TO-END against the cloud — drive the parent birth offer, then read the BORN child workspace it spawns.
   if (childBirth !== undefined) {

package/src/codegen_ts.ts

@@ -344,6 +344,11 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     ``,
     `/** The holon surface this client binds to (structurally satisfied by @githolon/client). */`,
     `export interface NomosHolon {`,
+    `  /** THE ONE ENCODER offer (the single v2-envelope codec lives in @githolon/client \`encodeIntentOfferBytes\`):`,
+    `   *  hand the holon a PLANNED directive + the verified \`actor\`; the holon encodes + offers. The generated`,
+    `   *  client calls THIS, never building offer bytes itself — so there is exactly ONE copy of the wire format. */`,
+    `  offerDirective(domain: string, directiveId: string, payload: unknown, opts?: { domainHash?: string; actor?: string }): Promise<string>;`,
+    `  /** Opaque-bytes offer — retained for carriers that already hold an encoded envelope (back-compat). */`,
     `  offer(intentBytes: string | Uint8Array): Promise<string>;`,
     `  query(queryId: string, params?: Record<string, unknown>): Promise<unknown>;`,
     `  queryById(aggregateId: string): Promise<unknown>;`,
@@ -364,8 +369,16 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `  discardDeadLetter(id: string): Promise<{ ok: boolean; removed: number }>;`,
     `}`,
     ``,
-    `const encodeIntentOffer = (domain: string, directiveId: string, payload: unknown, domainHash: string, actor?: string): Uint8Array =>`,
-    `  new TextEncoder().encode(JSON.stringify({ v: 2, intent: { domain, directiveId, payload, domainHash }, ...(actor ? { security: { actor } } : {}) }));`,
+    `/** AUTHORITY IS UNFORGEABLE-BY-CONSTRUCTION: a GATED directive (one carrying a \`.requires(relation)\` write`,
+    ` *  gate) authored with NO \`actor\` cannot produce an offer — it throws THIS before any submit, so an`,
+    ` *  actorless gated offer is impossible to GENERATE, never merely refused at the kernel gate. Bind the`,
+    ` *  client with \`{ actor }\` (the verified principal) to author a gated directive. */`,
+    `export class MissingOfferAuthority extends Error {`,
+    `  constructor(readonly domain: string, readonly directiveId: string, readonly requires: string) {`,
+    `    super(\`\${domain}/\${directiveId} requires the "\${requires}" relation — bind the client with { actor } (the verified principal) to author it; a gated offer cannot be made without an authority\`);`,
+    `    this.name = "MissingOfferAuthority";`,
+    `  }`,
+    `}`,
     ``,
   );
 
@@ -632,6 +645,13 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       const stamps = autoStampFields(schema);
       const mint = mintPlan?.get(d.id);
       const placed = placementDirs.has(d.id) ? ["shard"] : [];
+      // THE AUTHORITY GATE (codegen-time): a directive carrying `.requires(relation)` is GATED — its
+      // generated method refuses to encode an offer without an `actor` (throws MissingOfferAuthority
+      // BEFORE any submit), so an actorless gated offer is impossible to GENERATE, not merely refused.
+      const gate = (d as { requiresRelationGate?: { relation: string } }).requiresRelationGate;
+      const gateGuard = gate !== undefined
+        ? `      if (!actor || !actor.trim()) throw new MissingOfferAuthority(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${JSON.stringify(gate.relation)});\n`
+        : "";
       out.push(
         `/** \`${domain}/${d.id}\` payload (mirrors the engine's zod schema).${stamps.length ? ` Omitted ${stamps.map((s) => `\`${s}\``).join("/")} auto-stamp(s) ISO now() at offer.` : ""}${mint ? ` Omitted \`${mint.field}\` is KERNEL-MINTED at offer (returned on the result).` : ""}${placed.length ? " Omitted `shard` is picked LEAST-LOADED at offer (the routed holon)." : ""} */`,
         `export type ${payloadName} = ${tsTypeOfPayload(schema, stamps, mint ? [mint.field] : [], placed)};`,
@@ -649,21 +669,35 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           : `{ ...payload, ${mint.field} }`;
         methods.push(
           `    /** Author \`${domain}/${d.id}\`: the front-door MINTS \`${mint.field}\` (route-tagged) when omitted`,
-          `     *  — ids stay internal plumbing — and returns it with the new local head. */`,
+          `     *  — ids stay internal plumbing — and returns it with the new local head.${gate ? ` GATED: needs \`{ actor }\` (\`${gate.relation}\`).` : ""} */`,
           `    ${d.id}: async (payload: ${payloadName}): Promise<{ head: string; ${mint.field}: string }> => {`,
+          ...(gateGuard ? [gateGuard.replace(/\n$/, "")] : []),
           `      const ${mint.field} = payload.${mint.field} ?? (await (holon as NomosRoutedHolon).mint(${JSON.stringify(mint.mintType)}${mintOpts}));`,
-          `      const head = await holon.offer(encodeIntentOffer(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${body}, domainHash, actor));`,
+          `      const head = await holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${body}, { domainHash, actor });`,
           `      return { head, ${mint.field} };`,
           `    },`,
         );
         continue;
       }
-      methods.push(
-        `    /** Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head. */`,
-        stamps.length
-          ? `    ${d.id}: (payload: ${payloadName}) => holon.offer(encodeIntentOffer(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, stampNow(payload, ${JSON.stringify(stamps)}), domainHash, actor)),`
-          : `    ${d.id}: (payload: ${payloadName}) => holon.offer(encodeIntentOffer(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, payload, domainHash, actor)),`,
-      );
+      const offerPayload = stamps.length ? `stampNow(payload, ${JSON.stringify(stamps)})` : `payload`;
+      const offerCall = `holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${offerPayload}, { domainHash, actor })`;
+      if (gateGuard) {
+        // GATED directive: a block body that throws MissingOfferAuthority when no actor is bound — an
+        // actorless gated offer can't be constructed (the war: the gate is structural, not just kernel-side).
+        methods.push(
+          `    /** Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head.`,
+          `     *  GATED: needs \`{ actor }\` (the \`${gate!.relation}\` relation) — throws MissingOfferAuthority otherwise. */`,
+          `    ${d.id}: (payload: ${payloadName}): Promise<string> => {`,
+          gateGuard.replace(/\n$/, ""),
+          `      return ${offerCall};`,
+          `    },`,
+        );
+      } else {
+        methods.push(
+          `    /** Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head. */`,
+          `    ${d.id}: (payload: ${payloadName}) => ${offerCall},`,
+        );
+      }
     }
 
     for (const q of (mod.queries ?? []) as QueryDecl[]) {

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 {