@githolon/dsl 0.17.0 → 0.19.0

package/dart/lib/nomos_client.dart

@@ -26,11 +26,16 @@ library;
 export 'src/wire.dart';
 export 'src/driver.dart';
 export 'src/offer.dart';
+// homeNameOf(subject) — the canonical home-workspace name (parity with @githolon/client + the law side).
+export 'src/home.dart';
 export 'src/subscriptions.dart';
 export 'src/schema_validation.dart';
 // THE WEBVIEW BRIDGE (app-binding boundary) — the async Dart runtime that drives the REAL githolon running
 // in a WebView, so the generated typed client never needs a `MemoryPersistence` fake.
 export 'src/webview_bridge.dart';
+// TYPED DIAGNOSTICS (co2 feedback req 7) — the fixed set of ways the home-birth ceremony can fail, each
+// extending NomosBridgeError so existing handlers still catch them, named so the app can branch on `is`.
+export 'src/errors.dart';
 // The PROVIDER boundary (server-side capability-provider SDK runtime: TaskOutcome /
 // TaskSuccess / TaskFailure / TaskResult / TaskProvider / HostClock). The symmetric twin
 // of `offer.dart`; the generated per-task provider classes build on it.

package/dart/lib/src/errors.dart

@@ -0,0 +1,79 @@
+// 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.
+
+/// TYPED DIAGNOSTICS for the home factory (co2 feedback req 7).
+///
+/// The generic [NomosBridgeError] (in `webview_bridge.dart`) is the catch-all for a refusal the githolon
+/// surfaces verbatim. But the HOME-BIRTH CEREMONY ([NomosScope.home]) has a small, fixed set of ways it can
+/// fail — and each one wants a DIFFERENT remedy from the app (re-auth vs. retry vs. "deploy the home law").
+/// These typed errors name the exact failure so the app's `errorBuilder` can branch on `is`, and so a log
+/// line says WHICH leg of the ceremony broke, not just "connect failed".
+///
+/// All extend [NomosBridgeError] so existing `catch (NomosBridgeError)` handlers still catch them.
+library;
+
+import 'webview_bridge.dart' show NomosBridgeError;
+
+/// 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).
+/// REMEDY: re-acquire a fresh token from the auth provider and reconnect.
+class AuthTokenInvalid extends NomosBridgeError {
+  AuthTokenInvalid([String? message])
+      : super(message ?? 'the auth-provider token was missing or rejected (the cloud refused 401) — a birth needs a verified principal');
+}
+
+/// The workspace name the cloud reported for the born home does NOT equal `homeNameOf(subject)`. The home's
+/// own law commits to `home-<sha256(subject)>` (the squat invariant), so a mismatch means the cloud routed to
+/// the wrong slot — a fail-closed safety stop, never silently mount the wrong holon.
+class HomeNameMismatch extends NomosBridgeError {
+  /// What `homeNameOf(subject)` derived locally.
+  final String expected;
+
+  /// What the cloud reported (its status `lineage.id` / the name it served).
+  final String reported;
+  HomeNameMismatch({required this.expected, required this.reported, String? message})
+      : super(message ?? 'the cloud reported home "$reported" but this subject hashes to "$expected" — refusing to mount a home whose name does not bind its owner');
+}
+
+/// The workspace exists and is born, but the HOME LAW is not installed/active on it — so it is a plain
+/// workspace, not a home holon. Per req 2 there is NO generic fallback: a home that cannot be confirmed to
+/// run the home law FAILS here rather than silently mounting a lawless workspace. REMEDY: the tenant's
+/// governance must install the home law (the birth offer should author it; if it didn't, the deploy is wrong).
+class HomeLawMissing extends NomosBridgeError {
+  /// The workspace that is missing the home law.
+  final String workspace;
+  HomeLawMissing({required this.workspace, String? message})
+      : super(message ?? 'workspace "$workspace" is born but the home law is not installed/active on it — refusing to mount a plain workspace as a home');
+}
+
+/// The offer to the home's birth lane was REFUSED by the parent's gate (the law denied the birth — e.g. the
+/// principal lacks creation authority, the pool is exhausted, or the genesis recipe was rejected). Carries
+/// the cloud's verdict verbatim. REMEDY is tenant-specific (grant creation authority / raise the pool).
+class BirthRejected extends NomosBridgeError {
+  /// The birth-lane directive id that was offered (e.g. the tenant's `birthHome` / `seedHomeOwner`).
+  final String? directiveId;
+
+  /// The HTTP status the cloud answered, when known.
+  final int? statusCode;
+  BirthRejected({String? message, this.directiveId, this.statusCode})
+      : super(message ?? 'the home birth offer was refused by the law${directiveId != null ? ' (directive "$directiveId")' : ''}${statusCode != null ? ' [$statusCode]' : ''}');
+}
+
+/// A pack the cloud returned (or the local holon produced) was malformed — it could not be parsed/applied as
+/// a git pack. This is a transport/custody integrity fault, not a law refusal. REMEDY: retry; if persistent,
+/// the custody bytes are corrupt.
+class PackMalformed extends NomosBridgeError {
+  PackMalformed([String? message]) : super(message ?? 'a returned pack was malformed and could not be applied (custody integrity fault)');
+}
+
+/// The home law's content hash could not be resolved — the cloud reported no current law for the home's
+/// domain key, so the app cannot confirm WHICH law the home runs (and thus cannot baked-hash-pin or judge
+/// installed-ness). REMEDY: the home law must be deployed; if it was, retry once the deploy has folded.
+class LawHashUnavailable extends NomosBridgeError {
+  /// The workspace whose current law hash could not be resolved.
+  final String workspace;
+  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');
+}

