@githolon/dsl 0.91.0 → 0.92.0

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.57.0
+version: 0.58.0
 
 environment:
   sdk: ^3.5.0
@@ -20,7 +20,7 @@ dependencies:
   # The pure-data core (wire types, offer codec, NomosReads, schema validation, error
   # info). nomos_client depends on and re-exports it, so existing imports are unchanged.
   # For local monorepo dev, pubspec_overrides.yaml points this at ../dart_types.
-  nomos_types: ^0.4.1
+  nomos_types: ^0.5.0
   json_schema: ^5.2.2
   crypto: ^3.0.0
 

package/dart_types/lib/src/errors.dart

@@ -26,6 +26,9 @@ NomosBridgeError nomosErrorFromInfo(NomosErrorInfo info) {
   if (info.code.startsWith('nomos.authz.')) return AuthzRefusedError.fromInfo(info);
   if (info.code.startsWith('nomos.auth.')) return AuthError.fromInfo(info);
   if (info.code.startsWith('nomos.load.')) return LoadError.fromInfo(info);
+  if (info.code == 'nomos.attested_read.source_not_mounted') {
+    return SourceSessionNotMounted.fromInfo(info);
+  }
   return NomosBridgeError(info.message, info: info);
 }
 
@@ -62,6 +65,11 @@ 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).
+  static const mountSourceSession = 'mountSourceSession';
+
   /// No automatic remedy — surface to a human.
   static const none = 'none';
 
@@ -84,6 +92,8 @@ class NomosRecommendedAction {
         return 'reopen the holon (reconnect fresh)';
       case ensureParentSignerEnrollment:
         return 'restore the device signer on the parent (ensureParentSignerEnrollment / NomosScope.home repairs it on reopen)';
+      case mountSourceSession:
+        return 'mount the attested read\'s source workspace as a session on this plane (connect it / ref.acquire) so the read resolves in-engine';
       case none:
         return 'no automatic remedy — inspect the error';
       default:
@@ -413,6 +423,63 @@ class LoadError extends NomosBridgeError {
       '${sourceUrl != null ? ', sourceUrl: $sourceUrl' : ''}, recommendedAction: $recommendedAction): $message';
 }
 
+/// 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
+/// (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 {
+  /// The stable machine code — always `nomos.attested_read.source_not_mounted`.
+  final String code;
+
+  /// The name the directive's `read(..., {from})` (or explicit attested read) referenced — a session alias
+  /// or a workspace name.
+  final String? from;
+
+  /// The resolved SOURCE workspace that must be mounted on this plane.
+  final String? sourceWorkspace;
+
+  /// The declared query the foreign read names, when known.
+  final String? queryId;
+
+  /// The named remedy — [NomosRecommendedAction.mountSourceSession].
+  final String recommendedAction;
+
+  SourceSessionNotMounted({
+    this.code = 'nomos.attested_read.source_not_mounted',
+    required String message,
+    this.from,
+    this.sourceWorkspace,
+    this.queryId,
+    this.recommendedAction = NomosRecommendedAction.mountSourceSession,
+    NomosErrorInfo? info,
+  }) : super(message, info: info);
+
+  factory SourceSessionNotMounted.fromInfo(NomosErrorInfo info) {
+    String? attr(String name) {
+      final v = info.attributes['nomos.attested_read.$name'] ?? info.attributes[name];
+      return v?.toString();
+    }
+
+    return SourceSessionNotMounted(
+      code: info.code,
+      message: info.message,
+      from: attr('from'),
+      sourceWorkspace: attr('source_workspace') ?? attr('sourceWorkspace') ?? info.workspace,
+      queryId: (info.attributes['nomos.query_id'] ?? attr('queryId'))?.toString(),
+      recommendedAction: attr('recommendedAction') ?? attr('recommended_action') ?? NomosRecommendedAction.mountSourceSession,
+      info: info,
+    );
+  }
+
+  @override
+  String toString() =>
+      'SourceSessionNotMounted(source: $sourceWorkspace'
+      '${queryId != null ? ', query: $queryId' : ''}, recommendedAction: $recommendedAction): $message';
+}
+
 /// The custody phase a [CustodyError] was raised in.
 enum CustodyPhase { fold, author, fetch, unknown }
 

package/dart_types/pubspec.yaml

@@ -11,7 +11,7 @@ description: >-
   Pure kernel wire/data types for Nomos Dart frontends — no transport, no bridge,
   no runtime. The hand-written serde-JSON-compatible types plus the offer codec,
   reactive read engine, schema validation, and data-only error/trace types.
