@githolon/dsl 0.32.0 → 0.34.0

package/dart/lib/src/errors.dart

@@ -14,7 +14,111 @@
 /// All extend [NomosBridgeError] so existing `catch (NomosBridgeError)` handlers still catch them.
 library;
 
-import 'webview_bridge.dart' show NomosBridgeError;
+import 'webview_bridge.dart' show NomosBridgeError, NomosErrorInfo;
+
+/// Mint the MOST SPECIFIC typed error for a structured refusal — the one construction point the bridge
+/// uses everywhere it surfaces an `errorInfo`. A `nomos.custody.*` code becomes a [CustodyError] (typed,
+/// recoverable, carrying the eviction/escalation decision fields); everything else stays the generic
+/// [NomosBridgeError]. Apps `switch` on the type / `code`, never scrape prose.
+NomosBridgeError nomosErrorFromInfo(NomosErrorInfo info) {
+  if (info.code.startsWith('nomos.custody.')) return CustodyError.fromInfo(info);
+  return NomosBridgeError(info.message, info: info);
+}
+
+/// The custody phase a [CustodyError] was raised in.
+enum CustodyPhase { fold, author, fetch, unknown }
+
+/// Where the incomplete custody came from — the axis of the recovery decision.
+enum CustodySource { localSnapshot, cloudPack, unknown }
+
+/// A TYPED, RECOVERABLE CUSTODY ERROR — local custody (the clone/snapshot this holon folds from) is
+/// missing history the operation needed (`nomos.custody.shallow_insufficient` /
+/// `nomos.custody.missing_object`), and the in-client gap-fill repair could not complete it.
+///
+/// This replaces pattern-matching `shallow-insufficient` out of a stringly [NomosBridgeError]: the app
+/// switches on [code] and decides from the structured fields whether to EVICT LOCAL CUSTODY
+/// ([recommendedAction] == `quarantineLocalSnapshotAndReclone` — quarantine the snapshot, `inspectSnapshot`
+/// / `recoverFrom`, reconnect fresh) or ESCALATE CLOUD CUSTODY (`refetchFullHistoryAndRetry` — the cloud
+/// must serve the full chain). Trace IDs ride [NomosBridgeError.info.trace] as on every bridge error.
+class CustodyError extends NomosBridgeError {
+  /// The stable machine code, e.g. `nomos.custody.shallow_insufficient`.
+  final String code;
+
+  /// The workspace whose custody is incomplete.
+  final String? workspace;
+
+  /// The ref being folded (e.g. `refs/heads/main`).
+  final String? ref;
+
+  /// The ref's head commit at the time of the fault, when resolvable.
+  final String? head;
+
+  /// The missing object id the fold stopped at, when the kernel named one.
+  final String? missingObject;
+
+  /// The operation phase that hit the gap: fold (read), author (offer), fetch (the repair itself).
+  final CustodyPhase phase;
+
+  /// Provenance of the incomplete custody: a restored local snapshot, or a cloud-served pack.
+  final CustodySource source;
+
+  /// True when a known recovery lane exists (it always does for custody gaps — see [recommendedAction]).
+  final bool recoverable;
+
+  /// The named remedy: `quarantineLocalSnapshotAndReclone` | `refetchFullHistoryAndRetry`.
+  final String recommendedAction;
+
+  CustodyError({
+    required this.code,
+    required String message,
+    this.workspace,
+    this.ref,
+    this.head,
+    this.missingObject,
+    this.phase = CustodyPhase.unknown,
+    this.source = CustodySource.unknown,
+    this.recoverable = true,
+    this.recommendedAction = 'refetchFullHistoryAndRetry',
+    NomosErrorInfo? info,
+  }) : super(message, info: info);
+
+  /// Decode the structured custody payload the client attaches (`nomos.custody.*` attributes).
+  factory CustodyError.fromInfo(NomosErrorInfo info) {
+    String? attr(String name) {
+      final v = info.attributes['nomos.custody.$name'] ?? info.attributes[name];
+      return v?.toString();
+    }
+
+    return CustodyError(
+      code: info.code,
+      message: info.message,
+      workspace: info.workspace,
+      ref: attr('ref'),
+      head: attr('head'),
+      missingObject: attr('missing_object') ?? attr('missingObject'),
+      phase: CustodyPhase.values.firstWhere(
+        (p) => p.name == attr('phase'),
+        orElse: () => CustodyPhase.unknown,
+      ),
+      source: CustodySource.values.firstWhere(
+        (s) => s.name == attr('source'),
+        orElse: () => CustodySource.unknown,
+      ),
+      recoverable: attr('recoverable') != 'false',
+      recommendedAction: attr('recommended_action') ?? attr('recommendedAction') ?? 'refetchFullHistoryAndRetry',
+      info: info,
+    );
+  }
+
+  /// True when the remedy is to quarantine the local snapshot and re-clone (evict local custody).
+  bool get shouldEvictLocalCustody => recommendedAction == 'quarantineLocalSnapshotAndReclone';
+
+  @override
+  String toString() =>
+      'CustodyError($code${workspace != null ? ', workspace: $workspace' : ''}'
+      '${ref != null ? ', ref: $ref' : ''}${missingObject != null ? ', missing: $missingObject' : ''}'
+      ', phase: ${phase.name}, source: ${source.name}, recommendedAction: $recommendedAction): $message';
+}
 
 /// The auth-provider access token the cloud was given was missing, malformed, expired, or rejected — the
 /// cloud answered 401 / "invalid token" on a lane that requires a verified principal (every birth does).

