@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

package/src/commands/contract-revise.js

@@ -0,0 +1,236 @@
+import { createPresetContract } from "../core/contract-presets.js";
+import {
+  contractFingerprint,
+  readContract,
+  validateContract,
+  writeContract,
+} from "../core/contract.js";
+import {
+  appendProtocolEvent,
+  validateEventLedger,
+  validateStateLedgerCoherence,
+} from "../core/events.js";
+import { canonicalFingerprint, readJsonArtifact } from "../core/artifacts.js";
+import { resolveEffectiveContractBootstrapRepairAnchor } from "../core/contract-bootstrap-recovery.js";
+import {
+  CONTRACT_REVISED_EVENT,
+  assertContractRevisedDetails,
+} from "../core/contract-revision.js";
+import { resolveTaskContext, TASK_SELECTION_MODES } from "../core/task-context.js";
+import { assertTaskMutationAllowed, resolveTaskClaimState } from "../core/task-claim-state.js";
+import { assertWorkspaceBinding } from "../core/workspace-binding.js";
+import { withTaskTransaction } from "../core/transaction.js";
+import { mutateWorkState, readWorkState } from "../core/work-state.js";
+import { readPersistedRoute } from "../core/route-artifact.js";
+import { assertStateIdentity } from "../core/completion-relationships.js";
+
+const REVISION_PHASES = new Set(["CONTRACT_READY", "ROUTED", "PLANNED"]);
+
+function revisionError(message, artifacts = []) {
+  const error = new Error(message);
+  error.code = "E_CONTRACT_REVISION_UNSAFE";
+  if (artifacts.length > 0) error.artifacts = artifacts;
+  return error;
+}
+
+async function loadCandidate({ target, packageRoot, taskId, contractFile, preset, claims }) {
+  if (preset) return createPresetContract({ taskId, preset, claims });
+  let artifact;
+  try {
+    artifact = await readJsonArtifact(target, contractFile, "current-contract", packageRoot);
+  } catch (error) {
+    throw revisionError(`Unable to read replacement contract: ${error.message}`, error.artifacts ?? [contractFile]);
+  }
+  if (artifact.value.taskId !== taskId) {
+    throw revisionError(
+      `Replacement contract taskId "${artifact.value.taskId}" does not match requested taskId "${taskId}"`,
+      [contractFile],
+    );
+  }
+  return artifact.value;
+}
+
+function revisionStateProjection(state, contractFingerprintValue, phase) {
+  const next = {
+    ...state,
+    contractFingerprint: contractFingerprintValue,
+    phase,
+    requiredGates: [],
+    satisfiedGates: [],
+    requiredArtifacts: [],
+    checks: [],
+    failures: [],
+    blockers: [],
+    verificationEvidence: [],
+    completedSteps: phase === "CONTRACT_READY" ? ["contract"] : ["contract", "route"],
+    pendingSteps: phase === "CONTRACT_READY"
+      ? ["route", "planning", "implementation", "verification"]
+      : ["planning", "implementation", "verification"],
+  };
+  delete next.evidenceCoverage;
+  delete next.lastCompletionAttempt;
+  delete next.diagnosedHypothesis;
+  // The revision event carries the explicit PLANNED -> ROUTED rewind proof.
+  // Do not feed the old lifecycle transition marker back into createWorkState:
+  // the global transition table must remain forward-only.
+  delete next.previousPhase;
+  return next;
+}
+
+async function inspectRevisionEligibility({ target, packageRoot, taskId, context }) {
+  const state = await readWorkState(target, { packageRoot, taskId });
+  const contract = await readContract(target, packageRoot, { taskId });
+  if (!state) throw revisionError("Contract revision requires a current work-state checkpoint");
+  if (state.taskId !== taskId) throw revisionError("Work-state task identity does not match the selected task");
+  if (!REVISION_PHASES.has(state.phase)) {
+    throw revisionError(`Contract revision is unavailable in phase ${state.phase}`);
+  }
+  if (state.contractFingerprint !== contract.fingerprint) {
+    throw revisionError("Current work-state is not bound to the current contract artifact");
+  }
+  const ledger = await validateEventLedger(target, packageRoot, { taskId });
+  if (!ledger.valid) throw revisionError("Contract revision requires a valid event ledger", ledger.errors);
+  if (ledger.events.some((event) => event.event === "EXECUTION_STARTED")) {
+    throw revisionError("Contract revision is unavailable after execution has started");
+  }
+  const coherenceErrors = validateStateLedgerCoherence(state, ledger.events);
+  if (coherenceErrors.length > 0) {
+    throw revisionError("Contract revision cannot repair an inconsistent task", coherenceErrors);
+  }
+  const repairAnchor = resolveEffectiveContractBootstrapRepairAnchor(ledger.events);
+  if (repairAnchor) {
+    throw revisionError("Contract revision is unavailable for tasks with a contract-bootstrap repair or migration anchor");
+  }
+  const ownership = await resolveTaskClaimState(target, { taskId, packageRoot });
+  if (!ownership.ownershipValid || !ownership.mutationAllowed) {
+    throw revisionError("Contract revision cannot bypass invalid task ownership", ownership.ownershipErrors);
+  }
+  if (!context?.descriptor || context.descriptor.taskId !== taskId) {
+    throw revisionError("A valid task descriptor is required for contract revision");
+  }
+  return { state, contract, ledger, ownership };
+}
+
+async function assertPreRevisionRouteIdentity({ target, packageRoot, taskId, state, contract }) {
+  if (state.phase === "CONTRACT_READY") return;
+  try {
+    const route = await readPersistedRoute(target, packageRoot, { taskId });
+    assertStateIdentity({ contract, route, state });
+  } catch (error) {
+    throw revisionError(
+      `Contract revision requires a valid current route: ${error.message}`,
+      error.artifacts ?? [],
+    );
+  }
+}
+
+async function reviseLocked({ target, packageRoot, taskId, context, contractFile, preset, transaction }) {
+  await assertTaskMutationAllowed(target, { taskId, packageRoot });
+  await assertWorkspaceBinding(target, { taskId, packageRoot, operation: "contract-revise" });
+  const inspected = await inspectRevisionEligibility({ target, packageRoot, taskId, context });
+  const candidate = await loadCandidate({
+    target,
+    packageRoot,
+    taskId,
+    contractFile,
+    preset,
+    claims: context.descriptor.writeClaims,
+  });
+  await validateContract(candidate, packageRoot);
+  const nextFingerprint = contractFingerprint(candidate);
+  if (nextFingerprint === inspected.contract.fingerprint) {
+    return {
+      taskId,
+      revised: false,
+      alreadyCurrent: true,
+      phase: inspected.state.phase,
+      contractFingerprint: inspected.contract.fingerprint,
+      revision: inspected.state.revision,
+    };
+  }
+
+  await assertPreRevisionRouteIdentity({
+    target,
+    packageRoot,
+    taskId,
+    state: inspected.state,
+    contract: inspected.contract,
+  });
+
+  const before = inspected.state;
+  const nextPhase = before.phase === "PLANNED" ? "ROUTED" : before.phase;
+  const previousRouteFingerprint = before.routeFingerprint ?? null;
+  const projected = revisionStateProjection(before, nextFingerprint, nextPhase);
+  await writeContract(target, candidate, packageRoot, { taskId, operation: "contract-revise" });
+  const next = await mutateWorkState(target, {
+    expectedRevision: before.revision,
+    packageRoot,
+    taskId,
+  }, () => projected);
+  const details = {
+    previousContractFingerprint: inspected.contract.fingerprint,
+    contractFingerprint: nextFingerprint,
+    previousPhase: before.phase,
+    phase: next.phase,
+    previousStateRevision: before.revision,
+    revisedStateRevision: next.revision,
+    previousStateFingerprint: canonicalFingerprint(before),
+    revisedStateFingerprint: canonicalFingerprint(next),
+    previousRouteFingerprint,
+  };
+  assertContractRevisedDetails(details);
+  const event = await appendProtocolEvent(target, {
+    taskId,
+    event: CONTRACT_REVISED_EVENT,
+    details,
+  }, packageRoot, { taskId });
+  const commit = await appendProtocolEvent(target, {
+    taskId,
+    event: "TRANSACTION_COMMITTED",
+    details: { transactionId: transaction.transactionId, operation: "contract-revise" },
+  }, packageRoot, { taskId });
+  return {
+    taskId,
+    revised: true,
+    alreadyCurrent: false,
+    phase: next.phase,
+    previousContractFingerprint: inspected.contract.fingerprint,
+    contractFingerprint: nextFingerprint,
+    previousPhase: before.phase,
+    revision: next.revision,
+    eventSeq: event.seq,
+    transactionCommitSeq: commit.seq,
+  };
+}
+
+export async function runContractRevise({ target, packageRoot, taskId, contractFile = null, preset = null } = {}) {
+  if (!taskId) throw revisionError("contract-revise requires --task");
+  if ((!contractFile && !preset) || (contractFile && preset)) {
+    throw revisionError("contract-revise requires exactly one of --contract-file or --preset");
+  }
+  const context = await resolveTaskContext(target, {
+    taskId,
+    packageRoot,
+    explicitRequired: true,
+    selectionMode: TASK_SELECTION_MODES.MUTATION,
+  });
+  return withTaskTransaction({
+    target,
+    taskId: context.taskId,
+    packageRoot,
+    operation: "contract-revise",
+    recordCommitEvent: false,
+  }, async (transaction) => reviseLocked({
+    target,
+    packageRoot,
+    taskId: context.taskId,
+    context,
+    contractFile,
+    preset,
+    transaction,
+  }));
+}
+
+export function formatContractReviseResult(result) {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}