package/dart/lib/src/home.dart

@@ -0,0 +1,20 @@
+import 'dart:convert';
+
+import 'package:crypto/crypto.dart';
+
+/// The canonical home-workspace name for an identity SUBJECT (e.g. `user:<firebaseUid>`).
+///
+/// BYTE-IDENTICAL to `@githolon/client`'s `homeNameOf` and the law side
+/// (`dsl/src/framework/home.ts` `HOME_NAME_PREFIX`). A home holon is named by its SUBJECT — never the raw
+/// uid and never an app-chosen workspace name — so the same principal always resolves the same home, on
+/// every peer and on the cloud. Use it directly as the `workspace`:
+///
+/// ```dart
+/// NomosScope(workspace: homeNameOf('user:$firebaseUid'), ...)
+/// ```
+///
+/// Formula: `home-` + the first 40 hex chars of `sha256(utf8(subject))`.
+String homeNameOf(String subject) {
+  final hex = sha256.convert(utf8.encode(subject)).toString(); // lowercase hex
+  return 'home-${hex.substring(0, 40)}';
+}

package/dart/lib/src/webview_bridge.dart

@@ -156,12 +156,16 @@ class NomosBridge {
       required String workspace,
       String? clientId,
       String? authToken,
+      String? authorSecret,
       String? restoreFrom}) async {
     await _call('connect', {
       'cloud': cloud,
       'workspace': workspace,
       if (clientId != null) 'clientId': clientId,
       if (authToken != null) 'authToken': authToken,
+      // The device signing secret (base64, from [authorKeygen]) — the warrant default for every offer.
+      // Stays client-side; the kernel mints the signed-author attestation so authorship is replay-provable.
+      if (authorSecret != null) 'authorSecret': authorSecret,
       if (restoreFrom != null) 'restoreFrom': restoreFrom
     });
   }
