@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

package/src/core/evidence-readiness.js

@@ -164,6 +164,15 @@ export function terminalRequirements(requirements = []) {
   return normalizeRequirements(requirements).filter((requirement) => requirement.terminalOwned);
 }
 
+export function terminalRequirementsForContract(contractValue = {}, { additionalEvidence = [] } = {}) {
+  const pool = [
+    ...(contractValue.verification ?? []),
+    ...(contractValue.successCriteria ?? []),
+    ...additionalEvidence,
+  ];
+  return terminalRequirements(pool);
+}
+
 export function lifecycleRequirements(requirements = []) {
   return normalizeRequirements(requirements).filter((requirement) => requirement.type === "LIFECYCLE");
 }

package/src/core/execution-prerequisites.js

@@ -6,6 +6,7 @@ import { readPersistedRoute } from "./route-artifact.js";
 import { stateIdentityErrors } from "./completion-relationships.js";
 import { classifyLoadedWorkState } from "./work-state.js";
 import { taskArtifactPath } from "./task-paths.js";
+import { hasCurrentGateEvidence } from "./gate-provenance.js";
 
 const START_EXECUTION_EVENTS = Object.freeze([
   "CONTRACT_VALIDATED",
@@ -59,6 +60,7 @@ async function load(loadArtifact, code, message, artifacts, errors) {
   try {
     return await loadArtifact();
   } catch (error) {
+    if (error.code === "E_STATE_REVISION_CONFLICT") throw error;
     errors.push(issue(code, `${message}: ${error.message}`, artifacts));
     return null;
   }
@@ -129,9 +131,26 @@ function prerequisiteLedgerErrors(ledger, taskId, preflight, route) {
       [ARTIFACT_PATHS.events, ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.route],
     ));
   }
+  const latestContractRevisionSeq = currentEvents.findLast((event) => event.event === "CONTRACT_REVISED")?.seq ?? 0;
+  const currentEpochSatisfiedGates = new Set(preflight.requiredGates.filter((gate) => (
+    hasCurrentGateEvidence(currentEvents, taskId, gate, latestContractRevisionSeq)
+  )));
+  for (const gate of preflight.requiredGates) {
+    if (!currentEpochSatisfiedGates.has(gate)) {
+      errors.push(issue(
+        "E_PHASE_CHRONOLOGY_INVALID",
+        `execution started before current-contract gate satisfaction: ${gate}`,
+        [ARTIFACT_PATHS.events, ARTIFACT_PATHS.preflight],
+      ));
+    }
+  }
   return errors;
 }
 
