@githolon/dsl 0.91.0 → 0.93.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/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.5.0
+
+- Add typed `SourceSessionNotMounted` error (code `nomos.attested_read.source_not_mounted`) for the colocated attested-read fix — a foreign `read(q, {from})` whose source workspace isn't mounted now fails fast with a typed error + `mountSourceSession` remedy.
+
 ## 0.4.1
 
 - `canonicalPrincipal` / `signerObjectOf` — THE one principal normalizer (kernel truth:

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.93.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
@@ -1086,6 +1086,9 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `   *  and the holon computes the LIVE per-member verdict on \`holon.compat\`. A KNOWN-incompatible directive`,
     `   *  then refuses CLIENT-SIDE at write time (LawMismatchError), never as a server 422. */`,
     `  checkCompat?(compat: { lawHash: string; interfaceHash: string; packageName: string }, requirement?: unknown): NomosCompatVerdict | null;`,
+    `  /** RELEASE COHERENCE: throws a typed KernelCoherenceError at bind if the cloud's kernel lacks a`,
+    `   *  capability this law requires (e.g. \`compoundKeys\`) — instead of an opaque deep fold refusal. */`,
+    `  assertKernelCoherence?(requiresKernel: readonly string[], opts?: { lawHash?: string }): unknown;`,
     `  /** The live compat verdict (set by checkCompat). \`has(memberId)\` is the dark-launch feature flag;`,
     `   *  \`refresh()\` re-derives against the current projection. Absent until the factory binds. */`,
     `  compat?: NomosCompatVerdict;`,
@@ -1849,7 +1852,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 +1925,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 +1942,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 }[] }>);`,
         `    },`,
       );
     }
@@ -2094,6 +2112,9 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
             opts.interface !== undefined
               ? `  holon.checkCompat?.(${compatConstName(opts.packageName)}, ${interfaceConstName(opts.packageName)});`
               : `  holon.checkCompat?.(${compatConstName(opts.packageName)});`,
+            // RELEASE COHERENCE: throw a typed skew error AT BIND if the cloud's kernel lacks a capability
+            // this law requires (e.g. compoundKeys) — instead of the opaque deep fold refusal later.
+            `  holon.assertKernelCoherence?.(${compatConstName(opts.packageName)}.requiresKernel ?? [], { lawHash: ${compatConstName(opts.packageName)}.lawHash });`,
           ]
         : []),
       `  return {`,

package/src/compat_manifest.ts

@@ -17,4 +17,11 @@ export interface NomosCompat {
   readonly domains: Record<string, { readonly identityHash?: string }>;
   /** The generator provenance — the `@githolon/dsl` version + this manifest's schema. */
   readonly generator: { readonly dsl: string; readonly schema: number };
+  /** RELEASE COHERENCE (kernel_capabilities.ts): the named kernel capabilities this law
+   *  REQUIRES to fold (derived from its shape — e.g. `compoundKeys` for a `.key(a, b)` query).
+   *  connect() / deploy compares this against the target kernel's advertised capabilities and
+   *  fails with a TYPED message naming the mismatch, INSTEAD of the opaque deep-fold refusal.
+   *  Empty ⇒ no special capability needed (byte-identical to before this field for such a law
+   *  — but note: this manifest is frontend-only, never in the USD IR / domainHash). */
+  readonly requiresKernel: readonly string[];
 }

package/src/compile_package_main.ts

@@ -132,6 +132,7 @@ import { domainInterface, type DomainInterface } from "./shape_compat.js";
 import { generateTsProof, proofLegsIndex } from "./codegen_proof.js";
 import { checkDomainModules, formatFindings, hasRefusal } from "./law_check.js";
 import type { NomosCompat } from "./compat_manifest.js";
+import { requiredKernelFeatures, type FeatureProbeModule } from "./kernel_capabilities.js";
 
 const DSL_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -1046,11 +1047,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).
@@ -2552,12 +2553,26 @@ async function main(): Promise<void> {
     const identityHash = identity.hashes[key];
     compatDomains[key] = identityHash === undefined ? {} : { identityHash };
   }
+  // RELEASE COHERENCE — the kernel capabilities this law REQUIRES (compound-key queries +
+  // era-key features). Baked into the client so connect() can check it against the target
+  // kernel's advertised capabilities BEFORE the law folds (kernel_capabilities.ts).
+  const requiresKernel = ((): string[] => {
+    const probes: FeatureProbeModule[] = domainModules.map((m) => (m.queries ? { queries: m.queries } : {}));
+    try {
+      const parsed = JSON.parse(usdJson) as { layers?: Record<string, unknown>[] };
+      for (const layer of parsed.layers ?? []) probes.push({ layer });
+    } catch {
+      /* shape-derived features (compoundKeys) still apply from the queries above */
+    }
+    return requiredKernelFeatures(probes);
+  })();
   const nomosCompat: NomosCompat = {
     packageName: cfg.name,
     lawHash: domainHash,
     interfaceHash: sha256HexUtf8(canonicalJson(packageInterface)),
     domains: compatDomains,
     generator: { dsl: dslVersion, schema: 1 },
+    requiresKernel,
   };
 
   // ── 3b. the OpenAPI spec — THE PACKAGE'S SELF-DESCRIPTION (the host's runtime routing table;

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

package/src/index.ts

@@ -148,6 +148,20 @@ export { repair, repairsOf, isRepairDecl, type RepairDecl, type RepairMatcher, t
 // `nomos-compile` REFUSES law that references read() (a named compile error, never a runtime halt).
 // The captured-reads wave (task #58) wires the capability in and lifts the refusal.
 export { read } from "./read.js";
+// RELEASE COHERENCE — the kernel capability stamp + law↔kernel fit check (kernel_capabilities.ts).
+export {
+  requiredKernelFeatures,
+  capabilitiesForKernelHash,
+  assessKernelCoherence,
+  KernelCoherenceError,
+  KERNEL_CAPABILITY_REGISTRY,
+  ERA_KEY_TO_FEATURE,
+  type KernelFeature,
+  type KernelStamp,
+  type KernelCoherenceVerdict,
+  type KernelRegistryEntry,
+  type FeatureProbeModule,
+} from "./kernel_capabilities.js";
 // ATTESTED CROSS-WORKSPACE READS (slice B — attested_reads_design.md): the declared trust
 // surface (`trustSource`), the foreign query reference, and the reader-side SourceFrontier.
 export {

package/src/kernel_capabilities.ts

@@ -0,0 +1,245 @@
+// RELEASE COHERENCE — the kernel capability stamp + the law↔kernel fit check.
+//
+// THE PROBLEM THIS SOLVES (the co2 skew, 2026-07): a published release can be
+// internally inconsistent. The production kernel accepts law that a compiler emits;
+// the DEV/test-mint kernel a `githolon cloud dev` serves can be STALE and REFUSE the
+// same law — but only at runtime, deep in a law fold ("query declares 2 index keys;
+// the read router supports exactly one"). Four artifacts drift independently:
+//   · the compiler (@githolon/dsl) that EMITS the law,
+//   · the runner bundle (@githolon/client) that RUNS it,
+//   · the production kernel wasm the cloud serves,
+//   · the test-mint kernel wasm the dev cloud serves.
+// There is NO version/hash check that catches the skew before the opaque refusal.
+//
+// THE FIX: a kernel advertises a VERSION + a set of named CAPABILITIES (feature flags
+// keyed to the era keys / read-router lanes it implements). A package DECLARES the
+// kernel capabilities its law REQUIRES (derived from its shape — e.g. a compound-key
+// query needs `compoundKeys`). Before the law ever folds, we compare the two and fail
+// with a TYPED, human-legible message NAMING the mismatch — not the deep refusal.
+//
+// This module is the SINGLE SOURCE OF TRUTH for: the capability vocabulary, deriving a
+// package's requirements from its shape, the known-kernel registry (keyed by wasm
+// sha256), and the coherence assessment. The CLI (`githolon doctor`, deploy), the
+// generated client (baked `requiresKernel`), and the cloud worker's
+// `/v1/runtime/capabilities` endpoint all draw on it.
+
+import type { QueryDecl } from "./query.js";
+
+/** A named kernel capability — a feature/lane the wasm kernel must implement for a law
+ *  that uses it to fold. Each maps to a read-router lane or an era key. Additive: a new
+ *  capability name is minted here the same day the kernel arm ships. */
+export type KernelFeature =
+  /** The read router accepts a query with MORE THAN ONE index key (`.key(a, b, …)`),
+   *  routing it as a compound (AND) intersection. Pre-this kernels refuse >1 index key
+   *  ("the read router supports exactly one"). THE CONCRETE co2 SKEW. */
+  | "compoundKeys"
+  /** The #58 captured-read lane (`read()` in deployable law + `.reads(query)`). */
+  | "capturedReads"
+  /** The #41 declared-invariant gate (`invariant` / `workspaceInvariant`). */
+  | "invariantGate"
+  /** Surfaced(inner) — retained concurrent competing values as a pending set. */
+  | "surfacedMerge"
+  /** `.attributed()` / aggregate `{attributed:true}` per-field provenance. */
+  | "fieldProvenance"
+  /** Null as an opt-in named capability (`admitsNull()`). */
+  | "nullSemantics"
+  /** Dynamic attested reads under a trustPolicy allowList. */
+  | "attestedReads";
+
+/** The USD-IR era key each derived-from-law capability rides on, for the requirement
+ *  derivation below (a package that emits the era key needs the capability). */
+export const ERA_KEY_TO_FEATURE: Readonly<Record<string, KernelFeature>> = {
+  nomosReadGate: "capturedReads",
+  nomosInvariantGate: "invariantGate",
+  nomosSurfaced: "surfacedMerge",
+  nomosAttributed: "fieldProvenance",
+  nomosNullable: "nullSemantics",
+  nomosAttestedReads: "attestedReads",
+};
+
+/** A minimal shape of a compiled domain module — enough to derive its kernel needs. */
+export interface FeatureProbeModule {
+  readonly queries?: readonly QueryDecl[];
+  /** The domain's USD-IR layer (the era keys ride here). Optional — shape-derived
+   *  features (compoundKeys) work without it. */
+  readonly layer?: Record<string, unknown>;
+}
+
+/** DERIVE the kernel capabilities a package's law REQUIRES, from its shape + era keys.
+ *  The result is a sorted, de-duped list baked into the client compat manifest and
+ *  checked against a target kernel's advertised capabilities before the law folds.
+ *
+ *  The load-bearing case: ANY query with a compound (`.key(a, b)`) index needs
+ *  `compoundKeys` — exactly the lane the stale test-mint kernel lacked. */
+export function requiredKernelFeatures(modules: readonly FeatureProbeModule[]): KernelFeature[] {
+  const needs = new Set<KernelFeature>();
+  for (const m of modules) {
+    for (const q of m.queries ?? []) {
+      if (Array.isArray(q.key) && q.key.length > 1) needs.add("compoundKeys");
+    }
+    if (m.layer) {
+      for (const [eraKey, feature] of Object.entries(ERA_KEY_TO_FEATURE)) {
+        if (m.layer[eraKey] !== undefined) needs.add(feature);
+      }
+    }
+  }
+  return [...needs].sort();
+}
+
+/** A kernel's self-description: its version tag + the capabilities it implements. This is
+ *  the shape the kernel stamps (see `kernelStamp` op in wasm_git_holon.rs) AND the shape
+ *  the host `/v1/runtime/capabilities` endpoint synthesizes for the deployed wasm it can't
+ *  yet ask (keyed by the wasm sha256 in the registry below). */
+export interface KernelStamp {
+  /** The kernel semver-ish version tag baked into the wasm at build. */
+  readonly version: string;
+  /** The wasm artifact sha256 (64-hex), when known. */
+  readonly hash?: string;
+  /** The named capabilities this kernel implements. */
+  readonly features: readonly KernelFeature[];
+  /** Human note (e.g. "production", "test-mint (DEV ONLY)") — surfaced in the skew message. */
+  readonly note?: string;
+}
+
+/** THE KNOWN-KERNEL REGISTRY — maps a kernel wasm sha256 PREFIX to its capability stamp.
+ *  Keyed by prefix so a short hash (the co2 report cites `846c6bf8` / `f81cb952`) resolves.
+ *
+ *  WHY host-side and not only asked of the kernel: the CURRENTLY-DEPLOYED stale kernel
+ *  predates the stamp op — it cannot answer "what are your capabilities?". Until every
+ *  serving kernel carries the in-wasm stamp, this registry lets the host + client resolve
+ *  a deployed wasm's capabilities from its BYTES, which is always available. A kernel that
+ *  DOES carry the stamp op is preferred; this is the fallback that works today.
+ *
+ *  Add an entry the moment a new kernel wasm is cut (its sha256 + the features it gained). */
+export interface KernelRegistryEntry extends KernelStamp {
+  readonly prefix: string;
+  /** Human note (e.g. "production", "test-mint (DEV ONLY)"). */
+  readonly note?: string;
+}
+
+export const KERNEL_CAPABILITY_REGISTRY: readonly KernelRegistryEntry[] = [
+  {
+    prefix: "846c6bf8",
+    version: "kernel-846c6bf8",
+    note: "production (accepts compound-key law)",
+    features: [
+      "compoundKeys",
+      "capturedReads",
+      "invariantGate",
+      "surfacedMerge",
+      "fieldProvenance",
+      "nullSemantics",
+      "attestedReads",
+    ],
+  },
+  {
+    // CURRENT test-mint kernel (rebuilt from the SAME source as prod 846c6bf8, 2026-07-14; staged to R2 +
+    // built/staged by deploy.sh every release). Feature-equivalent to production — the dev cloud is coherent.
+    prefix: "f6e44b3a",
+    version: "kernel-f6e44b3a",
+    note: "test-mint (DEV) — current, feature-equivalent to production",
+    features: [
+      "compoundKeys",
+      "capturedReads",
+      "invariantGate",
+      "surfacedMerge",
+      "fieldProvenance",
+      "nullSemantics",
+      "attestedReads",
+    ],
+  },
+  {
+    prefix: "f81cb952",
+    version: "kernel-f81cb952",
+    note: "test-mint (DEV ONLY — STALE: predates compound-key read router; superseded by f6e44b3a)",
+    features: [
+      "capturedReads",
+      "invariantGate",
+      "surfacedMerge",
+      "fieldProvenance",
+      "nullSemantics",
+      "attestedReads",
+    ],
+  },
+];
+
+/** Resolve a kernel wasm hash (full or short) to its known capability stamp, or `null`
+ *  when the hash is unknown to the registry (a kernel we've never catalogued). */
+export function capabilitiesForKernelHash(hash: string | undefined | null): KernelStamp | null {
+  if (typeof hash !== "string" || hash.length < 6) return null;
+  const h = hash.toLowerCase().replace(/^sha256:|^policy:/, "");
+  const hit = KERNEL_CAPABILITY_REGISTRY.find((e) => h.startsWith(e.prefix) || e.prefix.startsWith(h));
+  return hit
+    ? { version: hit.version, hash: h, features: hit.features, ...(hit.note ? { note: hit.note } : {}) }
+    : null;
+}
+
+/** The verdict of a law↔kernel coherence assessment. */
+export interface KernelCoherenceVerdict {
+  readonly ok: boolean;
+  /** The required features the target kernel does NOT advertise. Empty ⇒ coherent. */
+  readonly missing: KernelFeature[];
+  /** A human-legible one-line message — the thing surfaced INSTEAD of the deep fold refusal. */
+  readonly message: string;
+}
+
+/** ASSESS whether a target kernel can fold a package's law. `requires` is the package's
+ *  derived requirement ({@link requiredKernelFeatures}); `kernel` is the target's stamp
+ *  (from its stamp op, or {@link capabilitiesForKernelHash}). A `null` kernel stamp means
+ *  the target's capabilities are UNKNOWN — reported distinctly (can't prove coherence).
+ *
+ *  The message names BOTH hashes and the offending capability — the co2 skew, legibly. */
+export function assessKernelCoherence(params: {
+  requires: readonly KernelFeature[];
+  kernel: KernelStamp | null;
+  /** The target kernel's hash, for the message even when the stamp is unknown. */
+  kernelHash?: string;
+  /** The law's hash, for the message. */
+  lawHash?: string;
+}): KernelCoherenceVerdict {
+  const { requires, kernel } = params;
+  const short = (h?: string) => (h ? `${String(h).replace(/^sha256:|^policy:/, "").slice(0, 8)}` : "<unknown>");
+  const lawH = short(params.lawHash);
+  const kernH = short(params.kernelHash ?? kernel?.hash);
+  if (requires.length === 0) {
+    return { ok: true, missing: [], message: `law ${lawH} requires no special kernel capabilities` };
+  }
+  if (kernel === null) {
+    return {
+      ok: false,
+      missing: [...requires],
+      message:
+        `cannot verify release coherence — this cloud's kernel ${kernH} is UNKNOWN to the ` +
+        `capability registry, so it cannot be confirmed to support [${requires.join(", ")}] that ` +
+        `law ${lawH} requires. Update the kernel registry or upgrade the cloud's kernel.`,
+    };
+  }
+  const missing = requires.filter((f) => !kernel.features.includes(f)) as KernelFeature[];
+  if (missing.length === 0) {
+    return { ok: true, missing: [], message: `kernel ${kernH} supports all capabilities law ${lawH} requires` };
+  }
+  return {
+    ok: false,
+    missing,
+    message:
+      `this cloud's kernel ${kernH} lacks capability '${missing.join("', '")}' that law ${lawH} requires — ` +
+      `the cloud is running a STALE kernel (${kernel.note ?? kernel.version}). ` +
+      (missing.includes("compoundKeys")
+        ? `A compound-key query (\`.key(a, b, …)\`) will be refused deep in a law fold with ` +
+          `"query declares N index keys; the read router supports exactly one". `
+        : ``) +
+      `Upgrade the cloud's kernel (or point at a cloud whose kernel is coherent with this release).`,
+  };
+}
+
+/** A typed error thrown when a coherence assertion fails — carries the structured verdict so
+ *  callers can render it or branch, instead of parsing a message. */
+export class KernelCoherenceError extends Error {
+  readonly verdict: KernelCoherenceVerdict;
+  readonly code = "kernel-capability-skew";
+  constructor(verdict: KernelCoherenceVerdict) {
+    super(verdict.message);
+    this.name = "KernelCoherenceError";
+    this.verdict = verdict;
+  }
+}