chainlesschain 0.166.6 → 0.166.9

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/interaction-adapter.js

@@ -205,6 +205,7 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
         // null (the default for plain questions) → no binding check, unchanged.
         binding: options.binding || null,
         bindingType: options.bindingType || null,
+        requireBinding: options.requireBinding === true,
       });
 
       if (approvalRequest) {
@@ -253,6 +254,7 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
         // Approval binding pass-through: a permission-gate producer supplies
         // it; plain questions never carry one (message stays byte-identical).
         ...(options.binding ? { binding: options.binding } : {}),
+        ...(options.requireBinding === true ? { requireBinding: true } : {}),
       },
     );
   }
@@ -290,6 +292,45 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
     return answer === "true" || answer === "yes" || answer === "y";
   }
 
+  /**
+   * Structured approval variant used by Desktop/WebSocket hosts. Unlike the
+   * legacy boolean askConfirm path, this preserves the canonical decision
+   * lifetime and requires the trusted host to echo the exact request binding.
+   */
+  async askApproval(question, options = {}) {
+    const {
+      binding = null,
+      default: dflt = false,
+      approval = {},
+      ...extra
+    } = options || {};
+    const answer = await this._ask(
+      "confirm",
+      question,
+      { default: dflt, approval, ...extra },
+      binding ? { binding, requireBinding: true } : {},
+    );
+    const candidate =
+      answer?.decision && typeof answer.decision === "object"
+        ? answer.decision
+        : answer;
+    if (
+      candidate &&
+      typeof candidate === "object" &&
+      [
+        "acceptOnce",
+        "acceptForTurn",
+        "acceptForSession",
+        "decline",
+        "cancel",
+      ].includes(candidate.kind)
+    ) {
+      return candidate;
+    }
+    if (answer === true) return { kind: "acceptOnce" };
+    return { kind: "decline" };
+  }
+
   /**
    * Agent-core AskUserQuestion transport for Desktop/WebSocket consumers.
    * It uses the same pending map and `session-answer` resolver as MCP
@@ -369,7 +410,7 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
    * Resolves the corresponding pending promise.
    */
   resolveAnswer(requestId, answer, binding = null) {
-    this._resolvePending(requestId, answer, "question", binding);
+    return this._resolvePending(requestId, answer, "question", binding);
   }
 
   /**
@@ -441,7 +482,7 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
   }
 
   resolveHostTool(requestId, payload) {
-    this._resolvePending(requestId, payload, "host-tool");
+    return this._resolvePending(requestId, payload, "host-tool");
   }
 
   rejectAllPending(reason = createAbortError("Interaction interrupted")) {
@@ -549,7 +590,7 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
   ) {
     const pending = this._pending.get(requestId);
     if (!pending) {
-      return;
+      return Object.freeze({ settled: false, reason: "not_pending" });
     }
     // Kind guard: a question-answer must not settle a host-tool request (or
     // vice versa). On a mismatch, IGNORE the message — leave the request pending
@@ -559,7 +600,7 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
     // value). Backward-compatible: callers passing no expectedKind, and
     // pre-kind pending entries, behave exactly as before.
     if (expectedKind && pending.kind && pending.kind !== expectedKind) {
-      return;
+      return Object.freeze({ settled: false, reason: "kind_mismatch" });
     }
 
     // Approval-binding guard (authority §"权限来源"): if this request was raised
@@ -572,17 +613,18 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
       pending.bindingType === "interaction" &&
       !sameInteractionBinding(pending.binding, incomingBinding)
     ) {
-      return;
+      return Object.freeze({ settled: false, reason: "binding_mismatch" });
     }
 
     let effective = payload;
     if (
       pending.bindingType !== "interaction" &&
       pending.binding &&
-      incomingBinding &&
-      !verifyApprovalBinding(pending.binding, incomingBinding)
+      ((pending.requireBinding && !incomingBinding) ||
+        (incomingBinding &&
+          !verifyApprovalBinding(pending.binding, incomingBinding)))
     ) {
-      effective = false;
+      effective = pending.requireBinding ? { kind: "decline" } : false;
     }
 
     this._pending.delete(requestId);
@@ -594,13 +636,23 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
         effective === true ||
         effective === "true" ||
         effective === "yes" ||
-        effective === "y";
+        effective === "y" ||
+        ["acceptOnce", "acceptForTurn", "acceptForSession"].includes(
+          effective?.kind || effective?.decision?.kind,
+        );
       this._notifyPendingApproval("approval.settled", {
         requestId,
         reason: normalizedApproval ? "approved" : "denied",
       });
     }
     pending.resolve(effective);
+    return Object.freeze({
+      settled: true,
+      reason:
+        effective !== payload && pending.requireBinding
+          ? "binding_mismatch_denied"
+          : "resolved",
+    });
   }
 }