@@ -172,6 +176,70 @@ class NomosBridge {
     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
+  /// replay — the durable, cryptographic answer to "who authored this?" (the warrant). Mint once per device.
+  Future<Map<String, Object?>> authorKeygen() async =>
+      _asMap(await _call('authorKeygen'));
+
+  /// Mint a DEVICE KEY for the VA root-of-trust (`{secret, public}`, base64) — an alias of [authorKeygen]
+  /// the birth-cert flow speaks. The SECRET stays on this device (secure storage); it signs birth certs
+  /// ([signBirthCert]) + writes ([connect]'s `authorSecret`) on the LOCAL kernel; the PUBLIC half is enrolled
+  /// on-chain ([enrollDevice]). Never put the secret on the chain.
+  Future<Map<String, Object?>> mintDeviceKey() async =>
+      _asMap(await _call('mintDeviceKey'));
+
+  /// VA ROOT-OF-TRUST: sign a BirthCert through the kernel `cert_sign` op (the SINGLE source of the cert
+  /// byte-layout — no Dart copy). `fields` = `{child, founder, verified, parentKey (this device's base64
+  /// ed25519 PUBLIC half), parentId, epoch}`; `deviceSecret` is that key's base64 SECRET half, handed to the
+  /// LOCAL kernel only (it never reaches a server). Returns the snake_case cert JSON `verify_to_root` parses.
+  Future<Map<String, Object?>> signBirthCert(
+          Map<String, Object?> fields, String deviceSecret) async =>
+      _asMap(await _call(
+          'signBirthCert', {'fields': fields, 'deviceSecret': deviceSecret}))['cert'] as Map<String, Object?>? ??
+      const {};
+
+  /// ENROLL THIS DEVICE — the LIVE gate: bind a device key's PUBLIC half to `principal` on-chain as a
+  /// `signer` so the holon's gate can PROVE this device's authorship on replay (and the VA chain attest it).
+  /// `publicKey` is the base64 PUBLIC half (from [mintDeviceKey]); `authToken` (defaults to the connect-time
+  /// bearer) is the VERIFIED identity that authorizes the enrollment. Returns the offer verdict.
+  Future<Map<String, Object?>> enrollDevice(
+          {required String principal,
+          required String publicKey,
+          String? authToken}) async =>
+      _asMap(await _call('enrollDevice', {
+        'principal': principal,
+        'publicKey': publicKey,
+        if (authToken != null) 'authToken': authToken,
+      }));
+
+  /// VERIFY_CHAIN — the kernel's from-genesis self-verification of THIS holon's folded ledger (read-only:
+  /// contiguity → every intent re-admitted through the ONE gate against the state folded from the prefix). For
+  /// a WARRANTED home this RE-FIRES the parent-attested-birth cert door on the cold-replay lane — so a
+  /// freshly-connected peer that CLONES a home and runs this IS the offline peer-verify (replay IS validation;
+  /// no new op). Returns the kernel verdict `{valid, error?, plansRerun?}`.
+  Future<Map<String, Object?>> verifyChain() async =>
+      _asMap(await _call('verifyChain'));
+
+  /// BIRTH A HOME — THE CEREMONY (VA root-of-trust, drift-proof), run end-to-end inside the connected holon:
+  /// derive the deterministic home name, mint + enroll the device key, DEVICE-SIGN the home cert through the
+  /// kernel `cert_sign` op (the single source of the byte layout), OFFER the PARAMETERIZED parent's `birthHome`
+  /// directive carrying the homeCert, poll the parent for the born home, and CONFIRM the born home's own
+  /// `verify_chain` is GREEN (the offline peer-verify — replay IS validation). `spec` MUST carry `parent` (the
+  /// tenant's platform whose governance includes `birthHome`), `principal`, `frameworkHash`, and `lawHash`;
+  /// `subject`/`authToken`/`directiveId` are optional. OURS is the ceremony; the parent is the TENANT's.
+  /// Returns `{home, device:{secret,public}, homeCert, born, verify:{valid,…}}`.
+  Future<Map<String, Object?>> birthHome(Map<String, Object?> spec) async =>
+      _asMap(await _call('birthHome', spec));
+
+  /// Sign a cross-custody SHARE attestation `{secret, asserterWorkspace, object, relation, subject,
+  /// attestedAt}` → `{publicKey, signature}`. This is what drives `recordShare` into an invitee's home
+  /// (the free global invitation system): the granting workspace signs that it shares `object#relation`
+  /// with `subject`, and the invitee's home gate verifies the signature before recording it.
+  Future<Map<String, Object?>> attestationSign(Map<String, Object?> args) async =>
+      _asMap(await _call('attestationSign', {'args': args}));
+
   /// A declared query's rows from the local projection.
   Future<List<Map<String, dynamic>>> query(String queryId,
           [Map<String, Object?> params = const {}]) async =>

package/dart/lib/src/wire.dart

@@ -92,6 +92,24 @@ sealed class Value {
         (k, v) => MapEntry(k, WireField.fromJson(v as Map<String, dynamic>)),
       ));
     }