package/src/commands/decision-show.js

@@ -0,0 +1,14 @@
+import { readDecisionArtifact } from "../core/decision/artifact.js";
+
+export async function runDecisionShow({ target, packageRoot, taskId, decisionId } = {}) {
+  if (typeof taskId !== "string" || !taskId || typeof decisionId !== "string" || !decisionId) {
+    const error = new Error("decision-show requires --task and --decision");
+    error.code = "E_DECISION_REQUEST_INVALID";
+    throw error;
+  }
+  return (await readDecisionArtifact(target, taskId, decisionId, packageRoot)).value;
+}
+
+export function formatDecisionShowResult(result) {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}

package/src/commands/decision-status.js

@@ -0,0 +1,22 @@
+import { readConfig } from "../core/config.js";
+import { DECISION_DEFAULT_POLICY, DECISION_ENGINE_ID, PINNED_JEV_MODEL } from "../core/decision/constants.js";
+import { normalizeDecisionPolicy } from "../core/decision/policy.js";
+import { createTypesafeEngine } from "../adapters/typesafe/engine.js";
+import { hasTypesafeCredentials } from "../adapters/typesafe/client.js";
+
+export async function runDecisionStatus({ target, packageRoot, health = false } = {}) {
+  let policy = DECISION_DEFAULT_POLICY;
+  try {
+    const config = await readConfig(target, packageRoot);
+    policy = normalizeDecisionPolicy(config.decisionEngine ?? DECISION_DEFAULT_POLICY);
+  } catch (error) {
+    if (error.code !== "ARTIFACT_MISSING") throw error;
+  }
+  const result = { required: true, engine: DECISION_ENGINE_ID, model: PINNED_JEV_MODEL, credentials: hasTypesafeCredentials() ? "configured" : "missing", status: hasTypesafeCredentials() ? "configured" : "missing" };
+  if (health) result.health = await createTypesafeEngine({ policy }).health();
+  return result;
+}
+
+export function formatDecisionStatusResult(result) {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}

