chainlesschain 0.166.6 → 0.166.7

package/src/lib/graph-kernel/store-cutover-evidence.js

@@ -0,0 +1,354 @@
+import { createHash } from "node:crypto";
+
+export const GRAPH_STORE_CUTOVER_EVIDENCE_SCHEMA =
+  "chainlesschain.graph-store-cutover-evidence/v1";
+
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const COMMIT = /^[a-f0-9]{40,64}$/u;
+const STORE = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,159}$/u;
+
+function normalizePlatform(value) {
+  const platform = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (platform === "win32") return "windows";
+  if (platform === "darwin") return "macos";
+  return platform;
+}
+
+function evidenceError(code, message, details = {}) {
+  const error = new Error(message);
+  error.name = "GraphStoreCutoverEvidenceError";
+  error.code = code;
+  Object.assign(error, details);
+  return error;
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.keys(value)
+      .filter((key) => value[key] !== undefined)
+      .sort()
+      .map((key) => [key, stableValue(value[key])]),
+  );
+}
+
+export function graphStoreEvidenceDigest(value) {
+  return `sha256:${createHash("sha256")
+    .update(JSON.stringify(stableValue(value)), "utf8")
+    .digest("hex")}`;
+}
+
+export function assertExactCommitSha(expectedCommit, actualCommit) {
+  const actual = String(actualCommit || "")
+    .trim()
+    .toLowerCase();
+  const expected = String(expectedCommit || "")
+    .trim()
+    .toLowerCase();
+  if (!COMMIT.test(actual) || (expected && !COMMIT.test(expected))) {
+    throw evidenceError(
+      "CC_GRAPH_STORE_EVIDENCE_INVALID",
+      "expected and actual commit SHAs must be exact hexadecimal identities",
+    );
+  }
+  if (expected && expected !== actual) {
+    throw evidenceError(
+      "CC_GRAPH_STORE_EVIDENCE_SHA_MISMATCH",
+      `expected commit ${expected} does not match checked-out HEAD ${actual}`,
+      { expectedCommit: expected, actualCommit: actual },
+    );
+  }
+  return actual;
+}
+
+function exactDigest(value, field) {
+  const output = String(value || "");
+  if (!DIGEST.test(output)) {
+    throw evidenceError(
+      "CC_GRAPH_STORE_EVIDENCE_INVALID",
+      `${field} must be a sha256 digest`,
+      { field },
+    );
+  }
+  return output;
+}
+
+function normalizeStore(value) {
+  const surface = String(value?.surface || "").trim();
+  const entryId = String(value?.entryId || "").trim();
+  const store = String(value?.store || "").trim();
+  if (!STORE.test(surface) || !STORE.test(entryId) || !STORE.test(store)) {
+    throw evidenceError(
+      "CC_GRAPH_STORE_EVIDENCE_INVALID",
+      "store evidence has an invalid surface, entry, or store identifier",
+    );
+  }
+  if (value?.recovered !== true || Number(value?.rpoLossCount) !== 0) {
+    throw evidenceError(
+      "CC_GRAPH_STORE_EVIDENCE_RPO_FAILED",
+      `store evidence does not prove RPO=0 recovery: ${store}`,
+      { store },
+    );
+  }
+  return Object.freeze({
+    surface,
+    entryId,
+    store,
+    cutpointDigest: exactDigest(value.cutpointDigest, "cutpointDigest"),
+    recoveryReceiptDigest: exactDigest(
+      value.recoveryReceiptDigest,
+      "recoveryReceiptDigest",
+    ),
+    rollbackDrillDigest: exactDigest(
+      value.rollbackDrillDigest,
+      "rollbackDrillDigest",
+    ),
+    rpoLossCount: 0,
+    recovered: true,
+  });
+}
+
+export function createGraphStoreCutoverEvidence({
+  source,
+  commitSha,
+  platform,
+  stores,
+  sourceReceipts,
+}) {
+  const record = normalizeGraphStoreCutoverEvidence(
+    {
+      schema: GRAPH_STORE_CUTOVER_EVIDENCE_SCHEMA,
+      status: "passed",
+      source,
+      commitSha,
+      platform,
+      stores,
+      sourceReceipts,
+    },
+    { requireEvidenceDigest: false },
+  );
+  const unsigned = { ...record };
+  delete unsigned.evidenceDigest;
+  return Object.freeze({
+    ...unsigned,
+    evidenceDigest: graphStoreEvidenceDigest(unsigned),
+  });
+}
+
+export function normalizeGraphStoreCutoverEvidence(
+  value,
+  { requireEvidenceDigest = true } = {},
+) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    value.schema !== GRAPH_STORE_CUTOVER_EVIDENCE_SCHEMA ||
+    value.status !== "passed"
+  ) {
+    throw evidenceError(
+      "CC_GRAPH_STORE_EVIDENCE_INVALID",
+      "store cutover evidence schema or status is invalid",
+    );
+  }
+  const source = String(value.source || "").trim();
+  const commitSha = String(value.commitSha || "")
+    .trim()
+    .toLowerCase();
+  const platform = normalizePlatform(value.platform);
+  if (!STORE.test(source) || !COMMIT.test(commitSha) || !platform) {
+    throw evidenceError(
+      "CC_GRAPH_STORE_EVIDENCE_INVALID",
+      "store evidence source, commit SHA, or platform is invalid",
+    );
+  }
+  if (!Array.isArray(value.stores) || value.stores.length === 0) {
+    throw evidenceError(
+      "CC_GRAPH_STORE_EVIDENCE_INVALID",
+      "store evidence must contain at least one real store receipt",
+    );
+  }
+  const stores = value.stores
+    .map(normalizeStore)
+    .sort(
+      (left, right) =>
+        left.surface.localeCompare(right.surface) ||
+        left.entryId.localeCompare(right.entryId) ||
+        left.store.localeCompare(right.store),
+    );
+  if (
+    new Set(
+      stores.map(
+        (entry) => `${entry.surface}\0${entry.entryId}\0${entry.store}`,
+      ),
+    ).size !== stores.length
+  ) {
+    throw evidenceError(
+      "CC_GRAPH_STORE_EVIDENCE_DUPLICATE",
+      "store evidence contains a duplicate store receipt",
+    );
+  }
+  const sourceReceipts = Object.fromEntries(
+    Object.entries(value.sourceReceipts || {})
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([name, receipt]) => [name, exactDigest(receipt, name)]),
+  );
+  if (Object.keys(sourceReceipts).length === 0) {
+    throw evidenceError(
+      "CC_GRAPH_STORE_EVIDENCE_INVALID",
+      "store evidence must bind its source journey receipts",
+    );
+  }
+  const normalized = {
+    schema: GRAPH_STORE_CUTOVER_EVIDENCE_SCHEMA,
+    status: "passed",
+    source,
+    commitSha,
+    platform,
+    stores,
+    sourceReceipts,
+  };
+  if (requireEvidenceDigest) {
+    const evidenceDigest = exactDigest(value.evidenceDigest, "evidenceDigest");
+    if (evidenceDigest !== graphStoreEvidenceDigest(normalized)) {
+      throw evidenceError(
+        "CC_GRAPH_STORE_EVIDENCE_TAMPERED",
+        "store cutover evidence digest does not match its contents",
+      );
+    }
+    normalized.evidenceDigest = evidenceDigest;
+  }
+  return Object.freeze(normalized);
+}
+
+export function graphStoreCutoverCoverage(manifest, evidenceRecords = []) {
+  const records = evidenceRecords.map((record) =>
+    normalizeGraphStoreCutoverEvidence(record),
+  );
+  const commits = new Set(records.map((record) => record.commitSha));
+  if (commits.size > 1) {
+    throw evidenceError(
+      "CC_GRAPH_STORE_EVIDENCE_SHA_MISMATCH",
+      "store evidence records must bind one exact commit SHA",
+    );
+  }
+  const availableStores = new Map();
+  for (const record of records) {
+    for (const store of record.stores) {
+      const key = `${store.surface}\0${store.entryId}\0${store.store}`;
+      const receipts = availableStores.get(key) || [];
+      receipts.push({
+        platform: record.platform,
+        evidenceDigest: record.evidenceDigest,
+        ...store,
+      });
+      availableStores.set(key, receipts);
+    }
+  }
+  const requiredPlatforms = [
+    ...(manifest.cutoverPolicy?.requiredPlatforms || []),
+  ]
+    .map(normalizePlatform)
+    .sort();
+  if (requiredPlatforms.length === 0) {
+    throw evidenceError(
+      "CC_GRAPH_STORE_EVIDENCE_INVALID",
+      "runtime manifest must declare required cutover platforms",
+    );
+  }
+  const entries = manifest.surfaces.flatMap((surface) =>
+    surface.entries
+      .filter((entry) => entry.cutoverStrategy === "migrate")
+      .map((entry) => {
+        const stores = [...entry.storeDispositions.migrate].sort();
+        const keyFor = (store) =>
+          `${surface.originSurface}\0${entry.id}\0${store}`;
+        const coveredStores = stores.filter((store) =>
+          availableStores.has(keyFor(store)),
+        );
+        const missingStores = stores.filter(
+          (store) => !availableStores.has(keyFor(store)),
+        );
+        const platformCoverage = stores.map((store) => {
+          const coveredPlatforms = [
+            ...new Set(
+              (availableStores.get(keyFor(store)) || []).map(
+                (receipt) => receipt.platform,
+              ),
+            ),
+          ].sort();
+          const missingPlatforms = requiredPlatforms.filter(
+            (platform) => !coveredPlatforms.includes(platform),
+          );
+          return Object.freeze({
+            store,
+            coveredPlatforms: Object.freeze(coveredPlatforms),
+            missingPlatforms: Object.freeze(missingPlatforms),
+            complete: missingPlatforms.length === 0,
+          });
+        });
+        const incompletePlatformStores = platformCoverage.filter(
+          (store) => !store.complete,
+        );
+        return Object.freeze({
+          surface: surface.originSurface,
+          entryId: entry.id,
+          stores: Object.freeze(stores),
+          coveredStores: Object.freeze(coveredStores),
+          missingStores: Object.freeze(missingStores),
+          platformCoverage: Object.freeze(platformCoverage),
+          incompletePlatformStores: Object.freeze(incompletePlatformStores),
+          complete:
+            missingStores.length === 0 && incompletePlatformStores.length === 0,
+        });
+      }),
+  );
+  const storeSlotCount = entries.reduce(
+    (count, entry) => count + entry.stores.length,
+    0,
+  );
+  const coveredStoreSlotCount = entries.reduce(
+    (count, entry) => count + entry.coveredStores.length,
+    0,
+  );
+  const completeStoreSlotCount = entries.reduce(
+    (count, entry) =>
+      count + entry.platformCoverage.filter((store) => store.complete).length,
+    0,
+  );
+  const platformStoreSlotCount = storeSlotCount * requiredPlatforms.length;
+  const coveredPlatformStoreSlotCount = entries.reduce(
+    (count, entry) =>
+      count +
+      entry.platformCoverage.reduce(
+        (storeCount, store) =>
+          storeCount +
+          store.coveredPlatforms.filter((platform) =>
+            requiredPlatforms.includes(platform),
+          ).length,
+        0,
+      ),
+    0,
+  );
+  return Object.freeze({
+    schema: "chainlesschain.graph-store-cutover-coverage/v1",
+    commitSha: [...commits][0] || null,
+    requiredPlatforms: Object.freeze(requiredPlatforms),
+    evidenceRecordCount: records.length,
+    migratableEntryCount: entries.length,
+    completeEntryCount: entries.filter((entry) => entry.complete).length,
+    storeSlotCount,
+    coveredStoreSlotCount,
+    missingStoreSlotCount: storeSlotCount - coveredStoreSlotCount,
+    completeStoreSlotCount,
+    incompletePlatformStoreSlotCount: storeSlotCount - completeStoreSlotCount,
+    platformStoreSlotCount,
+    coveredPlatformStoreSlotCount,
+    missingPlatformStoreSlotCount:
+      platformStoreSlotCount - coveredPlatformStoreSlotCount,
+    entries: Object.freeze(entries),
+  });
+}

