@githolon/dsl 0.24.0 → 0.25.0

package/dart/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 0.20.2
+- `NomosBridge.connect` accepts the internal `allowUnborn` opt-in used by `NomosScope.home`, so the
+  home-birth ceremony can boot a local bridge before the home workspace has a remote main. The default
+  remains strict for ordinary workspaces.
+
+## 0.20.1
+- `NomosBridgeError` now carries structured `NomosErrorInfo` alongside the existing human-readable
+  `message`. The envelope includes stable code/component/operation fields, workspace/domain/directive
+  context, trace/span ids, arbitrary attributes, and `toTelemetryAttributes()` for future OpenTelemetry
+  export without taking an SDK dependency.
+- Every bridge request now carries an OpenTelemetry-shaped trace context. String-only legacy runner errors
+  still work and are upgraded locally with operation/trace metadata.
+
 ## 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

package/dart/lib/src/webview_bridge.dart

@@ -15,6 +15,7 @@
 library;
 
 import 'dart:async';
+import 'dart:math';
 
 /// The protocol version the runner and the bridge agree on (`webview-runner.mjs` `WEBVIEW_BRIDGE_VERSION`).
 const int kWebviewBridgeVersion = 1;
@@ -27,11 +28,176 @@ abstract interface class BridgeTransport {
   Stream<Map<String, Object?>> get messages;
 }
 
+/// Trace/span context carried over the bridge as plain JSON. It is intentionally OpenTelemetry-shaped without
+/// importing an OTel SDK: apps can map it to spans later, while Nomos stays dependency-light at the runtime edge.
+class NomosTraceContext {
+  final String? traceId;
+  final String? spanId;
+  final String? parentSpanId;
+  final bool? sampled;
+
+  const NomosTraceContext({
+    this.traceId,
+    this.spanId,
+    this.parentSpanId,
+    this.sampled,
+  });
+
+  factory NomosTraceContext.fromJson(Object? value) {
+    if (value is! Map) return const NomosTraceContext();
+    final m = value.cast<String, Object?>();
+    return NomosTraceContext(
+      traceId: m['traceId']?.toString(),
+      spanId: m['spanId']?.toString(),
+      parentSpanId: m['parentSpanId']?.toString(),
+      sampled: m['sampled'] is bool ? m['sampled'] as bool : null,
+    );
+  }
+
+  Map<String, Object?> toJson() => {
+        if (traceId != null) 'traceId': traceId,
+        if (spanId != null) 'spanId': spanId,
+        if (parentSpanId != null) 'parentSpanId': parentSpanId,
+        if (sampled != null) 'sampled': sampled,
+      };
+
+  bool get isEmpty =>
+      traceId == null &&
+      spanId == null &&
+      parentSpanId == null &&
+      sampled == null;
+}
+
+/// Structured runtime error detail for the bridge boundary. Keep this data-only: it is safe to serialize, log,
+/// persist, or later attach to an OpenTelemetry span without importing tracing into the core client package.
+class NomosErrorInfo {
+  final String code;
+  final String message;
+  final String component;
+  final String? operation;
+  final String? workspace;
+  final String? domain;
+  final String? directiveId;
+  final NomosTraceContext trace;
+  final Map<String, Object?> attributes;
+  final NomosErrorInfo? cause;
+
+  const NomosErrorInfo({
+    required this.code,
+    required this.message,
+    this.component = 'nomos.client',
+    this.operation,
+    this.workspace,
+    this.domain,
+    this.directiveId,
+    this.trace = const NomosTraceContext(),
+    this.attributes = const {},
+    this.cause,
+  });
+
+  factory NomosErrorInfo.legacy(
+    Object? message, {
+    String code = 'nomos.bridge.error',
+    String component = 'nomos.client',
+    String? operation,
+    NomosTraceContext trace = const NomosTraceContext(),
+  }) {
+    return NomosErrorInfo(
+      code: code,
+      message: (message ?? 'the githolon refused the request').toString(),
+      component: component,
+      operation: operation,
+      trace: trace,
+    );
+  }
+
+  factory NomosErrorInfo.fromJson(
+    Object? value, {
+    Object? fallbackMessage,
+    String? fallbackOperation,
+    NomosTraceContext fallbackTrace = const NomosTraceContext(),
+  }) {
+    if (value is! Map) {
+      return NomosErrorInfo.legacy(
+        fallbackMessage,
+        operation: fallbackOperation,
+        trace: fallbackTrace,
+      );
+    }
+    final m = value.cast<String, Object?>();
+    final trace = NomosTraceContext.fromJson(m['trace']);
+    return NomosErrorInfo(
+      code: (m['code'] ?? 'nomos.bridge.error').toString(),
+      message: (m['message'] ??
+              fallbackMessage ??
+              'the githolon refused the request')
+          .toString(),
+      component: (m['component'] ?? 'nomos.client').toString(),
+      operation: m['operation']?.toString() ?? fallbackOperation,
+      workspace: m['workspace']?.toString(),
+      domain: m['domain']?.toString(),
+      directiveId: m['directiveId']?.toString(),
+      trace: trace.isEmpty ? fallbackTrace : trace,
+      attributes:
+          ((m['attributes'] as Map?)?.cast<String, Object?>()) ?? const {},
+      cause: m['cause'] == null
+          ? null
+          : NomosErrorInfo.fromJson(m['cause'],
+              fallbackOperation: fallbackOperation),
+    );
+  }
+
+  factory NomosErrorInfo.fromBridgeMessage(
+    Map<String, Object?> message, {
+    String? fallbackOperation,
+    NomosTraceContext fallbackTrace = const NomosTraceContext(),
+    Object? fallbackMessage,
+  }) {
+    return NomosErrorInfo.fromJson(
+      message['errorInfo'],
+      fallbackMessage: message['error'] ?? fallbackMessage,
+      fallbackOperation: fallbackOperation,
+      fallbackTrace: fallbackTrace,
+    );
+  }
+
+  Map<String, Object?> toJson() => {
+        'code': code,
+        'message': message,
+        'component': component,
+        if (operation != null) 'operation': operation,
+        if (workspace != null) 'workspace': workspace,
+        if (domain != null) 'domain': domain,
+        if (directiveId != null) 'directiveId': directiveId,
+        if (!trace.isEmpty) 'trace': trace.toJson(),
+        if (attributes.isNotEmpty) 'attributes': attributes,
+        if (cause != null) 'cause': cause!.toJson(),
+      };
+
+  /// Attribute map suitable for attaching to a future OTel span/event. The keys are stable and low-cardinality
+  /// where possible; high-cardinality values stay explicit (`workspace`, `domain`, directive) so apps can redact.
+  Map<String, Object?> toTelemetryAttributes() => {
+        'exception.type': code,
+        'exception.message': message,
+        'nomos.error.code': code,
+        'nomos.component': component,
+        if (operation != null) 'nomos.operation': operation,
+        if (workspace != null) 'nomos.workspace': workspace,
+        if (domain != null) 'nomos.domain': domain,
+        if (directiveId != null) 'nomos.directive_id': directiveId,
+        if (trace.traceId != null) 'trace_id': trace.traceId,
+        if (trace.spanId != null) 'span_id': trace.spanId,
+        ...attributes,
+      };
+}
+
 /// A typed refusal surfaced from the githolon's gate (a law refusal, a drift, a malformed op). Carries the
-/// human-first message verbatim — the generated client lets it throw, loudly, exactly like the TS client.
+/// human-first message verbatim plus structured detail for logging, UI mapping, and future OTel export.
 class NomosBridgeError implements Exception {
   final String message;
-  NomosBridgeError(this.message);
+  final NomosErrorInfo info;
+  NomosBridgeError(this.message, {NomosErrorInfo? info})
+      : info = info ?? NomosErrorInfo.legacy(message);
   @override
   String toString() => 'NomosBridgeError: $message';
 }