-version: 0.4.1
+version: 0.5.0
 
 environment:
   sdk: ^3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.91.0",
+  "version": "0.92.0",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/codegen_dart_client.ts

@@ -240,6 +240,13 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     const gateDoc = gate !== undefined
       ? `  /// GATED: needs an \`actor\` (the \`${gate.relation}\` relation) — throws MissingOfferAuthority otherwise.`
       : "";
+    // FALLBACK ATTESTATION INJECTION (co2): a directive whose law declares a foreign read (`.readsFrom(...)`)
+    // accepts pre-fetched signed envelopes as an optional `attestations:` param — the manual override when the
+    // colocation resolver can't serve the read (the source isn't mounted on the plane). The in-engine
+    // colocation path stays the default; only foreign-read directives carry the extra named param.
+    const wantAttest = (((d as { declaredForeignReads?: unknown[] }).declaredForeignReads?.length ?? 0) > 0);
+    const attNamed = wantAttest ? "List<Map<String, Object?>>? attestations" : "";
+    const attArg = wantAttest ? ", attestations: attestations" : "";
     // E2E SEALING (the sealing client): a directive with `.encrypted()` payload fields SEALS them via the
     // bound [keyStore] before dispatch (a missing key throws [EncryptionKeyUnavailable] — never a plaintext
     // write). One async block covers creates + mutate + gated + stamps; `seal: false` is the escape hatch.
@@ -255,7 +262,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
         `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the typed [NomosOfferOutcome].${createsDoc}`,
         `  /// Encrypted field(s) are SEALED via the bound [keyStore] before dispatch (pass \`seal: false\` to skip).${stampsDoc}`,
         ...(gateDoc ? [gateDoc] : []),
-        `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload, {bool seal = true}) async {`,
+        `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload, {bool seal = true${wantAttest ? ", " + attNamed : ""}}) async {`,
         ...(gateGuard ? [gateGuard] : []),
         `    final data = payload.toPayloadJson();`,
         ...(stamps.length > 0
@@ -265,7 +272,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
             ]
           : []),
         `    await _sealPayload(data, ${dartStr(d.id)}, seal);`,
-        `    return _offer(${dartStr(d.id)}, data);`,
+        `    return _offer(${dartStr(d.id)}, data${attArg});`,
         `  }`,
         ``,
       );
@@ -275,12 +282,12 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       methods.push(
         `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the typed [NomosOfferOutcome].${createsDoc}${stampsDoc}`,
         ...(gateDoc ? [gateDoc] : []),
-        `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload) {`,
+        `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload${wantAttest ? ", {" + attNamed + "}" : ""}) {`,
         ...(gateGuard ? [gateGuard] : []),
         `    final data = payload.toPayloadJson();`,
         `    final now = DateTime.now().toUtc().toIso8601String();`,
         ...stamps.map((s) => `    data.putIfAbsent(${dartStr(s)}, () => now);`),
-        `    return _offer(${dartStr(d.id)}, data);`,
+        `    return _offer(${dartStr(d.id)}, data${attArg});`,
         `  }`,
         ``,
       );
@@ -289,9 +296,9 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       methods.push(
         `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the typed [NomosOfferOutcome].${createsDoc}`,
         gateDoc,
-        `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload) {`,
+        `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload${wantAttest ? ", {" + attNamed + "}" : ""}) {`,
         gateGuard,
-        `    return _offer(${dartStr(d.id)}, payload.toPayloadJson());`,
+        `    return _offer(${dartStr(d.id)}, payload.toPayloadJson()${attArg});`,
         `  }`,
         ``,
       );
@@ -299,8 +306,8 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       methods.push(
         `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the typed [NomosOfferOutcome].${createsDoc}`,
         ...(gateDoc ? [gateDoc] : []),
-        `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload) =>`,
-        `      _offer(${dartStr(d.id)}, payload.toPayloadJson());`,
+        `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload${wantAttest ? ", {" + attNamed + "}" : ""}) =>`,
+        `      _offer(${dartStr(d.id)}, payload.toPayloadJson()${attArg});`,
         ``,
       );
     }
@@ -879,9 +886,9 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     ``,
     `  /// THE ONE DISPATCH LANE every generated directive method routes through: lazy preflight, then`,
     `  /// the session's offer (the generated-internal use of the engine-level lane).`,
