@cassiomc1/forgeloop 1.12.0 → 1.14.0

package/src/core/build-script.js

@@ -0,0 +1,151 @@
+function quotedValue(text, start) {
+  const quote = text[start];
+  let value = "";
+  let escaped = false;
+  for (let index = start + 1; index < text.length; index += 1) {
+    const character = text[index];
+    if (escaped) {
+      value += character;
+      escaped = false;
+    } else if (character === "\\") {
+      escaped = true;
+    } else if (character === quote) {
+      return { value, next: index + 1 };
+    } else {
+      value += character;
+    }
+  }
+  return null;
+}
+
+function bracketEnd(text, start) {
+  const marker = text.slice(start).match(/^\[(=*)\[/u);
+  if (!marker) return null;
+  const closing = `]${marker[1]}]`;
+  const end = text.indexOf(closing, start + marker[0].length);
+  return end < 0 ? null : { next: end + closing.length };
+}
+
+function maskRange(text, start, end) {
+  return text.slice(start, end).replace(/[^\n\r]/gu, " ");
+}
+
+function skipHashComment(text, start) {
+  const bracket = bracketEnd(text, start + 1);
+  if (text[start + 1] === "[" && bracket) return bracket.next;
+  const lineEnd = text.slice(start).search(/[\n\r]/u);
+  return lineEnd < 0 ? text.length : start + lineEnd;
+}
+
+function skipBuildToken(text, start) {
+  if (text[start] === "#") return { next: skipHashComment(text, start) };
+  if (text[start] === "\"" || text[start] === "'") {
+    const quoted = quotedValue(text, start);
+    return quoted ? { next: quoted.next } : null;
+  }
+  const bracket = bracketEnd(text, start);
+  return bracket ? { next: bracket.next } : { next: start + 1 };
+}
+
+export function maskBuildScript(text) {
+  if (typeof text !== "string") return null;
+  let result = "";
+  for (let index = 0; index < text.length;) {
+    const step = skipBuildToken(text, index);
+    if (!step) return null;
+    result += step.next === index + 1
+      ? text[index]
+      : maskRange(text, index, step.next);
+    index = step.next;
+  }
+  return result;
+}
+
+function callEnd(text, open) {
+  let depth = 1;
+  for (let index = open + 1; index < text.length; index += 1) {
+    const character = text[index];
+    const step = skipBuildToken(text, index);
+    if (!step) return null;
+    if (step.next !== index + 1) {
+      index = step.next - 1;
+      continue;
+    }
+    if (character === "(") depth += 1;
+    else if (character === ")") {
+      depth -= 1;
+      if (depth === 0) return index;
+    }
+  }
+  return null;
+}
+
+export function extractBuildCalls(text, names, { caseInsensitive = false } = {}) {
+  if (typeof text !== "string" || !Array.isArray(names)) return null;
+  const wanted = new Set(names.map((name) => caseInsensitive ? name.toLowerCase() : name));
+  const calls = [];
+  for (let index = 0; index < text.length;) {
+    const step = skipBuildToken(text, index);
+    if (!step) return null;
+    if (step.next !== index + 1) {
+      index = step.next;
+      continue;
+    }
+    const name = text.slice(index).match(/^[A-Za-z_][A-Za-z0-9_]*/u)?.[0];
+    if (!name || !wanted.has(caseInsensitive ? name.toLowerCase() : name)) {
+      index += name?.length ?? 1;
+      continue;
+    }
+    let open = index + name.length;
+    while (/\s/u.test(text[open] ?? "")) open += 1;
+    if (text[open] !== "(") {
+      index += name.length;
+      continue;
+    }
+    const close = callEnd(text, open);
+    if (close === null) return null;
+    calls.push({ name, body: text.slice(open + 1, close) });
+    index = close + 1;
+  }
+  return calls;
+}
+
+function splitBuildArguments(text) {
+  const parts = [];
+  let start = 0;
+  const depths = { "(": 0, "[": 0, "{": 0 };
+  for (let index = 0; index < text.length;) {
+    const step = skipBuildToken(text, index);
+    if (!step) return null;
+    if (step.next !== index + 1) {
+      index = step.next;
+      continue;
+    }
+    const character = text[index];
+    if (character === "(" || character === "[" || character === "{") depths[character] += 1;
+    if (character === ")" || character === "]" || character === "}") {
+      const opening = character === ")" ? "(" : character === "]" ? "[" : "{";
+      depths[opening] -= 1;
+      if (depths[opening] < 0) return null;
+    }
+    if (character === "," && Object.values(depths).every((depth) => depth === 0)) {
+      parts.push(text.slice(start, index).trim());
+      start = index + 1;
+    }
+    index += 1;
+  }
+  if (Object.values(depths).some((depth) => depth !== 0)) return null;
+  parts.push(text.slice(start).trim());
+  return parts.filter(Boolean);
+}
+
+export function quotedBuildArguments(text) {
+  const parts = splitBuildArguments(text);
+  if (!parts) return null;
+  return parts.flatMap((part) => {
+    const value = part.length >= 2 && (part[0] === "\"" || part[0] === "'")
+      ? quotedValue(part, 0)
+      : null;
+    return value && value.next === part.length ? [value.value] : [];
+  });
+}

package/src/core/c-cpp-project.js

@@ -0,0 +1,143 @@
+import { createLanguageProject, C_SOURCE_EXTENSIONS, CPP_SOURCE_EXTENSIONS, pathBelongsToRoot, portablePath } from "./multi-language-project.js";
+import { extractBuildCalls, maskBuildScript, quotedBuildArguments } from "./build-script.js";
+
+function invalidNative() {
+  return {
+    valid: false,
+    c: false,
+    cpp: false,
+    make: false,
+  };
+}
+
+function nativeLanguageTokens(text) {
+  const tokens = text.toUpperCase().match(/\b(?:CXX|CPP|C)\b/gu) ?? [];
+  return {
+    c: tokens.includes("C"),
+    cpp: tokens.some((language) => language === "CXX" || language === "CPP"),
+  };
+}
+
+function nativeLanguagesFromCMake(text) {
+  const result = { c: false, cpp: false };
+  const calls = extractBuildCalls(text, ["project", "enable_language"], { caseInsensitive: true });
+  if (!calls) return result;
+  for (const call of calls) {
+    const body = maskBuildScript(call.body);
+    if (body === null) continue;
+    if (call.name.toLowerCase() === "enable_language") {
+      const languages = nativeLanguageTokens(body);
+      result.c ||= languages.c;
+      result.cpp ||= languages.cpp;
+      continue;
+    }
+    const explicit = body.match(/\blanguages?\b([\s\S]*)/iu)?.[1]
+      ?? body.match(/^\s*[^\s]+\s+((?:C|CXX|CPP)\b[\s\S]*)/iu)?.[1]
+      ?? "";
+    const languages = nativeLanguageTokens(explicit);
+    result.c ||= languages.c;
+    result.cpp ||= languages.cpp;
+  }
+  return result;
+}
+
+export function parseCMake(text) {
+  if (typeof text !== "string" || text.length > 1024 * 1024 || /\r(?!\n)/u.test(text)) return invalidNative();
+  const source = maskBuildScript(text);
+  if (source === null) return invalidNative();
+  const languages = nativeLanguagesFromCMake(text);
+  const hasProject = /\bproject\s*\(/iu.test(source);
+  const hasLanguage = /\benable_language\s*\(/iu.test(source);
+  return { valid: hasProject || hasLanguage, ...languages, make: false };
+}
+
+export function parseMeson(text) {
+  if (typeof text !== "string" || text.length > 1024 * 1024 || /\r(?!\n)/u.test(text)) return invalidNative();
+  const calls = extractBuildCalls(text, ["project", "add_languages"]);
+  if (!calls || calls.length === 0) return invalidNative();
+  const languageValues = calls.flatMap((call) => {
+    const values = quotedBuildArguments(call.body) ?? [];
+    return call.name === "project" ? values.slice(1) : values;
+  });
+  return {
+    valid: true,
+    c: languageValues.some((value) => value.toLowerCase() === "c"),
+    cpp: languageValues.some((value) => ["cpp", "cxx"].includes(value.toLowerCase())),
+    make: false,
+  };
+}
+
+export function parseBazelNative(text) {
+  if (typeof text !== "string" || text.length > 1024 * 1024 || /\r(?!\n)/u.test(text)) return invalidNative();
+  const source = maskBuildScript(text);
+  const hasNativeRule = source !== null && /\b(?:cc_|c_)(?:library|binary|test|shared_library|static_library)\s*\(/u.test(source);
+  return { valid: hasNativeRule, c: false, cpp: false, make: false };
+}
+
+export function parseMakefile(text) {
+  if (typeof text !== "string" || text.length > 1024 * 1024 || /\r(?!\n)/u.test(text)) return invalidNative();
+  return { valid: true, c: false, cpp: false, make: true };
+}
+
+function sourceEvidence(sourceFiles, targetRoot, projectRoot, projectRoots) {
+  const c = sourceFiles.some((file) => C_SOURCE_EXTENSIONS.has(file.extension)
+    && pathBelongsToRoot(portablePath(targetRoot, file.path), projectRoot, projectRoots));
+  const cpp = sourceFiles.some((file) => CPP_SOURCE_EXTENSIONS.has(file.extension)
+    && pathBelongsToRoot(portablePath(targetRoot, file.path), projectRoot, projectRoots));
+  return { c, cpp };
+}
+
+function parseNativeManifest(manifestName, manifestText) {
+  const normalizedName = manifestName.toLowerCase();
+  if (normalizedName.includes("cmake")) return parseCMake(manifestText);
+  if (normalizedName.includes("meson")) return parseMeson(manifestText);
+  if (["makefile", "gnumakefile"].includes(normalizedName)) return parseMakefile(manifestText);
+  return parseBazelNative(manifestText);
+}
+
+function nativeFrameworks(parsed, source) {
+  return {
+    c: parsed.c || (parsed.valid && source.c),
+    cpp: parsed.cpp || (parsed.valid && source.cpp),
+  };
+}
+
+function nativePrimarySignals({ manifestRelative, projectRoot, parsed, source, c, cpp }) {
+  if (!c && !cpp) return [];
+  return [
+    ...(c && parsed.c ? [`${manifestRelative}:c`] : []),
+    ...(cpp && parsed.cpp ? [`${manifestRelative}:cpp`] : []),
+    ...(c && source.c && !parsed.c ? [`${projectRoot}/source:c`] : []),
+    ...(cpp && source.cpp && !parsed.cpp ? [`${projectRoot}/source:cpp`] : []),
+  ];
+}
+
+export function inspectNativeProject({ projectRoot, manifestRelative, manifestText, manifestName, targetRoot, sourceFiles, projectRoots }) {
+  const parsed = parseNativeManifest(manifestName, manifestText);
+  const source = sourceEvidence(sourceFiles, targetRoot, projectRoot, projectRoots);
+  const { c, cpp } = nativeFrameworks(parsed, source);
+  const primary = c || cpp;
+  const frameworks = [];
+  if (c) frameworks.push("c");
+  if (cpp) frameworks.push("cpp");
+  const primarySignals = nativePrimarySignals({ manifestRelative, projectRoot, parsed, source, c, cpp });
+  const supportingSignals = parsed.make ? [`${manifestRelative}:make`] : [];
+  return createLanguageProject({
+    kind: "native",
+    root: projectRoot,
+    manifest: manifestRelative,
+    frameworks,
+    primary,
+    primarySignals,
+    supportingSignals,
+    internal: { ...parsed, valid: parsed.valid },
+  });
+}
+
+export function nativeFrameworkForSource(fileName) {
+  const rawExtension = fileName.match(/\.[^.]+$/u)?.[0] ?? "";
+  const extension = rawExtension === ".C" ? ".C" : rawExtension.toLowerCase();
+  if (C_SOURCE_EXTENSIONS.has(extension)) return "c";
+  if (CPP_SOURCE_EXTENSIONS.has(extension)) return "cpp";
+  return null;
+}

package/src/core/checkpoint-revalidation.js

@@ -0,0 +1,319 @@
+import { canonicalFingerprint } from "./artifacts.js";
+import {
+  resolveCanonicalRouteEvolution,
+  resolveCanonicalPostRepairRouteBinding,
+  resolveEffectiveContractBootstrapRepairAnchor,
+} from "./contract-bootstrap-recovery.js";
+import { resolveCanonicalContractEvolution } from "./contract-revision.js";
+
+export const CHECKPOINT_REVALIDATED_EVENT = "CHECKPOINT_REVALIDATED";
+export const CHECKPOINT_REVALIDATION_PHASES = Object.freeze(["ROUTED"]);
+
+const REPOSITORY_FINGERPRINT_KEYS = Object.freeze(["branch", "head"]);
+const REVALIDATION_DETAIL_KEYS = Object.freeze([
+  "phase",
+  "previousRepositoryFingerprint",
+  "repositoryFingerprint",
+  "contractFingerprint",
+  "routeFingerprint",
+  "previousStateRevision",
+  "revalidatedStateRevision",
+  "previousStateFingerprint",
+  "revalidatedStateFingerprint",
+]);
+
+function invalid(message) {
+  const error = new Error(message);
+  error.code = "E_CHECKPOINT_REVALIDATION_UNSAFE";
+  return error;
+}
+
+function isFingerprint(value) {
+  return typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+}
+
+export function assertRepositoryFingerprint(value, label = "repository fingerprint", { requireHead = false } = {}) {
+  if (!value || typeof value !== "object" || Array.isArray(value)
+    || Object.keys(value).length !== REPOSITORY_FINGERPRINT_KEYS.length
+    || REPOSITORY_FINGERPRINT_KEYS.some((key) => !Object.prototype.hasOwnProperty.call(value, key))) {
+    throw invalid(`${label} must contain exactly branch and head`);
+  }
+  for (const key of REPOSITORY_FINGERPRINT_KEYS) {
+    if (value[key] !== null && (typeof value[key] !== "string" || !value[key].trim())) {
+      throw invalid(`${label}.${key} must be a non-empty string or null`);
+    }
+  }
+  if (requireHead && typeof value.head !== "string") {
+    throw invalid(`${label}.head must be available`);
+  }
+  return value;
+}
+
+export function assertCheckpointRevalidatedDetails(details) {
+  if (!details || typeof details !== "object" || Array.isArray(details)
+    || Object.keys(details).length !== REVALIDATION_DETAIL_KEYS.length
+    || REVALIDATION_DETAIL_KEYS.some((key) => !Object.prototype.hasOwnProperty.call(details, key))) {
+    throw invalid(`${CHECKPOINT_REVALIDATED_EVENT} requires its exact state-transition detail set`);
+  }
+  if (!CHECKPOINT_REVALIDATION_PHASES.includes(details.phase)) {
+    throw invalid(`${CHECKPOINT_REVALIDATED_EVENT} details.phase is unsupported`);
+  }
+  assertRepositoryFingerprint(details.previousRepositoryFingerprint, `${CHECKPOINT_REVALIDATED_EVENT} details.previousRepositoryFingerprint`);
+  assertRepositoryFingerprint(details.repositoryFingerprint, `${CHECKPOINT_REVALIDATED_EVENT} details.repositoryFingerprint`, { requireHead: true });
+  if (JSON.stringify(details.previousRepositoryFingerprint) === JSON.stringify(details.repositoryFingerprint)) {
+    throw invalid(`${CHECKPOINT_REVALIDATED_EVENT} must record repository drift`);
+  }
+  for (const key of ["contractFingerprint", "routeFingerprint", "previousStateFingerprint", "revalidatedStateFingerprint"]) {
+    if (!isFingerprint(details[key])) throw invalid(`${CHECKPOINT_REVALIDATED_EVENT} details.${key} must be a lowercase SHA-256 fingerprint`);
+  }
+  for (const key of ["previousStateRevision", "revalidatedStateRevision"]) {
+    if (!Number.isInteger(details[key]) || details[key] < 0) {
+      throw invalid(`${CHECKPOINT_REVALIDATED_EVENT} details.${key} must be a non-negative integer`);
+    }
+  }
+  if (details.revalidatedStateRevision !== details.previousStateRevision + 1) {
+    throw invalid(`${CHECKPOINT_REVALIDATED_EVENT} state revisions must advance exactly once`);
+  }
+  return details;
+}
+
+function sameRepositoryFingerprint(left, right) {
+  return left?.branch === right?.branch && left?.head === right?.head;
+}
+
+function bindingError(message) {
+  return { code: "E_CHECKPOINT_REVALIDATION_UNSAFE", message };
+}
+
+function eventHash(event) {
+  const { hash, ...body } = event ?? {};
+  return canonicalFingerprint(body);
+}
+
+function routeEvolutionAfter(
+  events,
+  sourceEvent,
+  sourceRouteFingerprint,
+  targetRouteFingerprint,
+  targetContractFingerprint = sourceEvent.details?.contractFingerprint,
+) {
+  const sourceIndex = events.indexOf(sourceEvent);
+  if (sourceIndex < 0 || !isFingerprint(sourceRouteFingerprint) || !isFingerprint(targetRouteFingerprint)) {
+    return false;
+  }
+
+  const contractFingerprint = sourceEvent.details?.contractFingerprint;
+  if (targetContractFingerprint !== contractFingerprint) {
+    const contractEvolution = resolveCanonicalContractEvolution(events, {
+      taskId: sourceEvent.taskId,
+      sourceSeq: sourceEvent.seq,
+      sourceContractFingerprint: contractFingerprint,
+      targetContractFingerprint,
+    });
+    if (!contractEvolution?.revisionEvents?.length) return false;
+
+    let currentRouteFingerprint = sourceRouteFingerprint;
+    let currentContractFingerprint = contractFingerprint;
+    let currentSeq = sourceEvent.seq;
+    for (const revisionEvent of contractEvolution.revisionEvents) {
+      const boundaryRouteFingerprint = revisionEvent.details.previousRouteFingerprint;
+      if (!isFingerprint(boundaryRouteFingerprint)) return false;
+      const preRevisionEvents = events.filter((event) => event.seq <= revisionEvent.seq);
+      const preRevisionRoute = resolveCanonicalRouteEvolution(preRevisionEvents, {
+        taskId: sourceEvent.taskId,
+        sourceSeq: currentSeq,
+        sourceRouteFingerprint: currentRouteFingerprint,
+        targetRouteFingerprint: boundaryRouteFingerprint,
+        contractFingerprint: currentContractFingerprint,
+      });
+      if (!preRevisionRoute) return false;
+      currentRouteFingerprint = boundaryRouteFingerprint;
+      currentContractFingerprint = revisionEvent.details.contractFingerprint;
+      currentSeq = revisionEvent.seq;
+    }
+    const postRevisionRoute = resolveCanonicalRouteEvolution(events, {
+      taskId: sourceEvent.taskId,
+      sourceSeq: currentSeq,
+      sourceRouteFingerprint: currentRouteFingerprint,
+      targetRouteFingerprint,
+      contractFingerprint: currentContractFingerprint,
+    });
+    return Boolean(postRevisionRoute);
+  }
+
+  const canonical = resolveCanonicalRouteEvolution(events, {
+    taskId: sourceEvent.taskId,
+    sourceSeq: sourceEvent.seq,
+    sourceRouteFingerprint,
+    targetRouteFingerprint,
+    contractFingerprint,
+  });
+  if (!canonical) return false;
+
+  const anchor = resolveEffectiveContractBootstrapRepairAnchor(events);
+  if (anchor?.details?.contractFingerprint === contractFingerprint) {
+    const binding = resolveCanonicalPostRepairRouteBinding(
+      events,
+      anchor.sourceMarker,
+      targetRouteFingerprint,
+    );
+    return Boolean(binding?.reboundEvents?.some(({ reboundEvent }) =>
+      reboundEvent.seq > sourceEvent.seq
+      && reboundEvent.details.routeFingerprint === targetRouteFingerprint));
+  }
+  return canonical.valid;
+}
+
+/**
+ * Resolves the only valid transaction witness for a checkpoint revalidation.
+ * The witness is intentionally positional: a later transaction commit cannot
+ * retroactively authorize an earlier revalidation event.
+ */
+export function resolveCheckpointRevalidationBoundary(events = [], revalidationEvent) {
+  const index = events.findIndex((candidate) => candidate === revalidationEvent
+    || (candidate?.seq === revalidationEvent?.seq
+      && candidate?.taskId === revalidationEvent?.taskId
+      && candidate?.event === CHECKPOINT_REVALIDATED_EVENT));
+  if (index < 0) return null;
+  const commitEvent = events[index + 1];
+  if (!commitEvent
+    || revalidationEvent?.event !== CHECKPOINT_REVALIDATED_EVENT
+    || commitEvent.event !== "TRANSACTION_COMMITTED"
+    || commitEvent.seq !== revalidationEvent.seq + 1
+    || commitEvent.previousHash !== revalidationEvent.hash
+    || revalidationEvent.hash !== eventHash(revalidationEvent)
+    || commitEvent.hash !== eventHash(commitEvent)
+    || commitEvent.taskId !== revalidationEvent.taskId
+    || typeof commitEvent.details?.transactionId !== "string"
+    || !commitEvent.details.transactionId
+    || commitEvent.details.operation !== "checkpoint-revalidate") {
+    return null;
+  }
+  return { revalidationEvent, transactionCommitEvent: commitEvent };
+}
+
+export function validateCheckpointRevalidationEventBindings(events = []) {
+  const errors = [];
+  const revalidations = events.filter((event) => event.event === CHECKPOINT_REVALIDATED_EVENT);
+  for (let index = 0; index < revalidations.length; index += 1) {
+    const event = revalidations[index];
+    let details;
+    try {
+      details = assertCheckpointRevalidatedDetails(event.details);
+    } catch (error) {
+      errors.push(bindingError(`event ${event.seq}: ${error.message}`));
+      continue;
+    }
+    if (!resolveCheckpointRevalidationBoundary(events, event)) {
+      errors.push(bindingError(`event ${event.seq} must be immediately followed by its checkpoint-revalidate transaction commit`));
+    }
+    const previous = revalidations[index - 1]?.details;
+    if (previous) {
+      if (!sameRepositoryFingerprint(details.previousRepositoryFingerprint, previous.repositoryFingerprint)) {
+        errors.push(bindingError(`event ${event.seq} is disconnected from the previous checkpoint revalidation repository`));
+      }
+      if (details.previousStateRevision < previous.revalidatedStateRevision) {
+        errors.push(bindingError(`event ${event.seq} rolls back the previous checkpoint revalidation revision`));
+      }
+      if (details.previousStateRevision === previous.revalidatedStateRevision
+        && details.previousStateFingerprint !== previous.revalidatedStateFingerprint) {
+        errors.push(bindingError(`event ${event.seq} does not continue the previous checkpoint revalidation state fingerprint`));
+      }
+      const contractEvolved = details.contractFingerprint !== previous.contractFingerprint
+        && resolveCanonicalContractEvolution(events, {
+          taskId: event.taskId,
+          sourceSeq: revalidations[index - 1].seq,
+          sourceContractFingerprint: previous.contractFingerprint,
+          targetContractFingerprint: details.contractFingerprint,
+        });
+      if (details.contractFingerprint !== previous.contractFingerprint && !contractEvolved) {
+        errors.push(bindingError(`event ${event.seq} changes the checkpoint revalidation contract identity without canonical contract provenance`));
+      }
+      if (details.routeFingerprint !== previous.routeFingerprint) {
+        const evolved = details.previousStateRevision > previous.revalidatedStateRevision
+          && routeEvolutionAfter(
+            events,
+            revalidations[index - 1],
+            previous.routeFingerprint,
+            details.routeFingerprint,
+            details.contractFingerprint,
+          );
+        if (!evolved) {
+          errors.push(bindingError(`event ${event.seq} changes the checkpoint revalidation route identity without canonical route provenance`));
+        }
+      }
+    } else {
+      const anchor = resolveEffectiveContractBootstrapRepairAnchor(events);
+      if (anchor?.details?.reconstructedStateRevision === details.previousStateRevision
+        && anchor.details.reconstructedStateFingerprint !== details.previousStateFingerprint) {
+        errors.push(bindingError(`event ${event.seq} does not bind the repaired checkpoint state fingerprint`));
+      }
+    }
+  }
+  return errors;
+}
+
+function validateCurrentContractBinding(state, events, event) {
+  const details = event.details;
+  if (!state?.contractFingerprint || details?.contractFingerprint === state.contractFingerprint) return null;
+  const evolved = Number.isInteger(state.revision)
+    && Number.isInteger(details?.revalidatedStateRevision)
+    && state.revision > details.revalidatedStateRevision
+    && resolveCanonicalContractEvolution(events, {
+      taskId: event.taskId,
+      sourceSeq: event.seq,
+      sourceContractFingerprint: details.contractFingerprint,
+      targetContractFingerprint: state.contractFingerprint,
+    });
+  return evolved ? null : bindingError(`event ${event.seq} does not bind the current contract identity through canonical contract provenance`);
+}
+
+function validateCurrentRouteBinding(state, events, event) {
+  const details = event.details;
+  if (!state?.routeFingerprint || details?.routeFingerprint === state.routeFingerprint) return null;
+  const routeChangedAfterCheckpoint = Number.isInteger(state.revision)
+    && Number.isInteger(details?.revalidatedStateRevision)
+    && state.revision > details.revalidatedStateRevision;
+  const evolved = routeChangedAfterCheckpoint
+    && routeEvolutionAfter(events, event, details.routeFingerprint, state.routeFingerprint, state.contractFingerprint);
+  return evolved ? null : bindingError(`event ${event.seq} does not bind the current route identity through canonical route provenance`);
+}
+
+function validateLatestCheckpointBinding(state, latest) {
+  if (!state || !latest || state.revision !== latest.details.revalidatedStateRevision) return [];
+  const details = latest.details;
+  const errors = [];
+  if (!sameRepositoryFingerprint(state.repositoryFingerprint, details.repositoryFingerprint)) {
+    errors.push(bindingError(`event ${latest.seq} does not bind the current repository fingerprint`));
+  }
+  if (state.phase !== details.phase || canonicalFingerprint(state) !== details.revalidatedStateFingerprint) {
+    errors.push(bindingError(`event ${latest.seq} does not bind the current checkpoint state`));
+  }
+  return errors;
+}
+
+export function validateCheckpointRevalidationCurrentBinding(state, events = []) {
+  const errors = [];
+  const revalidations = events.filter((event) => event.event === CHECKPOINT_REVALIDATED_EVENT);
+  const latest = revalidations.at(-1);
+  for (const event of revalidations) {
+    const contractError = validateCurrentContractBinding(state, events, event);
+    if (contractError) errors.push(contractError);
+    const routeError = validateCurrentRouteBinding(state, events, event);
+    if (routeError) errors.push(routeError);
+  }
+  errors.push(...validateLatestCheckpointBinding(state, latest));
+  return errors;
+}
+
+/**
+ * Validates the semantic chain of checkpoint-revalidation events. The event
+ * hash proves bytes were not changed accidentally; these checks prove that a
+ * rehashed event still describes a valid state transition.
+ */
+export function validateCheckpointRevalidationBindings(state, events = []) {
+  return [
+    ...validateCheckpointRevalidationEventBindings(events),
+    ...validateCheckpointRevalidationCurrentBinding(state, events),
+  ];
+}