+function prerequisiteArtifactPath(explicitPath, taskId, kind) {
+  return explicitPath ?? (taskId ? taskArtifactPath(taskId, kind) : ARTIFACT_PATHS[kind]);
+}
+
 export async function evaluateStartExecutionPrerequisites({
   target,
   state,
@@ -142,13 +161,14 @@ export async function evaluateStartExecutionPrerequisites({
   statePath = null,
   preflightPath = null,
   eventsPath = null,
+  readers = null,
 } = {}) {
   const effectiveTaskId = taskId ?? null;
-  const contractRel = contractPath ?? (effectiveTaskId ? taskArtifactPath(effectiveTaskId, "contract") : ARTIFACT_PATHS.contract);
-  const routeRel = routePath ?? (effectiveTaskId ? taskArtifactPath(effectiveTaskId, "route") : ARTIFACT_PATHS.route);
-  const stateRel = statePath ?? (effectiveTaskId ? taskArtifactPath(effectiveTaskId, "state") : ARTIFACT_PATHS.state);
-  const preflightRel = preflightPath ?? (effectiveTaskId ? taskArtifactPath(effectiveTaskId, "preflight") : ARTIFACT_PATHS.preflight);
-  const eventsRel = eventsPath ?? (effectiveTaskId ? taskArtifactPath(effectiveTaskId, "events") : ARTIFACT_PATHS.events);
+  const contractRel = prerequisiteArtifactPath(contractPath, effectiveTaskId, "contract");
+  const routeRel = prerequisiteArtifactPath(routePath, effectiveTaskId, "route");
+  const stateRel = prerequisiteArtifactPath(statePath, effectiveTaskId, "state");
+  const preflightRel = prerequisiteArtifactPath(preflightPath, effectiveTaskId, "preflight");
+  const eventsRel = prerequisiteArtifactPath(eventsPath, effectiveTaskId, "events");
 
   const errors = [];
   const requiredArtifacts = [
@@ -166,14 +186,14 @@ export async function evaluateStartExecutionPrerequisites({
   }
 
   const contract = await load(
-    () => readContract(target, packageRoot, { taskId: effectiveTaskId, contractPath }),
+    () => (readers?.readContract ?? readContract)(target, packageRoot, { taskId: effectiveTaskId, contractPath }),
     "E_PHASE_PREREQUISITE_MISSING",
     `EXECUTING requires ${contractRel}`,
     [contractRel],
     errors,
   );
   const route = await load(
-    () => readPersistedRoute(target, packageRoot, { taskId: effectiveTaskId, routePath }),
+    () => (readers?.readRoute ?? readPersistedRoute)(target, packageRoot, { taskId: effectiveTaskId, routePath }),
     "E_PHASE_PREREQUISITE_MISSING",
     `EXECUTING requires ${routeRel}`,
     [routeRel],
@@ -190,21 +210,24 @@ export async function evaluateStartExecutionPrerequisites({
   }
   errors.push(...stateIdentityErrors({ contract, route, state }));
 
-  const freshness = await classifyLoadedWorkState({
+  const freshness = await (readers?.classifyState ?? classifyLoadedWorkState)({
     target,
     state,
     contractFile: contractRel,
   });
   errors.push(...freshnessErrors(state, freshness));
 
-  const preflight = await evaluatePreflight({ target, packageRoot, taskId: effectiveTaskId, contractPath, routePath, statePath });
+  const preflight = await evaluatePreflight({ target, packageRoot, taskId: effectiveTaskId, contractPath, routePath, statePath, readers });
   let persistedPreflight = null;
+  let persistedPreflightReadError = null;
   try {
-    persistedPreflight = await readJsonArtifact(target, preflightRel, "preflight", packageRoot);
-  } catch {
+    persistedPreflight = await (readers?.readPreflight ?? readJsonArtifact)(target, preflightRel, "preflight", packageRoot);
+  } catch (error) {
+    if (error.code === "E_STATE_REVISION_CONFLICT") throw error;
+    persistedPreflightReadError = error;
     // validatePersistedPreflight reports the stable, actionable preflight reason.
   }
-  const persistedPreflightErrors = validatePersistedPreflight(persistedPreflight?.value, preflight);
+  const persistedPreflightErrors = validatePersistedPreflight(persistedPreflight?.value, preflight, persistedPreflightReadError);
   if (!sameStringSet(state.requiredGates, preflight.requiredGates)
     || !sameStringSet(state.satisfiedGates, preflight.satisfiedGates)) {
     errors.push(issue(
@@ -214,7 +237,7 @@ export async function evaluateStartExecutionPrerequisites({
     ));
   }
 
-  const ledger = await validateEventLedger(target, packageRoot, { taskId: effectiveTaskId, eventsPath });
+  const ledger = await (readers?.validateLedger ?? validateEventLedger)(target, packageRoot, { taskId: effectiveTaskId, eventsPath });
   errors.push(...prerequisiteLedgerErrors(ledger, contract.value.taskId, preflight, route));
   errors.push(...validateStateLedgerCoherence(state, ledger.events).map((error) => issue(
     error.code,

package/src/core/execution-profile.js

@@ -162,12 +162,63 @@ export function projectExecutionProfile(route) {
   return route.executionProfile?.resolved ?? LEGACY_EXECUTION_PROFILE;
 }
 
+function routeProfileSignals(normalizedRoute) {
+  const fullReasons = [];
+  const balancedReasons = [];
+  if (FULL_WORK_TYPES.has(normalizedRoute.workType)) fullReasons.push(`WORK_${normalizedRoute.workType.toUpperCase().replaceAll("-", "_")}`);
+  if (BALANCED_WORK_TYPES.has(normalizedRoute.workType)) balancedReasons.push(`WORK_${normalizedRoute.workType.toUpperCase().replaceAll("-", "_")}`);
+  for (const surface of normalizedRoute.surfaces) {
+    if (FULL_SURFACES.has(surface)) fullReasons.push(`SURFACE_${surface.toUpperCase().replaceAll("-", "_")}`);
+    else if (BALANCED_SURFACES.has(surface)) balancedReasons.push(`SURFACE_${surface.toUpperCase().replaceAll("-", "_")}`);
+  }
+  for (const risk of normalizedRoute.risks) {
+    if (FULL_RISKS.has(risk)) fullReasons.push(`RISK_${risk.toUpperCase().replaceAll("-", "_")}`);
+    else if (BALANCED_RISKS.has(risk)) balancedReasons.push(`RISK_${risk.toUpperCase().replaceAll("-", "_")}`);
+  }
+  if (normalizedRoute.behaviorChange) balancedReasons.push("WORK_BEHAVIOR_CHANGE");
+  if (normalizedRoute.executableChange) balancedReasons.push("WORK_EXECUTABLE_CHANGE");
+  return { fullReasons, balancedReasons };
+}
+
+function contractProfileSignals(textSignals, normalizedRoute) {
+  const fullReasons = [];
+  if (textSignals.secrets) fullReasons.push("RISK_SECRETS");
+  if (textSignals.personalData) fullReasons.push("RISK_PERSONAL_DATA");
+  if (textSignals.publication) fullReasons.push("RISK_PUBLICATION");
+  if (textSignals.destructive) fullReasons.push("RISK_DESTRUCTIVE");
+  if (textSignals.migration && normalizedRoute.surfaces.includes("database")) fullReasons.push("RISK_MIGRATION");
+  if (textSignals.payment) fullReasons.push("RISK_PAYMENT");
+  if (textSignals.externalMutation) fullReasons.push("RISK_EXTERNAL_MUTATION");
+  if (textSignals.authoritySensitiveExternalMutation) fullReasons.push("RISK_AUTHORITY_SENSITIVE_EXTERNAL_MUTATION");
+  if (textSignals.broadProductionValidation) fullReasons.push("RISK_PRODUCTION_VALIDATION");
+  return fullReasons;
+}
+
+function scopeProfileSignals(scope) {
+  const balancedReasons = [];
+  if (scope.multiDeliverable) balancedReasons.push("SCOPE_MULTI_DELIVERABLE");
+  if (scope.multiClaim) balancedReasons.push("SCOPE_MULTI_CLAIM");
+  if (scope.broad || scope.multiSurfaceExecutableChange) balancedReasons.push("SCOPE_BROAD");
+  return balancedReasons;
+}
+
+function profileSignals({ normalizedRoute, contract, taskDescriptor }) {
+  const route = routeProfileSignals(normalizedRoute);
+  const scope = scopeSignals({ routeInput: normalizedRoute, contract, taskDescriptor });
+  return {
+    fullReasons: [...route.fullReasons, ...contractProfileSignals(contractSignals(contract), normalizedRoute)],
+    balancedReasons: [...route.balancedReasons, ...scopeProfileSignals(scope)],
+    scope,
+  };
+}
+
 export function resolveExecutionProfile({
   routeInput = {},
   contract = null,
   taskDescriptor = null,
   configuredProfile = "auto",
   requestedProfile = null,
+  semanticRecommendation = null,
 } = {}) {
   const normalizedRoute = normalizedRouteInput(routeInput);
   const configured = normalizeRequestedProfile(configuredProfile, "configuredProfile");
@@ -181,43 +232,7 @@ export function resolveExecutionProfile({
   else reasons.push("PROFILE_DEFAULT_AUTO");
 
   let floor = "light";
-  const fullReasons = [];
-  const balancedReasons = [];
-  const addFull = (reason) => fullReasons.push(reason);
-  const addBalanced = (reason) => balancedReasons.push(reason);
-
-  if (FULL_WORK_TYPES.has(normalizedRoute.workType)) {
-    addFull(`WORK_${normalizedRoute.workType.toUpperCase().replaceAll("-", "_")}`);
-  }
-  if (BALANCED_WORK_TYPES.has(normalizedRoute.workType)) {
-    addBalanced(`WORK_${normalizedRoute.workType.toUpperCase().replaceAll("-", "_")}`);
-  }
-  for (const surface of normalizedRoute.surfaces) {
-    if (FULL_SURFACES.has(surface)) addFull(`SURFACE_${surface.toUpperCase().replaceAll("-", "_")}`);
-    else if (BALANCED_SURFACES.has(surface)) addBalanced(`SURFACE_${surface.toUpperCase().replaceAll("-", "_")}`);
-  }
-  for (const risk of normalizedRoute.risks) {
-    if (FULL_RISKS.has(risk)) addFull(`RISK_${risk.toUpperCase().replaceAll("-", "_")}`);
-    else if (BALANCED_RISKS.has(risk)) addBalanced(`RISK_${risk.toUpperCase().replaceAll("-", "_")}`);
-  }
-  if (normalizedRoute.behaviorChange) addBalanced("WORK_BEHAVIOR_CHANGE");
-  if (normalizedRoute.executableChange) addBalanced("WORK_EXECUTABLE_CHANGE");
-
-  const textSignals = contractSignals(contract);
-  if (textSignals.secrets) addFull("RISK_SECRETS");
-  if (textSignals.personalData) addFull("RISK_PERSONAL_DATA");
-  if (textSignals.publication) addFull("RISK_PUBLICATION");
-  if (textSignals.destructive) addFull("RISK_DESTRUCTIVE");
-  if (textSignals.migration && normalizedRoute.surfaces.includes("database")) addFull("RISK_MIGRATION");
-  if (textSignals.payment) addFull("RISK_PAYMENT");
-  if (textSignals.externalMutation) addFull("RISK_EXTERNAL_MUTATION");
-  if (textSignals.authoritySensitiveExternalMutation) addFull("RISK_AUTHORITY_SENSITIVE_EXTERNAL_MUTATION");
-  if (textSignals.broadProductionValidation) addFull("RISK_PRODUCTION_VALIDATION");
-
-  const scope = scopeSignals({ routeInput: normalizedRoute, contract, taskDescriptor });
-  if (scope.multiDeliverable) addBalanced("SCOPE_MULTI_DELIVERABLE");
-  if (scope.multiClaim) addBalanced("SCOPE_MULTI_CLAIM");
-  if (scope.broad || scope.multiSurfaceExecutableChange) addBalanced("SCOPE_BROAD");
+  const { fullReasons, balancedReasons, scope } = profileSignals({ normalizedRoute, contract, taskDescriptor });
 
   if (fullReasons.length > 0) {
     floor = "full";
@@ -247,7 +262,17 @@ export function resolveExecutionProfile({
   }
 
   const requestedRank = requested === "auto" ? PROFILE_RANK[floor] : PROFILE_RANK[requested];
-  const resolved = EXECUTION_PROFILES.find((profile) => PROFILE_RANK[profile] === Math.max(requestedRank, PROFILE_RANK[floor]));
+  let resolved = EXECUTION_PROFILES.find((profile) => PROFILE_RANK[profile] === Math.max(requestedRank, PROFILE_RANK[floor]));
+  const semanticProfile = typeof semanticRecommendation === "string"
+    ? semanticRecommendation
+    : semanticRecommendation?.executionProfile?.recommendedProfile
+      ?? semanticRecommendation?.recommendedProfile
+      ?? null;
+  if (["light", "balanced", "full"].includes(semanticProfile)
+    && PROFILE_RANK[semanticProfile] > PROFILE_RANK[resolved]) {
+    resolved = semanticProfile;
+    reasons.push("PROFILE_ESCALATED_BY_JEV");
+  }
   const escalated = requested !== "auto" && PROFILE_RANK[requested] < PROFILE_RANK[floor];
   if (escalated) reasons.push("PROFILE_ESCALATED_BY_SAFETY");
 

package/src/core/execution.js

@@ -1,12 +1,13 @@
-import { readdir } from "node:fs/promises";
-import path from "node:path";
+import { needsExistingProjectScope, withExistingProjectScope } from "../storage/existing-project-scope.js";
 import { ensureWithin, fileExists } from "./filesystem.js";
 import {
   ARTIFACT_PATHS,
   executionArtifactPath,
+  parseCapturedJsonArtifact,
   readJsonArtifact,
 } from "./artifacts.js";
 import { taskArtifactPath, taskExecutionPath } from "./task-paths.js";
+import { getOperationalStore, operationalArtifactExists } from "../storage/operational-context.js";
 
 export { E_COMMAND_RESOLUTION_AMBIGUOUS } from "./verification-capability.js";
 import {
@@ -26,18 +27,14 @@ function executionError(code, message, artifacts = []) {
   return error;
 }
 
-/**
- * Resolves where a new execution artifact should be written. Task-scoped
- * execution artifacts require a real modern task namespace (a task.json
- * descriptor). A descriptor-less task is legacy: writing task-scoped here
- * would create a phantom `.forgeloop/task-state/<key>/executions/` namespace
- * that corrupts task discovery. Reads already fall back across both
- * locations, so a legacy execution stays resolvable.
- */
+/** Resolve an execution identity; persistence separately requires canonical SQLite authority. */
 export async function resolveExecutionArtifactPath(target, taskId, executionId) {
+  if (await needsExistingProjectScope(target)) {
+    return withExistingProjectScope(target, () => resolveExecutionArtifactPath(target, taskId, executionId), { readOnly: true });
+  }
   if (!taskId) return executionArtifactPath(executionId);
   const descriptorRel = taskArtifactPath(taskId, "descriptor");
-  if (await fileExists(ensureWithin(target, descriptorRel))) {
+  if (operationalArtifactExists(target, descriptorRel) ?? await fileExists(ensureWithin(target, descriptorRel))) {
     return taskExecutionPath(taskId, executionId);
   }
   return executionArtifactPath(executionId);
@@ -87,42 +84,31 @@ export async function runCommandExecution({
 }
 
 export async function readExecutionArtifact({ target, executionRef, packageRoot, taskId } = {}) {
+  if (await needsExistingProjectScope(target)) {
+    return withExistingProjectScope(target, () => readExecutionArtifact({ target, executionRef, packageRoot, taskId }), { readOnly: true });
+  }
   let relativePath;
   try {
+    const store = getOperationalStore(target);
+    if (store && !taskId) {
+      // Validate the public reference before using it as a canonical identity.
+      executionArtifactPath(executionRef);
+      taskId = store.executionTaskId(executionRef);
+    }
     relativePath = taskId ? taskExecutionPath(taskId, executionRef) : executionArtifactPath(executionRef);
+    if (store?.recognizes(relativePath)) {
+      const execution = store.readExecution(taskId, executionRef);
+      return parseCapturedJsonArtifact(
+        execution === null ? null : `${JSON.stringify(execution, null, 2)}\n`,
+        relativePath,
+        "execution",
+        packageRoot,
+      );
+    }
     const artifact = await readJsonArtifact(target, relativePath, "execution", packageRoot);
     return artifact;
   } catch (error) {
     if (error.code === "E_EXECUTION_REF_INVALID") throw error;
-    if (error.code === "ARTIFACT_MISSING") {
-      if (taskId) {
-        try {
-          const fallbackPath = executionArtifactPath(executionRef);
-          const artifact = await readJsonArtifact(target, fallbackPath, "execution", packageRoot);
-          return artifact;
-        } catch {
-          // ignore fallback failure
-        }
-      } else {
-        try {
-          const taskStateDir = path.join(target, ".forgeloop", "task-state");
-          if (await fileExists(taskStateDir)) {
-            const entries = await readdir(taskStateDir, { withFileTypes: true });
-            for (const entry of entries) {
-              if (entry.isDirectory()) {
-                const execFile = path.join(taskStateDir, entry.name, "executions", `${executionRef}.json`);
-                if (await fileExists(execFile)) {
-                  const rel = path.relative(target, execFile).replaceAll("\\", "/");
-                  return await readJsonArtifact(target, rel, "execution", packageRoot);
-                }
-              }
-            }
-          }
-        } catch {
-          // ignore scan failure
-        }
-      }
-    }
     throw executionError("E_EXECUTION_REF_INVALID", "Execution reference does not resolve to a valid ForgeLoop artifact", [relativePath ?? ARTIFACT_PATHS.executionDirectory]);
   }
 }

package/src/core/filesystem.js

@@ -105,6 +105,17 @@ export function isPathWithin(root, candidate, { platform = process.platform } =
       && !pathApi.isAbsolute(relative));
 }
 
+/** Recheck an opened regular file against its admitted project path before reading. */
+export async function assertRegularProjectFileIdentity(file, filename, observed, root, invalid) {
+  const actual = await file.stat({ bigint: true });
+  const current = await lstat(filename, { bigint: true });
+  if (!actual.isFile() || !current.isFile() || current.isSymbolicLink()
+    || actual.dev !== observed.dev || actual.ino !== observed.ino
+    || current.dev !== observed.dev || current.ino !== observed.ino
+    || !isPathWithin(root, await realpathWithTransientWindowsRetry(filename))) throw invalid();
+  return actual;
+}
+
 export async function assertSafePath(root, relativePath) {
   const destination = ensureWithin(root, relativePath);
   const absoluteRoot = path.resolve(root);

package/src/core/gate-artifact.js

@@ -1,8 +1,13 @@
-import { assertSafePath, ensureWithin, fileExists, readBytes } from "./filesystem.js";
+import { assertSafePath, ensureWithin, fileExists, isPathWithin, realpathWithTransientWindowsRetry } from "./filesystem.js";
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
 import { ARTIFACT_PATHS, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
 import { assertSchema, readSchema } from "./schema-validation.js";
 import { sha256 } from "./manifest.js";
 import { taskGatePath } from "./task-paths.js";
+import { getOperationalStore, operationalArtifactExists, readOperationalText } from "../storage/operational-context.js";
+import { createHash } from "node:crypto";
+import { withNativeReadScope } from "./native-storage.js";
 
 function gateName(value) {
   if (typeof value !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(value)) {
@@ -32,26 +37,107 @@ export async function readGate(target, gate, packageRoot, options = {}) {
 }
 
 export async function readGateIfPresent(target, gate, packageRoot, options = {}) {
-  const relativePath = options?.gatePath ?? (options?.taskId ? taskGatePath(options.taskId, gate) : gatePath(gate, options));
-  await assertSafePath(target, relativePath);
-  const filePath = ensureWithin(target, relativePath);
-  if (!(await fileExists(filePath))) return null;
-  return readJsonArtifact(target, relativePath, "gate", packageRoot);
+  return withNativeReadScope(target, async () => {
+    const relativePath = options?.gatePath ?? (options?.taskId ? taskGatePath(options.taskId, gate) : gatePath(gate, options));
+    await assertSafePath(target, relativePath);
+    const selected = operationalArtifactExists(target, relativePath);
+    if (selected !== null) return selected ? readJsonArtifact(target, relativePath, "gate", packageRoot) : null;
+    const filePath = ensureWithin(target, relativePath);
+    if (!(await fileExists(filePath))) return null;
+    return readJsonArtifact(target, relativePath, "gate", packageRoot);
+  });
 }
 
-export async function validateGateArtifacts(target, gateValue, packageRoot) {
-  const schema = await readSchema("gate", packageRoot);
-  assertSchema(gateValue, schema, "gate");
-  const stale = [];
-  for (const artifact of gateValue.artifacts ?? []) {
-    await assertSafePath(target, artifact.path);
-    const artifactPath = ensureWithin(target, artifact.path);
-    if (!(await fileExists(artifactPath))) {
-      stale.push({ path: artifact.path, status: "missing" });
-      continue;
+/** Hash selected bytes through the operational read set, including missing rows. */
+export function readCanonicalGateArtifactBinding(target, relativePath) {
+  const store = getOperationalStore(target);
+  if (store?.recognizes(relativePath) && relativePath.replaceAll("\\", "/").endsWith("/events.ndjson")) {
+    if (!operationalArtifactExists(target, relativePath)) return { path: relativePath, sha256: null, byteLength: 0 };
+    const digest = createHash("sha256");
+    let byteLength = 0;
+    for (const event of store.iterateEvents(relativePath)) {
+      const bytes = `${JSON.stringify(event)}\n`;
+      byteLength += Buffer.byteLength(bytes);
+      digest.update(bytes);
     }
-    const digest = sha256(await readBytes(artifactPath));
-    if (digest !== artifact.sha256) stale.push({ path: artifact.path, status: "changed" });
+    return { path: relativePath, sha256: digest.digest("hex"), byteLength };
   }
-  return stale;
+  const source = readOperationalText(target, relativePath);
+  if (!source.selected) return null;
+  return { path: relativePath, sha256: source.text === null ? null : sha256(source.text), byteLength: source.text === null ? 0 : Buffer.byteLength(source.text) };
+}
+
+/** Admit one regular external evidence handle before reading any bytes. */
+async function withGateFile(target, relativePath, maxBytes, callback) {
+  const filename = await assertSafePath(target, relativePath);
+  const root = await realpathWithTransientWindowsRetry(target);
+  const resolved = await realpathWithTransientWindowsRetry(filename);
+  if (!isPathWithin(root, resolved)) throw new Error("Gate artifact resolves outside the project");
+  const file = await open(resolved, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const info = await file.stat();
+    const current = await lstat(resolved);
+    if (!info.isFile() || !current.isFile() || current.isSymbolicLink()
+      || info.dev !== current.dev || info.ino !== current.ino
+      || !isPathWithin(root, await realpathWithTransientWindowsRetry(resolved))) throw new Error("Gate artifact changed during file admission");
+    if (info.size > maxBytes) throw new Error(`Gate artifact exceeds the maximum size of ${maxBytes} bytes`);
+    return await callback(file);
+  } finally { await file.close(); }
+}
+
+async function* gateFileChunks(file, maxBytes) {
+  let byteLength = 0;
+  for await (const bytes of file.createReadStream({ autoClose: false, highWaterMark: 64 * 1024 })) {
+    byteLength += bytes.length;
+    if (byteLength > maxBytes) throw new Error(`Gate artifact exceeds the maximum size of ${maxBytes} bytes`);
+    yield bytes;
+  }
+}
+
+/** Hash external evidence from one verified handle, with bounded streaming memory. */
+export async function hashGateFile(target, relativePath, { maxBytes = Infinity } = {}) {
+  return withGateFile(target, relativePath, maxBytes, async file => {
+    const digest = createHash("sha256");
+    let byteLength = 0;
+    for await (const bytes of gateFileChunks(file, maxBytes)) {
+      byteLength += bytes.length;
+      digest.update(bytes);
+    }
+    return { path: relativePath, sha256: digest.digest("hex"), byteLength };
+  });
+}
+
+/** Explicit JSON gate input remains file-owned and allocation-bounded. */
+export async function readGateFileJson(target, relativePath, { maxBytes } = {}) {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) throw new Error("Gate evidence requires a finite byte limit");
+  return withGateFile(target, relativePath, maxBytes, async file => {
+    const chunks = [];
+    for await (const bytes of gateFileChunks(file, maxBytes)) chunks.push(bytes);
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  });
+}
+
+export async function validateGateArtifacts(target, gateValue, packageRoot) {
+  return withNativeReadScope(target, async () => {
+    const schema = await readSchema("gate", packageRoot);
+    assertSchema(gateValue, schema, "gate");
+    const stale = [];
+    for (const artifact of gateValue.artifacts ?? []) {
+      await assertSafePath(target, artifact.path);
+      const canonical = readCanonicalGateArtifactBinding(target, artifact.path);
+      if (canonical) {
+        if (canonical.sha256 === null) stale.push({ path: artifact.path, status: "missing" });
+        else if (canonical.sha256 !== artifact.sha256) stale.push({ path: artifact.path, status: "changed" });
+        continue;
+      }
+      const artifactPath = ensureWithin(target, artifact.path);
+      if (!(await fileExists(artifactPath))) {
+        stale.push({ path: artifact.path, status: "missing" });
+        continue;
+      }
+      const binding = await hashGateFile(target, artifact.path);
+      if (binding.sha256 !== artifact.sha256) stale.push({ path: artifact.path, status: "changed" });
+    }
+    return stale;
+  });
 }

package/src/core/gate-provenance.js

@@ -0,0 +1,125 @@
+import { isLedgerEventCollection, ledgerEventAt, ledgerEntriesOfTypes } from "./ledger-event-collection.js";
+import { canonicalFingerprint } from "./artifacts.js";
+
+export const GATE_SATISFIED_EVENT = "GATE_SATISFIED";
+export const GATE_REVALIDATED_EVENT = "GATE_REVALIDATED";
+const CONTRACT_REVISED_EVENT = "CONTRACT_REVISED";
+const TRANSACTION_COMMITTED_EVENT = "TRANSACTION_COMMITTED";
+
+function eventHash(event) {
+  const { hash, ...body } = event ?? {};
+  return canonicalFingerprint(body);
+}
+
+export function assertGateSatisfiedDetails(details) {
+  if (!details || typeof details !== "object" || Array.isArray(details)
+    || Object.keys(details).length !== 1
+    || typeof details.gate !== "string"
+    || details.gate.trim().length === 0) {
+    const error = new Error("GATE_SATISFIED requires exactly one non-empty gate detail");
+    error.code = "E_EVENT_INVALID";
+    throw error;
+  }
+  return details;
+}
+
+export function assertGateRevalidatedDetails(details) {
+  const keys = ["gate", "previousGateFingerprint", "gateFingerprint", "stalePaths"];
+  if (!details || typeof details !== "object" || Array.isArray(details)
+    || Object.keys(details).length !== keys.length
+    || keys.some((key) => !Object.prototype.hasOwnProperty.call(details, key))
+    || typeof details.gate !== "string"
+    || details.gate.trim().length === 0
+    || !/^[a-z0-9][a-z0-9-]*$/.test(details.gate)
+    || !/^[a-f0-9]{64}$/.test(details.previousGateFingerprint)
+    || !/^[a-f0-9]{64}$/.test(details.gateFingerprint)
+    || !Array.isArray(details.stalePaths)
+    || details.stalePaths.length === 0
+    || details.stalePaths.some((value) => typeof value !== "string" || value.trim().length === 0)
+    || [...details.stalePaths].sort().join("\0") !== details.stalePaths.join("\0")
+    || new Set(details.stalePaths).size !== details.stalePaths.length) {
+    const error = new Error("GATE_REVALIDATED requires a gate, two fingerprints, and sorted stale paths");
+    error.code = "E_GATE_REVALIDATION_INVALID";
+    throw error;
+  }
+  return details;
+}
+
+function gateIndex(events, gateEvent, eventName) {
+  return events.findIndex((event) => event === gateEvent
+    || (event?.seq === gateEvent?.seq
+      && event?.taskId === gateEvent?.taskId
+      && event?.event === eventName));
+}
+
+function isValidGateCommit(gateEvent, commitEvent, operation) {
+  return commitEvent?.event === TRANSACTION_COMMITTED_EVENT
+    && commitEvent.taskId === gateEvent.taskId
+    && commitEvent.seq === gateEvent.seq + 1
+    && commitEvent.previousHash === gateEvent.hash
+    && gateEvent.hash === eventHash(gateEvent)
+    && commitEvent.hash === eventHash(commitEvent)
+    && commitEvent.details
+    && typeof commitEvent.details === "object"
+    && !Array.isArray(commitEvent.details)
+    && Object.keys(commitEvent.details).length === 2
+    && typeof commitEvent.details.transactionId === "string"
+    && commitEvent.details.transactionId.length > 0
+    && commitEvent.details.operation === operation;
+}
+
+export function resolveGateRecordBoundary(events, gateEvent) {
+  if (!isLedgerEventCollection(events) || !gateEvent || gateEvent.event !== GATE_SATISFIED_EVENT) return null;
+  const index = gateIndex(events, gateEvent, GATE_SATISFIED_EVENT);
+  if (index < 0) return null;
+  const commitEvent = ledgerEventAt(events, index + 1);
+  return isValidGateCommit(gateEvent, commitEvent, "gate-record")
+    ? { gateEvent, transactionCommitEvent: commitEvent }
+    : null;
+}
+
+export function resolveGateRevalidationBoundary(events, gateEvent) {
+  if (!isLedgerEventCollection(events) || !gateEvent || gateEvent.event !== GATE_REVALIDATED_EVENT) return null;
+  const index = gateIndex(events, gateEvent, GATE_REVALIDATED_EVENT);
+  if (index < 0) return null;
+  const commitEvent = ledgerEventAt(events, index + 1);
+  return isValidGateCommit(gateEvent, commitEvent, "gate-revalidate")
+    ? { gateEvent, transactionCommitEvent: commitEvent }
+    : null;
+}
+
+export function hasCurrentGateEvidence(events, taskId, gate, latestContractRevisionSeq = 0) {
+  return events.some((event) => [GATE_SATISFIED_EVENT, GATE_REVALIDATED_EVENT].includes(event.event)
+    && event.taskId === taskId
+    && event.details?.gate === gate
+    && event.seq > latestContractRevisionSeq);
+}
+
+export function validateGateSatisfactionBindings(events = []) {
+  const errors = [];
+  for (const [index, event] of ledgerEntriesOfTypes(events, [GATE_SATISFIED_EVENT, GATE_REVALIDATED_EVENT])) {
+    if (![GATE_SATISFIED_EVENT, GATE_REVALIDATED_EVENT].includes(event.event)) continue;
+    const revalidated = event.event === GATE_REVALIDATED_EVENT;
+    try {
+      if (revalidated) assertGateRevalidatedDetails(event.details);
+      else assertGateSatisfiedDetails(event.details);
+    } catch (error) {
+      errors.push({ code: error.code ?? "E_EVENT_INVALID", message: `event ${event.seq} (${event.event}): ${error.message}` });
+      continue;
+    }
+    const revisedBeforeGate = events.slice(0, index).findLast((candidate) => candidate.taskId === event.taskId
+      && candidate.event === CONTRACT_REVISED_EVENT);
+    const boundary = revalidated
+      ? resolveGateRevalidationBoundary(events, event)
+      : resolveGateRecordBoundary(events, event);
+    if ((revalidated || revisedBeforeGate) && !boundary) {
+      errors.push({
+        code: revalidated ? "E_GATE_REVALIDATION_INVALID" : "E_EVENT_INVALID",
+        message: revalidated
+          ? `event ${event.seq} must be immediately followed by its gate-revalidate transaction commit`
+          : `event ${event.seq} must be immediately followed by its gate-record transaction commit after contract revision`,
+      });
+    }
+  }
+  return errors;
+}