@githolon/dsl 0.105.23 → 0.106.0

package/src/kernel_capabilities.ts

@@ -1,60 +1,33 @@
-// 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.
-
+// Kernel compatibility uses the standard OSGi Contract Namespace. Domain shape determines which
+// osgi.contract requirements a generated client carries; provider repositories advertise matching
+// capabilities. There is no hash registry, feature vocabulary manifest, or Nomos resolver language.
 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"
-  /** Law-declared immutable pending-conflict snapshots (compare-and-set merge refs). */
-  | "conflictSnapshots"
-  /** `.owned()` automatic owner stamp, atomic per-record seat, and framework-custodied epoch-0 key. */
-  | "ownedAudience"
-  /** Captured-clock temporal enum projections declared by `t.timestamp().temporalEnum(...)`. */
-  | "temporalEnum";
+export interface OsgiContractRequirement {
+  readonly namespace: "osgi.contract";
+  readonly name: string;
+  readonly version: string;
+}
+
+export const NOMOS_KERNEL_CONTRACT = "nomos.kernel.v1";
+export const NOMOS_KERNEL_CONTRACT_VERSION = "1.0.0";
 
-/** 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>> = {
+const EXTENSION_CONTRACTS = {
+  compoundKeys: "nomos.kernel.extension.compoundKeys",
+  capturedReads: "nomos.kernel.extension.capturedReads",
+  invariantGate: "nomos.kernel.extension.invariantGate",
+  surfacedMerge: "nomos.kernel.extension.surfacedMerge",
+  fieldProvenance: "nomos.kernel.extension.fieldProvenance",
+  nullSemantics: "nomos.kernel.extension.nullSemantics",
+  attestedReads: "nomos.kernel.extension.attestedReads",
+  conflictSnapshots: "nomos.kernel.extension.conflictSnapshots",
+  ownedAudience: "nomos.kernel.extension.ownedAudience",
+  temporalEnum: "nomos.kernel.extension.temporalEnum",
+} as const;
+
+type KernelExtension = keyof typeof EXTENSION_CONTRACTS;
+
+const ERA_KEY_TO_EXTENSION: Readonly<Record<string, KernelExtension>> = {
   nomosReadGate: "capturedReads",
   nomosInvariantGate: "invariantGate",
   nomosSurfaced: "surfacedMerge",
@@ -63,216 +36,85 @@ export const ERA_KEY_TO_FEATURE: Readonly<Record<string, KernelFeature>> = {
   nomosAttestedReads: "attestedReads",
 };
 
-/** A minimal shape of a compiled domain module — enough to derive its kernel needs. */
-export interface FeatureProbeModule {
+export interface KernelContractProbeModule {
   readonly queries?: readonly QueryDecl[];
   readonly deriveds?: readonly unknown[];
   readonly surfacedResolvers?: readonly unknown[];
   readonly aggregates?: readonly { audience?: { kind?: string } }[];
-  /** 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");
+const requirement = (name: string): OsgiContractRequirement => ({
+  namespace: "osgi.contract",
+  name,
+  version: NOMOS_KERNEL_CONTRACT_VERSION,
+});
+
+/** Derive exact OSGi Contract Namespace requirements from the emitted law shape. */
+export function requiredKernelContracts(
+  modules: readonly KernelContractProbeModule[],
+): OsgiContractRequirement[] {
+  const extensions = new Set<KernelExtension>();
+  for (const module of modules) {
+    for (const query of module.queries ?? []) {
+      if (Array.isArray(query.key) && query.key.length > 1) extensions.add("compoundKeys");
     }
-    if ((m.deriveds ?? []).some((derived) =>
+    if ((module.deriveds ?? []).some((derived) =>
       typeof derived === "object" && derived !== null && "kind" in derived &&
       derived.kind === "temporalEnum")) {
-      needs.add("temporalEnum");
+      extensions.add("temporalEnum");
     }
-    if ((m.surfacedResolvers?.length ?? 0) > 0) needs.add("conflictSnapshots");
-    if ((m.aggregates ?? []).some((aggregate) => aggregate.audience?.kind === "owned")) {
-      needs.add("ownedAudience");
+    if ((module.surfacedResolvers?.length ?? 0) > 0) extensions.add("conflictSnapshots");
+    if ((module.aggregates ?? []).some((aggregate) => aggregate.audience?.kind === "owned")) {
+      extensions.add("ownedAudience");
     }
-    if (m.layer) {
-      for (const [eraKey, feature] of Object.entries(ERA_KEY_TO_FEATURE)) {
-        if (m.layer[eraKey] !== undefined) needs.add(feature);
+    if (module.layer) {
+      for (const [eraKey, extension] of Object.entries(ERA_KEY_TO_EXTENSION)) {
+        if (module.layer[eraKey] !== undefined) extensions.add(extension);
       }
     }
   }
-  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;
+  return [
+    requirement(NOMOS_KERNEL_CONTRACT),
+    ...[...extensions].map((extension) => requirement(EXTENSION_CONTRACTS[extension])),
+  ].sort((a, b) => a.name.localeCompare(b.name));
 }
 
-export const KERNEL_CAPABILITY_REGISTRY: readonly KernelRegistryEntry[] = [
-  {
-    prefix: "f50d0cc5",
-    version: "kernel-f50d0cc5",
-    note: "current local production build",
-    features: [
-      "compoundKeys",
-      "capturedReads",
-      "invariantGate",
-      "surfacedMerge",
-      "fieldProvenance",
-      "nullSemantics",
-      "attestedReads",
-    ],
-  },
-  {
-    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;
+export interface OsgiContractCapability {
+  readonly namespace: "osgi.contract";
+  readonly name: string;
+  readonly versions: readonly string[];
 }
 
-/** The verdict of a law↔kernel coherence assessment. */
-export interface KernelCoherenceVerdict {
+export interface KernelContractVerdict {
   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 missing: readonly OsgiContractRequirement[];
   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. */
+/** Compare requirements and capabilities using OSGi Contract Namespace identity and versions. */
+export function assessKernelContracts(params: {
+  requirements: readonly OsgiContractRequirement[];
+  capabilities: readonly OsgiContractCapability[];
   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". `
-        : missing.includes("temporalEnum")
-          ? `A temporal enum read will be refused while mounting law with ` +
-            `"unknown nomos:readKind temporalEnum". `
-        : ``) +
-      `Upgrade the cloud's kernel (or point at a cloud whose kernel is coherent with this release).`,
-  };
+}): KernelContractVerdict {
+  const missing = params.requirements.filter((required) => !params.capabilities.some((offered) =>
+    offered.namespace === required.namespace && offered.name === required.name &&
+    offered.versions.includes(required.version)));
+  const law = params.lawHash ? params.lawHash.replace(/^sha256:|^policy:/, "").slice(0, 8) : "<unknown>";
+  return missing.length === 0
+    ? { ok: true, missing: [], message: `OSGi kernel contracts satisfy law ${law}` }
+    : {
+        ok: false,
+        missing,
+        message: `kernel lacks OSGi contract ${missing.map((item) => `${item.name}=${item.version}`).join(", ")} required by law ${law}`,
+      };
 }
 
-/** 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) {
+  readonly verdict: KernelContractVerdict;
+  readonly code = "kernel-contract-incompatible";
+  constructor(verdict: KernelContractVerdict) {
     super(verdict.message);
     this.name = "KernelCoherenceError";
     this.verdict = verdict;