@githolon/dsl 0.108.7 → 0.110.1

package/dart_types/lib/nomos_kernel_protocol.dart

@@ -1,6 +1,6 @@
 // Generated protocol types shared by every Dart and Flutter Nomos host.
 //
-// The source of truth is proto/nomos/kernel/v1 plus proto/nomos/runtime/v2. This package owns the
+// The source of truth is the typed protocol graph under proto/nomos. This package owns the
 // generated Dart projection so nomos_client and nomos_flutter cannot drift into
 // handwritten copies of the kernel/runtime ABI.
 library;
@@ -8,4 +8,24 @@ library;
 export 'src/proto/nomos/kernel/v1/kernel.pb.dart';
 export 'src/proto/nomos/kernel/v1/progress.pb.dart';
 export 'src/proto/nomos/custody/v1/snapshot.pb.dart';
+export 'src/proto/nomos/discovery/v1/workspace_placement.pb.dart';
+export 'src/proto/nomos/runtime/v2/application_desk.pb.dart';
+export 'src/proto/nomos/runtime/v2/application_readiness_desk.pb.dart';
+export 'src/proto/nomos/runtime/v2/authentication_desk.pb.dart';
+export 'src/proto/nomos/runtime/v2/custody_desk.pb.dart';
+export 'src/proto/nomos/runtime/v2/interaction_desk.pb.dart';
+export 'src/proto/nomos/runtime/v2/compatibility_desk.pb.dart';
+export 'src/proto/nomos/runtime/v2/law_desk.pb.dart';
+export 'src/proto/nomos/runtime/v2/maintenance_desk.pb.dart';
+export 'src/proto/nomos/runtime/v2/model_adoption_desk.pb.dart';
+export 'src/proto/nomos/runtime/v2/residency_desk.pb.dart';
+export 'src/proto/nomos/runtime/v2/correspondence_desk.pb.dart';
+export 'src/proto/nomos/runtime/v2/sealing_desk.pb.dart';
+export 'src/proto/nomos/runtime/v2/credentials_desk.pb.dart';
+export 'src/proto/nomos/runtime/v2/placement_desk.pb.dart';
+export 'src/proto/nomos/runtime/v2/recovery_desk.pb.dart';
+export 'src/proto/nomos/runtime/v2/records_desk.pb.dart';
+export 'src/proto/nomos/runtime/v2/observability_desk.pb.dart';
+export 'src/proto/nomos/runtime/v2/receiving_group_desk.pb.dart';
+export 'src/proto/nomos/runtime/v2/framework.pb.dart';
 export 'src/proto/nomos/runtime/v2/runtime.pb.dart';

package/dart_types/lib/nomos_types.dart

@@ -14,7 +14,7 @@
 ///  - The ONE effectful write verb `offer(intent)` + the typed reactive read engine
 ///    `NomosReads`.
 ///  - The tri-state `NomosSlot<T>`, runtime aggregate metadata, schema validation, and
-///    the data-only error/trace types (`NomosBridgeError`, `NomosErrorInfo`,
+///    the data-only error/trace types (`NomosRuntimeError`, `NomosErrorInfo`,
 ///    `NomosTraceContext`) plus the typed diagnostics.
 library;
 
@@ -27,6 +27,7 @@ export 'src/schema_validation.dart';
 export 'src/aggregate_meta.dart';
 export 'src/error_info.dart';
 export 'src/errors.dart';
+export 'src/runtime_outcome.dart';
 // Foreign references expose identity data, while navigation readers and attestation stay behind the
 // generated application runtime.
 export 'src/foreign_ref.dart' show ForeignRef;
@@ -57,3 +58,10 @@ export 'src/local_work_rejected.dart';
 // SURFACED MERGE CONFLICTS (architecture/surfaced_merge_conflict.md): the read-collapse types for a
 // `.merge(Surfaced(...))` field — SurfacedValue<T> (resolved scalar | pending observations). Pure data.
 export 'src/surfaced.dart';
+
+// THE APPROVED LAW MODEL: NomosApprovedModel — the package identity, approval reason, domain keys and
+// package loader a release declares. A required Reception argument, and pure data like the rest of this
+// package: it opens no custody and starts no runtime.
+export 'src/approved_model.dart';
+
+export 'src/admission_decision.dart';

