@githolon/dsl 0.92.0 → 0.93.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/package.json

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

@@ -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;`,
@@ -2109,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)), "..");
 
@@ -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/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;
+  }
+}