+    // `Value::Evidence(EvidenceRef)` — the content-addressed BACKING of a claim. The hash is the
+    // git blob oid bound at author time; the gate re-derives + backs it (kernel/src/evidence.rs,
+    // evidence.md §1/§5). Capture-time-irreversible provenance — decode it so it round-trips
+    // (a claim's evidence must survive every peer, not be dropped to an "unknown variant").
+    if (json.containsKey('Evidence')) {
+      final r = json['Evidence'] as Map<String, dynamic>;
+      return ValueEvidence(
+        hash: r['hash'] as String,
+        mediaType: r['media_type'] as String,
+        byteLength: (r['byte_length'] as num).toInt(),
+        storageClass: r['storage_class'] as String, // "Git" | "External"
+      );
+    }
+    // `Value::Json(CanonicalJson)` — first-class JSON committed INLINE (RFC 8785/JCS), replacing
+    // the old t.json-as-Value::Str. The held value is the decoded JSON tree.
+    if (json.containsKey('Json')) {
+      return ValueJson(json['Json']);
+    }
     throw FormatException('Unknown Value variant: ${json.keys}');
   }
 
@@ -165,6 +183,105 @@ class ValueMap extends Value {
   String toString() => 'ValueMap($value)';
 }
 
+/// `Value::Evidence(EvidenceRef)` ->
+/// `{"Evidence":{"hash":"<git-oid>","media_type":"application/pdf","byte_length":1024,"storage_class":"Git"}}`.
+///
+/// A content-addressed, framework-owned reference to the bytes that BACK a claim (`evidence.md` §1;
+/// `kernel/src/evidence.rs`). The `hash` is the git blob oid of the bytes — bound AT AUTHOR TIME and
+/// re-derived by the gate, so a claim's evidence binding is provable forever. The bytes live in the
+/// Evidence Store, never the ledger op. This variant is capture-time-irreversible provenance: it must
+/// round-trip on every peer, so the client decodes it (never drops it to "unknown variant").
+class ValueEvidence extends Value {
+  final String hash;
+  final String mediaType;
+  final int byteLength;
+  final String storageClass; // "Git" | "External"
+  const ValueEvidence({
+    required this.hash,
+    required this.mediaType,
+    required this.byteLength,
+    required this.storageClass,
+  });
+
+  @override
+  Map<String, dynamic> toJson() => {
+        'Evidence': {
+          'hash': hash,
+          'media_type': mediaType,
+          'byte_length': byteLength,
+          'storage_class': storageClass,
+        }
+      };
+
+  @override
+  bool operator ==(Object other) =>
+      other is ValueEvidence &&
+      other.hash == hash &&
+      other.mediaType == mediaType &&
+      other.byteLength == byteLength &&
+      other.storageClass == storageClass;
+  @override
+  int get hashCode => Object.hash('Evidence', hash, mediaType, byteLength, storageClass);
+  @override
+  String toString() =>
+      'ValueEvidence($hash, $mediaType, $byteLength, $storageClass)';
+}
+
+/// `Value::Json(CanonicalJson)` -> `{"Json": <any canonical-JSON value>}`.
+///
+/// First-class JSON committed INLINE (the kernel canonicalizes to RFC 8785 / JCS), replacing the old
+/// `t.json`-as-`Value::Str`. The held `value` is the decoded JSON tree (Map / List / num / String /
+/// bool / null). Equality is structural over the decoded tree.
+class ValueJson extends Value {
+  final dynamic value;
+  const ValueJson(this.value);
+
+  @override
+  Map<String, dynamic> toJson() => {'Json': value};
+
+  @override
+  bool operator ==(Object other) => other is ValueJson && _jsonEq(other.value, value);
+  @override
+  int get hashCode => Object.hash('Json', _jsonHash(value));
+  @override
+  String toString() => 'ValueJson($value)';
+}
+
+/// Structural deep-equality over a decoded JSON tree (Map / List / scalar) — no `dart:convert` dep.
+bool _jsonEq(dynamic a, dynamic b) {
+  if (identical(a, b)) return true;
+  if (a is Map && b is Map) {
+    if (a.length != b.length) return false;
+    for (final e in a.entries) {
+      if (!b.containsKey(e.key) || !_jsonEq(e.value, b[e.key])) return false;
+    }
+    return true;
+  }
+  if (a is List && b is List) {
+    if (a.length != b.length) return false;
+    for (var i = 0; i < a.length; i++) {
+      if (!_jsonEq(a[i], b[i])) return false;
+    }
+    return true;
+  }
+  return a == b;
+}
+
+/// Order-independent hash over a decoded JSON tree (consistent with [_jsonEq]).
+int _jsonHash(dynamic v) {
+  if (v is Map) {
+    var h = 0;
+    for (final e in v.entries) {
+      h ^= Object.hash(e.key, _jsonHash(e.value));
+    }
+    return Object.hash('jmap', h);
+  }
+  if (v is List) {
+    return Object.hash('jlist', Object.hashAll(v.map(_jsonHash)));
+  }
+  return v.hashCode;
+}
+
 /// `Field { value: Value, stamp: Hlc }` — only used when reading state back.
 ///
 /// Named `WireField` to avoid clashing with the DSL field-builder concept and