package/dart_types/lib/src/admission_decision.dart

@@ -0,0 +1,37 @@
+import 'dart:typed_data';
+import 'proto/nomos/kernel/v1/kernel.pbenum.dart' show KernelRefusalCode;
+export 'proto/nomos/kernel/v1/kernel.pbenum.dart' show KernelRefusalCode;
+
+/// Terminal admission decisions. Availability and delivery remain runtime observations.
+sealed class AdmissionDecision<S, R> { const AdmissionDecision(); }
+final class Admitted<S, R> extends AdmissionDecision<S, R> {
+  const Admitted(this.value);
+  final S value;
+}
+final class DomainRefused<S, R> extends AdmissionDecision<S, R> {
+  const DomainRefused(this.reason, this.evidence);
+  final R reason;
+  final NomosDomainRefusalEvidence evidence;
+}
+final class FrameworkRefused<S, R> extends AdmissionDecision<S, R> {
+  const FrameworkRefused(this.code, this.message);
+  final KernelRefusalCode code;
+  final String message;
+}
+final class UnsupportedRefusalContract<S, R> extends AdmissionDecision<S, R> {
+  const UnsupportedRefusalContract(this.evidence);
+  final NomosDomainRefusalEvidence evidence;
+}
+
+/// Ephemeral evidence attached by the deciding kernel. The law hash and type
+/// address identify the complete schema closure. It is not a saved refusal.
+final class NomosDomainRefusalEvidence {
+  NomosDomainRefusalEvidence({required List<int> lawSha256, required this.invariant,
+    required this.typeIdentity, required List<int> valueUsda})
+    : lawSha256 = Uint8List.fromList(lawSha256).asUnmodifiableView(),
+      valueUsda = Uint8List.fromList(valueUsda).asUnmodifiableView();
+  final Uint8List lawSha256;
+  final String invariant;
+  final String typeIdentity;
+  final Uint8List valueUsda;
+}

package/dart_types/lib/src/aggregate_meta.dart