@@ -40,6 +206,8 @@ class NomosBridgeError implements Exception {
 class NomosBridge {
   final BridgeTransport _transport;
   final Map<int, Completer<Object?>> _pending = {};
+  final Map<int, String> _pendingOps = {};
+  final Map<int, NomosTraceContext> _pendingTraces = {};
   final Map<String, StreamController<List<dynamic>>> _watches = {};
   // SHAPE COMPATIBILITY (#72): compat bindings emit a verdict MAP, not a row list.
   final Map<String, StreamController<Map<String, Object?>>> _compatWatches = {};
@@ -55,12 +223,31 @@ class NomosBridge {
       []; // recent span events — so BOOT spans (emitted during connect, before the UI subscribes) survive
   final Completer<void> _ready = Completer<void>();
   int _seq = 0;
+  final String _traceId = _newTraceId();
   late final StreamSubscription<Map<String, Object?>> _sub;
 
   NomosBridge(this._transport) {
     _sub = _transport.messages.listen(_onMessage);
   }
 
+  static Random _traceRandom() {
+    try {
+      return Random.secure();
+    } catch (_) {
+      return Random(DateTime.now().microsecondsSinceEpoch);
+    }
+  }
+
+  static String _newTraceId() {
+    final rng = _traceRandom();
+    String hex64() =>
+        rng.nextInt(0x100000000).toRadixString(16).padLeft(8, '0') +
+        rng.nextInt(0x100000000).toRadixString(16).padLeft(8, '0');
+    return '${hex64()}${hex64()}';
+  }
+
+  static String _spanIdFor(int id) => id.toRadixString(16).padLeft(16, '0');
+
   /// Completes once the runner has posted `{ event: "ready" }` (the wasm + client are booted).
   Future<void> get ready => _ready.future;
 
@@ -76,8 +263,10 @@ class NomosBridge {
       final ctrl = _watches[m['subId']];
       if (ctrl != null && !ctrl.isClosed) {
         if (m['ok'] == false) {
-          ctrl.addError(NomosBridgeError(
-              (m['error'] ?? 'the watch read failed').toString()));
+          final info = NomosErrorInfo.fromBridgeMessage(m,
+              fallbackMessage: 'the watch read failed',
+              fallbackOperation: 'watch');
+          ctrl.addError(NomosBridgeError(info.message, info: info));
         } else {
           ctrl.add((m['rows'] as List?) ?? const []);
         }
@@ -87,8 +276,10 @@ class NomosBridge {
       final cctrl = _compatWatches[m['subId']];
       if (cctrl != null && !cctrl.isClosed) {
         if (m['ok'] == false) {
-          cctrl.addError(NomosBridgeError(
-              (m['error'] ?? 'the compat watch failed').toString()));
+          final info = NomosErrorInfo.fromBridgeMessage(m,
+              fallbackMessage: 'the compat watch failed',
+              fallbackOperation: 'watchCompatibility');
+          cctrl.addError(NomosBridgeError(info.message, info: info));
         } else {
           cctrl.add(((m['rows'] as Map?)?.cast<String, Object?>()) ?? const {});
         }
@@ -121,12 +312,17 @@ class NomosBridge {
     final id = m['id'];
     if (id is! int) return;
     final completer = _pending.remove(id);
+    final op = _pendingOps.remove(id);
+    final trace = _pendingTraces.remove(id) ?? const NomosTraceContext();
     if (completer == null) return;
     if (m['ok'] == true) {
       completer.complete(m['result']);
     } else {
-      completer.completeError(NomosBridgeError(
-          (m['error'] ?? 'the githolon refused the request').toString()));
+      final info = NomosErrorInfo.fromBridgeMessage(m,
+          fallbackOperation: op,
+          fallbackTrace: trace,
+          fallbackMessage: 'the githolon refused the request');
+      completer.completeError(NomosBridgeError(info.message, info: info));
     }
   }
 
@@ -136,8 +332,20 @@ class NomosBridge {
     final id = ++_seq;
     final completer = Completer<Object?>();
     _pending[id] = completer;
-    _transport
-        .send({'v': kWebviewBridgeVersion, 'id': id, 'op': op, 'args': args});
+    _pendingOps[id] = op;
+    final trace = NomosTraceContext(
+      traceId: _traceId,
+      spanId: _spanIdFor(id),
+      sampled: true,
+    );
+    _pendingTraces[id] = trace;
+    _transport.send({
+      'v': kWebviewBridgeVersion,
+      'id': id,
+      'op': op,
+      'args': args,
+      'trace': trace.toJson(),
+    });
     return completer.future;
   }
 
@@ -157,7 +365,8 @@ class NomosBridge {
       String? clientId,
       String? authToken,
       String? authorSecret,
-      String? restoreFrom}) async {
+      String? restoreFrom,
+      bool allowUnborn = false}) async {
     await _call('connect', {
       'cloud': cloud,
       'workspace': workspace,
@@ -166,7 +375,8 @@ class NomosBridge {
       // 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
+      if (restoreFrom != null) 'restoreFrom': restoreFrom,
+      if (allowUnborn) 'allowUnborn': true,
     });
   }
 
@@ -218,8 +428,10 @@ class NomosBridge {
   /// 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?>? ??
+      _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
@@ -259,7 +471,8 @@ class NomosBridge {
   /// 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 =>
+  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.
@@ -330,6 +543,31 @@ class NomosBridge {
   /// (fetch wasm / clone ledger / instantiate) that streamed during connect(), before the UI subscribed.
   List<Map<String, Object?>> get recentSpans => List.unmodifiable(_spanBuffer);
 
+  int _localSpanSeq = 0;
+
+  /// Inject a LOCALLY-MEASURED span (e.g. the Dart-side DURABLE SAVE — the "saved to disk" number) into the
+  /// span stream so it appears on the flame chart AND the app's per-phase stats EXACTLY like a kernel span.
+  /// Emits a begin then an end with the same id, [t0]..[t1] in ms-epoch. Purely additive — engines that emit
+  /// their own spans are unaffected; this is for measurements the kernel can't see because they happen in Dart.
+  void noteLocalSpan({
+    required String track,
+    required String name,
+    required String kind,
+    required int t0,
+    required int t1,
+    String? id,
+  }) {
+    final sid = id ?? 'local-${_localSpanSeq++}';
+    for (final m in <Map<String, Object?>>[
+      {'event': 'span', 'span': {'phase': 'begin', 'id': sid, 'track': track, 'name': name, 'kind': kind, 't0': t0}},
+      {'event': 'span', 'span': {'phase': 'end', 'id': sid, 't1': t1}},
+    ]) {
+      _spanBuffer.add(m);
+      if (_spanBuffer.length > 400) _spanBuffer.removeRange(0, _spanBuffer.length - 400);
+      if (!_spanEvents.isClosed) _spanEvents.add(m);
+    }
+  }
+
   /// Ledger size (commits) + branch-vs-main (ahead) + projection bytes — the dashboard's slow state.
   Future<Map<String, Object?>> metrics() async =>
       _asMap(await _call('metrics'));
@@ -411,10 +649,20 @@ class NomosBridge {
   /// Tear down: stop the transport subscription + fail any in-flight calls.
   Future<void> dispose() async {
     await _sub.cancel();
-    for (final c in _pending.values) {
-      if (!c.isCompleted) c.completeError(NomosBridgeError('bridge disposed'));
+    for (final entry in _pending.entries) {
+      final c = entry.value;
+      if (!c.isCompleted) {
+        final trace = _pendingTraces[entry.key] ?? const NomosTraceContext();
+        final info = NomosErrorInfo.legacy('bridge disposed',
+            code: 'nomos.bridge.disposed',
+            operation: _pendingOps[entry.key],
+            trace: trace);
+        c.completeError(NomosBridgeError(info.message, info: info));
+      }
     }
     _pending.clear();
+    _pendingOps.clear();
+    _pendingTraces.clear();
     for (final w in _watches.values) {
       if (!w.isClosed) await w.close();
     }

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.20.0
+version: 0.21.0
 
 environment:
   sdk: ^3.5.0

package/dart/test/webview_bridge_test.dart

@@ -49,7 +49,17 @@ class FakeRunner implements BridgeTransport {
               'v': kWebviewBridgeVersion,
               'id': id,
               'ok': false,
-              'error': 'the law refused this intent'
+              'error': 'the law refused this intent',
+              'errorInfo': {
+                'code': 'nomos.law.refused',
+                'message': 'the law refused this intent',
+                'component': 'test.runner',
+                'operation': 'offer',
+                'domain': 'x',
+                'directiveId': 'refuseMe',
+                'trace': message['trace'],
+                'attributes': {'test.case': 'refusal'}
+              }
             });
           } else {
             _incoming.add(reply({'head': 'HEAD-offer'}));
@@ -79,7 +89,16 @@ class FakeRunner implements BridgeTransport {
           _incoming.add(reply({'count': 7}));
           break;
         case 'sync':
-          _incoming.add(reply({'pushed': true}));
+          if (args['admit'] == false) {
+            _incoming.add({
+              'v': kWebviewBridgeVersion,
+              'id': id,
+              'ok': false,
+              'error': 'legacy sync failed'
+            });
+          } else {
+            _incoming.add(reply({'pushed': true}));
+          }
           break;
         case 'autoSync':
           _incoming.add(reply({'started': true}));
@@ -198,8 +217,6 @@ Future<Object?> _invoke(
 /// What the corpus says the typed (unwrapped) return value should be, given the reply's `result`.
 Object? _expectedTyped(String op, Map<String, Object?> result) {
   switch (op) {
-    case 'offer':
-      return result['head'];
     case 'offer':
       return result['head'];
     case 'query':
@@ -277,6 +294,33 @@ void main() {
     expect((req['args'] as Map)['intentBytes'], intentBytes);
   });
 
+  test('requests carry OpenTelemetry-shaped trace context', () async {
+    await bridge.ready;
+    await bridge.connect(cloud: 'https://c', workspace: 'ws', clientId: 'c1');
+    final req = runner.sent.firstWhere((m) => m['op'] == 'connect');
+    final trace = (req['trace'] as Map).cast<String, Object?>();
+    expect(trace['traceId'], isA<String>());
+    expect((trace['traceId'] as String).length, 32);
+    expect(trace['spanId'], isA<String>());
+    expect((trace['spanId'] as String).length, 16);
+    expect(trace['sampled'], isTrue);
+  });
+
+  test('connect only sends allowUnborn when explicitly opted in', () async {
+    await bridge.ready;
+    await bridge.connect(cloud: 'https://c', workspace: 'strict');
+    var req = runner.sent.lastWhere((m) => m['op'] == 'connect');
+    expect((req['args'] as Map).containsKey('allowUnborn'), isFalse);
+
+    await bridge.connect(
+      cloud: 'https://c',
+      workspace: 'home-unborn',
+      allowUnborn: true,
+    );
+    req = runner.sent.lastWhere((m) => m['op'] == 'connect');
+    expect((req['args'] as Map)['allowUnborn'], isTrue);
+  });
+
   test(
       'connect / query / queryById / count / sync / lawStatus all wrap the runner',
       () async {
@@ -363,6 +407,34 @@ void main() {
       err = e;
     }
     expect(err, isA<NomosBridgeError>());
-    expect((err as NomosBridgeError).message, contains('law refused'));
+    final e = err as NomosBridgeError;
+    expect(e.message, contains('law refused'));
+    expect(e.info.code, 'nomos.law.refused');
+    expect(e.info.component, 'test.runner');
+    expect(e.info.operation, 'offer');
+    expect(e.info.domain, 'x');
+    expect(e.info.directiveId, 'refuseMe');
+    expect(e.info.trace.traceId, isNotEmpty);
+    expect(e.info.toTelemetryAttributes()['nomos.error.code'],
+        'nomos.law.refused');
+    expect(e.info.toTelemetryAttributes()['nomos.operation'], 'offer');
+  });
+
+  test(
+      'legacy string-only runner errors still get operation and trace metadata',
+      () async {
+    await bridge.ready;
+    Object? err;
+    try {
+      await bridge.sync(admit: false);
+    } on NomosBridgeError catch (e) {
+      err = e;
+    }
+    expect(err, isA<NomosBridgeError>());
+    final e = err as NomosBridgeError;
+    expect(e.message, 'legacy sync failed');
+    expect(e.info.code, 'nomos.bridge.error');
+    expect(e.info.operation, 'sync');
+    expect(e.info.trace.traceId, isNotEmpty);
   });
 }

package/package.json

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

@@ -92,15 +92,31 @@ export function birth(recipe: BirthRecipe): void {
  */
 export interface ParentAttestedBirthMarker {
   readonly __isParentAttestedBirth: true;
+  /** The singleton aggregate INSTANCE id holding the home owner (the subject the cert binds to). Lowered
+   *  into the `nomosParentAttestedBirth` era key so the KERNEL reads it, never hardcodes it. Optional — a
+   *  bare marker omits it and the kernel falls back to the framework `home` default (the era rule). */
+  readonly ownerObject?: string;
+  /** The field on that singleton holding the owner principal. */
+  readonly ownerField?: string;
+  /** The singleton aggregate INSTANCE id holding the travelling `BirthCertChain`. */
+  readonly certObject?: string;
+  /** The field on that singleton holding the JSON cert chain. */
+  readonly certField?: string;
 }
 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 {
+  return parentAttestedBirthMarker(mod) !== null;
+}
+
+/** Shape-discover the {@link requireParentAttestedBirth} sentinel AND return it (with any declared owner/cert
+ *  locators) — the composer lowers the locators into the era key so the kernel reads them. `null` ⇒ absent. */
+export function parentAttestedBirthMarker(mod: Record<string, unknown>): ParentAttestedBirthMarker | null {
   for (const v of Object.values(mod)) {
     if (v && typeof v === "object" && (v as ParentAttestedBirthMarker).__isParentAttestedBirth === true) {
-      return true;
+      return v as ParentAttestedBirthMarker;
     }
   }
-  return false;
+  return null;
 }

package/src/build_package.ts

@@ -58,7 +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";
+import { parentAttestedBirthMarker } from "./births.js";
 
 // ─────────────────────────────────────────────────────────────────────────────────
 // composeDomainModule — the named-keys `module(...)`
@@ -187,8 +187,20 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
   // 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));
+  // Discover the sentinel AND its declared owner/cert locators (the kernel reads them off the era key, names
+  // neither). A bare marker omits the locators ⇒ the kernel's framework default applies (the era rule).
+  const pabMarker =
+    parentAttestedBirthMarker(merged) ??
+    spec.modules.map((m) => parentAttestedBirthMarker(m)).find((x) => x !== null) ??
+    null;
+  const parentAttestedBirth = pabMarker
+    ? {
+        ...(pabMarker.ownerObject !== undefined ? { ownerObject: pabMarker.ownerObject } : {}),
+        ...(pabMarker.ownerField !== undefined ? { ownerField: pabMarker.ownerField } : {}),
+        ...(pabMarker.certObject !== undefined ? { certObject: pabMarker.certObject } : {}),
+        ...(pabMarker.certField !== undefined ? { certField: pabMarker.certField } : {}),
+      }
+    : null;
 
   return {
     name: spec.name,
@@ -217,7 +229,7 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
     ...(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 } : {}),
+    ...(parentAttestedBirth ? { parentAttestedBirth } : {}),
     ...(dartImports.length > 0 ? { dartImports } : {}),
     ...(spec.dartRefImports !== undefined && spec.dartRefImports.length > 0
       ? { dartRefImports: [...spec.dartRefImports] }

package/src/codegen_dart.ts

@@ -2463,7 +2463,9 @@ export interface DomainModule {
    * cross-ws read). ADDITIVE + OPTIONAL: a law that declares none omits the key and is byte-identical
    * to before it existed (the era rule); pre-feature + legacy/non-warranted workspaces replay green.
    */
-  parentAttestedBirth?: boolean;
+  parentAttestedBirth?:
+    | boolean
+    | { ownerObject?: string; ownerField?: string; certObject?: string; certField?: string };
   /**
    * The domain's NATIVE ZANZIBAR RELATION SCHEMA (`relation_schema.ts` — the userset-rewrite law,
    * P1). Pure-data per-type relation rewrites lowered to the `nomosRelations` USD era key (NO JS on

package/src/codegen_proof.ts

@@ -361,6 +361,12 @@ export interface ChildBirthLeg {
   readonly birthPayload: Record<string, unknown>;
   /** Required `…At` fields the runtime stamps with ISO now() at dispatch (mirrors the create leg). */
   readonly birthAutoStamped: readonly string[];
+  /** The payload field whose value is the authoring actor for this birth offer, when discoverable from the
+   *  genesis recipe's step actors. Needed for gated births (`.births().requires(...)`) so proof drives the
+   *  same actor the generated client would seal as `security.actor`. */
+  readonly birthActorField?: string;
+  /** The relation the birth offer requires (`.births().requires(...)`), when present. */
+  readonly birthRequiresRelation?: string;
   /** The payload field that carries the bootstrap framework-controller hash (runtime: the local wasm's own
    *  controller hash) — discovered from the recipe's `bootstrap/installDomain` step's payload, by matching
    *  the field whose synthesized value the recipe routed there. `undefined` ⇒ the recipe hard-codes it. */
@@ -379,6 +385,21 @@ export interface ChildBirthLeg {
   readonly childSeedInstanceId?: string;
   /** A child declared query that reads the seed back (returns the seed aggregate). `undefined` ⇒ by-id only. */
   readonly childQuery?: { readonly id: string; readonly key: readonly string[] };
+  /** Optional parent setup: when this birth is gated by authority that is established by first birthing the
+   *  parent workspace (home → estate is the canonical case), the proof runner drives this setup birth first
+   *  and then authors the child birth inside the born parent. */
+  readonly parentSetup?: ChildBirthParentSetup;
+}
+
+export interface ChildBirthParentSetup {
+  readonly parentDomain: string;
+  readonly birthDirectiveId: string;
+  readonly birthPayload: Record<string, unknown>;
+  readonly birthAutoStamped: readonly string[];
+  readonly birthActorField?: string;
+  readonly frameworkHashField?: string;
+  readonly lawHashField?: string;
+  readonly childDomain: string;
 }
 
 /** A stub `nomos` global (mint + sha256) so a `.births()` plan that mints / hashes a child name runs to
@@ -489,6 +510,19 @@ export function discoverChildBirthLeg(
   const nomosStep = installSteps.find((s) => s.domain === "nomos");
   const frameworkHashField = bootstrapStep ? fieldForValue(bootstrapStep.payload?.domainHash) : undefined;
   const lawHashField = nomosStep ? fieldForValue(nomosStep.payload?.domainHash) : undefined;
+  const actorField = (() => {
+    for (const step of chain as Array<DiscoveredGenesisStep & { actor?: unknown }>) {
+      const actor = step?.actor;
+      const exact = fieldForValue(actor);
+      if (exact !== undefined) return exact;
+      if (typeof actor !== "string") continue;
+      for (const [field, value] of Object.entries(synth.value)) {
+        if (typeof value !== "string" || value.length === 0) continue;
+        if (actor === `user:${value}` || actor === `key:${value}`) return field;
+      }
+    }
+    return undefined;
+  })();
 
   // The parent payload the leg dispatches: the synthesized values MINUS the framework/law-hash placeholders
   // (the runtime injects the REAL hashes onto those fields by name — a `sample-*` hash would fail the child
@@ -502,6 +536,8 @@ export function discoverChildBirthLeg(
     birthDirectiveId: birthDir.id,
     birthPayload,
     birthAutoStamped: synth.autoStamped,
+    ...(actorField !== undefined ? { birthActorField: actorField } : {}),
+    ...(birthDir.requiresRelationGate !== undefined ? { birthRequiresRelation: birthDir.requiresRelationGate.relation } : {}),
     ...(frameworkHashField !== undefined ? { frameworkHashField } : {}),
     ...(lawHashField !== undefined ? { lawHashField } : {}),
     childDomain,
@@ -512,6 +548,38 @@ export function discoverChildBirthLeg(
   };
 }
 
+function childBirthsForModule(mod: DomainModule, modules: readonly DomainModule[]): ChildBirthLeg[] {
+  const domain = mod.domain ?? mod.name;
+  const out: ChildBirthLeg[] = [];
+  for (const d of mod.directives as Directive<unknown>[]) {
+    if (d?.birthsChild !== true || typeof d.payloadSchema !== "object") continue;
+    const leg = discoverChildBirthLeg(d, domain, modules);
+    if (leg !== undefined) out.push(leg);
+  }
+  return out;
+}
+
+function asParentSetup(leg: ChildBirthLeg): ChildBirthParentSetup {
+  return {
+    parentDomain: leg.parentDomain,
+    birthDirectiveId: leg.birthDirectiveId,
+    birthPayload: leg.birthPayload,
+    birthAutoStamped: leg.birthAutoStamped,
+    ...(leg.birthActorField !== undefined ? { birthActorField: leg.birthActorField } : {}),
+    ...(leg.frameworkHashField !== undefined ? { frameworkHashField: leg.frameworkHashField } : {}),
+    ...(leg.lawHashField !== undefined ? { lawHashField: leg.lawHashField } : {}),
+    childDomain: leg.childDomain,
+  };
+}
+
+function attachParentSetup(leg: ChildBirthLeg, allBirths: readonly ChildBirthLeg[]): ChildBirthLeg {
+  if (leg.birthRequiresRelation === undefined) return leg;
+  const setup = allBirths.find((candidate) =>
+    candidate.childDomain === leg.parentDomain &&
+    !(candidate.parentDomain === leg.parentDomain && candidate.birthDirectiveId === leg.birthDirectiveId));
+  return setup === undefined ? leg : { ...leg, parentSetup: asParentSetup(setup) };
+}
+
 /** Discover the SINGLETON instance id a seed directive writes (a fixed `<Agg>:self`-shaped id), by running
  *  its plan with a probe payload + birth-probe globals and reading the first written op's instance id when
  *  it is a constant (the same id across two distinct probe payloads). `undefined` ⇒ not a fixed singleton. */
@@ -644,6 +712,7 @@ function birthDirectiveOf(mod: DomainModule): Directive<unknown> | undefined {
  *  domain is at least `compile-valid` (gaps 1+3 — every domain is proof-addressable). */
 export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[]): ProofLegs {
   const domain = mod.domain ?? mod.name;
+  const allBirths = modules.flatMap((m) => childBirthsForModule(m, modules));
   // The standalone-create leg (when the domain has a non-birth `.creates`). FAIL SOFT: an exotic payload
   // shape the synthesizer can't sample just drops the standalone leg (the domain stays compile-valid /
   // child-birth-provable), never loses the index.
@@ -655,11 +724,12 @@ export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[
   }
   // The child-birth leg (when the domain has a `.births()` directive) — discovered by running its plan.
   const birthDir = birthDirectiveOf(mod);
-  const childBirth = birthDir !== undefined ? discoverChildBirthLeg(birthDir, domain, modules) : undefined;
+  const childBirth = birthDir !== undefined ? allBirths.find((b) => b.parentDomain === domain && b.birthDirectiveId === birthDir.id) : undefined;
+  const childBirthWithSetup = childBirth !== undefined ? attachParentSetup(childBirth, allBirths) : undefined;
 
   const legs: ProofKind[] = ["compile-valid"];
   if (standalone !== null) legs.push("standalone-provable");
-  if (childBirth !== undefined) legs.push("child-birth-provable");
+  if (childBirthWithSetup !== undefined) legs.push("child-birth-provable");
 
   return {
     domain,
@@ -675,7 +745,7 @@ export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[
           ...(standalone.count !== undefined ? { count: standalone.count } : {}),
         }
       : {}),
-    ...(childBirth !== undefined ? { childBirth } : {}),
+    ...(childBirthWithSetup !== undefined ? { childBirth: childBirthWithSetup } : {}),
   };
 }
 
@@ -798,26 +868,65 @@ function liveChildBirthLegLines(cb: ChildBirthLeg, opts: TsProofOptions, n: () =
   // The birth payload literal: the synthesized values + the REAL hashes onto the discovered fields + the
   // auto-stamped `…At` fields stamped now.
   const lines: string[] = [];
+  const setup = cb.parentSetup;
+  const actorExpr = (field: string | undefined, payloadVar: string): string | undefined =>
+    field !== undefined ? `String(${payloadVar}[${JSON.stringify(field)}] ?? "")` : undefined;
+  const birthActorExpr = actorExpr(cb.birthActorField, "birthPayload");
   lines.push(
     `// ${n()}. CHILD BIRTH (G3 — birth is the defined consequence of an offer): drive \`${cb.parentDomain}/${cb.birthDirectiveId}\``,
     `//    against the cloud; the kernel's offer-effect installs the child law in-chain + folds the child's`,
     `//    genesis (estate/${cb.childSeedDirectiveId}) through the CHILD's own gate, then BORNS the child workspace.`,
     `{`,
+    `  const frameworkHashFor = async (workspace: string) => {`,
+    `    const st = await (await fetch(\`\${CLOUD}/v2/workspaces/\${workspace}\`)).json().catch(() => ({}));`,
+    `    const frameworkHash = st.controller?.domainHash ?? st.controllerHash ?? "";`,
+    `    if (!frameworkHash) fail(\`could not resolve the framework controller hash from workspace \${workspace} — needed for the child's in-chain installDomain\`);`,
+    `    return frameworkHash;`,
+    `  };`,
     `  const birthPayload: Record<string, unknown> = { ...${JSON.stringify(cb.birthPayload)} };`,
+    ...(
+      birthActorExpr !== undefined && cb.birthRequiresRelation !== undefined
+        ? [
+            `  const birthActor = ${birthActorExpr};`,
+            `  if (!birthActor) fail(${JSON.stringify(`child birth ${cb.parentDomain}/${cb.birthDirectiveId} is gated by .requires("${cb.birthRequiresRelation}") but the proof could not derive an actor from ${cb.birthActorField}`)});`,
+          ]
+        : [
+            `  const birthActor = PRINCIPAL;`,
+          ]
+    ),
+    ...(setup !== undefined
+      ? [
+          `  // Parent setup: this child birth is gated by authority seeded when the parent workspace is born.`,
+          `  const setupPayload: Record<string, unknown> = { ...${JSON.stringify(setup.birthPayload)} };`,
+          ...(setup.birthActorField !== undefined && cb.birthActorField !== undefined
+            ? [`  setupPayload[${JSON.stringify(setup.birthActorField)}] = birthPayload[${JSON.stringify(cb.birthActorField)}];`]
+            : []),
+          ...(setup.frameworkHashField !== undefined ? [`  setupPayload[${JSON.stringify(setup.frameworkHashField)}] = await frameworkHashFor(WS);`] : []),
+          ...(setup.lawHashField !== undefined ? [`  setupPayload[${JSON.stringify(setup.lawHashField)}] = ${hashConst};`] : []),
+          ...setup.birthAutoStamped.map((f) => `  setupPayload[${JSON.stringify(f)}] = new Date().toISOString();`),
+          `  const setupActor = ${actorExpr(setup.birthActorField, "setupPayload") ?? "birthActor"} || birthActor;`,
+          `  const sr = await fetch(\`\${CLOUD}/v2/workspaces/\${WS}/${setup.birthDirectiveId}\`, { method: "POST", headers: { "content-type": "application/json", "x-nomos-principal": setupActor }, body: JSON.stringify(setupPayload) });`,
+          `  const sd = await sr.json();`,
+          `  if (!sd.ok) fail(\`parent setup ${setup.parentDomain}/${setup.birthDirectiveId} refused: \${JSON.stringify(sd)}\`);`,
+          `  const setupBorn: Array<{ workspace?: string }> = sd.born ?? [];`,
+          `  const birthParentWs = setupBorn[0]?.workspace;`,
+          `  if (!birthParentWs) fail(\`parent setup admitted but spawned no workspace (born=\${JSON.stringify(setupBorn)})\`);`,
+          `  ok(\`parent setup — \${birthParentWs} born by ${setup.parentDomain}/${setup.birthDirectiveId} before gated child birth\`);`,
+        ]
+      : [
+          `  const birthParentWs = WS;`,
+        ]),
     ...(cb.frameworkHashField !== undefined
       ? [
           `  // The framework CONTROLLER hash (the bootstrap install-target the child runs as intent 0) — read it`,
           `  // from the workspace's own status (the kernel's controllerHash); the child install resolves the bytes`,
           `  // by hash from the parent's custody, so this MUST be the real framework hash (a guess would fail).`,
-          `  const st = await (await fetch(\`\${CLOUD}/v2/workspaces/\${WS}\`)).json().catch(() => ({}));`,
-          `  const frameworkHash = st.controller?.domainHash ?? st.controllerHash ?? "";`,
-          `  if (!frameworkHash) fail("could not resolve the framework controller hash from the workspace status — needed for the child's in-chain installDomain");`,
-          `  birthPayload[${JSON.stringify(cb.frameworkHashField)}] = frameworkHash;`,
+          `  birthPayload[${JSON.stringify(cb.frameworkHashField)}] = await frameworkHashFor(birthParentWs);`,
         ]
       : []),
     `  birthPayload[${JSON.stringify(cb.lawHashField ?? "lawHash")}] = ${hashConst};`,
     ...cb.birthAutoStamped.map((f) => `  birthPayload[${JSON.stringify(f)}] = new Date().toISOString();`),
-    `  const br = await fetch(\`\${CLOUD}/v2/workspaces/\${WS}/${cb.birthDirectiveId}\`, { method: "POST", headers: { "content-type": "application/json", "x-nomos-principal": PRINCIPAL }, body: JSON.stringify(birthPayload) });`,
+    `  const br = await fetch(\`\${CLOUD}/v2/workspaces/\${birthParentWs}/${cb.birthDirectiveId}\`, { method: "POST", headers: { "content-type": "application/json", "x-nomos-principal": birthActor }, body: JSON.stringify(birthPayload) });`,
     `  const bd = await br.json();`,
     `  if (!bd.ok) fail(\`child birth offer ${cb.parentDomain}/${cb.birthDirectiveId} refused: \${JSON.stringify(bd)}\`);`,
     `  const born: Array<{ workspace?: string }> = bd.born ?? [];`,

package/src/directive.ts

@@ -92,6 +92,26 @@ export interface Directive<P = unknown> {
       readonly signature: string;
     };
   };
+  /**
+   * THE KEYLESS VERIFIED-FIRST-DEVICE GATE (architecture/keyless_verified_onboard.md). When set, this
+   * directive bootstraps a principal's FIRST device-signer from an ON-CHAIN, device-bound IdP attestation:
+   * its authorization is the carried `idpToken` (re-verified against the workspace AuthProvider IDENTICALLY
+   * on author / receive / verify_chain), NOT a pre-enrolled signer — so a brand-new IdP-verified user can
+   * seat its first key self-serve + peer-to-peer. Lowered into the `nomosVerifiedFirstEnroll` era key as a
+   * per-directive FIELD MAPPING (the payload fields the gate reads the token / seated keyHash / claimed
+   * issuer from), so the KERNEL hardcodes NEITHER the directive id NOR the field names — it reads both from
+   * THIS law declaration (the same way it reads `.attestationAuthorized()`'s gate). Defaulted to the
+   * framework `enrollFirstDevice` convention by `.verifiedFirstDevice()`; a tenant can author its OWN
+   * first-enroll directive over the same machinery. OMITTED for law with no such directive (the era rule).
+   */
+  readonly firstDeviceEnrollGate?: {
+    /** The payload field holding the IdP token (the captured premise the gate re-verifies). */
+    readonly tokenField: string;
+    /** The payload field holding sha256(device pubkey) being seated (the gate ties it to the signer). */
+    readonly keyHashField: string;
+    /** The payload field holding the claimed issuer (the gate asserts it == the prefix AuthProvider.issuer). */
+    readonly verifiedViaField: string;
+  };
   /**
    * The directive's DECLARED read boundary: the ref types its `plan` may READ (the
    * "IR for law boundaries" decision — the boundary is part of the domain identity).
@@ -194,6 +214,20 @@ export interface RequirableDirective<P> extends Directive<P> {
    * host-free. Framework-only (the home law's `recordShare`). Returns a NEW requirable directive.
    */
   attestationAuthorized(owner: { ownerObject: string; ownerField: string }): RequirableDirective<P>;
+  /**
+   * Declare this directive a KEYLESS VERIFIED-FIRST-DEVICE bootstrap (keyless_verified_onboard.md): its
+   * authorization is a carried, device-bound IdP `idpToken` re-verified against the workspace AuthProvider —
+   * not a pre-enrolled signer — so a brand-new principal can seat its FIRST device key self-serve +
+   * peer-to-peer. Lowered into the `nomosVerifiedFirstEnroll` era key as a per-directive payload FIELD
+   * MAPPING, so the kernel reads the directive id + field names from the law (hardcoding neither). The field
+   * names DEFAULT to the framework `enrollFirstDevice` convention; override only to author a custom shape.
+   * Returns a NEW requirable directive.
+   */
+  verifiedFirstDevice(opts?: {
+    tokenField?: string;
+    keyHashField?: string;
+    verifiedViaField?: string;
+  }): RequirableDirective<P>;
   /**
    * Declare the directive's READ boundary. TWO argument kinds, one declaration site:
    *   * a STRING declares a ref TYPE its `plan` may read (the original boundary —
@@ -392,6 +426,25 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
         },
       });
     },
+    verifiedFirstDevice(opts?: {
+      tokenField?: string;
+      keyHashField?: string;
+      verifiedViaField?: string;
+    }): RequirableDirective<P> {
+      // KEYLESS VERIFIED-FIRST-DEVICE (keyless_verified_onboard.md): the carried device-bound `idpToken` IS
+      // the authorization — lowered into the `nomosVerifiedFirstEnroll` era key as the payload FIELD MAPPING
+      // the one gate reads, so the kernel hardcodes NEITHER the directive id NOR the field names (it reads
+      // both from this declaration). Field names default HERE (in the DSL) to the framework convention; a
+      // tenant may override to author its own first-enroll directive over the same kernel machinery.
+      return makeRequirable({
+        ...base,
+        firstDeviceEnrollGate: {
+          tokenField: opts?.tokenField ?? "idpToken",
+          keyHashField: opts?.keyHashField ?? "keyHash",
+          verifiedViaField: opts?.verifiedViaField ?? "verifiedVia",
+        },
+      });
+    },
     reads(...reads: (string | QueryDecl)[]): RequirableDirective<P> {
       // Split by argument kind: strings are the ref-type boundary; QueryDecls are the
       // captured-read lane (#58). Both accumulate, dedup (ref types by value, queries

package/src/framework/home.ts

@@ -35,7 +35,7 @@ import { query } from "../query.js";
 import { birth } from "../births.js";
 import { workspaceInvariant, refAs } from "./workspace_invariant.js";
 import { identityRelations } from "./signing_identity.js";
-import { requireParentAttestedBirth } from "../births.js";
+import { requireParentAttestedBirth, type ParentAttestedBirthMarker } from "../births.js";
 import { GenesisWarrant, seedGenesis } from "./genesis.js";
 
 // `nomos.sha256` — the TRUSTLESS, pure hash computed IN the githolon (Rust sha2 bound in the sealed engine;
@@ -150,7 +150,7 @@ export function homeNameOf(subject: string): string {
  * so HomeOwner is seeded and `homeNameBindsOwner` passes (a birth without it would be an invalid, un-owned
  * home).
  */
-const HOME_LAW_DOMAIN = "home";
+export const HOME_LAW_DOMAIN = "home";
 export const birthHome = directive("birthHome")
   .creates(HomeOwner) // the birth's law-declared touched type — the child's HomeOwner is what this offer seeds
   .payload(
@@ -359,4 +359,13 @@ export const seedBirthAttestation = directive("seedBirthAttestation")
  * `NotRootedAtRoot`). Era-ruled: a home law that does NOT export this carries no key and replays byte-
  * identical (the squat-only `homeNameBindsOwner` check still runs; the cert check is simply inert).
  */
-export const parentAttestedBirth = requireParentAttestedBirth;
+export const parentAttestedBirth: ParentAttestedBirthMarker = {
+  ...requireParentAttestedBirth,
+  // DECLARE the owner + cert locators so the KERNEL reads them (it names neither): the home owner lives at
+  // the `HomeOwner` singleton's `principal`, the travelling cert at the `BirthAttestation` singleton's
+  // `certChain`. Mirrors how `.attestationAuthorized()` declares its owner-source — the kernel hardcodes none.
+  ownerObject: HOME_OWNER_ID,
+  ownerField: "principal",
+  certObject: BIRTH_ATTESTATION_ID,
+  certField: "certChain",
+};

package/src/framework/signing_identity.ts

@@ -269,6 +269,64 @@ export const enrollSignerSelfRequiresVerified = workspaceInvariant("EnrollSigner
       : { reject: "enroll-signer-self-requires-verified-principal" },
   );
 
+/**
+ * `enrollFirstDevice` (architecture/keyless_verified_onboard.md) — THE KEYLESS VERIFIED FIRST-DEVICE
+ * self-onboard. A brand-new principal (an IdP-verified user with NO enrolled signer key) bootstraps its
+ * FIRST device-signer on a WARRANTED parent, self-serve + peer-to-peer, no admin/server in the loop.
+ *
+ * SELF-BIND (identical to {@link enrollSignerSelf}): the object is the AUTHORING principal's identity
+ * (`ctx.principal()`), NEVER a payload field — a device can only ever seat a key for ITS OWN identity.
+ *
+ * The PAYLOAD carries the IdP's signed identity assertion as an ON-CHAIN CAPTURED PREMISE — `idpToken`
+ * (the JWT). The kernel's `nomosVerifiedFirstEnroll` arm re-verifies `idpToken` IDENTICALLY on author /
+ * receive / verify_chain against the workspace's law-declared AuthProvider keys (which are themselves
+ * on-chain law-state, so every replaying peer has them — a JWT is a signed PUBLIC assertion, not a secret;
+ * the IdP is the identity root-of-trust, parallel to K_root for lineage). Era-inert unless the law composes
+ * this directive. (Replay across IdP key rotation needs the signing key RETAINED in AuthProvider.keys — an
+ * append-only `rotateKeys` is the follow-up; until then the tenant keeps the active keys in the set.)
+ *
+ * SAFETY (kernel-enforced, NOT here): the token MUST be device-bound (`token[nonce|cnf] == sha256(the
+ * signing device pubkey)`) under `AuthProvider.requireDeviceBinding` (DEFAULT true) so an on-chain token is
+ * useless to a thief; proof-of-possession ties the signing key to the seated key; `verifiedVia` must equal
+ * the prefix AuthProvider issuer. The plan only seats the leaf; the kernel owns the verification.
+ */
+export const enrollFirstDevice = directive("enrollFirstDevice")
+  .ensures(RelationTuple)
+  .payload(
+    z.object({
+      keyHash: sha256Hex, // sha256hex of the ed25519 device PUBLIC key being bootstrapped (== the signer)
+      /** The IdP/issuer that vouched (must equal the prefix AuthProvider.issuer — kernel-asserted). */
+      verifiedVia: z.string().min(1),
+      /** The SignerEpoch this binding is valid from (caller reads the current epoch and stamps it). */
+      validFromEpoch: z.number().int().nonnegative(),
+      grantedAt: z.string().min(1), // ISO-8601, caller-stamped (determinism)
+      /** THE CAPTURED PREMISE: the IdP's signed identity assertion (JWT), re-verified on every lane against
+       *  the on-chain AuthProvider keys. */
+      idpToken: z.string().min(1),
+    }),
+  )
+  .plan((p, ctx) => {
+    // SELF-BIND: the object is the AUTHORING principal's identity (read the raw principal from the endorsed
+    // evidence — the framework may; an author cannot). The kernel arm proves the principal is the IdP subject.
+    const me = ctx.principal().asAuthoritySubject<string>("bootstrap my first device signer key from a verified IdP token");
+    const rawPrincipal = endorsementOf(me)?.principal ?? "";
+    return writeTuple({
+      object: signerObject(rawPrincipal),
+      relation: SIGNER_RELATION,
+      subject: "key:" + p.keyHash,
+      grantedBy: ctx.principal().asAttribution(),
+      grantedAt: p.grantedAt,
+      verifiedVia: p.verifiedVia,
+      validFromEpoch: p.validFromEpoch,
+    });
+  })
+  // THE KEYLESS GATE DECLARATION: the carried device-bound `idpToken` IS this directive's authorization
+  // (re-verified against the workspace AuthProvider on every lane), not a pre-enrolled signer. This lowers
+  // the per-directive payload FIELD MAPPING into the `nomosVerifiedFirstEnroll` era key, so the KERNEL reads
+  // the directive id + field names from the law — naming neither. Defaults are this directive's own payload
+  // shape (`idpToken`/`keyHash`/`verifiedVia`).
+  .verifiedFirstDevice();
+
 /**
  * `revokeSigner` — REMOVE-WINS revoke of a signer key for the AUTHORING identity (self-bind: a device
  * revokes only keys of its OWN principal). Flips the signer leaf to `status:revoked` (reuse the existing

package/src/framework/workspaces.ts

@@ -952,6 +952,12 @@ export const setPlatformPool = directive("setPlatformPool")
  * principals only WITHIN that platform's own tree. The cloud's own provider
  * (captain app) is the depth-0 case, configured by the host.
  */
+/** THE AUTHPROVIDER SINGLETON INSTANCE ID — the ONE place this string lives DSL-side (the kernel owns the
+ *  matching `nomos_identity::auth_provider::AUTH_PROVIDER_ID`; a drift-guard test keeps them identical). The
+ *  kernel verifies presented tokens against the AuthProvider at this id, so its SHAPE is kernel-owned
+ *  first-class machinery; `setAuthProvider`/`rotateKeys` compile to it. */
+export const AUTH_PROVIDER_ID = "auth-provider:platform";
+
 export const AuthProvider = aggregate("AuthProvider", {
   /** The singleton key — always `"platform"`. */
   scope: t.string().merge(Lww),
@@ -982,6 +988,16 @@ export const AuthProvider = aggregate("AuthProvider", {
    *  CA vouches) and each key matches its leaf cert — no host trust, no admin. Pinned once via the
    *  admin-gated {@link setAuthProvider}. Absent ⇒ no trustless rotation (rotate via setAuthProvider). */
   rootCert: t.string().merge(Lww).optional(),
+  /** OPTIONAL — the JWT claim carrying the DEVICE BINDING for the keyless first-device enroll
+   *  (the `enrollFirstDevice` lane, keyless_verified_onboard.md): the kernel asserts
+   *  `token[deviceBindingClaim] == sha256(the signing device pubkey)`, so an on-chain token is useless to a
+   *  thief (no device secret). Standard values: `"nonce"` (OIDC) or `"cnf"`. Absent ⇒ none configured. */
+  deviceBindingClaim: t.string().merge(Lww).optional(),
+  /** OPTIONAL — `"false"` to OPT OUT of the device-binding requirement (accept the bounded ~token-lifetime
+   *  replay window — for IdPs that can't carry a nonce, eyes-open). The kernel applies STRICT (require the
+   *  binding) when this is absent or `"true"` — strict-by-default, so a naked token never lands unless the
+   *  tenant explicitly relaxes it. */
+  requireDeviceBinding: t.string().merge(Lww).optional(),
   /** Human label for audit ("acme supabase", ...). */
   label: t.string().merge(Lww),
   /** Who set it (attribution). */
@@ -1010,13 +1026,17 @@ export const setAuthProvider = directive("setAuthProvider")
       principalClaim: z.string().min(1).optional(),
       /** OPTIONAL — the pinned CA root (base64 DER) enabling trustless {@link rotateKeys}. */
       rootCert: z.string().min(1).optional(),
+      /** OPTIONAL — the device-binding claim for keyless first-device enroll ("nonce" | "cnf"). */
+      deviceBindingClaim: z.string().min(1).optional(),
+      /** OPTIONAL — "false" to accept the bounded replay window (strict device-binding is the default). */
+      requireDeviceBinding: z.enum(["true", "false"]).optional(),
       label: z.string().min(1),
       setBy: z.string().min(1),
       setAt: epochMs,
     }),
   )
   .plan((p) => {
-    const ap = instance(AuthProvider, "auth-provider:platform");
+    const ap = instance(AuthProvider, AUTH_PROVIDER_ID);
     return [
       withMarker(set(ap, "scope", "platform"), "ensures"),
       set(ap, "issuer", p.issuer),
@@ -1025,6 +1045,8 @@ export const setAuthProvider = directive("setAuthProvider")
       ...(p.keys ? [set(ap, "keys", p.keys)] : []),
       ...(p.principalClaim ? [set(ap, "principalClaim", p.principalClaim)] : []),
       ...(p.rootCert ? [set(ap, "rootCert", p.rootCert)] : []),
+      ...(p.deviceBindingClaim ? [set(ap, "deviceBindingClaim", p.deviceBindingClaim)] : []),
+      ...(p.requireDeviceBinding ? [set(ap, "requireDeviceBinding", p.requireDeviceBinding)] : []),
       set(ap, "label", p.label),
       set(ap, "setBy", p.setBy),
       set(ap, "setAt", p.setAt),
@@ -1050,7 +1072,7 @@ export const rotateKeys = directive("rotateKeys")
     }),
   )
   .plan((p) => {
-    const ap = instance(AuthProvider, "auth-provider:platform");
+    const ap = instance(AuthProvider, AUTH_PROVIDER_ID);
     // The kernel's x5c admission gate authorizes this (validate_rotate_keys); the plan just stores the
     // CA-vouched JWKS. The `ensures` marker upserts onto the existing AuthProvider singleton.
     return [withMarker(set(ap, "keys", p.keys), "ensures"), set(ap, "setAt", p.rotatedAt)];

package/src/index.ts

@@ -267,6 +267,7 @@ export {
   signerEpochStrictlyIncreases,
   enrollSignerSelf,
   enrollSignerSelfRequiresVerified,
+  enrollFirstDevice,
   revokeSigner,
   revokeSignerEpochStrictlyIncreases,
   signerTuplesByObject,

package/src/usd.ts

@@ -285,6 +285,28 @@ export interface UsdLayer {
       }
     >;
   };
+  /**
+   * THE KEYLESS VERIFIED-FIRST-DEVICE GATE (architecture/keyless_verified_onboard.md). Present IFF ≥1
+   * directive declares `.verifiedFirstDevice()`: a per-directive payload FIELD MAPPING. A principal's FIRST
+   * device-signer may then bootstrap on a WARRANTED parent from an ON-CHAIN, device-bound IdP attestation:
+   * the kernel's `nomosVerifiedFirstEnroll` arm reads THIS declaration — the directive id + the payload
+   * fields the token / seated keyHash / claimed issuer ride in — and re-verifies the carried `idpToken`
+   * against the workspace's AuthProvider IDENTICALLY on author/receive/verify_chain (self-serve +
+   * peer-to-peer, no admin/server). The KERNEL hardcodes NEITHER the directive id NOR the field names — it
+   * reads both here (the same way it reads `nomosAttestationGate`). OMITTED for law with no such directive
+   * (the era rule — byte-identical hash; the arm inert).
+   */
+  readonly nomosVerifiedFirstEnroll?: {
+    readonly v: 1;
+    readonly directives: Record<
+      string,
+      {
+        readonly tokenField: string;
+        readonly keyHashField: string;
+        readonly verifiedViaField: string;
+      }
+    >;
+  };
   /**
    * THE BIRTH GATE DECLARATION (G3 — birth is a declared kernel primitive, the unix model). Present IFF ≥1
    * directive declares `.births()`: the SORTED set of their ids. A directive named here BIRTHS a child
@@ -311,6 +333,12 @@ export interface UsdLayer {
    */
   readonly nomosParentAttestedBirth?: {
     readonly v: 1;
+    /** The LAW-DECLARED owner + cert locators (the kernel reads them; names neither). The framework `home`
+     *  convention; a pre-declaration `{v:1}` key falls back to the kernel default (the era rule). */
+    readonly ownerObject: string;
+    readonly ownerField: string;
+    readonly certObject: string;
+    readonly certField: string;
   };
   /**
    * STABLE IDENTIFIERS (#58 — names are labels, identity is minted). The layer's
@@ -759,10 +787,43 @@ export function emitUsd(
       const nomosBirthGate =
         birthDirectives.length > 0 ? { v: 1 as const, directives: birthDirectives } : undefined;
       // THE PEER-SOVEREIGN ROOT-OF-TRUST: the home/child law declared it requires a parent-attested-birth
-      // cert chain (the `requireParentAttestedBirth` sentinel, discovered by composeDomainModule). Emit the
-      // era key iff true; omit otherwise (a law that doesn't require it is byte-identical — the era rule).
-      const nomosParentAttestedBirth =
-        (l.module as { parentAttestedBirth?: boolean }).parentAttestedBirth === true ? { v: 1 as const } : undefined;
+      // cert chain (the `requireParentAttestedBirth` sentinel). Emit the era key with the LAW-DECLARED owner +
+      // cert locators (so the kernel reads them, names neither); a bare marker (no locators) falls back to the
+      // framework `home` convention. Omit when absent (a law that doesn't require it is byte-identical).
+      const pabSrc = (
+        l.module as {
+          parentAttestedBirth?: boolean | { ownerObject?: string; ownerField?: string; certObject?: string; certField?: string };
+        }
+      ).parentAttestedBirth;
+      const nomosParentAttestedBirth = pabSrc
+        ? {
+            v: 1 as const,
+            ownerObject: (typeof pabSrc === "object" && pabSrc.ownerObject) || "home-owner:self",
+            ownerField: (typeof pabSrc === "object" && pabSrc.ownerField) || "principal",
+            certObject: (typeof pabSrc === "object" && pabSrc.certObject) || "birth-attestation:self",
+            certField: (typeof pabSrc === "object" && pabSrc.certField) || "certChain",
+          }
+        : undefined;
+      // THE KEYLESS VERIFIED-FIRST-DEVICE GATE (keyless_verified_onboard.md): collect each directive declaring
+      // `.verifiedFirstDevice()` → its payload FIELD MAPPING (where the token / seated keyHash / claimed issuer
+      // ride). The kernel's nomosVerifiedFirstEnroll arm reads the directive id + field names from THIS
+      // declaration (hardcoding neither) and bootstraps a first device-signer from the carried device-bound
+      // IdP attestation. Omit-when-empty (the era rule — byte-identical hash; the arm inert).
+      const firstEnrollReq: Record<
+        string,
+        { tokenField: string; keyHashField: string; verifiedViaField: string }
+      > = {};
+      for (const d of [...l.module.directives].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))) {
+        if (d.firstDeviceEnrollGate !== undefined) {
+          firstEnrollReq[d.id] = {
+            tokenField: d.firstDeviceEnrollGate.tokenField,
+            keyHashField: d.firstDeviceEnrollGate.keyHashField,
+            verifiedViaField: d.firstDeviceEnrollGate.verifiedViaField,
+          };
+        }
+      }
+      const nomosVerifiedFirstEnroll =
+        Object.keys(firstEnrollReq).length > 0 ? { v: 1 as const, directives: firstEnrollReq } : undefined;
       // THE CAPTURED-READ GATE DECLARATION (#58): collected from the canonical
       // manifest's per-directive `capturedReads` (omit-when-empty — read-free law's
       // USD is byte-identical apart from the always-on stableIds key).
@@ -894,6 +955,7 @@ export function emitUsd(
         ...(nomosAttestationGate !== undefined ? { nomosAttestationGate } : {}),
         ...(nomosBirthGate !== undefined ? { nomosBirthGate } : {}),
         ...(nomosParentAttestedBirth !== undefined ? { nomosParentAttestedBirth } : {}),
+        ...(nomosVerifiedFirstEnroll !== undefined ? { nomosVerifiedFirstEnroll } : {}),
         ...(Object.keys(visAggregates).length > 0
           ? { nomosReadVisibility: { v: 1 as const, aggregates: visAggregates } }
           : {}),

package/src/usd_layers.ts

@@ -183,6 +183,9 @@ function domainLayerAttrLines(domain: string, layer: UsdLayer, indent: string):
     ...(layer.nomosParentAttestedBirth !== undefined
       ? [`${indent}custom string nomos:parentAttestedBirthHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosParentAttestedBirth)))}`]
       : []),
+    ...(layer.nomosVerifiedFirstEnroll !== undefined
+      ? [`${indent}custom string nomos:verifiedFirstEnrollHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosVerifiedFirstEnroll)))}`]
+      : []),
   ];
 }
 
@@ -782,11 +785,31 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
       }
       if (b.size > 0) birthGate = { v: 1, directives: [...b].sort() };
     }
-    // THE PEER-SOVEREIGN ROOT-OF-TRUST: the era key is present iff ANY layer in the stack declares it
-    // (a boolean union — once required, required). Omit-when-absent (era rule).
+    // THE PEER-SOVEREIGN ROOT-OF-TRUST: the era key is present iff ANY layer declares it (once required,
+    // required). Carry the FIRST layer's declared owner/cert locators verbatim (preserve them — do NOT
+    // reconstruct {v:1}, which would drop the locators the kernel reads). Omit-when-absent (era rule).
     let parentAttestedBirth: UsdLayer["nomosParentAttestedBirth"];
-    if (stack.some((l) => l.nomosParentAttestedBirth !== undefined)) {
-      parentAttestedBirth = { v: 1 };
+    for (const l of stack) {
+      if (l.nomosParentAttestedBirth !== undefined) {
+        parentAttestedBirth = l.nomosParentAttestedBirth;
+        break;
+      }
+    }
+    // THE KEYLESS VERIFIED-FIRST-DEVICE GATE: directiveId → payload field mapping, merged later-wins across
+    // layers, SORTED keys (mirrors the attestation gate). Omit-when-empty (era rule).
+    let verifiedFirstEnroll: UsdLayer["nomosVerifiedFirstEnroll"];
+    {
+      type VfeSrc = NonNullable<UsdLayer["nomosVerifiedFirstEnroll"]>["directives"][string];
+      const v = new Map<string, VfeSrc>();
+      for (const l of stack) {
+        if (l.nomosVerifiedFirstEnroll === undefined) continue;
+        for (const [id, src] of Object.entries(l.nomosVerifiedFirstEnroll.directives)) v.set(id, src);
+      }
+      if (v.size > 0) {
+        const rec: Record<string, VfeSrc> = {};
+        for (const k of [...v.keys()].sort()) rec[k] = v.get(k)!;
+        verifiedFirstEnroll = { v: 1, directives: rec };
+      }
     }
     return {
       path,
@@ -806,6 +829,7 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
       ...(attestationGate !== undefined ? { nomosAttestationGate: attestationGate } : {}),
       ...(birthGate !== undefined ? { nomosBirthGate: birthGate } : {}),
       ...(parentAttestedBirth !== undefined ? { nomosParentAttestedBirth: parentAttestedBirth } : {}),
+      ...(verifiedFirstEnroll !== undefined ? { nomosVerifiedFirstEnroll: verifiedFirstEnroll } : {}),
     };
   });
 
@@ -935,6 +959,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
   const attestationGateByDomain = new Map<string, UsdLayer["nomosAttestationGate"]>();
   const birthGateByDomain = new Map<string, UsdLayer["nomosBirthGate"]>();
   const parentAttestedBirthByDomain = new Map<string, UsdLayer["nomosParentAttestedBirth"]>();
+  const verifiedFirstEnrollByDomain = new Map<string, UsdLayer["nomosVerifiedFirstEnroll"]>();
   for (const p of prims) {
     if (p.attrs.get("nomos:kind") === "domain") {
       const domain = attrString(p, "nomos:domain");
@@ -996,6 +1021,11 @@ export function parseUsdaDocument(text: string): UsdDocument {
       if (typeof pabHex === "string") {
         parentAttestedBirthByDomain.set(domain, JSON.parse(unhexUtf8(pabHex)) as UsdLayer["nomosParentAttestedBirth"]);
       }
+      // THE KEYLESS VERIFIED-FIRST-DEVICE GATE: the hex-carried era marker.
+      const vfeHex = p.attrs.get("nomos:verifiedFirstEnrollHex");
+      if (typeof vfeHex === "string") {
+        verifiedFirstEnrollByDomain.set(domain, JSON.parse(unhexUtf8(vfeHex)) as UsdLayer["nomosVerifiedFirstEnroll"]);
+      }
     }
   }
 
@@ -1095,6 +1125,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
       const attGate = attestationGateByDomain.get(domain);
       const birthGate = birthGateByDomain.get(domain);
       const parentAttestedBirth = parentAttestedBirthByDomain.get(domain);
+      const verifiedFirstEnroll = verifiedFirstEnrollByDomain.get(domain);
       return {
         path: `/Nomos/${domain}`,
         prims: [...b.prims].sort(byPath),
@@ -1113,6 +1144,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
         ...(attGate !== undefined ? { nomosAttestationGate: attGate } : {}),
         ...(birthGate !== undefined ? { nomosBirthGate: birthGate } : {}),
         ...(parentAttestedBirth !== undefined ? { nomosParentAttestedBirth: parentAttestedBirth } : {}),
+        ...(verifiedFirstEnroll !== undefined ? { nomosVerifiedFirstEnroll: verifiedFirstEnroll } : {}),
       };
     })
     .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));