package/dart/pubspec.lock

@@ -74,7 +74,7 @@ packages:
     source: hosted
     version: "1.15.0"
   crypto:
-    dependency: transitive
+    dependency: "direct main"
     description:
       name: crypto
       sha256: c8ea0233063ba03258fbcf2ca4d6dadfefe14f02fab57702265467a19f27fadf

package/dart/pubspec.yaml

@@ -11,13 +11,14 @@ 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.17.0
+version: 0.18.0
 
 environment:
   sdk: ^3.5.0
 
 dependencies:
   json_schema: ^5.2.2
+  crypto: ^3.0.0
 
 dev_dependencies:
   test: ^1.25.0

package/dart/test/home_parity_test.dart

@@ -0,0 +1,9 @@
+import 'package:nomos_client/nomos_client.dart';
+import 'package:test/test.dart';
+void main() {
+  test('homeNameOf matches the JS/law formula', () {
+    expect(homeNameOf('user:abc-123'), 'home-5094641143043f9281b6b9146cc345a254a5d3af');
+    expect(homeNameOf('user:abc-123').startsWith('home-'), isTrue);
+    expect(homeNameOf('user:abc-123').length, 45); // 'home-' + 40 hex
+  });
+}

package/dart/test/wire_test.dart

@@ -46,9 +46,57 @@ void main() {
       (m) => Value.fromJson(m),
     );
 
+    // Value::Evidence — the content-addressed claim BACKING (capture-time-irreversible provenance).
+    // The raw serde shape is snake_case (the Rust EvidenceRef field names) + storage_class as a bare
+    // unit-variant string ("Git"/"External"). It MUST round-trip, never drop to "unknown variant".
+    roundTrips(
+      'Value::Evidence',
+      '{"Evidence":{"hash":"e69de29bb2d1d6434b8b29ae775ad8c2e48c5391","media_type":"application/pdf","byte_length":1024,"storage_class":"Git"}}',
+      (m) => Value.fromJson(m),
+    );
+    // Value::Json — first-class inline JSON (RFC 8785/JCS), nested object value.
+    roundTrips(
+      'Value::Json',
+      '{"Json":{"a":1,"b":["x","y"],"c":{"d":true}}}',
+      (m) => Value.fromJson(m),
+    );
+
     test('Value::Int -> ValueInt', () {
       expect(Value.fromJson({'Int': 10}), const ValueInt(10));
     });