package/dart/lib/src/webview_bridge.dart

@@ -17,6 +17,8 @@ library;
 import 'dart:async';
 import 'dart:math';
 
+import 'errors.dart' show nomosErrorFromInfo;
+
 /// The protocol version the runner and the bridge agree on (`webview-runner.mjs` `WEBVIEW_BRIDGE_VERSION`).
 const int kWebviewBridgeVersion = 1;
 
@@ -336,7 +338,7 @@ class NomosBridge {
           final info = NomosErrorInfo.fromBridgeMessage(m,
               fallbackMessage: 'the watch read failed',
               fallbackOperation: 'watch');
-          ctrl.addError(NomosBridgeError(info.message, info: info));
+          ctrl.addError(nomosErrorFromInfo(info));
         } else {
           ctrl.add((m['rows'] as List?) ?? const []);
         }
@@ -349,7 +351,7 @@ class NomosBridge {
           final info = NomosErrorInfo.fromBridgeMessage(m,
               fallbackMessage: 'the compat watch failed',
               fallbackOperation: 'watchCompatibility');
-          cctrl.addError(NomosBridgeError(info.message, info: info));
+          cctrl.addError(nomosErrorFromInfo(info));
         } else {
           cctrl.add(((m['rows'] as Map?)?.cast<String, Object?>()) ?? const {});
         }
@@ -410,7 +412,7 @@ class NomosBridge {
           fallbackOperation: op,
           fallbackTrace: trace,
           fallbackMessage: 'the githolon refused the request');
-      completer.completeError(NomosBridgeError(info.message, info: info));
+      completer.completeError(nomosErrorFromInfo(info));
     }
   }
 
@@ -931,7 +933,7 @@ class NomosBridge {
             code: 'nomos.bridge.disposed',
             operation: _pendingOps[entry.key],
             trace: trace);
-        c.completeError(NomosBridgeError(info.message, info: info));
+        c.completeError(nomosErrorFromInfo(info));
       }
     }
     _pending.clear();

package/dart/test/webview_bridge_test.dart

@@ -61,6 +61,36 @@ class FakeRunner implements BridgeTransport {
                 'attributes': {'test.case': 'refusal'}
               }
             });
+          } else if (intentJson.contains('"directiveId":"custodyGap"')) {
+            // The client's typed custody error: structured errorInfo, code=nomos.custody.*.
+            _incoming.add({
+              'v': kWebviewBridgeVersion,
+              'id': id,
+              'ok': false,
+              'error':
+                  'shallow-insufficient: fold refs/heads/main: find commit: NotFound',
+              'errorInfo': {
+                'code': 'nomos.custody.shallow_insufficient',
+                'message':
+                    'shallow-insufficient: fold refs/heads/main: find commit: NotFound',
+                'component': 'nomos.custody',
+                'operation': 'offer',
+                'workspace': 'ws-1',
+                'trace': message['trace'],
+                'attributes': {
+                  'nomos.custody.ref': 'refs/heads/main',
+                  'nomos.custody.head':
+                      'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+                  'nomos.custody.missing_object':
+                      'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
+                  'nomos.custody.phase': 'author',
+                  'nomos.custody.source': 'localSnapshot',
+                  'nomos.custody.recoverable': true,
+                  'nomos.custody.recommended_action':
+                      'quarantineLocalSnapshotAndReclone',
+                }
+              }
+            });
           } else {
             _incoming.add(reply({'head': 'HEAD-offer'}));
           }
