chainlesschain 0.166.6 → 0.166.9

package/src/lib/graph-kernel/adapters.js

@@ -1,4 +1,9 @@
 import { graphDigest } from "./compiler.js";
+import {
+  GRAPH_AUTHORITY_MODES,
+  GraphRunAuthorityRegistry,
+  createGraphAuthorityBinding,
+} from "./authority.js";
 
 export const GRAPH_RUNTIME_SURFACES = Object.freeze([
   "cli_team",
@@ -22,8 +27,16 @@ function contractError(code, message, details = {}) {
 
 export function validateRuntimeClaims(claims) {
   const errors = [];
-  if (!GRAPH_RUNTIME_SURFACES.includes(claims?.surface)) {
-    errors.push("surface must identify a known execution plane");
+  const originSurface = claims?.originSurface || claims?.surface;
+  if (!GRAPH_RUNTIME_SURFACES.includes(originSurface)) {
+    errors.push("originSurface must identify a known execution plane");
+  }
+  if (
+    claims?.originSurface &&
+    claims?.surface &&
+    claims.originSurface !== claims.surface
+  ) {
+    errors.push("surface compatibility alias must match originSurface");
   }
   if (!new Set(["real", "simulated", "planned"]).has(claims?.execution)) {
     errors.push("execution must be real, simulated, or planned");
@@ -37,7 +50,21 @@ export function validateRuntimeClaims(claims) {
   if (typeof claims?.terminalEvidence !== "boolean") {
     errors.push("terminalEvidence must be explicit");
   }
-  if (claims?.surface === "browser") {
+  if (
+    !Array.isArray(claims?.authorityModes) ||
+    claims.authorityModes.length === 0 ||
+    claims.authorityModes.some((mode) => !GRAPH_AUTHORITY_MODES.includes(mode))
+  ) {
+    errors.push(
+      "authorityModes must declare supported per-run authority modes",
+    );
+  }
+  if (claims?.authoritative === true) {
+    errors.push(
+      "authoritative is not a surface claim; authority must be bound per GraphRun",
+    );
+  }
+  if (originSurface === "browser") {
     if (
       claims.persistence !== "non_durable" &&
       claims.restartHydration !== true
@@ -49,13 +76,13 @@ export function validateRuntimeClaims(claims) {
     }
   }
   if (
-    claims?.authoritative === true &&
+    claims?.authorityModes?.includes("canonical") &&
     (claims.execution !== "real" ||
       claims.persistence !== "durable" ||
       claims.terminalEvidence !== true)
   ) {
     errors.push(
-      "authoritative runtime requires real durable evidence-bound execution",
+      "canonical authority requires real durable evidence-bound execution",
     );
   }
   return Object.freeze({
@@ -65,9 +92,9 @@ export function validateRuntimeClaims(claims) {
 }
 
 export class GraphRuntimeAdapterRegistry {
-  constructor() {
+  constructor({ authorityRegistry = new GraphRunAuthorityRegistry() } = {}) {
     this.adapters = new Map();
-    this.authoritativeSurface = null;
+    this.authorityRegistry = authorityRegistry;
   }
 
   register(adapter) {
@@ -78,6 +105,8 @@ export class GraphRuntimeAdapterRegistry {
       );
     }
     const claims = clone(adapter.runtimeClaims());
+    claims.originSurface ||= claims.surface;
+    claims.surface ||= claims.originSurface;
     const validation = validateRuntimeClaims(claims);
     if (!validation.valid) {
       throw contractError(
@@ -86,23 +115,17 @@ export class GraphRuntimeAdapterRegistry {
         { errors: validation.errors },
       );
     }
-    if (claims.authoritative) {
-      if (
-        this.authoritativeSurface &&
-        this.authoritativeSurface !== claims.surface
-      ) {
-        throw contractError(
-          "CC_GRAPH_MULTIPLE_AUTHORITATIVE_WRITERS",
-          "only one Graph Kernel adapter may write authoritative run state",
-        );
-      }
-      this.authoritativeSurface = claims.surface;
+    if (this.adapters.has(claims.originSurface)) {
+      throw contractError(
+        "CC_GRAPH_ADAPTER_ALREADY_REGISTERED",
+        `graph runtime adapter is already registered: ${claims.originSurface}`,
+      );
     }
-    this.adapters.set(claims.surface, {
+    this.adapters.set(claims.originSurface, {
       adapter,
       claims: Object.freeze(claims),
     });
-    return this.claims(claims.surface);
+    return this.claims(claims.originSurface);
   }
 
   claims(surface) {
@@ -121,6 +144,56 @@ export class GraphRuntimeAdapterRegistry {
   adapter(surface) {
     return this.adapters.get(surface)?.adapter || null;
   }
+
+  bindRunAuthority(originSurface, input, options = {}) {
+    const claims = this.claims(originSurface);
+    if (!claims) {
+      throw contractError(
+        "CC_GRAPH_ADAPTER_NOT_REGISTERED",
+        `graph runtime adapter is not registered: ${originSurface}`,
+      );
+    }
+    const authorityMode = String(input?.authorityMode || "");
+    if (!claims.authorityModes.includes(authorityMode)) {
+      throw contractError(
+        "CC_GRAPH_AUTHORITY_MODE_UNSUPPORTED",
+        `${originSurface} does not support ${authorityMode} authority`,
+      );
+    }
+    if (originSurface === "browser" && authorityMode === "canonical") {
+      throw contractError(
+        "CC_GRAPH_BROWSER_NON_DURABLE",
+        "browser runtime cannot acquire canonical authority while non-durable",
+      );
+    }
+    const authoritySource =
+      authorityMode === "canonical"
+        ? "graph_kernel"
+        : authorityMode === "shadow"
+          ? "graph_kernel_shadow"
+          : "legacy_runtime";
+    const binding = createGraphAuthorityBinding({
+      ...input,
+      originSurface,
+      authorityMode,
+      authoritySource,
+    });
+    return this.authorityRegistry.bind(binding, options);
+  }
+
+  runAuthority(logicalRunId) {
+    return this.authorityRegistry.get(logicalRunId);
+  }
+
+  transitionSurface(originSurface, stage) {
+    if (!this.adapters.has(originSurface)) {
+      throw contractError(
+        "CC_GRAPH_ADAPTER_NOT_REGISTERED",
+        `graph runtime adapter is not registered: ${originSurface}`,
+      );
+    }
+    return this.authorityRegistry.transition(originSurface, stage);
+  }
 }
 
 function terminalProjection(value) {

package/src/lib/graph-kernel/authority.js

@@ -0,0 +1,324 @@
+export const GRAPH_AUTHORITY_SCHEMA = "chainlesschain.graph-authority/v1";
+export const GRAPH_PROJECTION_VERSION = 1;
+export const GRAPH_AUTHORITY_MODES = Object.freeze([
+  "legacy",
+  "shadow",
+  "canonical",
+]);
+export const GRAPH_CUTOVER_STAGES = Object.freeze([
+  "legacy",
+  "shadow",
+  "canary",
+  "canonical",
+  "legacy_read_only",
+]);
+
+const AUTHORITY_SOURCES = new Set([
+  "legacy_runtime",
+  "graph_kernel_shadow",
+  "graph_kernel",
+]);
+
+function authorityError(code, message, details = {}) {
+  const error = new Error(message);
+  error.name = "GraphAuthorityError";
+  error.code = code;
+  Object.assign(error, details);
+  return error;
+}
+
+function clone(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+
+function identifier(value, label) {
+  const output = String(value || "").trim();
+  if (!/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,159}$/u.test(output)) {
+    throw authorityError("CC_GRAPH_AUTHORITY_INVALID", `${label} is invalid`, {
+      field: label,
+    });
+  }
+  return output;
+}
+
+function eventHead(value) {
+  if (value == null) return null;
+  const output = String(value);
+  if (!/^sha256:[a-f0-9]{64}$/u.test(output)) {
+    throw authorityError(
+      "CC_GRAPH_AUTHORITY_INVALID",
+      "eventHead must be a sha256 digest or null",
+      { field: "eventHead" },
+    );
+  }
+  return output;
+}
+
+function leaseExpiry(value) {
+  if (value == null) return null;
+  const output = String(value);
+  const milliseconds = Date.parse(output);
+  if (!Number.isFinite(milliseconds)) {
+    throw authorityError(
+      "CC_GRAPH_AUTHORITY_INVALID",
+      "writerLeaseExpiresAt must be an ISO timestamp",
+      { field: "writerLeaseExpiresAt" },
+    );
+  }
+  return new Date(milliseconds).toISOString();
+}
+
+export function createGraphAuthorityBinding(input = {}) {
+  const authorityMode = String(input.authorityMode || "").trim();
+  if (!GRAPH_AUTHORITY_MODES.includes(authorityMode)) {
+    throw authorityError(
+      "CC_GRAPH_AUTHORITY_INVALID",
+      "authorityMode must be legacy, shadow, or canonical",
+      { field: "authorityMode" },
+    );
+  }
+  const authoritySource = String(input.authoritySource || "").trim();
+  if (!AUTHORITY_SOURCES.has(authoritySource)) {
+    throw authorityError(
+      "CC_GRAPH_AUTHORITY_INVALID",
+      "authoritySource is not recognized",
+      { field: "authoritySource" },
+    );
+  }
+  if (
+    (authorityMode === "canonical" && authoritySource !== "graph_kernel") ||
+    (authorityMode === "shadow" && authoritySource !== "graph_kernel_shadow") ||
+    (authorityMode === "legacy" && authoritySource !== "legacy_runtime")
+  ) {
+    throw authorityError(
+      "CC_GRAPH_AUTHORITY_SOURCE_MISMATCH",
+      "authoritySource does not match authorityMode",
+    );
+  }
+  const authorityGeneration = Number(input.authorityGeneration);
+  if (!Number.isSafeInteger(authorityGeneration) || authorityGeneration < 1) {
+    throw authorityError(
+      "CC_GRAPH_AUTHORITY_INVALID",
+      "authorityGeneration must be a positive safe integer",
+      { field: "authorityGeneration" },
+    );
+  }
+  const projectionVersion = Number(
+    input.projectionVersion ?? GRAPH_PROJECTION_VERSION,
+  );
+  if (!Number.isSafeInteger(projectionVersion) || projectionVersion < 1) {
+    throw authorityError(
+      "CC_GRAPH_AUTHORITY_INVALID",
+      "projectionVersion must be a positive safe integer",
+      { field: "projectionVersion" },
+    );
+  }
+  const binding = {
+    schema: GRAPH_AUTHORITY_SCHEMA,
+    logicalRunId: identifier(input.logicalRunId, "logicalRunId"),
+    originSurface: identifier(input.originSurface, "originSurface"),
+    authorityMode,
+    authoritySource,
+    authorityGeneration,
+    writerId: identifier(input.writerId, "writerId"),
+    writerLeaseId: identifier(input.writerLeaseId, "writerLeaseId"),
+    writerLeaseExpiresAt: leaseExpiry(input.writerLeaseExpiresAt),
+    eventHead: eventHead(input.eventHead),
+    projectionVersion,
+  };
+  if (authorityMode === "canonical" && !binding.writerLeaseExpiresAt) {
+    throw authorityError(
+      "CC_GRAPH_WRITER_LEASE_REQUIRED",
+      "canonical authority requires an expiring writer lease",
+    );
+  }
+  return Object.freeze(binding);
+}
+
+export function assertGraphAuthorityWriter(
+  binding,
+  writer,
+  {
+    now = Date.now(),
+    expectedEventHead = undefined,
+    requireCanonical = true,
+  } = {},
+) {
+  const current = createGraphAuthorityBinding(binding);
+  if (requireCanonical && current.authorityMode !== "canonical") {
+    throw authorityError(
+      "CC_GRAPH_NON_CANONICAL_WRITER",
+      "only canonical authority may mutate canonical Graph state",
+    );
+  }
+  if (
+    current.authoritySource !== writer?.authoritySource ||
+    current.authorityGeneration !== Number(writer?.authorityGeneration) ||
+    current.writerId !== writer?.writerId ||
+    current.writerLeaseId !== writer?.writerLeaseId
+  ) {
+    throw authorityError(
+      "CC_GRAPH_STALE_WRITER",
+      "writer identity, generation, or lease does not own this GraphRun",
+      {
+        authorityGeneration: current.authorityGeneration,
+        writerId: current.writerId,
+      },
+    );
+  }
+  if (
+    current.writerLeaseExpiresAt &&
+    Date.parse(current.writerLeaseExpiresAt) <= Number(now)
+  ) {
+    throw authorityError(
+      "CC_GRAPH_WRITER_LEASE_EXPIRED",
+      "GraphRun writer lease has expired",
+    );
+  }
+  if (
+    expectedEventHead !== undefined &&
+    current.eventHead !== expectedEventHead
+  ) {
+    throw authorityError(
+      "CC_GRAPH_EVENT_HEAD_CONFLICT",
+      "GraphRun event head changed before mutation",
+      { expectedEventHead, actualEventHead: current.eventHead },
+    );
+  }
+  return current;
+}
+
+const CUTOVER_TRANSITIONS = Object.freeze({
+  legacy: new Set(["shadow"]),
+  shadow: new Set(["legacy", "canary"]),
+  canary: new Set(["shadow", "canonical"]),
+  canonical: new Set(["canary", "legacy_read_only"]),
+  legacy_read_only: new Set(["canonical"]),
+});
+
+export function assertGraphCutoverTransition(from, to) {
+  if (
+    !GRAPH_CUTOVER_STAGES.includes(from) ||
+    !GRAPH_CUTOVER_STAGES.includes(to)
+  ) {
+    throw authorityError(
+      "CC_GRAPH_CUTOVER_STAGE_INVALID",
+      "Graph cutover stage is invalid",
+    );
+  }
+  if (from === to) return to;
+  if (!CUTOVER_TRANSITIONS[from].has(to)) {
+    throw authorityError(
+      "CC_GRAPH_CUTOVER_TRANSITION_INVALID",
+      `Graph cutover cannot transition from ${from} to ${to}`,
+    );
+  }
+  return to;
+}
+
+export class GraphRunAuthorityRegistry {
+  constructor({ now = Date.now } = {}) {
+    this.now = now;
+    this.runs = new Map();
+    this.cutovers = new Map();
+  }
+
+  bind(input, { replace = false } = {}) {
+    const next = createGraphAuthorityBinding(input);
+    const previous = this.runs.get(next.logicalRunId);
+    if (previous) {
+      if (next.authorityGeneration < previous.authorityGeneration) {
+        throw authorityError(
+          "CC_GRAPH_STALE_GENERATION",
+          "authority generation cannot move backwards",
+        );
+      }
+      if (next.authorityGeneration === previous.authorityGeneration) {
+        const sameOwner =
+          next.authoritySource === previous.authoritySource &&
+          next.authorityMode === previous.authorityMode &&
+          next.writerId === previous.writerId &&
+          next.writerLeaseId === previous.writerLeaseId;
+        if (!sameOwner) {
+          throw authorityError(
+            "CC_GRAPH_MULTIPLE_AUTHORITATIVE_WRITERS",
+            "one logical GraphRun cannot have two writers in one generation",
+          );
+        }
+      } else {
+        if (!replace) {
+          throw authorityError(
+            "CC_GRAPH_AUTHORITY_REPLACEMENT_REQUIRED",
+            "a higher writer generation requires an explicit replacement",
+          );
+        }
+        if (next.eventHead !== previous.eventHead) {
+          throw authorityError(
+            "CC_GRAPH_EVENT_HEAD_CONFLICT",
+            "writer replacement must bind the exact persisted event head",
+          );
+        }
+      }
+    }
+    this.runs.set(next.logicalRunId, next);
+    return this.get(next.logicalRunId);
+  }
+
+  assertWriter(logicalRunId, writer, options = {}) {
+    const current = this.runs.get(identifier(logicalRunId, "logicalRunId"));
+    if (!current) {
+      throw authorityError(
+        "CC_GRAPH_AUTHORITY_NOT_FOUND",
+        "GraphRun has no registered authority",
+      );
+    }
+    return assertGraphAuthorityWriter(current, writer, {
+      now: this.now(),
+      ...options,
+    });
+  }
+
+  advanceEventHead(
+    logicalRunId,
+    writer,
+    { expectedEventHead, eventHead: next },
+  ) {
+    const current = this.assertWriter(logicalRunId, writer, {
+      expectedEventHead,
+    });
+    const updated = createGraphAuthorityBinding({
+      ...current,
+      eventHead: next,
+    });
+    this.runs.set(current.logicalRunId, updated);
+    return this.get(current.logicalRunId);
+  }
+
+  transition(originSurface, to) {
+    const surface = identifier(originSurface, "originSurface");
+    const from = this.cutovers.get(surface) || "legacy";
+    this.cutovers.set(surface, assertGraphCutoverTransition(from, to));
+    return Object.freeze({ originSurface: surface, from, to });
+  }
+
+  cutoverStage(originSurface) {
+    return (
+      this.cutovers.get(identifier(originSurface, "originSurface")) || "legacy"
+    );
+  }
+
+  get(logicalRunId) {
+    const value = this.runs.get(identifier(logicalRunId, "logicalRunId"));
+    return value ? Object.freeze(clone(value)) : null;
+  }
+
+  list() {
+    return Object.freeze(
+      [...this.runs.values()]
+        .map(clone)
+        .sort((left, right) =>
+          left.logicalRunId.localeCompare(right.logicalRunId),
+        ),
+    );
+  }
+}

package/src/lib/graph-kernel/compiler.js

@@ -1,19 +1,14 @@
 import { createHash } from "node:crypto";
-import { readFileSync } from "node:fs";
+import graphProtocolSchema from "../../generated/cc-agent-protocol.schema.json" with { type: "json" };
 import { validate } from "../json-schema-validate.js";
 
-const graphProtocolSchema = JSON.parse(
-  readFileSync(
-    new URL("../../generated/cc-agent-protocol.schema.json", import.meta.url),
-    "utf8",
-  ),
-);
-
 export const GRAPH_DEFINITION_VERSION = 1;
 export const GRAPH_DEFINITION_MIN_VERSION = Math.max(
   0,
   GRAPH_DEFINITION_VERSION - 1,
 );
+export const GRAPH_DEFINITION_MIGRATION_EVIDENCE_SCHEMA =
+  "chainlesschain.graph-definition-migration/v1";
 export const GRAPH_COMPILE_ERROR = "CC_GRAPH_COMPILE_FAILED";
 
 const compiledGraphs = new WeakSet();
@@ -1292,6 +1287,22 @@ export function compileGraphDefinition(input, options = {}) {
     definition,
     `cc.graph.definition/${definition.schemaVersion}`,
   );
+  const migrationBackup =
+    migrated.migratedFrom == null ? null : deepFreeze(stableValue(input));
+  const definitionMigration =
+    migrationBackup == null
+      ? null
+      : deepFreeze({
+          schema: GRAPH_DEFINITION_MIGRATION_EVIDENCE_SCHEMA,
+          fromVersion: migrated.migratedFrom,
+          toVersion: definition.schemaVersion,
+          revisionDigest,
+          backupDefinition: migrationBackup,
+          rollbackDigest: graphDigest(
+            migrationBackup,
+            `cc.graph.definition-backup/${migrated.migratedFrom}`,
+          ),
+        });
   const compiled = {
     schema: "chainlesschain.compiled-graph/v1",
     schemaVersion: definition.schemaVersion,
@@ -1300,6 +1311,7 @@ export function compileGraphDefinition(input, options = {}) {
     revision: definition.revision,
     revisionDigest,
     migratedFrom: migrated.migratedFrom,
+    definitionMigration,
     nodes: deepFreeze(
       Object.fromEntries([...nodes].map(([id, value]) => [id, value])),
     ),
@@ -1376,25 +1388,59 @@ export function assertCompiledGraph(value) {
 }
 
 export function migrateGraphDefinition(input, options = {}) {
-  const { definition, migratedFrom } = migrateDefinition(input, options);
-  const compiled = compileGraphDefinition(definition, options);
-  const backupDefinition =
-    migratedFrom == null ? null : deepFreeze(stableValue(input));
+  const compiled = compileGraphDefinition(input, options);
+  const migration = compiled.definitionMigration;
   return Object.freeze({
     dryRun: options.dryRun !== false,
-    fromVersion: migratedFrom ?? definition.schemaVersion,
+    fromVersion: migration?.fromVersion ?? compiled.schemaVersion,
     toVersion: compiled.schemaVersion,
     definition: compiled.definition,
     revisionDigest: compiled.revisionDigest,
-    backupRequired: migratedFrom != null,
+    backupRequired: migration != null,
+    backupDefinition: migration?.backupDefinition || null,
+    rollbackDigest: migration?.rollbackDigest || null,
+  });
+}
+
+export function validateGraphDefinitionMigrationEvidence(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    const error = new TypeError(
+      "graph definition migration evidence is required",
+    );
+    error.code = "CC_GRAPH_MIGRATION_EVIDENCE_INVALID";
+    throw error;
+  }
+  if (
+    value.schema !== GRAPH_DEFINITION_MIGRATION_EVIDENCE_SCHEMA ||
+    Number(value.fromVersion) !== GRAPH_DEFINITION_VERSION - 1 ||
+    Number(value.toVersion) !== GRAPH_DEFINITION_VERSION ||
+    !/^sha256:[a-f0-9]{64}$/u.test(String(value.revisionDigest || ""))
+  ) {
+    const error = new TypeError(
+      "graph definition migration evidence has an invalid schema or version",
+    );
+    error.code = "CC_GRAPH_MIGRATION_EVIDENCE_INVALID";
+    throw error;
+  }
+  const backupDefinition = restoreGraphDefinitionBackup(
+    value.backupDefinition,
+    value.rollbackDigest,
+  );
+  const replay = compileGraphDefinition(backupDefinition);
+  if (replay.revisionDigest !== value.revisionDigest) {
+    const error = new TypeError(
+      "graph definition migration replay does not match its canonical revision",
+    );
+    error.code = "CC_GRAPH_MIGRATION_REPLAY_MISMATCH";
+    throw error;
+  }
+  return deepFreeze({
+    schema: GRAPH_DEFINITION_MIGRATION_EVIDENCE_SCHEMA,
+    fromVersion: GRAPH_DEFINITION_VERSION - 1,
+    toVersion: GRAPH_DEFINITION_VERSION,
+    revisionDigest: value.revisionDigest,
     backupDefinition,
-    rollbackDigest:
-      backupDefinition == null
-        ? null
-        : graphDigest(
-            backupDefinition,
-            `cc.graph.definition-backup/${migratedFrom}`,
-          ),
+    rollbackDigest: value.rollbackDigest,
   });
 }