@cassiomc1/forgeloop 1.14.0 → 2.0.0-rc.4

package/src/core/contract-bootstrap-recovery.js

@@ -1,3 +1,5 @@
+import { ledgerRelationMap } from "./ledger-relations.js";
+import { isLedgerEventCollection, ledgerEventAt, ledgerEventAtIs, ledgerEventsOfTypes, ledgerTypeSummary } from "./ledger-event-collection.js";
 import { canonicalFingerprint } from "./artifacts.js";
 
 export const CONTRACT_BOOTSTRAP_REPAIR_EVENT = "CONTRACT_BOOTSTRAP_REPAIR_RECORDED";
@@ -212,13 +214,13 @@ function isRepairTransactionCommit(event, taskId) {
  * repair transaction merely because they follow the marker.
  */
 export function resolveContractBootstrapRepairBoundary(events, marker = null) {
-  if (!Array.isArray(events)) return null;
-  const markers = events.filter((event) => event.event === CONTRACT_BOOTSTRAP_REPAIR_EVENT);
-  if (markers.length !== 1) return null;
-  const resolvedMarker = marker ?? markers[0];
+  if (!isLedgerEventCollection(events)) return null;
+  const { count, first } = ledgerTypeSummary(events, CONTRACT_BOOTSTRAP_REPAIR_EVENT);
+  if (count !== 1) return null;
+  const resolvedMarker = marker ?? first;
   const markerIndex = events.indexOf(resolvedMarker);
   if (markerIndex < 0 || resolvedMarker.seq !== markerIndex + 1) return null;
-  const repairCommit = events[markerIndex + 1];
+  const repairCommit = ledgerEventAt(events, markerIndex + 1);
   if (!isRepairTransactionCommit(repairCommit, resolvedMarker.taskId)
     || repairCommit.seq !== resolvedMarker.seq + 1) return null;
   return {
@@ -261,7 +263,7 @@ export function resolveCanonicalRouteEvolution(events, {
   targetRouteFingerprint,
   contractFingerprint,
 } = {}) {
-  if (!Array.isArray(events)
+  if (!isLedgerEventCollection(events)
     || typeof taskId !== "string" || !taskId
     || !Number.isInteger(sourceSeq) || sourceSeq < 0
     || (sourceRouteFingerprint !== null && !isFingerprint(sourceRouteFingerprint))
@@ -270,9 +272,9 @@ export function resolveCanonicalRouteEvolution(events, {
   let currentFingerprint = sourceRouteFingerprint;
   const reboundEvents = [];
   for (let index = 0; index < events.length - 1; index += 1) {
-    const reboundEvent = events[index];
+    const reboundEvent = ledgerEventAt(events, index);
     if (reboundEvent?.seq <= sourceSeq || reboundEvent?.event !== "ROUTE_REBOUND") continue;
-    const routeCommit = events[index + 1];
+    const routeCommit = ledgerEventAt(events, index + 1);
     if (!isCanonicalRouteReboundBoundary(reboundEvent, routeCommit, {
       taskId,
       contractFingerprint,
@@ -315,8 +317,8 @@ export function resolveCanonicalPostRepairCheckpointBinding(events, marker) {
   if (checkpointEvents.length !== 1) return null;
   const checkpointEvent = checkpointEvents[0];
   const checkpointIndex = boundary.postRepairEvents.indexOf(checkpointEvent);
-  const phaseEvent = boundary.postRepairEvents[checkpointIndex + 1];
-  const transactionCommit = boundary.postRepairEvents[checkpointIndex + 2];
+  const phaseEvent = ledgerEventAt(boundary.postRepairEvents, checkpointIndex + 1);
+  const transactionCommit = ledgerEventAt(boundary.postRepairEvents, checkpointIndex + 2);
   const details = checkpointEvent.details;
   if (checkpointEvent.taskId !== boundary.marker.taskId
     || checkpointEvent.hash !== eventHash(checkpointEvent)
@@ -343,26 +345,25 @@ export function resolveCanonicalPostRepairCheckpointBinding(events, marker) {
 }
 
 export function isContractBootstrapRepairCandidate(events, ledgerErrors = [], taskId = null) {
-  if (!Array.isArray(events) || events.length < 4) return null;
-  const effectiveTaskId = taskId ?? events[0]?.taskId;
+  if (!isLedgerEventCollection(events) || events.length < 4) return null;
+  const effectiveTaskId = taskId ?? ledgerEventAt(events, 0)?.taskId;
   if (typeof effectiveTaskId !== "string" || !effectiveTaskId) return null;
   if (events.some((event) => event.taskId !== effectiveTaskId)) return null;
-  if (events.some((event) => event.event === CONTRACT_BOOTSTRAP_REPAIR_EVENT)) return null;
-  if (events[0]?.event !== "TASK_RECEIVED" || events[1]?.event !== "TRANSACTION_COMMITTED"
-    || events[1]?.details?.operation !== "task-create") return null;
+  if (ledgerTypeSummary(events, CONTRACT_BOOTSTRAP_REPAIR_EVENT).count) return null;
+  if (ledgerEventAt(events, 0)?.event !== "TASK_RECEIVED" || ledgerEventAt(events, 1)?.event !== "TRANSACTION_COMMITTED"
+    || ledgerEventAt(events, 1)?.details?.operation !== "task-create") return null;
   if (!events.some((event) => event.event === "DISCOVERY_STARTED")) return null;
-  const contractEvents = events.filter((event) => event.event === "CONTRACT_VALIDATED");
-  if (contractEvents.length !== 2) return null;
-  const [canonical, duplicate] = contractEvents;
+  const { count: contractCount, first: canonical, latest: duplicate } = ledgerTypeSummary(events, "CONTRACT_VALIDATED");
+  if (contractCount !== 2) return null;
   if (!isFingerprint(canonical.details?.contractFingerprint)
     || canonical.details.contractFingerprint !== duplicate.details?.contractFingerprint) return null;
   if (canonical.hash !== eventHash(canonical) || duplicate.hash !== eventHash(duplicate)) return null;
   const canonicalIndex = events.indexOf(canonical);
   const duplicateIndex = events.indexOf(duplicate);
-  const canonicalCommit = events[canonicalIndex + 1];
-  const duplicateCommit = events[duplicateIndex + 1];
+  const canonicalCommit = ledgerEventAt(events, canonicalIndex + 1);
+  const duplicateCommit = ledgerEventAt(events, duplicateIndex + 1);
   if (!isCommitFor(canonicalCommit, "contract-create") || !isCommitFor(duplicateCommit, "contract-create")) return null;
-  if (duplicateIndex !== events.length - 2 || events.at(-1) !== duplicateCommit) return null;
+  if (duplicateIndex !== events.length - 2 || !ledgerEventAtIs(events, events.length - 1, duplicateCommit)) return null;
   if (events.some((event) => HISTORICAL_EVENTS.has(event.event))) return null;
   if (!Array.isArray(ledgerErrors) || ledgerErrors.length < 1) return null;
   if (ledgerErrors.some((error) => !isExactDuplicateContractChronologyError(error))) return null;
@@ -383,7 +384,7 @@ export function isContractBootstrapRepairMarkerValid(events, marker) {
     if (!resolveContractBootstrapRepairBoundary(events, marker)) return false;
     assertContractBootstrapRepairDetails(marker.details);
     if (marker.taskId !== marker.details.taskId || marker.hash !== eventHash(marker)) return false;
-    if (marker.seq < 1 || events[marker.seq - 1] !== marker) return false;
+    if (marker.seq < 1 || !ledgerEventAtIs(events, marker.seq - 1, marker)) return false;
     const prefix = events.slice(0, marker.seq - 1);
     const prefixErrors = [];
     const candidate = isContractBootstrapRepairCandidate(prefix, prefixErrors, marker.taskId);
@@ -528,11 +529,11 @@ function migrationMatchesLegacyRepairBoundary({ migration, marker, repairCommit
 }
 
 function resolveContractBootstrapRepairMigration(events, migration) {
-  if (!Array.isArray(events) || !migration || migration.event !== CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_EVENT) return null;
+  if (!isLedgerEventCollection(events) || !migration || migration.event !== CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_EVENT) return null;
   const marker = events.find((event) => event.seq === migration.details?.legacyMarkerSeq);
   const markerIndex = marker ? events.indexOf(marker) : -1;
   const migrationIndex = events.indexOf(migration);
-  const commit = events[migrationIndex + 1];
+  const commit = ledgerEventAt(events, migrationIndex + 1);
   const boundary = marker ? resolveContractBootstrapRepairBoundary(events, marker) : null;
   if (!marker || !isLegacyContractBootstrapRepairMarkerShape(marker)
     || markerIndex < 0 || !boundary
@@ -545,9 +546,9 @@ function resolveContractBootstrapRepairMigration(events, migration) {
 }
 
 export function validateContractBootstrapRepairMigrations(events, errors, { allowUnmigratedLegacyContractBootstrapRepairMarkers = false } = {}) {
-  const markers = events.filter((event) => event.event === CONTRACT_BOOTSTRAP_REPAIR_EVENT);
-  const migrations = events.filter((event) => event.event === CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_EVENT);
-  const migrationBySeq = new Map();
+  const markers = ledgerEventsOfTypes(events, [CONTRACT_BOOTSTRAP_REPAIR_EVENT]);
+  const migrations = ledgerEventsOfTypes(events, [CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_EVENT]);
+  const migrationBySeq = ledgerRelationMap();
   for (const migration of migrations) {
     try {
       assertContractBootstrapRepairMigrationDetails(migration.details);
@@ -569,14 +570,15 @@ export function validateContractBootstrapRepairMigrations(events, errors, { allo
       });
       continue;
     }
-    migrationBySeq.set(migration.details.legacyMarkerSeq, migration);
+    migrationBySeq.set(migration.details.legacyMarkerSeq, events.indexOf(migration));
   }
-  if (markers.length > 1) {
+  if (ledgerTypeSummary(events, CONTRACT_BOOTSTRAP_REPAIR_EVENT).count > 1) {
     errors.push({ code: "E_CONTRACT_BOOTSTRAP_REPAIR_INVALID", message: "contract bootstrap repair marker must occur at most once" });
   }
   for (const marker of markers) {
     if (!isLegacyContractBootstrapRepairMarkerShape(marker)) continue;
-    const migration = migrationBySeq.get(marker.seq);
+    const migrationPosition = migrationBySeq.get(marker.seq);
+    const migration = migrationPosition === undefined ? undefined : ledgerEventAt(events, migrationPosition);
     if (!migration) {
       if (!allowUnmigratedLegacyContractBootstrapRepairMarkers) {
         errors.push({
@@ -595,7 +597,8 @@ export function validateContractBootstrapRepairMigrations(events, errors, { allo
       });
     }
   }
-  for (const [legacySeq, migration] of migrationBySeq) {
+  for (const [legacySeq, position] of migrationBySeq) {
+    const migration = ledgerEventAt(events, position);
     errors.push({
       code: "E_EVENT_INVALID",
       message: `migration event ${migration.seq} references unknown legacy contract bootstrap repair marker seq ${legacySeq}`,
@@ -604,24 +607,22 @@ export function validateContractBootstrapRepairMigrations(events, errors, { allo
 }
 
 export function isLegacyContractBootstrapRepairMigrationCandidate(events, taskId = null) {
-  if (!Array.isArray(events)) return null;
-  const markers = events.filter((event) => event.event === CONTRACT_BOOTSTRAP_REPAIR_EVENT);
-  if (markers.length !== 1) return null;
-  const marker = markers[0];
+  if (!isLedgerEventCollection(events)) return null;
+  const { count, first: marker } = ledgerTypeSummary(events, CONTRACT_BOOTSTRAP_REPAIR_EVENT);
+  if (count !== 1) return null;
   if (!isLegacyContractBootstrapRepairMarkerShape(marker)) return null;
   const effectiveTaskId = taskId ?? marker.taskId;
   if (marker.taskId !== effectiveTaskId || events.some((event) => event.taskId !== effectiveTaskId)) return null;
-  if (events.some((event) => event.event === CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_EVENT)) return null;
+  if (ledgerTypeSummary(events, CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_EVENT).count) return null;
   const boundary = resolveContractBootstrapRepairBoundary(events, marker);
   if (!boundary || boundary.postRepairEvents.length > 0) return null;
   return { taskId: effectiveTaskId, marker, repairCommit: boundary.repairCommit };
 }
 
 export function resolveEffectiveContractBootstrapRepairAnchor(events) {
-  if (!Array.isArray(events)) return null;
-  const markers = events.filter((event) => event.event === CONTRACT_BOOTSTRAP_REPAIR_EVENT);
-  if (markers.length !== 1) return null;
-  const sourceMarker = markers[0];
+  if (!isLedgerEventCollection(events)) return null;
+  const { count, first: sourceMarker } = ledgerTypeSummary(events, CONTRACT_BOOTSTRAP_REPAIR_EVENT);
+  if (count !== 1) return null;
   if (isContractBootstrapRepairMarkerValid(events, sourceMarker)) {
     return { kind: "MODERN", sourceMarker, details: sourceMarker.details };
   }
@@ -643,7 +644,7 @@ export function resolveEffectiveContractBootstrapRepairAnchor(events) {
 }
 
 export function repairMarkerErrors(events, errors, { allowUnmigratedLegacyContractBootstrapRepairMarkers = false } = {}) {
-  const marker = events.find((event) => event.event === CONTRACT_BOOTSTRAP_REPAIR_EVENT);
+  const marker = ledgerTypeSummary(events, CONTRACT_BOOTSTRAP_REPAIR_EVENT).first;
   const boundary = resolveContractBootstrapRepairBoundary(events, marker);
   const migratedLegacy = resolveEffectiveContractBootstrapRepairAnchor(events)?.kind === "MIGRATED_LEGACY";
   const recognized = isContractBootstrapRepairMarkerValid(events, marker)

package/src/core/contract-revision.js

@@ -1,3 +1,4 @@
+import { isLedgerEventCollection, ledgerEventAt, ledgerEventsOfTypes, ledgerTypeSummary } from "./ledger-event-collection.js";
 import { canonicalFingerprint } from "./artifacts.js";
 
 export const CONTRACT_REVISED_EVENT = "CONTRACT_REVISED";
@@ -87,13 +88,13 @@ function validRevisionCommit(revisionEvent, commitEvent) {
 }
 
 export function resolveContractRevisionBoundary(events, revisionEvent) {
-  if (!Array.isArray(events) || !revisionEvent || revisionEvent.event !== CONTRACT_REVISED_EVENT) return null;
+  if (!isLedgerEventCollection(events) || !revisionEvent || revisionEvent.event !== CONTRACT_REVISED_EVENT) return null;
   const index = events.findIndex((event) => event === revisionEvent
     || (event?.seq === revisionEvent.seq
       && event?.taskId === revisionEvent.taskId
       && event?.event === CONTRACT_REVISED_EVENT));
   if (index < 0) return null;
-  const commitEvent = events[index + 1];
+  const commitEvent = ledgerEventAt(events, index + 1);
   return validRevisionCommit(revisionEvent, commitEvent)
     ? { revisionEvent, transactionCommitEvent: commitEvent }
     : null;
@@ -105,7 +106,7 @@ export function resolveCanonicalContractEvolution(events, {
   sourceContractFingerprint,
   targetContractFingerprint,
 } = {}) {
-  if (!Array.isArray(events)
+  if (!isLedgerEventCollection(events)
     || typeof taskId !== "string" || !taskId
     || !Number.isInteger(sourceSeq) || sourceSeq < 0
     || !isFingerprint(sourceContractFingerprint)
@@ -138,12 +139,12 @@ export function resolveCanonicalContractEvolution(events, {
 }
 
 export function latestContractRevision(events = []) {
-  return events.filter((event) => event.event === CONTRACT_REVISED_EVENT).at(-1) ?? null;
+  return ledgerTypeSummary(events, CONTRACT_REVISED_EVENT).latest ?? null;
 }
 
 export function validateContractRevisionEventBindings(events = []) {
   const errors = [];
-  const revisions = events.filter((event) => event.event === CONTRACT_REVISED_EVENT);
+  const revisions = ledgerEventsOfTypes(events, [CONTRACT_REVISED_EVENT]);
   let currentContractFingerprint = null;
   let currentStateRevision = null;
   for (const event of revisions) {
@@ -184,10 +185,8 @@ export function validateContractRevisionEventBindings(events = []) {
 
 export function validateContractRevisionCurrentBinding(state, events = []) {
   const errors = [];
-  const revisions = events.filter((event) => event.event === CONTRACT_REVISED_EVENT);
-  if (revisions.length === 0) return errors;
-  const first = revisions[0];
-  const latest = revisions.at(-1);
+  const { count, first, latest } = ledgerTypeSummary(events, CONTRACT_REVISED_EVENT);
+  if (!count) return errors;
   const initial = events.find((event) => event.taskId === state?.taskId && event.event === "CONTRACT_VALIDATED");
   const evolution = resolveCanonicalContractEvolution(events, {
     taskId: state?.taskId,

package/src/core/decision/artifact.js

@@ -5,6 +5,7 @@ import { assertSecretFree } from "../receipt.js";
 import { DECISION_AUTHORITY, DECISION_EVIDENCE_AUTHORITY, DECISION_POLICY_VERSION, PINNED_JEV_MODEL } from "./constants.js";
 import { DECISION_ERROR_CODES, decisionError } from "./errors.js";
 import { getTaskTransaction, withTaskTransaction } from "../transaction.js";
+import { operationalArtifactExists } from "../../storage/operational-context.js";
 
 export function buildDecisionArtifact(input = {}) {
   const artifact = {
@@ -58,7 +59,7 @@ export async function writeDecisionArtifact(target, taskId, decisionId, artifact
     ));
   }
   const relativePath = taskDecisionPath(taskId, decisionId);
-  if (await fileExists(ensureWithin(target, relativePath))) {
+  if (operationalArtifactExists(target, relativePath) ?? await fileExists(ensureWithin(target, relativePath))) {
     throw decisionError(DECISION_ERROR_CODES.IMMUTABLE, `Semantic decision artifact already exists: ${decisionId}`);
   }
   return writeJsonArtifact(target, relativePath, artifact, "semantic-decision", packageRoot, { ...options, taskId, operation: "semantic-decision" });

package/src/core/decision/events.js

@@ -1,3 +1,5 @@
+import { ledgerRelationSet } from "../ledger-relations.js";
+import { ledgerEventsOfTypes } from "../ledger-event-collection.js";
 import { canonicalFingerprint } from "../artifacts.js";
 import { readDecisionArtifact } from "./artifact.js";
 import { DECISION_KINDS, DECISION_STATUS, SEMANTIC_DECISION_RECORDED_EVENT, SEMANTIC_DECISION_SUPERSEDED_EVENT } from "./constants.js";
@@ -42,8 +44,8 @@ export function decisionSupersededEventDetails(previousArtifact, supersededBy) {
 
 export function validateSemanticDecisionEventBindings(events = []) {
   const errors = [];
-  const recorded = new Map();
-  for (const event of events) {
+  const recorded = ledgerRelationSet();
+  for (const event of ledgerEventsOfTypes(events, [SEMANTIC_DECISION_RECORDED_EVENT, SEMANTIC_DECISION_SUPERSEDED_EVENT])) {
     if (![SEMANTIC_DECISION_RECORDED_EVENT, SEMANTIC_DECISION_SUPERSEDED_EVENT].includes(event.event)) continue;
     try { assertSemanticDecisionDetails(event.details, event.event); } catch (error) {
       errors.push({ code: error.code ?? DECISION_ERROR_CODES.RESULT_INVALID, message: `event ${event.seq} (${event.event}): ${error.message}` });
@@ -54,7 +56,7 @@ export function validateSemanticDecisionEventBindings(events = []) {
       if (recorded.has(key)) {
         errors.push({ code: DECISION_ERROR_CODES.RESULT_INVALID, message: `event ${event.seq} records duplicate decision ID ${event.details.decisionId}` });
       }
-      recorded.set(key, event);
+      recorded.add(key);
     }
     if (event.event === SEMANTIC_DECISION_SUPERSEDED_EVENT) {
       const key = `${event.taskId}:${event.details.decisionId}`;
@@ -79,12 +81,12 @@ export function validateSemanticDecisionEventBindings(events = []) {
   return errors;
 }
 
-export async function validateSemanticDecisionArtifactBindings(target, packageRoot, events = []) {
+export async function validateSemanticDecisionArtifactBindings(target, packageRoot, events = [], { reader = readDecisionArtifact } = {}) {
   const errors = [];
-  for (const event of events) {
+  for (const event of ledgerEventsOfTypes(events, [SEMANTIC_DECISION_RECORDED_EVENT])) {
     if (event.event !== SEMANTIC_DECISION_RECORDED_EVENT) continue;
     try {
-      const artifact = (await readDecisionArtifact(target, event.taskId, event.details.decisionId, packageRoot)).value;
+      const artifact = (await reader(target, event.taskId, event.details.decisionId, packageRoot)).value;
       if (artifact.taskId !== event.taskId
         || artifact.decisionId !== event.details.decisionId
         || canonicalFingerprint(artifact) !== event.details.artifactFingerprint
@@ -94,6 +96,7 @@ export async function validateSemanticDecisionArtifactBindings(target, packageRo
         errors.push({ code: DECISION_ERROR_CODES.LEDGER_INVALID, message: `event ${event.seq} does not match its immutable semantic decision artifact` });
       }
     } catch (error) {
+      if (error.code === "E_STATE_REVISION_CONFLICT") throw error;
       errors.push({ code: DECISION_ERROR_CODES.LEDGER_INVALID, message: `event ${event.seq} semantic decision artifact is unavailable or invalid` });
     }
   }

package/src/core/decision/resolver.js

@@ -2,12 +2,14 @@ import { readdir } from "node:fs/promises";
 
 import { canonicalFingerprint, readJsonArtifact } from "../artifacts.js";
 import { fileExists, ensureWithin } from "../filesystem.js";
-import { readEvents, validateEventLedger } from "../events.js";
+import { validateEventLedger } from "../events.js";
 import { taskDecisionDirectory } from "../task-paths.js";
 import { getQuestionSet } from "./question-registry.js";
 import { DECISION_ERROR_CODES, decisionError } from "./errors.js";
 import { DECISION_ENGINE_ID, DECISION_POLICY_VERSION, PINNED_JEV_MODEL, SEMANTIC_DECISION_RECORDED_EVENT, SEMANTIC_DECISION_SUPERSEDED_EVENT } from "./constants.js";
 import { assertDecisionFresh } from "./freshness.js";
+import { listOperationalArtifactNames } from "../../storage/operational-context.js";
+import { withProjectReadSnapshot } from "../../storage/project-read-snapshot.js";
 
 function invalid(message, code = DECISION_ERROR_CODES.BINDING_INVALID) {
   return decisionError(code, message);
@@ -89,14 +91,16 @@ export function assertRequiredFreshDecision({ artifact, currentBindings = {}, ex
 
 async function decisionArtifacts(target, taskId, packageRoot) {
   const directory = taskDecisionDirectory(taskId);
-  const absolute = ensureWithin(target, directory);
-  if (!(await fileExists(absolute))) return [];
-  const names = (await readdir(absolute, { withFileTypes: true }))
-    .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
-    .map((entry) => entry.name.slice(0, -5))
-    .sort();
+  let names = listOperationalArtifactNames(target, taskId, "decisions");
+  if (names === null) {
+    const absolute = ensureWithin(target, directory);
+    if (!(await fileExists(absolute))) return [];
+    names = (await readdir(absolute, { withFileTypes: true }))
+      .filter(entry => entry.isFile()).map(entry => entry.name);
+  }
+  const ids = names.filter(name => name.endsWith(".json")).map(name => name.slice(0, -5)).sort();
   const artifacts = [];
-  for (const decisionId of names) {
+  for (const decisionId of ids) {
     try {
       artifacts.push((await readJsonArtifact(target, `${directory}/${decisionId}.json`, "semantic-decision", packageRoot)).value);
     } catch {
@@ -106,11 +110,15 @@ async function decisionArtifacts(target, taskId, packageRoot) {
   return artifacts;
 }
 
-export async function resolveRequiredSemanticDecision({ target, packageRoot, taskId, decisionKind, decisionId = null, currentBindings = {} } = {}) {
-  if (typeof taskId !== "string" || !taskId) throw decisionError(DECISION_ERROR_CODES.REQUIRED, "A task-bound semantic decision is required.");
+export async function resolveRequiredSemanticDecision(options = {}) {
+  if (typeof options.taskId !== "string" || !options.taskId) throw decisionError(DECISION_ERROR_CODES.REQUIRED, "A task-bound semantic decision is required.");
+  return withProjectReadSnapshot(options.target, () => resolveSelectedSemanticDecision(options));
+}
+
+async function resolveSelectedSemanticDecision({ target, packageRoot, taskId, decisionKind, decisionId = null, currentBindings = {} }) {
   const ledgerResult = await validateEventLedger(target, packageRoot, { taskId });
   if (!ledgerResult.valid) throw decisionError(DECISION_ERROR_CODES.LEDGER_INVALID, "The task ledger is invalid for semantic decision resolution.", ledgerResult.errors);
-  const events = await readEvents(target, packageRoot, { taskId });
+  const events = ledgerResult.events;
   const candidates = decisionId
     ? [(await readJsonArtifact(target, `${taskDecisionDirectory(taskId)}/${decisionId}.json`, "semantic-decision", packageRoot)).value]
     : await decisionArtifacts(target, taskId, packageRoot);

package/src/core/decision/service.js

@@ -1,6 +1,6 @@
 import { canonicalFingerprint } from "../artifacts.js";
 import { readConfig } from "../config.js";
-import { appendProtocolEvent, readEvents } from "../events.js";
+import { appendProtocolEvent, iterateEvents } from "../events.js";
 import { withTaskMutation } from "../task-command.js";
 import { DECISION_DEFAULT_POLICY, PINNED_JEV_MODEL, SEMANTIC_DECISION_RECORDED_EVENT } from "./constants.js";
 import { buildDecisionArtifact, decisionArtifactFingerprint, readDecisionArtifact, writeDecisionArtifact } from "./artifact.js";
@@ -15,6 +15,15 @@ import { resolveRequiredSemanticDecision } from "./resolver.js";
 import { DECISION_ERROR_CODES, decisionError } from "./errors.js";
 import { getTaskTransaction } from "../transaction.js";
 import { getTestSemanticProvider } from "./test-provider.js";
+import { needsExistingProjectScope, withExistingProjectScope } from "../../storage/existing-project-scope.js";
+import { withProjectReadSnapshot } from "../../storage/project-read-snapshot.js";
+
+async function withDecisionScope(options, run) {
+  if (options.target && options.taskId && await needsExistingProjectScope(options.target)) {
+    return withExistingProjectScope(options.target, () => run(options));
+  }
+  return run(options);
+}
 
 function resolveProvider(provider) {
   return provider ?? getTestSemanticProvider();
@@ -50,7 +59,7 @@ function buildArtifact({ taskId, decisionId, policy, validated, result, request,
     questionSetFingerprint: validated.questionSet.fingerprint,
     questionSet: validated.questionSet,
     stateFingerprint: canonicalFingerprint(validated.state),
-    taskStateFingerprint: canonicalFingerprint(validated.state.lifecycle),
+    taskStateFingerprint: taskBindings.taskStateFingerprint ?? canonicalFingerprint(validated.state.lifecycle),
     semanticStateFingerprint: canonicalFingerprint(validated.state.semantic),
     policyVersion: policy.policyVersion,
     policyFingerprint: decisionPolicyFingerprint(policy),
@@ -77,7 +86,7 @@ async function readCachedSemanticDecision({ policy, decisionId, target, taskId,
     currentBindings: {
       ...taskBindings,
       stateFingerprint: canonicalFingerprint(validated.state),
-      taskStateFingerprint: canonicalFingerprint(validated.state.lifecycle),
+      taskStateFingerprint: taskBindings.taskStateFingerprint ?? canonicalFingerprint(validated.state.lifecycle),
       semanticStateFingerprint: canonicalFingerprint(validated.state.semantic),
       questionSetFingerprint: validated.questionSet.fingerprint,
       policyFingerprint: decisionPolicyFingerprint(policy),
@@ -90,13 +99,15 @@ async function readCachedSemanticDecision({ policy, decisionId, target, taskId,
 
 async function persistDecision(target, packageRoot, resolvedDecisionId, artifact, ctx) {
   await writeDecisionArtifact(target, ctx.taskId, resolvedDecisionId, artifact, packageRoot, { taskId: ctx.taskId, operation: "semantic-decision" });
-  const priorEvents = await readEvents(target, packageRoot, { taskId: ctx.taskId });
+  const priorRecords = [];
+  const supersededIds = new Set();
+  for await (const candidate of iterateEvents(target, packageRoot, { taskId: ctx.taskId })) {
+    if (candidate.event === SEMANTIC_DECISION_RECORDED_EVENT && candidate.taskId === ctx.taskId
+      && candidate.details?.decisionKind === artifact.decisionKind) priorRecords.push(candidate);
+    if (candidate.event === "SEMANTIC_DECISION_SUPERSEDED") supersededIds.add(candidate.details?.decisionId);
+  }
   const event = await appendProtocolEvent(target, { taskId: ctx.taskId, event: SEMANTIC_DECISION_RECORDED_EVENT, details: decisionEventDetails(artifact) }, packageRoot, { taskId: ctx.taskId });
-  const previous = priorEvents.findLast((candidate) => candidate.event === SEMANTIC_DECISION_RECORDED_EVENT
-    && candidate.taskId === ctx.taskId
-    && candidate.details?.decisionKind === artifact.decisionKind
-    && !priorEvents.some((superseded) => superseded.event === "SEMANTIC_DECISION_SUPERSEDED"
-      && superseded.details?.decisionId === candidate.details?.decisionId));
+  const previous = priorRecords.findLast(candidate => !supersededIds.has(candidate.details?.decisionId));
   if (!previous) return { artifact, artifactFingerprint: decisionArtifactFingerprint(artifact), event, supersededEvent: null };
   const previousArtifact = await readDecisionArtifact(target, ctx.taskId, previous.details.decisionId, packageRoot);
   const supersededEvent = await appendProtocolEvent(target, {
@@ -107,16 +118,23 @@ async function persistDecision(target, packageRoot, resolvedDecisionId, artifact
   return { artifact, artifactFingerprint: decisionArtifactFingerprint(artifact), event, supersededEvent };
 }
 
-export async function recordSemanticDecision({ target, packageRoot, taskId, decisionId, request, provider = null } = {}) {
+export async function recordSemanticDecision(options = {}) {
+  return withDecisionScope(options, recordSelectedSemanticDecision);
+}
+
+async function recordSelectedSemanticDecision({ target, packageRoot, taskId, decisionId, request, provider = null }) {
   const resolvedDecisionId = decisionId ?? `${String(request?.decisionKind ?? "decision").toLowerCase()}-${Date.now()}-${randomUUID().slice(0, 8)}`;
-  const policy = await loadPolicy(target, packageRoot);
-  const taskBindings = target && taskId ? await readCurrentDecisionBindings(target, packageRoot, taskId) : {};
-  const validated = validateDecisionRequest({
-    ...request,
-    taskId,
-    state: { lifecycle: taskBindings.state ?? {}, semantic: request?.state ?? {} },
+  const { policy, taskBindings, validated, cached } = await withProjectReadSnapshot(target, async () => {
+    const policy = await loadPolicy(target, packageRoot);
+    const taskBindings = target && taskId ? await readCurrentDecisionBindings(target, packageRoot, taskId) : {};
+    const validated = validateDecisionRequest({
+      ...request,
+      taskId,
+      state: { lifecycle: taskBindings.state ?? {}, semantic: request?.state ?? {} },
+    });
+    const cached = await readCachedSemanticDecision({ policy, decisionId, target, taskId, packageRoot, validated, taskBindings, request });
+    return { policy, taskBindings, validated, cached };
   });
-  const cached = await readCachedSemanticDecision({ policy, decisionId, target, taskId, packageRoot, validated, taskBindings, request });
   if (cached) return { artifact: cached, artifactFingerprint: decisionArtifactFingerprint(cached), event: null, supersededEvent: null, cached: true, policy };
   const engine = resolveProvider(provider) ?? createTypesafeEngine({ policy });
   if (provider && (provider.id !== "typesafe-jev" || provider.model !== PINNED_JEV_MODEL || typeof provider.evaluate !== "function")) {
@@ -128,27 +146,34 @@ export async function recordSemanticDecision({ target, packageRoot, taskId, deci
   return { ...persisted, policy };
 }
 
-export async function ensureSemanticDecision({ target, packageRoot, taskId, decisionId, request, provider = null, allowNetwork = true } = {}) {
-  const policy = await loadPolicy(target, packageRoot);
-  const taskBindings = await readCurrentDecisionBindings(target, packageRoot, taskId);
-  const validated = validateDecisionRequest({
-    ...request,
-    taskId,
-    state: { lifecycle: taskBindings.state ?? {}, semantic: request?.state ?? {} },
-  });
-  const currentBindings = {
-    ...taskBindings,
-    stateFingerprint: canonicalFingerprint(validated.state),
-    taskStateFingerprint: canonicalFingerprint(validated.state.lifecycle),
-    semanticStateFingerprint: canonicalFingerprint(validated.state.semantic),
-    questionSetFingerprint: validated.questionSet.fingerprint,
-    policyFingerprint: decisionPolicyFingerprint(policy),
-    model: PINNED_JEV_MODEL,
-    ...(request?.candidateSetFingerprint !== undefined ? { candidateSetFingerprint: request.candidateSetFingerprint } : {}),
-  };
-  const cached = await getTaskTransaction(target) ? null : await readCachedDecision({
-    target, packageRoot, taskId, decisionKind: validated.decisionKind,
-    currentBindings,
+export async function ensureSemanticDecision(options = {}) {
+  return withDecisionScope(options, ensureSelectedSemanticDecision);
+}
+
+async function ensureSelectedSemanticDecision({ target, packageRoot, taskId, decisionId, request, provider = null, allowNetwork = true }) {
+  const { policy, validated, cached } = await withProjectReadSnapshot(target, async () => {
+    const policy = await loadPolicy(target, packageRoot);
+    const taskBindings = await readCurrentDecisionBindings(target, packageRoot, taskId);
+    const validated = validateDecisionRequest({
+      ...request,
+      taskId,
+      state: { lifecycle: taskBindings.state ?? {}, semantic: request?.state ?? {} },
+    });
+    const currentBindings = {
+      ...taskBindings,
+      stateFingerprint: canonicalFingerprint(validated.state),
+      taskStateFingerprint: taskBindings.taskStateFingerprint ?? canonicalFingerprint(validated.state.lifecycle),
+      semanticStateFingerprint: canonicalFingerprint(validated.state.semantic),
+      questionSetFingerprint: validated.questionSet.fingerprint,
+      policyFingerprint: decisionPolicyFingerprint(policy),
+      model: PINNED_JEV_MODEL,
+      ...(request?.candidateSetFingerprint !== undefined ? { candidateSetFingerprint: request.candidateSetFingerprint } : {}),
+    };
+    const cached = await getTaskTransaction(target) ? null : await readCachedDecision({
+      target, packageRoot, taskId, decisionKind: validated.decisionKind,
+      currentBindings,
+    });
+    return { policy, validated, cached };
   });
   if (cached) return { artifact: cached, artifactFingerprint: decisionArtifactFingerprint(cached), cached: true, policy };
   if (!allowNetwork && !provider) throw decisionError(DECISION_ERROR_CODES.REQUIRED, `A current ${validated.decisionKind} decision is required.`);

package/src/core/decision/task-bindings.js

@@ -2,6 +2,7 @@ import { canonicalFingerprint } from "../artifacts.js";
 import { readContract } from "../contract.js";
 import { readPersistedRoute } from "../route-artifact.js";
 import { readWorkState } from "../work-state.js";
+import { withProjectReadSnapshot } from "../../storage/project-read-snapshot.js";
 
 async function readOptionalArtifact(reader) {
   try {
@@ -12,7 +13,11 @@ async function readOptionalArtifact(reader) {
   }
 }
 
-export async function readCurrentDecisionBindings(target, packageRoot, taskId, { candidateSetFingerprint, policyFingerprint } = {}) {
+export async function readCurrentDecisionBindings(target, packageRoot, taskId, options = {}) {
+  return withProjectReadSnapshot(target, () => readSnapshotBindings(target, packageRoot, taskId, options));
+}
+
+async function readSnapshotBindings(target, packageRoot, taskId, { candidateSetFingerprint, policyFingerprint }) {
   const state = await readWorkState(target, { packageRoot, taskId });
   const contract = await readOptionalArtifact(() => readContract(target, packageRoot, { taskId }));
   const route = await readOptionalArtifact(() => readPersistedRoute(target, packageRoot, { taskId }));

package/src/core/diagnosis-model.js

@@ -1,3 +1,5 @@
+import { ledgerEventsOfTypes } from "./ledger-event-collection.js";
+
 import { canonicalFingerprint } from "./artifacts.js";
 import { assertFailureClass } from "./protocol.js";
 
@@ -212,3 +214,12 @@ export function currentCycleDiagnosis(events, taskId, verificationCycle) {
   }
   return null;
 }
+
+
+export function latestDiagnosisForTask(events, taskId) {
+  let latest = null;
+  for (const event of ledgerEventsOfTypes(events ?? [], ["DIAGNOSIS_RECORDED"])) {
+    if (!taskId || event.taskId === taskId) latest = event;
+  }
+  return latest;
+}

package/src/core/diagnosis.js

@@ -1,5 +1,6 @@
 import { appendProtocolEvent, validateEventLedger } from "./events.js";
 import { readWorkState, mutateWorkState } from "./work-state.js";
+import { getTaskTransaction, withTaskTransaction } from "./transaction.js";
 import {
   DIAGNOSIS_INFORMATION_GAIN,
   assertDiagnosisDetails,
@@ -22,7 +23,15 @@ export {
   normalizeDiagnosisText,
 };
 
-export async function recordDiagnosis({
+export async function recordDiagnosis(options) {
+  if (await getTaskTransaction(options.target)) return recordDiagnosisInTransaction(options);
+  const state = await readWorkState(options.target, { packageRoot: options.packageRoot, taskId: options.taskId, statePath: options.statePath });
+  if (!state) return recordDiagnosisInTransaction(options);
+  return withTaskTransaction({ target: options.target, taskId: options.taskId ?? state.taskId,
+    packageRoot: options.packageRoot, operation: "record-diagnosis" }, () => recordDiagnosisInTransaction(options));
+}
+
+async function recordDiagnosisInTransaction({
   target,
   packageRoot,
   hypothesis,