package/src/commands/discover.js

@@ -0,0 +1,41 @@
+import { appendProtocolEvent, readEvents, validateEventLedger } from "../core/events.js";
+import { withTaskMutation } from "../core/task-command.js";
+
+function initialHistory(events, taskId) {
+  if (events.length < 2) return false;
+  return events[0]?.taskId === taskId
+    && events[0]?.event === "TASK_RECEIVED"
+    && events[1]?.taskId === taskId
+    && events[1]?.event === "TRANSACTION_COMMITTED"
+    && events[1]?.details?.operation === "task-create";
+}
+
+export async function runDiscover({ target, packageRoot, taskId, task } = {}) {
+  return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "discover", async (ctx) => {
+    const events = await readEvents(target, packageRoot, { taskId: ctx.taskId });
+    const ledger = await validateEventLedger(target, packageRoot, { taskId: ctx.taskId });
+    if (!ledger.valid) {
+      const error = new Error("Initial discovery requires a valid task event ledger");
+      error.code = "E_LEDGER_INVALID";
+      error.artifacts = ledger.errors.flatMap((entry) => entry.artifacts ?? []);
+      throw error;
+    }
+    if (!initialHistory(events, ctx.taskId)) {
+      const error = new Error("Initial discovery requires the canonical task-create history");
+      error.code = "E_INITIAL_LIFECYCLE_INVALID";
+      throw error;
+    }
+    const existing = events.find((event) => event.event === "DISCOVERY_STARTED");
+    if (existing) return { taskId: ctx.taskId, phase: "DISCOVERING", idempotent: true, eventSeq: existing.seq };
+    const event = await appendProtocolEvent(target, {
+      taskId: ctx.taskId,
+      event: "DISCOVERY_STARTED",
+      details: { source: "canonical-discover" },
+    }, packageRoot, { taskId: ctx.taskId });
+    return { taskId: ctx.taskId, phase: "DISCOVERING", idempotent: false, eventSeq: event.seq };
+  });
+}
+
+export function formatDiscoverResult(result) {
+  return `phase: ${result.phase}\n${result.idempotent ? "idempotent: true\n" : ""}`;
+}