-    `  Future<NomosOfferOutcome> _offer(String directiveId, Object? payload) async {`,
+    `  Future<NomosOfferOutcome> _offer(String directiveId, Object? payload, {List<Map<String, Object?>>? attestations}) async {`,
     `    await _preflightOnce();`,
-    `    return bridge.offerOutcome(domain: ${dartStr(domain)}, directiveId: directiveId, payload: payload, actor: actor, domainHash: domainHash);`,
+    `    return bridge.offerOutcome(domain: ${dartStr(domain)}, directiveId: directiveId, payload: payload, actor: actor, domainHash: domainHash, attestations: attestations);`,
     `  }`,
     ``,
     ...(encPresent ? dartEncClassMembers(encMap!) : []),

package/src/codegen_ts.ts

@@ -1012,7 +1012,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `  /** THE ONE ENCODER offer (the single v2-envelope codec lives in @githolon/client \`encodeIntentOfferBytes\`):`,
     `   *  hand the holon a PLANNED directive + the verified \`actor\`; the holon encodes + offers. The generated`,
     `   *  client calls THIS, never building offer bytes itself — so there is exactly ONE copy of the wire format. */`,
-    `  offerDirective(domain: string, directiveId: string, payload: unknown, opts?: { domainHash?: string; actor?: string; returnCreated?: boolean }): Promise<string | { head: string; created?: { type: string; id: string }[]; workspace?: string }>;`,
+    `  offerDirective(domain: string, directiveId: string, payload: unknown, opts?: { domainHash?: string; actor?: string; returnCreated?: boolean; attestations?: readonly { queryId: string; result: unknown; attestation: unknown }[] }): Promise<string | { head: string; created?: { type: string; id: string }[]; workspace?: string }>;`,
     `  /** Opaque-bytes offer — retained for carriers that already hold an encoded envelope (back-compat). */`,
     `  offer(intentBytes: string | Uint8Array): Promise<string>;`,
     ...(hasBirths
@@ -1849,7 +1849,22 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       // escape hatch, and `pv` (the sealed copy) replaces `payload` downstream. Non-encrypted directives
       // are byte-identical (wantSeal === false ⇒ no prelude, no extra param, plain `payload`).
       const wantSeal = encMap?.[domain]?.directives?.[d.id] !== undefined;
-      const paramSig = wantSeal ? `payload: ${payloadName}, callOpts?: { seal?: boolean }` : `payload: ${payloadName}`;
+      // FALLBACK ATTESTATION INJECTION (co2): a directive whose law declares a foreign read
+      // (`.readsFrom(...)`) accepts pre-fetched signed envelopes as `callOpts.attestations` — the manual
+      // escape hatch when the colocation resolver can't serve the read (the source isn't on the plane). The
+      // in-engine colocation path (the offer resolves the read from the mounted source, zero HTTP) remains
+      // the default; this is the explicit override a caller reaches for. Emitted ONLY for foreign-read
+      // directives (an ordinary directive's signature is byte-identical).
+      const wantAttest = (((d as { declaredForeignReads?: unknown[] }).declaredForeignReads?.length ?? 0) > 0);
+      const attTy = `readonly { queryId: string; result: unknown; attestation: unknown }[]`;
+      const callOptsFields = [
+        ...(wantSeal ? ["seal?: boolean"] : []),
+        ...(wantAttest ? [`attestations?: ${attTy}`] : []),
+      ];
+      const paramSig = callOptsFields.length
+        ? `payload: ${payloadName}, callOpts?: { ${callOptsFields.join("; ")} }`
+        : `payload: ${payloadName}`;
+      const offerExtra = wantAttest ? ", attestations: callOpts?.attestations" : "";
       const sealPrelude = wantSeal
         ? `      const _sealed = await _sealFields(holon, keyStore, ${encConst}[${JSON.stringify(domain)}].directives[${JSON.stringify(d.id)}] as Record<string, { scope: string; aggSid: string; fieldSid: string }>, payload as Record<string, unknown>, callOpts?.seal !== false) as ${payloadName};`
         : "";
@@ -1907,7 +1922,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           ...(gateGuard ? [gateGuard.replace(/\n$/, "")] : []),
           ...(sealPrelude ? [sealPrelude] : []),
           `      const ${mint.field} = payload.${mint.field} ?? (await (holon as NomosRoutedHolon).mint(${JSON.stringify(mint.mintType)}${mintOpts}));`,
-          `      return _outcome(holon.workspace, holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${body}, { domainHash, actor, returnCreated: true }) as Promise<string | { head: string; created?: { type: string; id: string }[] }>, { workspace: holon.workspace, type: ${JSON.stringify(dd.aggregateId ?? mint.mintType)}, id: ${mint.field} });`,
+          `      return _outcome(holon.workspace, holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${body}, { domainHash, actor, returnCreated: true${offerExtra} }) as Promise<string | { head: string; created?: { type: string; id: string }[] }>, { workspace: holon.workspace, type: ${JSON.stringify(dd.aggregateId ?? mint.mintType)}, id: ${mint.field} });`,
           `    },`,
         );
         continue;