package/src/lib/graph-kernel/trace-reducer.js

@@ -280,6 +280,12 @@ export function reduceGraphTrace(
     runId: state.id,
     throughSeq: ordered.at(-1)?.seq || 0,
     eventHeadHash: ordered.at(-1)?.hash || null,
+    originSurface: state.authority?.originSurface || null,
+    authoritySource: state.authority?.authoritySource || null,
+    authorityMode: state.authority?.authorityMode || null,
+    authorityGeneration: state.authority?.authorityGeneration || null,
+    writerId: state.authority?.writerId || null,
+    projectionVersion: state.authority?.projectionVersion || null,
     definitionId: definition.id,
     graphRevision: state.graphRevision,
     revisionDigest: state.revisionDigest,

package/src/lib/graph-kernel/trigger-adapter.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { MemoryRolloutStore } from "../app-server/rollout-store.js";
+import { createGraphAuthorityBinding } from "./authority.js";
 
 const JOURNAL_THREAD_ID = "scheduler-graph-dispatch";
 
@@ -61,6 +62,61 @@ export class SchedulerGraphTriggerAdapter {
     this.journal = journal;
   }
 
+  runtimeClaims() {
+    return Object.freeze({
+      originSurface: "scheduler",
+      surface: "scheduler",
+      execution: "real",
+      persistence: "durable",
+      isolated: true,
+      terminalEvidence: true,
+      authorityModes: Object.freeze(["canonical"]),
+      featureGated: true,
+    });
+  }
+
+  _recover(runId) {
+    try {
+      return this.kernel.recoverRun(runId);
+    } catch (error) {
+      if (error?.code !== "CC_GRAPH_STALE_WRITER") throw error;
+    }
+    const events = this.kernel.eventStore.read(runId);
+    const latest = events.at(-1);
+    const previous = [...events]
+      .reverse()
+      .find((event) => event.payload?.state?.authority)?.payload
+      .state.authority;
+    const writer = this.kernel.writerIdentity;
+    if (
+      !latest ||
+      !previous ||
+      Number(writer.authorityGeneration) <= Number(previous.authorityGeneration)
+    ) {
+      const error = new Error(
+        "scheduler recovery requires an explicitly higher Graph writer generation",
+      );
+      error.code = "CC_GRAPH_STALE_GENERATION";
+      throw error;
+    }
+    return this.kernel.recoverRun(runId, {
+      authority: createGraphAuthorityBinding({
+        ...previous,
+        logicalRunId: runId,
+        originSurface: "scheduler",
+        authorityMode: "canonical",
+        authoritySource: "graph_kernel",
+        authorityGeneration: writer.authorityGeneration,
+        writerId: writer.writerId,
+        writerLeaseId: writer.writerLeaseId,
+        writerLeaseExpiresAt: new Date(
+          this.kernel.now() + this.kernel.writerLeaseTtlMs,
+        ).toISOString(),
+        eventHead: latest.hash,
+      }),
+    });
+  }
+
   dispatch(occurrence, compiledGraph, options = {}) {
     const key = dispatchKey(occurrence);
     const digest = keyDigest(key);
@@ -72,7 +128,7 @@ export class SchedulerGraphTriggerAdapter {
       try {
         run = this.kernel.getRun(existing.runId);
       } catch {
-        run = this.kernel.recoverRun(existing.runId);
+        run = this._recover(existing.runId);
       }
       return Object.freeze({
         occurrenceStatus: "succeeded",
@@ -86,7 +142,7 @@ export class SchedulerGraphTriggerAdapter {
       .find((entry) => entry.phase === "pending");
     if (pending) {
       try {
-        const graphRun = this.kernel.recoverRun(pending.runId);
+        const graphRun = this._recover(pending.runId);
         if (graphRun.revisionDigest !== compiledGraph.revisionDigest) {
           const error = new Error(
             "pending scheduler dispatch is bound to a different GraphRevision",
@@ -127,6 +183,7 @@ export class SchedulerGraphTriggerAdapter {
       const graphRun = this.kernel.startRun(compiledGraph, {
         ...options,
         runId,
+        originSurface: "scheduler",
         occurrenceRef: {
           jobRevision: occurrence.jobRevision,
           occurrenceId: occurrence.occurrenceId || occurrence.idempotencyKey,
@@ -173,7 +230,7 @@ export class SchedulerGraphTriggerAdapter {
     try {
       graphRun = this.kernel.getRun(accepted.runId);
     } catch {
-      graphRun = this.kernel.recoverRun(accepted.runId);
+      graphRun = this._recover(accepted.runId);
     }
     return Object.freeze({
       occurrenceStatus: "succeeded",

package/src/lib/legacy-runtime-authority.js

@@ -0,0 +1,160 @@
+import { createRuntimeGraphCutoverAuthorityResolver } from "./graph-kernel/cutover-authority-resolver.js";
+import {
+  graphRuntimeSurfaceEntry,
+  loadGraphRuntimeSurfaceManifest,
+} from "./graph-kernel/runtime-surface-manifest.js";
+
+const AUTHORITY_MODES = new Set(["legacy", "shadow", "canonical"]);
+const ENTRYPOINTS = Object.freeze([
+  ["CLIAutonomousAgent.", "cli-legacy-autonomous"],
+  ["Orchestrator.", "cli-legacy-orchestrate"],
+]);
+const resolverCache = new Map();
+const runtimeManifest = loadGraphRuntimeSurfaceManifest();
+
+function authorityError(code, message, details = {}) {
+  const error = new Error(message);
+  error.name = "CLILegacyRuntimeAuthorityError";
+  error.code = code;
+  Object.assign(error, details);
+  return error;
+}
+
+function fallbackMode(env) {
+  const mode = String(env.CHAINLESSCHAIN_GRAPH_COWORK || "legacy")
+    .trim()
+    .toLowerCase();
+  if (!AUTHORITY_MODES.has(mode)) {
+    throw authorityError(
+      "CC_GRAPH_AUTHORITY_MODE_INVALID",
+      "CHAINLESSCHAIN_GRAPH_COWORK must be legacy, shadow, or canonical",
+    );
+  }
+  return mode;
+}
+
+function entryIdFor(entrypoint) {
+  const value = String(entrypoint || "");
+  return ENTRYPOINTS.find(([prefix]) => value.startsWith(prefix))?.[1];
+}
+
+function retirementContractFor(entryId) {
+  if (!entryId) return null;
+  const entry = graphRuntimeSurfaceEntry(
+    runtimeManifest,
+    "cowork",
+    entryId,
+  ).entry;
+  const replacementTargets = (entry.replacementEntryIds || []).map(
+    (replacementEntryId) => {
+      for (const surface of runtimeManifest.surfaces || []) {
+        const target = (surface.entries || []).find(
+          (candidate) => candidate.id === replacementEntryId,
+        );
+        if (!target) continue;
+        return Object.freeze({
+          entryId: target.id,
+          originSurface: surface.originSurface,
+          rolloutKey: target.rolloutKey,
+          entrypoints: Object.freeze([...(target.entrypoints || [])]),
+          recoveryEntrypoints: Object.freeze([
+            ...(target.recoveryEntrypoints || []),
+          ]),
+        });
+      }
+      return null;
+    },
+  );
+  return Object.freeze({
+    replacementEntrypoint: entry.replacementEntrypoint || null,
+    replacementEntryIds: Object.freeze([...(entry.replacementEntryIds || [])]),
+    historicalReadFunctions: Object.freeze([
+      ...(entry.historicalReadFunctions || []),
+    ]),
+    replacementTargets: Object.freeze(replacementTargets.filter(Boolean)),
+  });
+}
+
+export function cliLegacyRuntimeAuthorityMode(env = process.env, options = {}) {
+  const configured = fallbackMode(env);
+  const entryId = options.entryId;
+  if (!entryId) return configured;
+  let resolver = options.resolver;
+  if (!resolver) {
+    const key = `${entryId}\0${configured}\0${
+      env.CHAINLESSCHAIN_GRAPH_CUTOVER_STATE_DIR || ""
+    }`;
+    resolver = resolverCache.get(key);
+    if (!resolver) {
+      resolver = createRuntimeGraphCutoverAuthorityResolver({
+        env,
+        surface: "cowork",
+        entryId,
+        fallbackMode: configured,
+      });
+      resolverCache.set(key, resolver);
+    }
+  }
+  const resolved =
+    typeof resolver === "function"
+      ? resolver({ runKey: options.runKey, optIn: options.optIn === true })
+      : resolver.resolve({
+          runKey: options.runKey,
+          optIn: options.optIn === true,
+          fallbackMode: configured,
+        });
+  const mode = typeof resolved === "string" ? resolved : resolved?.mode;
+  if (!AUTHORITY_MODES.has(mode)) {
+    throw authorityError(
+      "CC_GRAPH_AUTHORITY_MODE_INVALID",
+      "CLI legacy runtime authority resolver returned an invalid mode",
+    );
+  }
+  return mode;
+}
+
+export function assertCLILegacyMutationAllowed(
+  entrypoint,
+  env = process.env,
+  options = {},
+) {
+  const entryId = options.entryId || entryIdFor(entrypoint);
+  const mode =
+    options.authorityMode ||
+    cliLegacyRuntimeAuthorityMode(env, { ...options, entryId });
+  if (
+    mode !== "canonical" &&
+    String(env.CHAINLESSCHAIN_CLI_LEGACY_READ_ONLY || "") !== "1"
+  ) {
+    return Object.freeze({
+      authorityMode: mode,
+      authoritySource:
+        mode === "shadow" ? "graph_kernel_shadow" : "legacy_runtime",
+      legacyReadOnly: false,
+    });
+  }
+  const retirementContract = retirementContractFor(entryId);
+  const replacementEntrypoint = retirementContract?.replacementEntrypoint;
+  throw authorityError(
+    "CC_CLI_LEGACY_RUNTIME_READ_ONLY",
+    `CLI legacy runtime is read-only; '${entrypoint}' must use ${replacementEntrypoint || "the canonical Graph Kernel entrypoint"}`,
+    {
+      entrypoint: String(entrypoint),
+      entryId,
+      replacementEntrypoint,
+      replacementEntryIds: retirementContract?.replacementEntryIds || [],
+      historicalReadFunctions:
+        retirementContract?.historicalReadFunctions || [],
+      replacementTargets: retirementContract?.replacementTargets || [],
+      authorityMode: "canonical",
+      authoritySource: "graph_kernel",
+    },
+  );
+}
+
+export function cliLegacyRuntimeReadOnly(env = process.env, options = {}) {
+  return (
+    cliLegacyRuntimeAuthorityMode(env, options) === "canonical" ||
+    String(env.CHAINLESSCHAIN_CLI_LEGACY_READ_ONLY || "") === "1"
+  );
+}