package/src/commands/doctor.js

@@ -4,11 +4,25 @@ import { readTemplateEntries } from "../core/templates.js";
 import { createEvidence } from "../core/evidence.js";
 import { LAYOUT_VERSION } from "../core/target-layout.js";
 import { inspectNativeAdapter, validateNativeAdapterTargets } from "../core/native-adapters.js";
-import { findIncompleteTransactions, recoverIncompleteTransactions } from "../core/transaction.js";
+import { findIncompleteTransactions } from "../core/transaction.js";
 import { isRepositoryCandidate } from "../repository-index/lifecycle.js";
 import { getRepositoryIndexStatus, sanitizeRepositoryIndexStatus } from "../repository-index/status.js";
 import { searchRepository } from "../repository-index/search.js";
 import { getPersistentTransportStatus } from "../persistent-transport/client.js";
+import { hasTypesafeCredentials } from "../adapters/typesafe/client.js";
+import { PINNED_JEV_MODEL } from "../core/decision/constants.js";
+import { getOperationalStore } from "../storage/operational-context.js";
+
+function semanticDecisionPlaneFinding() {
+  const credentialState = hasTypesafeCredentials() ? "credentials configured" : "credentials missing";
+  return finding(
+    "semantic-decision-plane",
+    "info",
+    ".forgeloop/config.json",
+    `Semantic decision plane: ${credentialState}; pinned model ${PINNED_JEV_MODEL}.`,
+    "Set TYPESAFE_API_KEY in the host environment before invoking a new semantic decision; recovery and inspection remain local.",
+  );
+}
 
 function finding(code, severity, relativePath, message, remediation = null, evidence = null) {
   const evidenceRecord = evidence && typeof evidence === "object"
@@ -180,20 +194,39 @@ async function inspectRepositoryIndexForDoctor({ target, packageRoot, repository
   return result;
 }
 
+async function inspectStorageForDoctor(target, findings) {
+  let storage = null;
+  const store = getOperationalStore(target);
+  if (store) {
+    const { checkStorageIntegrity, readStorageMeta } = await import("../storage/connection.js");
+    const integrity = checkStorageIntegrity(store.db);
+    const metadata = readStorageMeta(store.db);
+    storage = { backend: "sqlite", storageVersion: metadata.storage_version, schemaVersion: metadata.schema_version, integrity };
+    findings.push(finding(
+      integrity.ok ? "sqlite-storage-integrity" : "E_STORAGE_INTEGRITY_INVALID",
+      integrity.ok ? "info" : "error",
+      ".forgeloop/state.sqlite",
+      integrity.ok ? "SQLite pages, foreign keys, ledger hashes and artifact bindings passed storage integrity checks." : "SQLite storage integrity checks failed; no automatic evidence repair was attempted.",
+      integrity.ok ? "Domain chronology and authority still require their existing validators." : "Preserve the database and diagnose the reported storage inconsistencies before writing or migrating.",
+    ));
+  }
+
+  return storage ? { storage } : {};
+}
+
+async function findDoctorTransactions(target) {
+  // SQLite recovery belongs to its native open/transaction boundary. Retained
+  // legacy manifests are import evidence, not operational recovery input.
+  return getOperationalStore(target) ? [] : findIncompleteTransactions(target);
+}
+
 export async function runDoctor({ target, packageRoot, adoptPaths = [], strict = false, fix = false, repositoryIndex, repositoryIndexOptions }) {
   const findings = [];
-  let incompleteTransactions = await findIncompleteTransactions(target);
-  if (fix && incompleteTransactions.some((transaction) => transaction.status === "COMMITTING")) {
-    const recovered = await recoverIncompleteTransactions(target);
-    for (const transaction of recovered) {
-      findings.push(finding(
-        transaction.status === "ROLLED_BACK" ? "TRANSACTION_RECOVERED" : "E_TRANSACTION_RECOVERY_FAILED",
-        transaction.status === "ROLLED_BACK" ? "info" : "error",
-        `.forgeloop/.txn/${transaction.transactionId}`,
-        `Transaction recovery result: ${transaction.status}.`,
-      ));
-    }
-    incompleteTransactions = await findIncompleteTransactions(target);
+  const incompleteTransactions = await findDoctorTransactions(target);
+  if (fix && incompleteTransactions.length) {
+    findings.push(finding("E_STORAGE_OPERATION_UNSUPPORTED", "error", ".forgeloop/.txn",
+      "Filesystem transaction repair is retired; retained evidence was preserved.",
+      "Reconcile incomplete transactions with the compatible pre-migration release before importing into SQLite."));
   }
   for (const transaction of incompleteTransactions) {
     findings.push(finding(
@@ -392,11 +425,16 @@ export async function runDoctor({ target, packageRoot, adoptPaths = [], strict =
     findings,
   });
 
+  findings.push(semanticDecisionPlaneFinding());
+
+  const storageFields = await inspectStorageForDoctor(target, findings);
+
   const ok = findings.every((item) => item.severity !== "error")
     && (!strict || findings.every((item) => item.severity !== "warning"));
   return {
     ok,
     findings,
+    ...storageFields,
     repositoryIndex: repositoryIndexResult,
     evidence: [createEvidence({
       kind: "OBSERVED",

package/src/commands/gate-record.js

@@ -0,0 +1,194 @@
+import path from "node:path";
+import { lstat } from "node:fs/promises";
+
+import { assertSafePath, ensureWithin } from "../core/filesystem.js";
+import { readPersistedRoute } from "../core/route-artifact.js";
+import { readContract } from "../core/contract.js";
+import { readGuideMetadata, requiredGatesForGuides } from "../core/guide-metadata.js";
+import { optionalConfig } from "../core/preflight-loaders.js";
+import { persistGate, readCanonicalGateArtifactBinding, hashGateFile, readGateFileJson } from "../core/gate-artifact.js";
+import { readWorkState } from "../core/work-state.js";
+import { taskArtifactPath, taskGatePath } from "../core/task-paths.js";
+import { withTaskMutation } from "../core/task-command.js";
+import { PROTOCOL_VERSION } from "../core/protocol.js";
+import { staleReasons } from "../core/next-action-artifacts.js";
+import { ARTIFACT_PATHS } from "../core/artifacts.js";
+import { appendProtocolEvent, validateEventLedger } from "../core/events.js";
+
+const STATUSES = new Set(["satisfied", "unverified", "blocked"]);
+const PRE_EXECUTION_PHASES = new Set(["ROUTED", "DESIGNING", "PLANNED"]);
+const MAX_TEXT = 2000;
+const MAX_REPEATABLE_ITEMS = 32;
+const MAX_GATE_ARTIFACT_BYTES = 4 * 1024 * 1024;
+const MAX_GATE_EVIDENCE_BYTES = 64 * 1024;
+const CONFIG_REQUIRED_GATES_MARKER = "config.requiredGates";
+
+const TASK_ARTIFACT_KEYS_BY_PATH = Object.freeze({
+  [ARTIFACT_PATHS.state]: "state",
+  [ARTIFACT_PATHS.contract]: "contract",
+  [ARTIFACT_PATHS.route]: "route",
+});
+
+function gateError(message, options = {}) {
+  const error = new Error(message);
+  error.code = options.code ?? "E_GATE_INVALID";
+  if (options.cause !== undefined) error.cause = options.cause;
+  if (options.artifacts !== undefined) error.artifacts = options.artifacts;
+  return error;
+}
+
+function taskScopedFreshnessPath(taskId, artifactPath) {
+  const key = TASK_ARTIFACT_KEYS_BY_PATH[artifactPath];
+  return key ? taskArtifactPath(taskId, key) : artifactPath;
+}
+
+function bounded(values, name, options = {}) {
+  const maximum = options.maximum ?? MAX_REPEATABLE_ITEMS;
+  if (!Array.isArray(values)) {
+    throw gateError(`${name} must be an array`);
+  }
+  if (values.length > maximum) {
+    throw gateError(`${name} entries must not exceed ${maximum}`);
+  }
+  if (values.some((value) => typeof value !== "string" || value.trim().length === 0 || value.length > MAX_TEXT)) {
+    throw gateError(`${name} entries must be non-empty strings of at most ${MAX_TEXT} characters`);
+  }
+  return values.map((value) => value.trim());
+}
+
+async function hashArtifact(target, artifactPath) {
+  if (typeof artifactPath !== "string" || !artifactPath || path.isAbsolute(artifactPath)) {
+    throw gateError(`Gate artifact must be a project-relative path: ${artifactPath}`);
+  }
+  try {
+    ensureWithin(target, artifactPath);
+  } catch (cause) {
+    throw gateError(`Gate artifact escapes the project: ${artifactPath}`, { cause });
+  }
+  const canonical = readCanonicalGateArtifactBinding(target, artifactPath);
+  if (canonical) {
+    await assertSafePath(target, artifactPath);
+    if (canonical.sha256 === null) throw gateError(`Gate artifact is unavailable: ${artifactPath}`);
+    if (canonical.byteLength > MAX_GATE_ARTIFACT_BYTES) throw gateError(`Gate artifact exceeds the maximum size of ${MAX_GATE_ARTIFACT_BYTES} bytes: ${artifactPath}`);
+    return { path: artifactPath, sha256: canonical.sha256 };
+  }
+  let info;
+  try { info = await lstat(ensureWithin(target, artifactPath)); }
+  catch (cause) { throw gateError(`Gate artifact is unavailable: ${artifactPath}`, { cause }); }
+  if (!info.isFile() || info.isSymbolicLink()) throw gateError(`Gate artifact must be a regular file: ${artifactPath}`);
+  if (info.size > MAX_GATE_ARTIFACT_BYTES) throw gateError(`Gate artifact exceeds the maximum size of ${MAX_GATE_ARTIFACT_BYTES} bytes: ${artifactPath}`);
+  try {
+    const binding = await hashGateFile(target, artifactPath, { maxBytes: MAX_GATE_ARTIFACT_BYTES });
+    return { path: artifactPath, sha256: binding.sha256 };
+  } catch (cause) {
+    throw gateError(`Gate artifact is unavailable or unsafe: ${artifactPath}`, { cause });
+  }
+}
+
+async function readEvidenceFile(target, evidencePath) {
+  if (typeof evidencePath !== "string" || !evidencePath || path.isAbsolute(evidencePath)) {
+    throw gateError(`Gate evidence must be a project-relative path: ${evidencePath}`);
+  }
+  try {
+    const value = await readGateFileJson(target, evidencePath, { maxBytes: MAX_GATE_EVIDENCE_BYTES });
+    return { path: evidencePath, value };
+  } catch (cause) {
+    throw gateError(`Gate evidence file is invalid: ${evidencePath}`, { cause });
+  }
+}
+
+async function assertCurrentRoute(target, packageRoot, taskId, state, route) {
+  let contract;
+  try {
+    contract = await readContract(target, packageRoot, { taskId });
+  } catch (cause) {
+    throw gateError(`Cannot verify the active route against the current contract: ${cause.message}`, {
+      code: "E_ROUTE_STALE",
+      cause,
+    });
+  }
+  const freshness = staleReasons(state, contract, route);
+  if (freshness.length === 0) return;
+  const reason = freshness.find((entry) => entry.code === "E_ROUTE_STALE") ?? freshness[0];
+  throw gateError(reason.message, {
+    code: reason.code,
+    artifacts: reason.artifacts.map((artifactPath) => taskScopedFreshnessPath(taskId, artifactPath)),
+  });
+}
+
+function hasCurrentEpochGateEvent(events, taskId, gate) {
+  const latestRevisionSeq = events.findLast((event) => event.event === "CONTRACT_REVISED")?.seq ?? 0;
+  return events.some((event) => event.event === "GATE_SATISFIED"
+    && event.taskId === taskId
+    && event.details?.gate === gate
+    && event.seq > latestRevisionSeq);
+}
+
+export async function runGateRecord({ target, packageRoot, taskId, gate, status, artifacts = [], decisions = [], unknowns = [], assumptions = [], evidenceFile = null } = {}) {
+  if (!STATUSES.has(status)) {
+    throw gateError(`Invalid gate status: ${status}`);
+  }
+  return withTaskMutation(target, { taskId, packageRoot }, "gate-record", async (ctx) => {
+    const state = await readWorkState(target, { packageRoot, taskId: ctx.taskId });
+    if (!state || !PRE_EXECUTION_PHASES.has(state.phase)) {
+      throw gateError(`gate-record is only available before execution; found ${state?.phase ?? "no phase"}`, { code: "E_PHASE_FREEZE" });
+    }
+    const route = await readPersistedRoute(target, packageRoot, { taskId: ctx.taskId });
+    await assertCurrentRoute(target, packageRoot, ctx.taskId, state, route);
+    const config = await optionalConfig(target, packageRoot, []);
+    const required = [...new Set([...(await requiredGatesForGuides(route.value.guides, packageRoot)), ...(config.requiredGates ?? [])])];
+    if (!required.includes(gate)) {
+      throw gateError(`Gate is not required by the active route: ${gate}`, { code: "E_GATE_NOT_REQUIRED" });
+    }
+    const artifactPaths = bounded(artifacts, "artifact");
+    const normalizedDecisions = bounded(decisions, "decision");
+    const normalizedUnknowns = bounded(unknowns, "unknown");
+    const approvedAssumptions = bounded(assumptions, "assumption");
+    const fileEvidence = evidenceFile ? await readEvidenceFile(target, evidenceFile) : null;
+    if (status === "satisfied" && (normalizedUnknowns.length > 0 || (normalizedDecisions.length === 0 && !fileEvidence))) {
+      throw gateError("A satisfied gate requires no unknowns and at least one decision");
+    }
+    const hashedArtifacts = [];
+    for (const artifactPath of artifactPaths) hashedArtifacts.push(await hashArtifact(target, artifactPath));
+    const guideMetadata = await readGuideMetadata(packageRoot);
+    const requiredBy = [
+      ...route.value.guides.filter((guide) => (guideMetadata[guide]?.requiresGates ?? []).includes(gate)),
+      ...((config.requiredGates ?? []).includes(gate) ? [CONFIG_REQUIRED_GATES_MARKER] : []),
+    ];
+    const value = {
+      schemaVersion: 1,
+      protocolVersion: PROTOCOL_VERSION,
+      taskId: ctx.taskId,
+      gate,
+      status,
+      requiredBy,
+      artifacts: hashedArtifacts,
+      decisions: normalizedDecisions,
+      unknowns: normalizedUnknowns,
+      approvedAssumptions,
+      evidence: [
+        ...normalizedDecisions.map((decision) => ({ kind: "CALLER_RECORDED", authority: "CALLER", text: decision })),
+        ...(fileEvidence ? [{ kind: "CALLER_RECORDED", authority: "CALLER", path: fileEvidence.path, details: fileEvidence.value }] : []),
+      ],
+    };
+    const persisted = await persistGate(target, value, packageRoot, { taskId: ctx.taskId });
+    if (status === "satisfied") {
+      const ledger = await validateEventLedger(target, packageRoot, { taskId: ctx.taskId });
+      if (!ledger.valid) {
+        throw gateError("gate-record requires a valid event ledger", { code: "E_EVENT_INVALID", artifacts: ledger.errors });
+      }
+      if (!hasCurrentEpochGateEvent(ledger.events, ctx.taskId, gate)) {
+        await appendProtocolEvent(target, {
+          taskId: ctx.taskId,
+          event: "GATE_SATISFIED",
+          details: { gate },
+        }, packageRoot, { taskId: ctx.taskId });
+      }
+    }
+    return { taskId: ctx.taskId, gate, status, path: persisted.path ?? persisted.relativePath ?? taskGatePath(ctx.taskId, gate), artifacts: hashedArtifacts };
+  });
+}
+
+export function formatGateRecordResult(result) {
+  return `gate: ${result.gate}\nstatus: ${result.status}\n`;
+}