@@ -1924,7 +1939,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
         `    ${d.id}: async (${paramSig}): Promise<NomosOutcome> => {`,
         ...(gateGuard ? [gateGuard.replace(/\n$/, "")] : []),
         ...(sealPrelude ? [sealPrelude] : []),
-        `      return _outcome(holon.workspace, holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${offerPayload}, { domainHash, actor, returnCreated: true }) as Promise<string | { head: string; created?: { type: string; id: string }[] }>);`,
+        `      return _outcome(holon.workspace, holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${offerPayload}, { domainHash, actor, returnCreated: true${offerExtra} }) as Promise<string | { head: string; created?: { type: string; id: string }[] }>);`,
         `    },`,
       );
     }

package/src/compile_package_main.ts

@@ -1046,11 +1046,11 @@ const DART_TYPES_IMPORT = `import 'package:nomos_types/nomos_types.dart';`;
  *  just the floor generated code needs — a lagging pin forces tenants into dependency_overrides. */
 // 0.3.0: SurfacedValue<T>/SurfacedObservation/PendingConflictRow — generated Surfaced-field typing +
 //        the pendingConflicts read rows.
-const NOMOS_TYPES_DEP = "^0.4.1";
+const NOMOS_TYPES_DEP = "^0.5.0";
 // 0.48.x: session-bound clients (XClient.bind/NomosClientInterface/DomainClientSessionMismatch/
 //         DomainNotInstalledForSession, engine.follow, pendingConflicts lanes) — the generated client
 //         REQUIRES this surface. 0.48.1 fixes NomosSession.watchPendingConflicts delegation.
-const NOMOS_CLIENT_DEP = "^0.57.0";
+const NOMOS_CLIENT_DEP = "^0.58.0";
 // DRIFT TRIPWIRE: pubspec_pins.test.ts asserts these equal the CURRENT versions in dsl/dart/pubspec.yaml
 // and dsl/dart_types/pubspec.yaml — a Dart release without this bump fails the suite, so tenants never
 // land back in dependency_overrides (the exact co2 report this closes, third occurrence).

package/src/framework/workspaces.ts

@@ -86,6 +86,17 @@ import { signerObject, SIGNER_RELATION } from "./signing_identity.js";
 // them up as part of the `workspaces` domain. (architecture/platform_birth_genesis_bootstrap.md)
 export { GenesisWarrant, seedGenesis } from "./genesis.js";
 export { identityRelations, enrollSigner } from "./signing_identity.js";
+// THE BIRTH-ATTESTATION CARRIER (the K_root attestation spine for platform-hosted homes). A platform must
+// CARRY its own `platform_cert` at `birth-attestation:self` so the kernel's `assemble_home_cert_chain`
+// PREPENDS `[home_cert, delegation]` to it and the child home roots at K_root. Governance carries the cert
+// (this trio) but DELIBERATELY does NOT export the `parentAttestedBirth` era marker — a platform's own 1-link
+// `[platform_cert]` chain would fail `verify_to_root` (>=2 links), so its own verify doors must stay inert
+// while it still carries the cert for its children. Fully additive (new aggregate + directive, no era key ⇒
+// pre-existing chains replay byte-identical). architecture/co2_attestation_spine.md.
+export { BIRTH_ATTESTATION_ID, BirthAttestation, birthAttestation, seedBirthAttestation } from "./home.js";
+// THE ENROLL-ONCE DELEGATION LANE — a platform records each tenant's device-key delegation (signed by its
+// onboarding signer S_P) so the kernel reads it at `signer-delegation:<user>` when assembling a home's chain.
+export { SignerDelegation, enrollDelegation, signerDelegationByUser } from "./signing_identity.js";
 
 // ── WORKSPACE SELF-IDENTITY (the law reads its OWN install-context) ──────────────────────────────────
 // The governance bundle runs on root AND every born platform. A workspace knows its ROLE via this