+    test('Value::Evidence decodes the snake_case ref + bare storage class', () {
+      final v = Value.fromJson({
+        'Evidence': {
+          'hash': 'abc123',
+          'media_type': 'image/png',
+          'byte_length': 42,
+          'storage_class': 'External',
+        }
+      });
+      expect(
+        v,
+        const ValueEvidence(
+          hash: 'abc123',
+          mediaType: 'image/png',
+          byteLength: 42,
+          storageClass: 'External',
+        ),
+      );
+    });
+    test('Value::Json structural equality over the decoded tree', () {
+      expect(
+        Value.fromJson({
+          'Json': {
+            'a': 1,
+            'b': [true, null]
+          }
+        }),
+        const ValueJson({
+          'a': 1,
+          'b': [true, null]
+        }),
+      );
+    });
   });
 
   group('Op variants', () {

package/package.json

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

@@ -0,0 +1,106 @@
+// 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 EFFECT — birth is an EXPLICIT, DECLARED kernel primitive (G3, the unix model).
+ *
+ * "A syscall does a defined thing and finishes; no implicit side-effects inferred from scanning state."
+ * A `.births()` directive's `plan` PRODUCES the child's genesis recipe (reuse `buildGenesisChain`) and
+ * records it onto the intent's BIRTH EFFECT via `birth(recipe)`. The recipe rides the committed intent as
+ * a DECLARED OUTPUT — exactly like a captured read rides `captured_ports.reads` — NEVER as a field set on a
+ * domain aggregate the kernel would have to scan (a circular dependency the kernel must never have).
+ *
+ * The kernel reads the `.births` DECLARATION from the law manifest (the `nomosBirthGate` era key, the SAME
+ * mechanism it reads `.reads`/`.creates`/invariants by — NOT domain state) to KNOW an admitted directive
+ * births; it then takes the recipe off this carried effect and spawns + self-validates the child through its
+ * OWN gate (the `materialize_genesis` keystone). The dev never sees this sink — they call `birth(recipe)`;
+ * the library routes it here and `executeDirectiveToIntent` drains it onto the intent.
+ */
+
+/** ONE birth recipe the plan produced — the child's genesis chain (the `buildGenesisChain` JSON array of
+ *  `{domain, directiveId, payload, actor[, domainPackageB64, domainHash]}` steps). Carried verbatim onto the
+ *  intent's birth effect; the kernel folds it through the child's own gate (each step self-verifies). */
+export interface BirthRecipe {
+  /** The child workspace name the parent asked to birth (lineage + the child's `:ws` segment). */
+  readonly workspace: string;
+  /** The genesis chain: the ordered steps the child runs through its OWN gate to validate itself from intent 0. */
+  readonly genesisChain: unknown;
+}
+
+// ── the per-dispatch birth footprint — library state drained by `executeDirectiveToIntent` (mirrors the
+//    captured-read footprint in read.ts; internal to the directive runtime, never a sandbox side channel). ──
+let footprint: BirthRecipe[] = [];
+/** Clear the footprint before a plan runs (called by `executeDirectiveToIntent`). */
+export function __resetBirths(): void {
+  footprint = [];
+}
+/** Take + clear the births recorded during a plan (called by `executeDirectiveToIntent`). */
+export function __drainBirths(): BirthRecipe[] {
+  const f = footprint;
+  footprint = [];
+  return f;
+}
+
+/**
+ * Record a BIRTH the plan declares: the child's genesis recipe rides the committed intent as a DECLARED
+ * effect (the kernel takes it off the intent after admit and spawns + self-validates the child). The
+ * directive MUST declare `.births()` (which lands the `nomosBirthGate` era key in the law's USD-IR) — the
+ * kernel executes the birth ONLY for a directive its resolved law names there (the era rule: pre-feature
+ * chains carry no key, so they replay byte-green and the kernel does nothing). A plan may birth at most one
+ * child per intent (one offer, one defined consequence — the unix model).
+ *
+ * TO BIRTH A LEAF CHILD RUNNING ITS OWN LAW (a home, an estate child) — copy `framework/home.ts`'s
+ * `birthHome`. The recipe is just the two-layer law install + your own seed step; there is NO helper to
+ * fabricate it and you do NOT need a new primitive (recursion is the law — a home births children exactly
+ * as root births platforms). `buildGenesisChain` is the ONE builder for the PLATFORM shape (it adds the
+ * `seedGenesis → grantAdmin → birthCloud` tail); a leaf just omits that tail:
+ *
+ * ```ts
+ * export const birthEstateChild = directive("birthEstateChild")
+ *   .creates(EstateChild)
+ *   .payload(z.object({ child: z.string(), owner: z.string(),
+ *     frameworkHash: z.string(), lawHash: z.string(), bornAt: z.string() }))
+ *   .plan((p) => {
+ *     const actor = "user:" + p.owner;
+ *     birth({ workspace: p.child, genesisChain: [
+ *       { domain: "bootstrap", directiveId: "installDomain", actor, payload: { domainHash: p.frameworkHash }, domainHash: p.frameworkHash, domainPackageB64: "" },
+ *       { domain: "nomos",     directiveId: "installDomain", actor, payload: { domainHash: p.lawHash },       domainHash: p.lawHash,       domainPackageB64: "" },
+ *       { domain: "estate",    directiveId: "seedEstateChild", actor, payload: { owner: p.owner, bornAt: p.bornAt } },
+ *     ] });
+ *     return [];
+ *   })
+ *   .births()             // the kernel's run_birth_effect folds the recipe through the CHILD's own gate
+ *   .requires("creator"); // grant the parent's owner #creator (self-bound) — the birth authority
+ * ```
+ */
+export function birth(recipe: BirthRecipe): void {
+  footprint.push(recipe);
+}
+
+/**
+ * THE PEER-SOVEREIGN ROOT-OF-TRUST SENTINEL (the BirthAttestation cert chain). A home/child law EXPORTS
+ * this marker to declare it REQUIRES a parent-attested-birth: a warranted workspace running this law must
+ * travel with a SIGNED cert chain proving its founder was VERIFIED by its parent at birth, rooting at the
+ * pinned `K_root`. The composer discovers this by shape (`__isParentAttestedBirth`) — like an aggregate
+ * handle — and lowers it to the `nomosParentAttestedBirth` USD era key (emitted iff present). The kernel's
+ * verify doors then verify the travelling cert chain OFFLINE (no cross-ws read). ERA-RULED: a law that
+ * never exports it carries no key and replays byte-identical (pre-feature + legacy/non-warranted homes).
+ *
+ *   export const parentAttested = requireParentAttestedBirth;   // in the home law module
+ */
+export interface ParentAttestedBirthMarker {
+  readonly __isParentAttestedBirth: true;
+}
+export const requireParentAttestedBirth: ParentAttestedBirthMarker = { __isParentAttestedBirth: true };
+
+/** Shape-discover the {@link requireParentAttestedBirth} sentinel in a module's exports (the composer). */
+export function moduleRequiresParentAttestedBirth(mod: Record<string, unknown>): boolean {
+  for (const v of Object.values(mod)) {
+    if (v && typeof v === "object" && (v as ParentAttestedBirthMarker).__isParentAttestedBirth === true) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/build_package.ts

@@ -19,14 +19,15 @@
  *     15-positional-parameter `module(...)` helper (dedupe by wire id, the
  *     impure-capability directive check, default read-models, and the
  *     HASH-LOAD-BEARING omit-when-empty key discipline).
- *   * `buildReadManifest(modules)` — the LEVEL-2 read-projection artifact
- *     (`domain_manifests.json`: aggregateFieldKinds + query/count/spatial/derived/
- *     combined routing descriptors), hoisted from `emit_manifests.ts`. Field KINDS,
- *     not drivers — see that file's header for why the split is load-bearing.
- *   * `buildIdentity(modules)` / `writeIdentity(emit, outDir)` — the per-domain
- *     IDENTITY manifest + admits_domain_hash registry (#193/#136), hoisted from
- *     `emit_identity.ts` (palette-gap domains recorded-and-excluded, the
- *     cross-language sha anchor asserted per emitted domain).
+ *   * `buildReadManifest(modules)` — the read-projection descriptor (aggregateFieldKinds +
+ *     query/count/spatial/derived/combined routing). Field KINDS, not drivers. NO LONGER WRITTEN to
+ *     `build/` (the old `domain_manifests.json` sidecar was a local diagnostic the contract ignored); the
+ *     read routing lives in the package OpenAPI now. Kept as a function for callers that want the value.
+ *   * `buildIdentity(modules)` — the per-domain IDENTITY emit + admits_domain_hash registry (#193/#136),
+ *     hoisted from `emit_identity.ts` (palette-gap domains recorded-and-excluded). The admission identity
+ *     is carried in the package USD IR + the committed `nomos.stable-ids.json` lockfile; the old
+ *     `domain_identity_*.json` sidecars (and `writeIdentity`) are REMOVED. The per-domain hash is surfaced
+ *     in the compile summary.
  *   * `packageUsda(usdJson, javascript)` — the `.package.usda` envelope, byte-exact
  *     to `build_nomos.mjs` `packageUsda()` == Rust `domain_package_from_js`
  *     (deterministic-rquickjs/src/domain_package.rs).
@@ -57,6 +58,7 @@ import { domainHash, emitManifestBytes } from "./manifest.js";
 import { emitUsd } from "./usd.js";
 import { expandCapabilityExports } from "./capability_exports.js";
 import { RelationTuple } from "./framework/relations.js";
+import { moduleRequiresParentAttestedBirth } from "./births.js";
 
 // ─────────────────────────────────────────────────────────────────────────────────
 // composeDomainModule — the named-keys `module(...)`
@@ -181,6 +183,12 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
   const workspaceInvariants = [...(spec.workspaceInvariants ?? [])];
   const relationTypes = [...(spec.relationTypes ?? [])];
   const dartImports = [...(spec.dartImports ?? [])];
+  // THE PEER-SOVEREIGN ROOT-OF-TRUST: a home/child law that exports `requireParentAttestedBirth` declares
+  // it requires a parent-attested-birth cert chain. Discovered by shape across the module list (the SAME
+  // duck-typing aggregates/directives use). Omit-when-false (era rule): a law that never declares it is
+  // byte-identical in the canonical manifest/USD to before the key existed.
+  const parentAttestedBirth =
+    moduleRequiresParentAttestedBirth(merged) || spec.modules.some((m) => moduleRequiresParentAttestedBirth(m));
 
   return {
     name: spec.name,
@@ -207,6 +215,9 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
     // Omit-when-empty — the relation schema is hashed law (P1); a relation-free domain's
     // canonical manifest/USD stays byte-identical (the nomosRelations era rule).
     ...(relationTypes.length > 0 ? { relationTypes } : {}),
+    // THE PEER-SOVEREIGN ROOT-OF-TRUST: omit-when-false — a law that doesn't require parent-attested
+    // birth is byte-identical in the canonical manifest/USD (the nomosParentAttestedBirth era rule).
+    ...(parentAttestedBirth ? { parentAttestedBirth: true } : {}),
     ...(dartImports.length > 0 ? { dartImports } : {}),
     ...(spec.dartRefImports !== undefined && spec.dartRefImports.length > 0
       ? { dartRefImports: [...spec.dartRefImports] }
@@ -702,25 +713,10 @@ export function buildIdentity(modules: readonly DomainModule[]): IdentityEmit {
   return { manifests, hashes, excluded };
 }
 
-/**
- * Serialize the identity emit to its on-disk artifacts. The consumed maps stay
- * STRICTLY `{domain: value}` (the Rust `parse_identity_map` treats EVERY key as a
- * domain and fail-closes the WHOLE map on one bad entry); the exclusion record goes
- * to a SEPARATE sidecar the gate never reads.
- */
-export function writeIdentity(
-  emit: IdentityEmit,
-  outDir: string,
-): { manifestsPath: string; hashesPath: string; excludedPath: string } {
-  mkdirSync(outDir, { recursive: true });
-  const manifestsPath = join(outDir, "domain_identity_manifests.json");
-  const hashesPath = join(outDir, "domain_identity_hashes.json");
-  const excludedPath = join(outDir, "domain_identity_excluded.json");
-  writeFileSync(manifestsPath, JSON.stringify(emit.manifests, null, 2) + "\n", "utf8");
-  writeFileSync(hashesPath, JSON.stringify(emit.hashes, null, 2) + "\n", "utf8");
-  writeFileSync(excludedPath, JSON.stringify(emit.excluded, null, 2) + "\n", "utf8");
-  return { manifestsPath, hashesPath, excludedPath };
-}
+// writeIdentity (the domain_identity_*.json sidecars) — REMOVED. The admission identity is carried in the
+// package USD IR + the committed nomos.stable-ids.json lockfile; the deploy/runtime contract never read the
+// sidecars (they were local diagnostics that only confused /build consumers). `buildIdentity` stays — its
+// per-domain hash is surfaced in the compile summary.
 
 // ─────────────────────────────────────────────────────────────────────────────────
 // The .package.usda envelope + the USD-IR emit