@@ -71,7 +71,7 @@ class NomosAggregateMeta {
 
   /// The AGGREGATE WIRE TYPE of a kernel aggregate id: minted ids are
   /// `<domain>.<Type>_<uuidv7>`, so the type is the prefix before the trailing
-  /// `_<uuid>` (the same rule `@githolon/client` applies to Create events).
+  /// `_<uuid>` (the same rule `@githolon/peer-office` applies to Create events).
   /// Returns the input unchanged when no uuid suffix is present (already a type).
   static String typeOfId(String aggregateId) =>
       aggregateId.replaceFirst(RegExp(r'_[0-9a-fA-F-]+$'), '');

package/dart_types/lib/src/approved_model.dart

@@ -0,0 +1,65 @@
+/// THE LAW MODEL AN APPLICATION RELEASE APPROVES.
+///
+/// Pure validated data, and a REQUIRED argument to the Reception, so a tenant
+/// cannot bind an application without naming this type. It lives here — beside
+/// `CustodyBreakPolicy` — precisely because it belongs to no runtime: it opens no
+/// custody, holds no session and starts nothing. The Peer Office model-adoption
+/// desk consumes it; its phases and outcomes are the desk's observations and stay
+/// behind the Reception.
+library;
+
+import 'dart:typed_data';
+
+final RegExp _lowerHex64 = RegExp(r'^[0-9a-f]{64}$');
+
+/// The law model an application release approves, supplied once at the
+/// application's Reception. Every field is required: the office refuses to
+/// adopt without the package identity, the domain keys it observes, the
+/// attributed reason the kernel's transition demands, or the package bytes a
+/// child must stage — none of them can be invented later.
+final class NomosApprovedModel {
+  NomosApprovedModel({
+    required this.lawSha256,
+    required this.reason,
+    required List<String> domainKeys,
+    required this.loadPackage,
+  }) : domainKeys = List.unmodifiable(domainKeys) {
+    if (!_lowerHex64.hasMatch(lawSha256)) {
+      throw ArgumentError.value(
+        lawSha256,
+        'lawSha256',
+        'must be the kernel-derived identity of the compiled law package (64 lowercase hex)',
+      );
+    }
+    if (reason.trim().isEmpty) {
+      throw ArgumentError.value(
+        reason,
+        'reason',
+        'must be the attributed approval text the release recorded',
+      );
+    }
+    if (this.domainKeys.isEmpty ||
+        this.domainKeys.any((key) => key.trim().isEmpty)) {
+      throw ArgumentError.value(
+        domainKeys,
+        'domainKeys',
+        'must name the application domain keys the office observes on each workspace',
+      );
+    }
+  }
+
+  /// The kernel-derived identity of the compiled `.law.usdz` closure.
+  final String lawSha256;
+
+  /// The attributed approval text. The kernel's transition demands it whenever
+  /// retirements or retypes are present; the office never invents one.
+  final String reason;
+
+  /// The application's domain keys. A workspace serving none of them is left
+  /// alone; keys it does not serve are ignored.
+  final List<String> domainKeys;
+
+  /// The exact compiled package bytes, read only when a workspace must stage
+  /// them (a bundled asset, a file beside the generated facade).
+  final Future<Uint8List> Function() loadPackage;
+}

package/dart_types/lib/src/custody.dart

@@ -7,7 +7,7 @@
 // resolve them. The bridge decodes these from the runner's `custody` events + `custodyStatus` reply.
 library;
 
-import 'proto/nomos/runtime/v2/runtime.pb.dart' as runtime;
+import 'proto/nomos/runtime/v2/recovery_desk.pb.dart' as recovery;
 
 /// WHY a chain was superseded — the lineage annotation lifted from the workspace status onto a break.
 class NomosCustodySupersession {
@@ -98,16 +98,13 @@ class NomosCustodyBreak {
       };
 }
 
-/// The app's decision for a custody break (the declared or interactive policy outcome).
+/// The mount's declared response to a custody discontinuity.
 enum CustodyBreakPolicy {
   /// Salvage local-only work, re-clone the new incarnation, park the salvage re-offerable, resume.
   adopt,
 
   /// Stay on local truth, go offline-only (the local holon keeps serving; sync suspends).
-  reject,
-
-  /// Surface the break on [custodyEvents] and await `resolveCustodyBreak(...)` (async UX — a dialog).
-  ask;
+  reject;
 
   String get wire => name;
 }
@@ -130,8 +127,7 @@ class NomosSupersededChain {
       {'ref': ref, 'supersededAt': supersededAt, 'reason': reason};
 }
 
-/// A custody lifecycle event pushed over the bridge (mirrors syncEvents). `kind` is one of
-/// "detected" | "rejected" | "adopting" | "adopted" | "ask"; "ask" awaits `resolveCustodyBreak`.
+/// A custody lifecycle event pushed over the bridge (mirrors syncEvents).
 class NomosCustodyEvent {
   final String kind;
   final String? session;
@@ -147,22 +143,18 @@ class NomosCustodyEvent {
     this.parkedIntents,
   });
 
-  /// True when this event is an interactive prompt awaiting a decision.
-  bool get isAsk => kind == 'ask';
-
   factory NomosCustodyEvent.fromRuntime(
-    runtime.CustodyChanged event, {
+    recovery.CustodyChanged event, {
     String? session,
   }) {
     final custodyBreak = event.hasCustodyBreak() ? event.custodyBreak : null;
     return NomosCustodyEvent(
       kind: switch (event.kind) {
-        runtime.CustodyChangeKind.CUSTODY_CHANGE_KIND_DETECTED => 'detected',
-        runtime.CustodyChangeKind.CUSTODY_CHANGE_KIND_REJECTED => 'rejected',
-        runtime.CustodyChangeKind.CUSTODY_CHANGE_KIND_ADOPTING => 'adopting',
-        runtime.CustodyChangeKind.CUSTODY_CHANGE_KIND_ADOPT_REFUSED =>
+        recovery.CustodyChangeKind.CUSTODY_CHANGE_KIND_DETECTED => 'detected',
+        recovery.CustodyChangeKind.CUSTODY_CHANGE_KIND_REJECTED => 'rejected',
+        recovery.CustodyChangeKind.CUSTODY_CHANGE_KIND_ADOPTING => 'adopting',
+        recovery.CustodyChangeKind.CUSTODY_CHANGE_KIND_ADOPT_REFUSED =>
           'adopt-refused',
-        runtime.CustodyChangeKind.CUSTODY_CHANGE_KIND_ASK => 'ask',
         _ => 'unspecified',
       },
       session: session,
@@ -170,7 +162,7 @@ class NomosCustodyEvent {
           ? null
           : NomosCustodyBreak(
               kind: custodyBreak.kind ==
-                      runtime.CustodyBreakKind.CUSTODY_BREAK_KIND_DIVERGED
+                      recovery.CustodyBreakKind.CUSTODY_BREAK_KIND_DIVERGED
                   ? NomosCustodyBreakKind.diverged
                   : NomosCustodyBreakKind.superseded,
               localGenesis: custodyBreak.localGenesis,

package/dart_types/lib/src/error_info.dart

@@ -6,7 +6,7 @@
 /// Data-only error/trace types for the bridge boundary. These carry NO transport, NO
 /// bridge, NO runtime — they are pure serializable value types, so they live in
 /// `nomos_types` and are safe to depend on from generated types files + UI code. The
-/// async [NomosBridge] runtime (in `nomos_client`'s `webview_bridge.dart`) builds on them.
+/// async Reception/runtime surface builds on them.
 library;
 
 /// Trace/span context carried over the bridge as plain JSON. It is intentionally OpenTelemetry-shaped without
@@ -174,11 +174,11 @@ class NomosErrorInfo {
 
 /// A typed refusal surfaced from the githolon's gate (a law refusal, a drift, a malformed op). Carries the
 /// human-first message verbatim plus structured detail for logging, UI mapping, and future OTel export.
-class NomosBridgeError implements Exception {
+class NomosRuntimeError implements Exception {
   final String message;
   final NomosErrorInfo info;
-  NomosBridgeError(this.message, {NomosErrorInfo? info})
+  NomosRuntimeError(this.message, {NomosErrorInfo? info})
       : info = info ?? NomosErrorInfo.legacy(message);
   @override
-  String toString() => 'NomosBridgeError: $message';
+  String toString() => 'NomosRuntimeError: $message';
 }

package/dart_types/lib/src/errors.dart

@@ -5,22 +5,22 @@
 
 /// 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
+/// The generic [NomosRuntimeError] is the catch-all for a refusal from the Peer Office or kernel
 /// 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.
+/// All extend [NomosRuntimeError] so existing `catch (NomosRuntimeError)` handlers still catch them.
 library;
 
-import 'error_info.dart' show NomosBridgeError, NomosErrorInfo;
+import 'error_info.dart' show NomosRuntimeError, NomosErrorInfo;
 
 /// Mint the MOST SPECIFIC typed error for a structured refusal — the one construction point the bridge
 /// uses everywhere it surfaces an `errorInfo`. A `nomos.custody.*` code becomes a [CustodyError] (typed,
 /// recoverable, carrying the eviction/escalation decision fields); everything else stays the generic
-/// [NomosBridgeError]. Apps `switch` on the type / `code`, never scrape prose.
-NomosBridgeError nomosErrorFromInfo(NomosErrorInfo info) {
+/// [NomosRuntimeError]. Apps `switch` on the type / `code`, never scrape prose.
+NomosRuntimeError nomosErrorFromInfo(NomosErrorInfo info) {
   if (info.code == 'nomos.owned.recovery_pending') {
     return OwnedRecoveryPending.fromInfo(info);
   }
@@ -38,7 +38,7 @@ NomosBridgeError nomosErrorFromInfo(NomosErrorInfo info) {
   if (info.code == 'kernel-capability-skew') {
     return KernelCoherenceError.fromInfo(info);
   }
-  return NomosBridgeError(info.message, info: info);
+  return NomosRuntimeError(info.message, info: info);
 }
 
 /// THE ONE recommendedAction vocabulary, shared across EVERY typed error (custody, law, auth, load). A repair
@@ -77,9 +77,8 @@ class NomosRecommendedAction {
   /// [ParentSignerEnrollmentMissing] (a reborn parent that lost the signer tuple).
   static const ensureParentSignerEnrollment = 'ensureParentSignerEnrollment';
 
-  /// Mount the SOURCE workspace of a colocated attested read as a session on this device's plane
-  /// (`bridge.connect(session: <sourceWs>)` / `ref.acquire(bridge)`) — the ONE remedy for
-  /// [SourceSessionNotMounted] (a directive's `read(q, {from})` resolves in-engine from the mounted source).
+  /// Retain the SOURCE workspace on this peer so Replica Follow can make its
+  /// custody locally resident — the remedy for [SourceSessionNotMounted].
   static const mountSourceSession = 'mountSourceSession';
 
   /// Ask the designated recovery person to open this workspace once. Nomos completes the handoff privately.
@@ -131,7 +130,7 @@ class NomosRecommendedAction {
 
 /// All-device-loss recovery is a normal, resumable lifecycle state. The app may render the one concrete
 /// [recommendedAction]; the private recovery protocol stays inside Nomos.
-class OwnedRecoveryPending extends NomosBridgeError {
+class OwnedRecoveryPending extends NomosRuntimeError {
   final String code;
   final String? workspace;
   final String stage;
@@ -181,7 +180,7 @@ class OwnedRecoveryPending extends NomosBridgeError {
 /// §5 connect-time compat check, or a dispatch-time refusal when a payload's baked hash names law the workspace
 /// no longer runs. When [structurallyCompatible] is true the operation can still proceed (structural subtyping);
 /// when false it names the [incompatibleMember] that broke. REMEDY: `recompileClient` or `redeployLaw`.
-class LawMismatchError extends NomosBridgeError {
+class LawMismatchError extends NomosRuntimeError {
   /// The stable machine code, e.g. `nomos.law.mismatch`.
   final String code;
 
@@ -287,7 +286,7 @@ class LawMismatchError extends NomosBridgeError {
 ///     `.requires(<relation>)` tuple is absent for the actor on [object].
 /// These fields ride the UNSEALED presentation lanes only (verdict / 422 body / bridge errorInfo) —
 /// never the sealed chain bytes.
-class AuthzRefusedError extends NomosBridgeError {
+class AuthzRefusedError extends NomosRuntimeError {
   /// The stable machine code, e.g. `nomos.authz.signer_enrollment_missing`.
   final String code;
 
@@ -415,7 +414,7 @@ class ParentSignerEnrollmentMissing extends AuthzRefusedError {
 /// AUTH — the auth-provider token was missing/malformed/expired/rejected, or its issuer does not match the
 /// workspace's law-declared key (`nomos.auth.*`, e.g. `nomos.auth.issuer_mismatch`, `nomos.auth.token_invalid`,
 /// `nomos.auth.token_expired`). REMEDY is always `reauth`: acquire a fresh token and reconnect.
-class AuthError extends NomosBridgeError {
+class AuthError extends NomosRuntimeError {
   /// The stable machine code, e.g. `nomos.auth.issuer_mismatch`.
   final String code;
 
@@ -471,7 +470,7 @@ class AuthError extends NomosBridgeError {
 /// (`nomos.load.*`, e.g. `nomos.load.wasm_fetch_failed`, `nomos.load.instantiate_failed`,
 /// `nomos.load.manifest_failed`). This is a transport/runtime fault, never a law refusal. REMEDY: `retry` for a
 /// transient fetch, `reopen` when the loaded runtime is unusable.
-class LoadError extends NomosBridgeError {
+class LoadError extends NomosRuntimeError {
   /// The stable machine code, e.g. `nomos.load.wasm_fetch_failed`.
   final String code;
 
@@ -520,12 +519,13 @@ class LoadError extends NomosBridgeError {
 
 /// SOURCE SESSION NOT MOUNTED (`nomos.attested_read.source_not_mounted`) — a directive whose law declares a
 /// colocated foreign read (`read(query, {from: <sourceWs>})`) was offered while the SOURCE workspace was NOT
-/// mounted as a session on this device's engine plane. A colocated attested read resolves + signs IN-ENGINE
+/// mounted as a session on this device's kernel host. A colocated attested read resolves + signs IN-ENGINE
 /// (zero HTTP) from the mounted source; when the source is absent the bridge refuses IMMEDIATELY (this error)
 /// instead of a doomed ~31s remote fetch that answers an unsigned projection. The remedy is
-/// [NomosRecommendedAction.mountSourceSession]: open [sourceWorkspace] as a session on the SAME bridge/realm
-/// (`bridge.connect(session: sourceWorkspace)` / `ref.acquire(bridge)`) BEFORE offering the directive.
-class SourceSessionNotMounted extends NomosBridgeError {
+/// [NomosRecommendedAction.mountSourceSession]: ensure [sourceWorkspace] has a retained placement on this
+/// peer and wait for Replica Follow to make it resident before offering the directive. Binding an interaction
+/// session is deliberately insufficient.
+class SourceSessionNotMounted extends NomosRuntimeError {
   /// The stable machine code — always `nomos.attested_read.source_not_mounted`.
   final String code;
 
@@ -582,7 +582,7 @@ class SourceSessionNotMounted extends NomosBridgeError {
 }
 
 /// The provider-selected OSGi resource does not satisfy the generated law's Contract Namespace requirements.
-class KernelCoherenceError extends NomosBridgeError {
+class KernelCoherenceError extends NomosRuntimeError {
   /// The stable machine code — always `kernel-contract-incompatible`.
   final String code;
 
@@ -609,12 +609,12 @@ enum CustodySource { localSnapshot, cloudPack, unknown }
 /// missing history the operation needed (`nomos.custody.shallow_insufficient` /
 /// `nomos.custody.missing_object`), and the in-client gap-fill repair could not complete it.
 ///
-/// This replaces pattern-matching `shallow-insufficient` out of a stringly [NomosBridgeError]: the app
+/// This replaces pattern-matching `shallow-insufficient` out of a stringly [NomosRuntimeError]: the app
 /// switches on [code] and decides from the structured fields whether to EVICT LOCAL CUSTODY
 /// ([recommendedAction] == `quarantineLocalSnapshotAndReclone` — quarantine the snapshot, `inspectSnapshot`
 /// / `recoverFrom`, reconnect fresh) or ESCALATE CLOUD CUSTODY (`refetchFullHistoryAndRetry` — the cloud
-/// must serve the full chain). Trace IDs ride [NomosBridgeError.info.trace] as on every bridge error.
-class CustodyError extends NomosBridgeError {
+/// must serve the full chain). Trace IDs ride [NomosRuntimeError.info.trace] as on every bridge error.
+class CustodyError extends NomosRuntimeError {
   /// The stable machine code, e.g. `nomos.custody.shallow_insufficient`.
   final String code;
 
@@ -701,7 +701,7 @@ class CustodyError extends 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 {
+class AuthTokenInvalid extends NomosRuntimeError {
   final String code = 'nomos.auth.token_invalid';
   final String recommendedAction = NomosRecommendedAction.reauth;
   AuthTokenInvalid([String? message])
@@ -714,7 +714,7 @@ class AuthTokenInvalid extends NomosBridgeError {
 /// 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 {
+class HomeNameMismatch extends NomosRuntimeError {
   final String code = 'nomos.home.name_mismatch';
   final String recommendedAction = NomosRecommendedAction.reopen;
 
@@ -737,7 +737,7 @@ class HomeNameMismatch extends NomosBridgeError {
 /// 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 {
+class HomeLawMissing extends NomosRuntimeError {
   final String code = 'nomos.home.law_missing';
   final String recommendedAction = NomosRecommendedAction.redeployLaw;
 
@@ -753,7 +753,7 @@ class HomeLawMissing extends NomosBridgeError {
 /// 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 {
+class BirthRejected extends NomosRuntimeError {
   final String code = 'nomos.home.birth_refused';
   final String recommendedAction = NomosRecommendedAction.redeployLaw;
 
@@ -772,7 +772,7 @@ class BirthRejected extends NomosBridgeError {
 /// 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 {
+class PackMalformed extends NomosRuntimeError {
   final String code = 'nomos.custody.pack_malformed';
   final String recommendedAction =
       NomosRecommendedAction.refetchFullHistoryAndRetry;
@@ -786,7 +786,7 @@ class PackMalformed extends NomosBridgeError {
 /// 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 {
+class LawHashUnavailable extends NomosRuntimeError {
   final String code = 'nomos.home.law_hash_unavailable';
   final String recommendedAction = NomosRecommendedAction.redeployLaw;
 
@@ -804,7 +804,7 @@ class LawHashUnavailable extends NomosBridgeError {
 /// BEFORE any submit, so an actorless gated offer is impossible to GENERATE (never merely refused at the
 /// kernel gate). REMEDY: construct the generated client with an `actor` (the verified principal — under a
 /// home scope this is the subject; the bridge owns signing). Secrets NEVER appear here — only the identity.
-class MissingOfferAuthority extends NomosBridgeError {
+class MissingOfferAuthority extends NomosRuntimeError {
   /// The domain of the gated directive.
   final String domain;
 

package/dart_types/lib/src/foreign_ref.dart

@@ -4,13 +4,15 @@
 //
 // These types live in the pure `nomos_types` core (no bridge, no lifecycle) so BOTH the layered TYPES
 // package (frontend-safe) AND the runtime `nomos_client` package resolve them; `nomos_client` re-exports
-// this barrel, and its `NomosBridge` implements [NomosForeignReader] over the device's multi-workspace plane.
+// this barrel, and Dart Reception implements [NomosForeignReader] over the device's multi-workspace plane.
 library;
 
+import 'dart:typed_data';
+
 import 'nomos_ref.dart';
 
 /// Reads a FOREIGN workspace on demand — the surface a [ForeignRef] resolves against. It is STRUCTURAL: any
-/// object with this shape works. `nomos_client`'s `NomosBridge` implements it over the device's local
+/// object with this shape works. `nomos_client`'s Reception implements it over the device's local
 /// multi-workspace plane (`bridge.session(ws).queryById(id)`, mounting the workspace lazily); the TS twin is
 /// the `openRealm()` reader. A plain single-workspace holon is NOT one — pass the multi-workspace reader.
 abstract class NomosForeignReader {
@@ -18,17 +20,16 @@ abstract class NomosForeignReader {
   NomosForeignWorkspaceReader foreignWorkspace(String workspace);
 }
 
-/// One foreign workspace's by-id read surface. Returns the
-/// RAW projection rows (`[{type,id,data}, …]`) — the ForeignRef decodes the matching row's flat `data` map
-/// via the target `fromJson` it captured at construction (the same shape [NomosReads.decodeRows] consumes).
+/// One foreign workspace's by-id read surface. It returns the kernel's canonical
+/// nominal USDA image; only code generated from the target domain may decode it.
 abstract class NomosForeignWorkspaceReader {
-  /// The projection rows for kernel aggregate [id] (a by-id read). Each row is a `{type, id, data}` map, its
-  /// `data` the flat already-decoded field map. An EMPTY list ⇒ the target has not been folded / is absent.
-  Future<List<Map<String, dynamic>>> queryById(String id);
+  /// Canonical USDA result bytes for one nominal aggregate kind and identity.
+  /// Only the generated target codec may interpret the application value.
+  Future<Uint8List> queryById(String aggregateType, String id);
 
   /// OPTIONAL reactive by-id read — the target's rows re-emitted on each projection tick. `null` when this
   /// reader offers no watch lane (then the internal watcher calls back once with `null` and no-ops).
-  Stream<List<Map<String, dynamic>>>? watchById(String id) => null;
+  Stream<Uint8List>? watchById(String aggregateType, String id) => null;
 }
 
 /// The outcome of an internal foreign-reference resolution, with the reason named — a foreign read can come back empty
@@ -61,11 +62,29 @@ class ForeignUnreachable<T> extends ForeignResolveResult<T> {
   const ForeignUnreachable(this.error);
 }
 
+enum ForeignReadFailureKind { denied, unreachable }
+
+/// A failed read is not an absent business record. Keep only address and
+/// classification metadata here; never retain/print transport or auth payloads.
+final class ForeignReadFailure implements Exception {
+  final ForeignReadFailureKind kind;
+  final String workspace;
+  final String type;
+  final String id;
+  final String sourceErrorType;
+  const ForeignReadFailure(
+      this.kind, this.workspace, this.type, this.id, this.sourceErrorType);
+
+  @override
+  String toString() => 'ForeignReadFailure(${kind.name}: $workspace/$type/$id; '
+      'source=$sourceErrorType)';
+}
+
 /// A typed, inspectable cross-application business reference. Tenant code can retain, serialize and pass
 /// it back to generated application methods; navigation, decoding and attestation remain framework state.
 final class ForeignRef<T> {
   final NomosRef<T> _ref;
-  final T Function(Map<String, dynamic> data, [String id]) _decode;
+  final T? Function(Uint8List bytes, String workspace, String id)? _decode;
 
   const ForeignRef._(this._ref, this._decode);
 
@@ -92,31 +111,23 @@ abstract final class NmsInternalForeignRefs {
     required String id,
     required String workspace,
     required String type,
-    required T Function(Map<String, dynamic> data, [String id]) fromJson,
+    T? Function(Uint8List bytes, String workspace, String id)? fromUsda,
   }) =>
       ForeignRef<T>._(
         NmsInternalNomosRefs.create<T>(
             workspace: workspace, type: type, id: id),
-        fromJson,
+        fromUsda,
       );
 
-  static T? _decodeRows<T>(
-      ForeignRef<T> reference, List<Map<String, dynamic>> rows) {
-    if (rows.isEmpty) return null;
-    final id = NmsInternalNomosRefs.id(reference._ref);
-    Map<String, dynamic>? match;
-    for (final r in rows) {
-      if (r['id'] == id) {
-        match = r;
-        break;
-      }
+  static T? _decodeResult<T>(ForeignRef<T> reference, Uint8List bytes) {
+    final decoder = reference._decode;
+    if (decoder == null) {
+      throw StateError(
+        'This ForeignRef was decoded by a retired projection-map path; '
+        'regenerate its application client to install the nominal USDA codec.',
+      );
     }
-    match ??= rows.first;
-    final data = match['data'];
-    if (data is! Map<String, dynamic>) return null;
-    final rawId = match['id'];
-    final rowId = rawId is String ? rawId : (rawId?.toString() ?? id);
-    return reference._decode(data, rowId);
+    return decoder(bytes, reference.workspace, reference.id);
   }
 
   static Future<ForeignResolveResult<T>> resolveResult<T>(
@@ -125,8 +136,11 @@ abstract final class NmsInternalForeignRefs {
     final workspace = NmsInternalNomosRefs.workspace(reference._ref);
     if (id.isEmpty || workspace.isEmpty) return ForeignNotFound<T>();
     try {
-      final rows = await nomos.foreignWorkspace(workspace).queryById(id);
-      final row = _decodeRows(reference, rows);
+      final bytes = await nomos.foreignWorkspace(workspace).queryById(
+            reference.type,
+            id,
+          );
+      final row = _decodeResult(reference, bytes);
       return row != null ? ForeignFound<T>(row) : ForeignNotFound<T>();
     } catch (error) {
       final m = error.toString().toLowerCase();
@@ -140,7 +154,19 @@ abstract final class NmsInternalForeignRefs {
   static Future<T?> resolve<T>(
       ForeignRef<T> reference, NomosForeignReader nomos) async {
     final r = await resolveResult(reference, nomos);
-    return r is ForeignFound<T> ? r.row : null;
+    if (r is ForeignFound<T>) return r.row;
+    if (r is ForeignNotFound<T>) return null;
+    final error =
+        r is ForeignDenied<T> ? r.error : (r as ForeignUnreachable<T>).error;
+    throw ForeignReadFailure(
+      r is ForeignDenied<T>
+          ? ForeignReadFailureKind.denied
+          : ForeignReadFailureKind.unreachable,
+      reference.workspace,
+      reference.type,
+      reference.id,
+      error.runtimeType.toString(),
+    );
   }
 
   static void Function() watch<T>(ForeignRef<T> reference,
@@ -151,13 +177,16 @@ abstract final class NmsInternalForeignRefs {
       cb(null);
       return () {};
     }
-    final stream = nomos.foreignWorkspace(workspace).watchById(id);
+    final stream = nomos.foreignWorkspace(workspace).watchById(
+          reference.type,
+          id,
+        );
     if (stream == null) {
       cb(null);
       return () {};
     }
     final sub = stream.listen(
-      (rows) => cb(_decodeRows(reference, rows)),
+      (bytes) => cb(_decodeResult(reference, bytes)),
       onError: (Object _) => cb(null),
     );
     return sub.cancel;