@@ -420,6 +450,41 @@ void main() {
     expect(e.info.toTelemetryAttributes()['nomos.operation'], 'offer');
   });
 
+  test(
+      'a custody fault surfaces as the TYPED CustodyError (switch on code, never scrape prose)',
+      () async {
+    await bridge.ready;
+    Object? err;
+    try {
+      await bridge.offer(
+          intentBytes: base64Encode(utf8.encode(jsonEncode({
+        'v': 2,
+        'intent': {
+          'domain': 'x',
+          'directiveId': 'custodyGap',
+          'payload': {},
+          'domainHash': 'h'
+        }
+      }))));
+    } on NomosBridgeError catch (e) {
+      err = e; // still catchable as the generic bridge error
+    }
+    expect(err, isA<CustodyError>());
+    final e = err as CustodyError;
+    expect(e.code, 'nomos.custody.shallow_insufficient');
+    expect(e.workspace, 'ws-1');
+    expect(e.ref, 'refs/heads/main');
+    expect(e.head, 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa');
+    expect(e.missingObject, 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb');
+    expect(e.phase, CustodyPhase.author);
+    expect(e.source, CustodySource.localSnapshot);
+    expect(e.recoverable, isTrue);
+    expect(e.recommendedAction, 'quarantineLocalSnapshotAndReclone');
+    expect(e.shouldEvictLocalCustody, isTrue);
+    expect(e.info.trace.traceId, isNotEmpty); // trace IDs ride as on every bridge error
+    expect(e.message, contains('shallow-insufficient'));
+  });
+
   test(
       'legacy string-only runner errors still get operation and trace metadata',
       () async {

package/package.json

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

@@ -166,6 +166,16 @@ export interface AggregateHandle<
    * `readModelAggregates`). Identified by OBJECT IDENTITY (the branded singleton), so a tenant
    * aggregate that merely SHARES a name is never misclassified. OMITTED on tenant aggregates. */
   readonly framework?: true;
+  /**
+   * READ-PROJECTION NAMESPACING opt-out (`read_projection_namespace.ts`). TRUE ⇒ this
+   * aggregate's type name stays GLOBAL (bare, un-namespaced) on every surface — for
+   * KERNEL-COUPLED framework aggregates whose bare name/instance-id convention the
+   * kernel hardcodes. Statically-named framework aggregates ride the explicit
+   * allowlist instead; this flag is the DYNAMICALLY-NAMED factory lane (e.g.
+   * `platformAdmin()`'s founder aggregate, impure-capability envelopes). NOT hashed
+   * itself — its EFFECT (the bare vs qualified name) is what the law carries.
+   */
+  readonly global?: boolean;
   /** Presence-only flag (hashed); OMITTED ENTIRELY when no invariant is declared. */
   readonly hasInvariant?: true;
   /** The executable body — ships in the engine bundle, NOT the manifest. */
@@ -230,7 +240,7 @@ export interface AudienceMethods<Id extends string, F extends Record<string, Fie
 export function aggregate<const Id extends string, F extends Record<string, Field>>(
   id: Id,
   fields: F,
-  opts?: { invariant?: AggregateInvariantFn; invariantDeclassify?: string; cap?: number; visibility?: ReadVisibility },
+  opts?: { invariant?: AggregateInvariantFn; invariantDeclassify?: string; cap?: number; visibility?: ReadVisibility; global?: boolean },
 ): AggregateHandle<Id, F> & AudienceMethods<Id, F> {
   const { stored, hasMany } = partitionFields(fields);
   if (opts?.cap !== undefined && (!Number.isInteger(opts.cap) || opts.cap < 1)) {
@@ -279,6 +289,7 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
       : {}),
     ...(opts?.invariantDeclassify !== undefined ? { invariantDeclassify: opts.invariantDeclassify } : {}),
     ...(opts?.cap !== undefined ? { cap: opts.cap } : {}),
+    ...(opts?.global === true ? { global: true } : {}),
     ...(encryptedFields.length > 0 ? { encryptedFields } : {}),
     ...(metaFields.length > 0 ? { metaFields } : {}),
   };

package/src/authoring.ts

@@ -27,6 +27,7 @@ import type { AggregateHandle } from "./aggregate.js";
 import type { Field } from "./fields.js";
 import type { FieldOp, PlannedOp, PlannedEventMarker } from "./ops.js";
 import { endorsementOf } from "./principal_evidence.js";
+import { __qualifyAggregateType } from "./framework/relations.js";
 
 // ── the per-dispatch authoring sink — library state the engine never sees (NOT a side channel out of
 //    the sandbox; it is internal to the directive runtime, drained synchronously by `executeDirectiveToIntent`). ──
@@ -121,7 +122,9 @@ class Ref implements AggregateRef {
 
 /** Ask Nomos to CREATE a new aggregate of the handle's type → a fluent reference (id minted, no choice). */
 export function create(agg: AggregateHandle): AggregateRef {
-  return new Ref(agg, mint(agg.id), "creates");
+  // READ-PROJECTION NAMESPACING: mint under the QUALIFIED type tag — the kernel's id-mint gate
+  // verifies a Create's id was minted for EXACTLY the declared (qualified) `__type`.
+  return new Ref(agg, mint(__qualifyAggregateType(agg.id)), "creates");
 }
 
 /** A reference to an EXISTING aggregate the dev already holds an id for (e.g. from the payload / a read). */

package/src/birth_meter.ts

@@ -0,0 +1,300 @@
+// 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}.  If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * THE BIRTH METER (metered birth, slice A — `architecture/metered_birth_and_attested_reads.md`).
+ *
+ * THE ONE-HOP VOUCHING PRINCIPLE: trust is established BY INDUCTION AT BIRTH and verified LOCALLY —
+ * a parent vouches for its child IN ITS OWN CHAIN; nobody walks to root. The parent's own ledger
+ * already witnesses every birth it performs (the admitted `.births()` intent is IN the parent's
+ * chain), so the count of a parent's children is a PARENT-LOCAL fact and the existing
+ * same-workspace #58 captured-read lane covers it. NO cross-workspace reads anywhere in this slice.
+ *
+ * Three structural pieces, all era-ruled by the bundle (a pre-feature bundle carries none of this
+ * and replays byte-identical; a bundle recompiled under this DSL carries all of it by construction):
+ *
+ *  A1 — THE BIRTH RECORD IS STRUCTURAL. Every `.births()` directive's intent ALSO writes a
+ *       {@link NomosBirthRecord} event (one deterministic-id record per child; a re-birth of the
+ *       same name UPDATES the record — Lww) in the SAME intent as the birth effect. The library
+ *       appends it in `executeDirectiveToIntent` (the ONE plan-output assembly BOTH lanes — client
+ *       authoring and the sealed engine — funnel through), so tenant law gets it by construction,
+ *       zero tenant code. The kernel arm (`verify_births_witness` + the `nomosBirthRecordGate` era
+ *       key) REFUSES a birth whose intent carries no record — ONLY for bundles declaring the key.
+ *
+ *  A2 — THE BIRTH QUOTA IS PARENT-LOCAL LAW. The `.births()` lane auto-captures
+ *       {@link birthRecordsByPrincipal} + the parent's allowance facts (the #58 captured-read lane,
+ *       CAS-re-derived on every lane), and a synthesized framework `workspaceInvariant` (the exact
+ *       WorkspaceQuota shape) refuses `birth-quota-exceeded` once the subject already holds its
+ *       allowance. Allowance resolution: the latest {@link BirthGrant} for the subject if any, else
+ *       the workspace's {@link BirthPolicy} singleton, else {@link DEFAULT_MAX_BIRTHS_PER_PRINCIPAL}.
+ *
+ *  A3 — THE POOL CHAINS TO ROOT. A parent births a child WITH the child's own descendant budget
+ *       (`buildGenesisChain`'s `descendantPool` threads a `seedBirthPolicy` genesis step), so every
+ *       child is BORN BOUNDED: root bounds platforms, platforms bound homes, homes bound estates —
+ *       the tree meters by induction. V1 BOUNDARY (deliberate): each node enforces ITS OWN
+ *       count-quota only; cross-level pool CONSERVATION arithmetic (a child may not grant more than
+ *       it holds) is v2 — stated in the design doc, not silently pretended here.
+ *
+ * THE METER SUBJECT: the payload-carried birth subject (`principal`, else `owner` — the SAME
+ * convention `birthChild`/`birthHome` already carry), a pure function of the committed payload so
+ * it is identical on author / edge admission / verify_chain. A `.births()` payload carrying NEITHER
+ * fails CLOSED (`birth-quota-missing-subject`) — un-meterable ⇒ un-born, the ratified doctrine.
+ */
+import { aggregate, instance, type AggregateHandle } from "./aggregate.js";
+import { t } from "./fields.js";
+import { Lww } from "./drivers.js";
+import { query, type QueryDecl } from "./query.js";
+import { __captureBirthMeterRead } from "./read.js";
+import { set, withMarker, type PlannedOp } from "./ops.js";
+import type { WorkspaceInvariantDecl, WorkspaceInvariantVerdict } from "./framework/workspace_invariant.js";
+import type { BirthRecipe } from "./births.js";
+
+// ── A1 — the structural birth record ───────────────────────────────────────────────────────────────
+
+/** The deterministic instance-id prefix — `nomos-birth-record:<child>` (one record per child name;
+ *  a re-birth of the same name updates the SAME record, Lww). The kernel's `nomosBirthRecordGate`
+ *  era key carries this prefix so the wasm arm reads it from LAW, never hardcodes it. */
+export const NOMOS_BIRTH_RECORD_PREFIX = "nomos-birth-record:";
+
+/** The birth record's deterministic aggregate instance id for a child workspace name. */
+export function birthRecordId(child: string): string {
+  return NOMOS_BIRTH_RECORD_PREFIX + child;
+}
+
+/**
+ * NomosBirthRecord — THE STRUCTURAL BIRTH RECORD (A1). One row per child this workspace has
+ * birthed, written AUTOMATICALLY in the same intent as the birth effect (the `.births()` lane).
+ * The framework twin of `DomainInstallation`: a kernel-recognized, law-folded lifecycle fact.
+ */
+export const NomosBirthRecord = aggregate("NomosBirthRecord", {
+  /** The child workspace name the birth effect spawned. */
+  child: t.string().merge(Lww),
+  /** The birth SUBJECT — the payload-carried `principal`/`owner` the quota meters (see banner). */
+  principal: t.string().merge(Lww),
+  /** sha256 of the child's genesis chain JSON (the recipe the offer carried — content-addressed lineage). */
+  childGenesisHash: t.string().merge(Lww),
+  /** Caller-stamped birth time from the payload (`bornAt`, else `requestedAt`) — the timestamp doctrine. */
+  bornAt: t.string().merge(Lww),
+});
+
+/** BirthPolicy — the workspace's birth-allowance singleton (id `birth-policy:workspace`), the
+ *  `CloudPolicy` shape one level down: the default max live births per subject in THIS workspace. */
+export const BIRTH_POLICY_ID = "birth-policy:workspace";
+export const BirthPolicy = aggregate("BirthPolicy", {
+  /** The query key (constant `"workspace"`) — a declared field so `birthPolicy` can index it. */
+  scope: t.string().merge(Lww),
+  maxBirthsPerPrincipal: t.int().merge(Lww),
+  setBy: t.string().merge(Lww),
+  /** Caller-stamped (ISO or epoch-ms string) — the timestamp doctrine. */
+  setAt: t.string().merge(Lww),
+});
+
+/** BirthGrant — a per-subject allowance override (id `birth-grant:<principal>`), the `QuotaGrant`
+ *  shape: the LATEST grant (max grantedAt) for a subject is the allowance in force. */
+export function birthGrantId(principal: string): string {
+  return "birth-grant:" + principal;
+}
+export const BirthGrant = aggregate("BirthGrant", {
+  principal: t.string().merge(Lww),
+  maxBirths: t.int().merge(Lww),
+  grantedBy: t.string().merge(Lww),
+  /** epoch-ms — the recency tiebreak (latest grant wins), caller-stamped. */
+  grantedAt: t.int().merge(Lww),
+});
+
+// ── the meter's declared queries (the #58 captured-read recipes) ────────────────────────────────────
+
+/** A subject's birth records — the quota gate counts them (parent-LOCAL; no cross-ws read). */
+export const birthRecordsByPrincipal = query("birthRecordsByPrincipal")
+  .key("principal")
+  .returns(NomosBirthRecord);
+
+/** The workspace's birth-policy singleton (`scope: "workspace"`). */
+export const birthPolicy = query("birthPolicy").key("scope").returns(BirthPolicy);
+
+/** A subject's allowance grants — the LATEST one overrides the BirthPolicy default. */
+export const birthGrantByPrincipal = query("birthGrantByPrincipal")
+  .key("principal")
+  .returns(BirthGrant);
+
+/** The three meter reads every `.births()` directive auto-declares (`nomosReadGate`). */
+export const BIRTH_METER_QUERIES: readonly QueryDecl[] = [
+  birthRecordsByPrincipal,
+  birthPolicy,
+  birthGrantByPrincipal,
+];
+
+/**
+ * THE DEFAULT BIRTH ALLOWANCE when a workspace carries neither a BirthPolicy singleton nor a grant
+ * for the subject: a CONSERVATIVE floor for non-root workspaces (a home births a handful of estate
+ * children; a platform that needs more seeds a BirthPolicy at its own genesis — the A3 induction —
+ * or grants per-subject allowances). Root/platform governance already carries the 50-workspace
+ * `WorkspaceQuota`; THIS default only ever binds law that never set its own policy.
+ */
+export const DEFAULT_MAX_BIRTHS_PER_PRINCIPAL = 5;
+
+// ── the meter subject + the auto-record/auto-capture halves the `.births()` lane calls ─────────────
+
+/** The payload-carried birth SUBJECT the meter counts under: `principal`, else `owner`, else `""`
+ *  (fail-closed at the invariant). A pure function of the committed payload — identical on every lane. */
+export function birthMeterSubject(payload: Record<string, unknown>): string {
+  // The payload-carried subject convention, in priority order: `principal` (birthChild/createWorkspace),
+  // `owner` (birthHome), `ownerSubject` (the estate-birth shape). A pure function of the committed
+  // payload — identical on every lane; empty ⇒ the quota invariant fails closed.
+  for (const key of ["principal", "owner", "ownerSubject"]) {
+    const v = payload[key];
+    if (typeof v === "string" && v.length > 0) return v;
+  }
+  return "";
+}
+
+/** The record's caller-stamped birth time off the payload (`bornAt`, else `requestedAt`, else `""`). */
+export function birthMeterBornAt(payload: Record<string, unknown>): string {
+  const b = payload["bornAt"];
+  if (typeof b === "string" && b.length > 0) return b;
+  const r = payload["requestedAt"];
+  if (typeof r === "number" || (typeof r === "string" && r.length > 0)) return String(r);
+  return "";
+}
+
+/** sha256 via the ONE deterministic host port (`nomos.sha256` — the same global `homeNameOf` uses,
+ *  provided by the sealed engine AND the client runtime, so both lanes hash identically). */
+function sha256(text: string): string {
+  const host = (globalThis as { nomos?: { sha256?: (s: string) => string } }).nomos;
+  if (host === undefined || typeof host.sha256 !== "function") {
+    throw new Error(
+      "birth-meter: the `nomos.sha256` host port is not available — a `.births()` dispatch needs the " +
+        "engine/client runtime (tests: stub `globalThis.nomos.sha256`).",
+    );
+  }
+  return host.sha256(text);
+}
+
+/**
+ * CAPTURE the three meter reads on the write path (A2 — the plan side of the birth-quota gate; the
+ * exact `countQuotaReads` shape). Called by `executeDirectiveToIntent` for every `.births()` dispatch
+ * that planned ≥1 birth — the values ride `captured_ports.reads`, CAS-re-derived + byte-compared at
+ * the pre-apply position on every lane; the verdict is the synthesized invariant's.
+ */
+export function captureBirthMeterReads(subject: string): void {
+  __captureBirthMeterRead(birthRecordsByPrincipal, { principal: subject });
+  __captureBirthMeterRead(birthGrantByPrincipal, { principal: subject });
+  __captureBirthMeterRead(birthPolicy, { scope: "workspace" });
+}
+
+/**
+ * THE AUTO-RECORD (A1): the `NomosBirthRecord` field ops for ONE planned birth, appended by
+ * `executeDirectiveToIntent` to the SAME intent that carries the birth effect. Deterministic-id
+ * upsert (Lww — a re-birth of the same child name updates the record), a fan-out sibling event
+ * exactly like `installDomain`'s `DomainInstallation` writes.
+ */
+export function planBirthRecordOps(
+  recipe: BirthRecipe,
+  subject: string,
+  bornAt: string,
+): PlannedOp[] {
+  const rec = instance(NomosBirthRecord, birthRecordId(recipe.workspace));
+  return [
+    // ENSURE, not a bare update: the record id is deterministic and the FIRST birth of a child writes a
+    // row that does not yet exist — the referential gate refuses a Mutate of a non-existent id, so the
+    // event must lower `Ensure` (create-or-update), exactly how `installDomain` lowers its
+    // DomainInstallation singleton (`withMarker(..., "ensures")`). One marked op sets the whole event's
+    // marker; both lanes share THIS function, so the op shape is byte-identical by construction.
+    withMarker(set(rec, "child", recipe.workspace), "ensures"),
+    set(rec, "principal", subject),
+    set(rec, "childGenesisHash", sha256(JSON.stringify(recipe.genesisChain))),
+    set(rec, "bornAt", bornAt),
+  ];
+}
+
+// ── A2 — the quota verdict + the synthesized per-directive invariant ────────────────────────────────
+
+/** A captured-read row as `derive_captured_read` shapes it: `{id, data:{field:value}}`. */
+type MeterRow = { id?: string; data?: Record<string, unknown> };
+
+/**
+ * THE BIRTH-QUOTA VERDICT — the PURE predicate over the COMMITTED captured reads (the same
+ * `{queryId,args,result}` the plan recorded, CAS-re-derived on every lane). Counts the subject's
+ * birth records and compares against its allowance (the latest BirthGrant.maxBirths if any, else
+ * BirthPolicy.maxBirthsPerPrincipal, else {@link DEFAULT_MAX_BIRTHS_PER_PRINCIPAL}). The NEW birth's
+ * record is NOT yet in the pre-apply state, so `count < allowance` (strict) is the correct test. A
+ * subject-less birth fails CLOSED. Identical on author, edge admission, and verify_chain.
+ */
+export function birthQuotaVerdict(
+  reads: readonly { queryId: string; args: Record<string, string>; result: unknown }[],
+  subject: string,
+): WorkspaceInvariantVerdict {
+  if (!subject) return { reject: "birth-quota-missing-subject" };
+  const rowsOf = (queryId: string, argKey: string, argValue: string): MeterRow[] => {
+    const hit = reads.find((r) => r.queryId === queryId && r.args[argKey] === argValue);
+    return Array.isArray(hit?.result) ? (hit!.result as MeterRow[]) : [];
+  };
+  const count = rowsOf(birthRecordsByPrincipal.id, "principal", subject).length;
+  // ALLOWANCE: the LATEST BirthGrant (max grantedAt) wins; else the BirthPolicy singleton; else the floor.
+  let allowance: number | undefined;
+  let latestGrantedAt = -Infinity;
+  for (const g of rowsOf(birthGrantByPrincipal.id, "principal", subject)) {
+    const at = Number(g.data?.grantedAt ?? -Infinity);
+    const max = Number(g.data?.maxBirths ?? NaN);
+    if (Number.isFinite(at) && at > latestGrantedAt && Number.isFinite(max)) {
+      latestGrantedAt = at;
+      allowance = max;
+    }
+  }
+  if (allowance === undefined) {
+    const policyRows = rowsOf(birthPolicy.id, "scope", "workspace");
+    const max = Number(policyRows[0]?.data?.maxBirthsPerPrincipal ?? NaN);
+    if (Number.isFinite(max)) allowance = max;
+  }
+  if (allowance === undefined) allowance = DEFAULT_MAX_BIRTHS_PER_PRINCIPAL;
+  return count < allowance ? { accept: true } : { reject: "birth-quota-exceeded" };
+}
+
+/** The synthesized invariant's stable, deterministic id for a `.births()` directive. */
+export function birthQuotaInvariantId(directiveId: string): string {
+  return `${directiveId}__birthQuota`;
+}
+
+/**
+ * Synthesize THE BIRTH-QUOTA workspace invariant for ONE directive (A2). `[]` unless the directive
+ * declares `.births()` (the era rule — a birth-free directive synthesizes nothing, byte-identical).
+ * Applied at the SAME three sites the precondition desugaring rides (`composeDomainModule`, the
+ * engine slice build, the openapi decls) so the manifest's `nomosInvariantGate` entry and the sealed
+ * engine's executable body can never disagree. The verdict reads the row LIST off the captured reads
+ * (`ctx.reads` — the snapshot ref-set is empty; ref-resolution cannot enumerate), the exact
+ * WorkspaceQuota shape.
+ */
+export function synthesizeBirthQuotaInvariants(directive: {
+  id: string;
+  birthsChild?: boolean;
+}): WorkspaceInvariantDecl[] {
+  if (directive.birthsChild !== true) return [];
+  return [
+    {
+      id: birthQuotaInvariantId(directive.id),
+      on: directive.id,
+      reads: () => [],
+      assert: (_snapshots, ctx) => {
+        // A `.births()` plan that planned NO birth (e.g. birthChild without a genesis) captures no
+        // meter reads and consumes no allowance — accept without judging (nothing was born).
+        const reads = (ctx?.reads ?? []) as {
+          queryId: string;
+          args: Record<string, string>;
+          result: unknown;
+        }[];
+        if (!reads.some((r) => r.queryId === birthRecordsByPrincipal.id)) return { accept: true };
+        return birthQuotaVerdict(reads, birthMeterSubject(ctx?.intent ?? {}));
+      },
+      __isWorkspaceInvariant: true as const,
+    },
+  ];
+}
+
+/** The meter aggregates every `.births()`-declaring domain auto-ensures (the RelationTuple courtesy). */
+export const BIRTH_METER_AGGREGATES: readonly AggregateHandle[] = [
+  NomosBirthRecord,
+  BirthPolicy,
+  BirthGrant,
+] as unknown as readonly AggregateHandle[];

package/src/birth_meter_ensure.ts

@@ -0,0 +1,67 @@
+// 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}.  If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * THE BIRTH-RECORD SANCTIONING DECLARATION (metered birth, slice A1 — the id-mint-gate half).
+ *
+ * The auto-appended `NomosBirthRecord` event is an ENSURE at a deterministic id
+ * (`nomos-birth-record:<child>`). The kernel's id-mint gate admits an Ensure-INTRODUCED typed id
+ * ONLY through the sanctioned upsert-by-deterministic-key lane: the CERTIFIED manifest must declare
+ * the type as an `ensures` TARGET — i.e. the law must carry a directive whose marker is `Ensure`
+ * targeting `NomosBirthRecord` (exactly how `installDomain` sanctions `DomainInstallation`, or the
+ * governance `setBirthPolicy` sanctions `BirthPolicy`). A tenant `.births()` law writes the record
+ * by construction but authors NO such directive — so this module supplies it, injected at the ONE
+ * module-merge seam every plane shares (compose / engine slice / self-describe / compile openapi),
+ * keeping the compiled openapi and the lump's `describe()` byte-consistent.
+ *
+ * {@link nomosBirthRecordEnsure} is DELIBERATELY USELESS TO DISPATCH: its plan writes NOTHING (zero
+ * ops — it cannot forge a record), it exists purely so the law's manifest/USD carries the
+ * `Ensure → NomosBirthRecord` declaration the id-mint gate reads. Era-ruled like everything else in
+ * the meter: only a `.births()`-declaring domain gains it; every other law is byte-identical.
+ */
+import { z } from "zod";
+import { directive } from "./directive.js";
+import type { Directive } from "./directive.js";
+import {
+  NomosBirthRecord,
+  BirthPolicy,
+  BirthGrant,
+} from "./birth_meter.js";
+
+/**
+ * The sanctioning declaration — an `ensures(NomosBirthRecord)` directive whose plan emits ZERO ops.
+ * Its only load-bearing property is its manifest/USD presence (marker `Ensure`, target
+ * `NomosBirthRecord`), which opens the id-mint gate's declared-ensures lane for the auto-appended
+ * birth record. Dispatching it is a harmless no-op (no events, nothing folds).
+ */
+export const nomosBirthRecordEnsure = directive("nomosBirthRecordEnsure")
+  .ensures(NomosBirthRecord)
+  .payload(z.object({}).strict())
+  .plan(() => []);
+
+/**
+ * Inject the birth-meter's structural exports into a merged module-exports bag IFF it declares ≥1
+ * `.births()` directive (the RelationTuple "discoverable without re-exports" courtesy, at the one
+ * merge seam): the sanctioning {@link nomosBirthRecordEnsure} directive + the meter aggregates (so
+ * the engine registry / self-describe see the same surface the composed manifest carries). A
+ * birth-free bag is returned UNTOUCHED (the era rule — byte-identical). Existing keys are never
+ * overwritten (a law composing the framework governance surface keeps its own bindings).
+ */
+export function withBirthMeterExports<M extends Record<string, unknown>>(mod: M): M {
+  const declaresBirth = Object.values(mod).some(
+    (v) =>
+      v !== null &&
+      typeof v === "object" &&
+      (v as { birthsChild?: boolean }).birthsChild === true &&
+      typeof (v as Directive<unknown>).plan === "function",
+  );
+  if (!declaresBirth) return mod;
+  const out: Record<string, unknown> = { ...mod };
+  if (!("nomosBirthRecordEnsure" in out)) out["nomosBirthRecordEnsure"] = nomosBirthRecordEnsure;
+  if (!("NomosBirthRecord" in out)) out["NomosBirthRecord"] = NomosBirthRecord;
+  if (!("BirthPolicy" in out)) out["BirthPolicy"] = BirthPolicy;
+  if (!("BirthGrant" in out)) out["BirthGrant"] = BirthGrant;
+  return out as M;
+}