@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

package/src/core/test-intelligence/inventory.js

@@ -0,0 +1,73 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+
+const TEST_DIRECTORIES = Object.freeze(["test", "tests", "spec", "specs"]);
+const TEST_FILE_PATTERN = /\.(?:test|spec)\.(?:c|cpp|go|java|js|jsx|mjs|py|rb|rs|ts|tsx)$/i;
+
+async function filesUnder(root, relative = "") {
+  const current = path.join(root, relative);
+  let entries = [];
+  try { entries = await readdir(current, { withFileTypes: true }); } catch { return []; }
+  const result = [];
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    const child = path.join(relative, entry.name);
+    if (entry.isDirectory()) result.push(...await filesUnder(root, child));
+    else if (entry.isFile() && TEST_FILE_PATTERN.test(entry.name)) result.push(child);
+  }
+  return result;
+}
+
+function stableId(framework, file, suite, name) {
+  return `test-${createHash("sha256").update(JSON.stringify({ framework, file, suite, name })).digest("hex").slice(0, 24)}`;
+}
+
+function frameworkFor(source) {
+  if (/node:test/.test(source)) return "node:test";
+  if (/vitest/.test(source)) return "vitest";
+  if (/jest/.test(source)) return "jest";
+  if (/pytest|unittest/.test(source)) return "python";
+  return "unknown";
+}
+
+function collectUnits(source) {
+  const units = [];
+  const matcher = /\b(test|it)\s*\(\s*(["'`])([^"'`]+)\2/g;
+  let match;
+  while ((match = matcher.exec(source))) units.push({ name: match[3].trim(), line: source.slice(0, match.index).split("\n").length });
+  return units;
+}
+
+function signals(file, name) {
+  const text = `${file} ${name}`.toLowerCase();
+  return {
+    requiredBehavior: /contract|acceptance|required|lifecycle|protocol/.test(text),
+    security: /security|auth|secret|permission|credential|csp|injection/.test(text),
+    publicApi: /api|compat|public|cli|protocol/.test(text),
+    criticalPath: /critical|transaction|lock|concurr|race|recovery/.test(text),
+    integration: /integration|e2e|browser|provider|package|release/.test(text),
+    migration: /migration|schema|upgrade|downgrade/.test(text),
+    release: /package|release|publish|smoke/.test(text),
+    platformSpecific: /windows|win32|macos|darwin|linux|platform|native/.test(text),
+  };
+}
+
+export async function inventoryTests(projectRoot = process.cwd()) {
+  const files = [];
+  for (const directory of TEST_DIRECTORIES) files.push(...await filesUnder(projectRoot, directory));
+  const tests = [];
+  for (const relativeFile of [...new Set(files)].sort()) {
+    const source = await readFile(path.join(projectRoot, relativeFile), "utf8");
+    const framework = frameworkFor(source);
+    for (const unit of collectUnits(source)) {
+      const file = relativeFile.replaceAll(path.sep, "/");
+      tests.push({
+        testId: stableId(framework, file, "", unit.name), file, framework, suite: "", name: unit.name,
+        line: unit.line, sourceSummary: `${file}:${unit.line} ${unit.name}`.slice(0, 500),
+        targets: [file], runtimeMs: null, uniqueBranches: null, signals: signals(file, unit.name),
+      });
+    }
+  }
+  tests.sort((a, b) => a.testId.localeCompare(b.testId));
+  return { schemaVersion: 1, source: "DETERMINISTIC", tests };
+}

package/src/core/test-intelligence/prune.js

@@ -0,0 +1,94 @@
+import { readTestUtility } from "./service.js";
+import { assertSafePath } from "../filesystem.js";
+import { cp, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const PROTECTED_CLASSES = new Set([
+  "KEEP_REQUIRED", "KEEP_RISK_GUARD", "KEEP_UNIQUE", "KEEP_AUTHORITY_BOUNDARY",
+  "KEEP_RECOVERY_INVARIANT", "KEEP_RELEASE_SMOKE", "KEEP_MIGRATION_COMPATIBILITY",
+  "KEEP_PLATFORM_BEHAVIOR",
+]);
+
+function planFor(test) {
+  if (test.protected || PROTECTED_CLASSES.has(test.classification)) return { action: "KEEP", reason: "PROTECTED_TEST" };
+  if (test.classification === "REDUNDANT_CANDIDATE" && test.recommendation === "PROBE_REMOVAL") return { action: "PROBE_REMOVAL", reason: "SEMANTIC_AND_DETERMINISTIC_EVIDENCE_REQUIRED" };
+  if (test.classification === "KEEP_DOCUMENTATION_VALUE") return { action: "KEEP", reason: "DOCUMENTATION_VALUE" };
+  return { action: "BLOCKED", reason: "INSUFFICIENT_PROVENANCE" };
+}
+
+export async function buildPrunePlan({ target, packageRoot, taskId } = {}) {
+  const utility = await readTestUtility({ target, packageRoot, taskId });
+  const items = utility.value.tests.map((test) => ({ testId: test.testId, file: test.file, name: test.name, ...planFor(test) }));
+  return { schemaVersion: 1, taskId, semanticStatus: utility.value.semanticStatus, items, deletionAuthority: false };
+}
+
+export async function runPruneProbe({ target, packageRoot, taskId, testId } = {}) {
+  const plan = await buildPrunePlan({ target, packageRoot, taskId });
+  const item = plan.items.find((candidate) => candidate.testId === testId);
+  if (!item) {
+    const error = new Error(`Unknown test ID: ${testId}`); error.code = "E_TEST_ID_UNKNOWN"; throw error;
+  }
+  if (item.action !== "PROBE_REMOVAL") {
+    const error = new Error(`Test prune probe blocked for ${testId}: ${item.reason}`);
+    error.code = "E_TEST_PRUNE_BLOCKED";
+    throw error;
+  }
+  const temporaryRoot = await mkdtemp(path.join(os.tmpdir(), "forgeloop-prune-probe-"));
+  try {
+    // Persisted utility records do not grant access outside the project or
+    // through symlinks copied into the disposable workspace.
+    await assertSafePath(target, item.file);
+    await cp(target, temporaryRoot, {
+      recursive: true,
+      dereference: false,
+      filter(source) {
+        const relative = path.relative(target, source);
+        return relative !== ".forgeloop" && relative !== ".git" && !relative.startsWith(`${path.sep}.forgeloop${path.sep}`) && !relative.startsWith(`${path.sep}.git${path.sep}`) && relative !== "node_modules";
+      },
+    });
+    const dependencies = path.join(target, "node_modules");
+    try { await symlink(dependencies, path.join(temporaryRoot, "node_modules"), "junction"); } catch { /* dependencies are optional for static probes */ }
+    if (item.file.endsWith(".mjs") || item.file.endsWith(".js")) {
+      const candidatePath = await assertSafePath(temporaryRoot, item.file);
+      const source = await readFile(candidatePath, "utf8");
+      const escapedName = item.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const pattern = new RegExp(`\\b(test|it)\\s*\\(\\s*([\\"'])${escapedName}\\2`);
+      if (!pattern.test(source)) {
+        return { status: "INCONCLUSIVE", reason: "TEST_UNIT_NOT_LOCATED", testId, liveWorktreeModified: false, temporaryWorkspaceCleaned: true };
+      }
+      const disabled = source.replace(pattern, (_, keyword, quote) => `${keyword}.skip(${quote}${item.name}${quote}`);
+      await writeFile(candidatePath, disabled, "utf8");
+      const result = await execFileAsync(process.execPath, ["--test", item.file], {
+        cwd: temporaryRoot,
+        timeout: 120_000,
+        maxBuffer: 2_000_000,
+        windowsHide: true,
+      });
+      return {
+        status: "INCONCLUSIVE",
+        reason: "COVERAGE_OR_MUTATION_EVIDENCE_UNAVAILABLE",
+        testId,
+        affectedTestExitCode: 0,
+        affectedTestOutput: `${result.stdout ?? ""}${result.stderr ?? ""}`.slice(-8_000),
+        liveWorktreeModified: false,
+        temporaryWorkspaceCleaned: true,
+      };
+    }
+    return { status: "INCONCLUSIVE", reason: "FRAMEWORK_PROBE_UNSUPPORTED", testId, liveWorktreeModified: false, temporaryWorkspaceCleaned: true };
+  } catch (error) {
+    return {
+      status: "BLOCKED",
+      reason: error.code === "ETIMEDOUT" ? "AFFECTED_TEST_TIMEOUT" : "AFFECTED_TEST_FAILED",
+      testId,
+      error: error.message,
+      liveWorktreeModified: false,
+      temporaryWorkspaceCleaned: true,
+    };
+  } finally {
+    await rm(temporaryRoot, { recursive: true, force: true });
+  }
+}

package/src/core/test-intelligence/semantic-state.js

@@ -0,0 +1,15 @@
+export const TEST_UTILITY_BATCH_SIZE = 8;
+
+export function batchTests(tests = [], size = TEST_UTILITY_BATCH_SIZE) {
+  const batches = [];
+  for (let index = 0; index < tests.length; index += size) batches.push(tests.slice(index, index + size));
+  return batches;
+}
+
+export function buildTestSemanticState(tests = []) {
+  return {
+    tests: tests.map(({ testId, file, framework, suite, name, line, sourceSummary, targets, runtimeMs, uniqueBranches, signals }) => ({
+      testId, file, framework, suite, name, line, sourceSummary, targets, runtimeMs, uniqueBranches, signals,
+    })),
+  };
+}

package/src/core/test-intelligence/service.js

@@ -0,0 +1,40 @@
+import { taskArtifactPath } from "../task-paths.js";
+import { writeJsonArtifact, readJsonArtifact } from "../artifacts.js";
+import { withTaskMutation } from "../task-command.js";
+import { inventoryTests } from "./inventory.js";
+import { buildTestUtilityArtifact } from "./utility.js";
+import { canonicalFingerprint } from "../artifacts.js";
+import { readWorkState } from "../work-state.js";
+import { buildTestUtilityQuestionSet } from "../decision/question-registry.js";
+import { ensureSemanticDecision } from "../decision/service.js";
+import { batchTests, buildTestSemanticState } from "./semantic-state.js";
+
+export async function runTestInventory({ projectRoot = process.cwd() } = {}) { return inventoryTests(projectRoot); }
+
+export async function runTestUtility({ target, packageRoot, taskId, provider = null } = {}) {
+  const inventory = await inventoryTests(target);
+  const semanticDecisions = [];
+  const state = await readWorkState(target, { packageRoot, taskId });
+  for (const [index, batch] of batchTests(inventory.tests).entries()) {
+    const questionSet = buildTestUtilityQuestionSet(batch);
+    semanticDecisions.push(await ensureSemanticDecision({
+      target, packageRoot, taskId, provider,
+      decisionId: `test-utility-${index}-${canonicalFingerprint(batch.map((test) => test.testId)).slice(0, 16)}`,
+      request: {
+        decisionKind: "TEST_UTILITY", questionSetId: questionSet.id, questionSet,
+        state: { lifecycle: state, ...buildTestSemanticState(batch) },
+        candidateIds: batch.map((test) => test.testId),
+        candidateSetFingerprint: canonicalFingerprint(batch.map((test) => test.testId)),
+      },
+    }));
+  }
+  return withTaskMutation(target, { taskId, packageRoot }, "test-utility", async (ctx) => {
+    const artifact = buildTestUtilityArtifact({ taskId: ctx.taskId, inventory, semanticDecisions: semanticDecisions.map((decision) => decision.artifact) });
+    const written = await writeJsonArtifact(target, taskArtifactPath(ctx.taskId, "testUtility"), artifact, "test-utility", packageRoot, { taskId: ctx.taskId, operation: "test-utility" });
+    return { path: written.path, artifact, inventory };
+  });
+}
+
+export async function readTestUtility({ target, packageRoot, taskId } = {}) {
+  return readJsonArtifact(target, taskArtifactPath(taskId, "testUtility"), "test-utility", packageRoot);
+}

package/src/core/test-intelligence/utility.js

@@ -0,0 +1,50 @@
+import { canonicalFingerprint } from "../artifacts.js";
+
+function classify(test, judgment = null, confidence = 1) {
+  const signal = test.signals ?? {};
+  if (signal.requiredBehavior) return { classification: "KEEP_REQUIRED", recommendation: "KEEP", protected: true };
+  if (signal.security) return { classification: "KEEP_RISK_GUARD", recommendation: "KEEP", protected: true };
+  if (signal.criticalPath) return { classification: "KEEP_RECOVERY_INVARIANT", recommendation: "KEEP", protected: true };
+  if (signal.migration) return { classification: "KEEP_MIGRATION_COMPATIBILITY", recommendation: "KEEP", protected: true };
+  if (signal.publicApi) return { classification: "KEEP_UNIQUE", recommendation: "KEEP", protected: true };
+  if (signal.release) return { classification: "KEEP_RELEASE_SMOKE", recommendation: "KEEP", protected: true };
+  if (signal.platformSpecific) return { classification: "KEEP_PLATFORM_BEHAVIOR", recommendation: "KEEP", protected: true };
+  if (signal.integration) return { classification: "KEEP_INTEGRATION_GUARD", recommendation: "KEEP", protected: true };
+  if (!judgment || confidence < 0.75) return { classification: "UNKNOWN", recommendation: "BLOCKED", protected: false };
+  if (judgment.protocol_invariant) return { classification: "KEEP_RECOVERY_INVARIANT", recommendation: "KEEP", protected: true };
+  if (judgment.semantic_duplicate) {
+    return {
+      classification: "REDUNDANT_CANDIDATE",
+      recommendation: judgment.requires_system_two_review ? "BLOCKED" : "PROBE_REMOVAL",
+      protected: false,
+    };
+  }
+  if (judgment.likely_obsolete) return { classification: "OBSOLETE_CANDIDATE", recommendation: "BLOCKED", protected: false };
+  if (judgment.likely_flaky_low_signal) return { classification: "FLAKY_LOW_SIGNAL", recommendation: "BLOCKED", protected: false };
+  if (judgment.expensive_relative_to_signal) return { classification: "EXPENSIVE_LOW_SIGNAL", recommendation: "BLOCKED", protected: false };
+  if (judgment.documentation_value) return { classification: "KEEP_DOCUMENTATION_VALUE", recommendation: "KEEP", protected: false };
+  if (judgment.integration_value) return { classification: "KEEP_INTEGRATION_GUARD", recommendation: "KEEP", protected: true };
+  if (judgment.has_unique_semantic_intent) return { classification: "KEEP_UNIQUE", recommendation: "KEEP", protected: false };
+  return { classification: "UNKNOWN", recommendation: "BLOCKED", protected: false };
+}
+
+export function buildTestUtilityArtifact({ taskId, inventory, semanticStatus = "NOT_REQUESTED", semanticDecision = null, semanticDecisions = [] } = {}) {
+  const decisions = semanticDecisions.length > 0 ? semanticDecisions : (semanticDecision ? [semanticDecision] : []);
+  const byTest = new Map(decisions.flatMap((decision) => Object.entries(decision.decision?.tests ?? {}).map(([testId, judgment]) => [testId, {
+    judgment, confidence: Math.min(...Object.keys(judgment).map((key) => decision.confidence?.[`test_${(decision.decision.candidateIds ?? []).indexOf(testId)}_${key}`] ?? 0)),
+  }])));
+  return {
+    schemaVersion: 1,
+    protocolVersion: 1,
+    taskId,
+    generatedAt: new Date().toISOString(),
+    inventoryFingerprint: canonicalFingerprint(inventory),
+    semanticStatus: decisions.length > 0 ? "PROVIDER_REPORTED" : semanticStatus,
+    ...(decisions.length > 0 ? {
+      ...(decisions.length === 1 ? { decisionId: decisions[0].decisionId, semanticDecisionFingerprint: canonicalFingerprint(decisions[0]) } : {}),
+      decisionIds: decisions.map((decision) => decision.decisionId),
+      semanticDecisionFingerprints: decisions.map((decision) => canonicalFingerprint(decision)),
+    } : {}),
+    tests: (inventory?.tests ?? []).map((test) => ({ ...test, ...classify(test, byTest.get(test.testId)?.judgment, byTest.get(test.testId)?.confidence ?? 0) })),
+  };
+}

package/src/core/trace.js

@@ -1,5 +1,5 @@
-import { buildTaskSnapshot } from "./task-snapshot.js";
-import { diagnosisEventsForTask } from "./diagnosis-model.js";
+import { withTaskSnapshot } from "./task-snapshot.js";
+import { ledgerEventsOfTypes } from "./ledger-event-collection.js";
 import {
   assertDiagnosticCaseDetails,
   assertInterventionDetails,
@@ -51,6 +51,7 @@ const EVENT_CATEGORY_MAP = Object.freeze({
   TASK_RECOVERY_RECORDED: "recovery",
   TASK_RECOVERY_RESUMED: "recovery",
   OPERATOR_RECOVERY_RECORDED: "recovery",
+  TASK_ABANDONED: "recovery",
   LEGACY_RECOVERY_MIGRATION_RECORDED: "recovery",
   GATE_SATISFIED: "policy",
   COMPLETION_VALIDATED: "completion",
@@ -82,6 +83,13 @@ const LIFECYCLE_TRANSITIONS = Object.freeze([
   "COMPLETION_REJECTED",
 ]);
 
+const STATIC_EVENT_SUMMARIES = Object.freeze({
+  TASK_RECOVERY_RESUMED: "Task resumed after recovery",
+  OPERATOR_RECOVERY_RECORDED: "Operator recovery recorded",
+  TASK_ABANDONED: "Task explicitly abandoned",
+  LEGACY_RECOVERY_MIGRATION_RECORDED: "Legacy recovery migration recorded",
+});
+
 export function eventCategory(eventType) {
   return EVENT_CATEGORY_MAP[eventType] ?? "integrity";
 }
@@ -93,6 +101,8 @@ export function timestampQuality(event) {
 
 function eventSummary(event) {
   const d = event.details ?? {};
+  const staticSummary = STATIC_EVENT_SUMMARIES[event.event];
+  if (staticSummary) return staticSummary;
   switch (event.event) {
     case "TASK_RECEIVED":
       return `Task received${d.taskId ? ` (${d.taskId})` : ""}`;
@@ -132,12 +142,6 @@ function eventSummary(event) {
       return "Continuity checkpoint recorded";
     case "TASK_RECOVERY_RECORDED":
       return `Task recovery recorded (${d.classification ?? "unknown"})`;
-    case "TASK_RECOVERY_RESUMED":
-      return "Task resumed after recovery";
-    case "OPERATOR_RECOVERY_RECORDED":
-      return "Operator recovery recorded";
-    case "LEGACY_RECOVERY_MIGRATION_RECORDED":
-      return "Legacy recovery migration recorded";
     case "COMPLETION_VALIDATED":
       return "Completion validated";
     case "COMPLETION_REJECTED":
@@ -197,23 +201,6 @@ export function normalizeProtocolEvent(event, context = {}) {
   };
 }
 
-function lifecycleTransitions(events) {
-  const transitions = [];
-  let lastPhaseEvent = null;
-  for (const event of events) {
-    if (!LIFECYCLE_TRANSITIONS.includes(event.event)) continue;
-    transitions.push({
-      sequence: event.seq,
-      at: event.at,
-      type: event.event,
-      details: event.details ?? {},
-      previous: lastPhaseEvent?.type ?? null,
-    });
-    lastPhaseEvent = event;
-  }
-  return transitions;
-}
-
 function projectChecks(snapshot) {
   const state = snapshot.state;
   const attemptsByCheck = new Map();
@@ -285,7 +272,8 @@ function projectChecks(snapshot) {
 }
 
 function legacyDiagnoses(events, taskId) {
-  return diagnosisEventsForTask(events, taskId).map((event) => ({
+  return [...ledgerEventsOfTypes(events, ["DIAGNOSIS_RECORDED"])]
+    .filter(event => !taskId || event.taskId === taskId).map((event) => ({
     sequence: event.seq,
     at: event.at,
     sourceModel: "LEGACY_DIAGNOSIS_V1",
@@ -353,35 +341,53 @@ const PHASE_DERIVATIONS = Object.freeze({
   INTERVENTION_RECORDED: () => "CORRECTING",
 });
 
-function reconstructPhaseChronology(events) {
+function phaseStep(event, currentPhase) {
+  const milestone = PHASE_MILESTONES[event.event];
+  if (milestone) return { phase: milestone.phase, quality: milestone.quality };
+  const derive = PHASE_DERIVATIONS[event.event];
+  const derived = derive ? derive(event.details ?? {}) : null;
+  return { phase: derived ?? currentPhase, quality: derived || currentPhase ? "derived" : "unknown" };
+}
+
+function orderedSequences(events) {
+  let previous = -Infinity;
+  return events.every(event => {
+    if (!Number.isFinite(event.seq) || event.seq <= previous) return false;
+    previous = event.seq;
+    return true;
+  });
+}
+
+function* phasedEvents(events, validatedOrder = false) {
   let currentPhase = null;
-  const phaseBySequence = new Map();
-  const qualityBySequence = new Map();
-  for (const event of events) {
-    const milestone = PHASE_MILESTONES[event.event];
-    if (milestone) {
-      currentPhase = milestone.phase;
-      qualityBySequence.set(event.seq, milestone.quality);
-    } else {
-      const derive = PHASE_DERIVATIONS[event.event];
-      const derived = derive ? derive(event.details ?? {}) : null;
-      if (derived) {
-        currentPhase = derived;
-        qualityBySequence.set(event.seq, "derived");
-      } else {
-        qualityBySequence.set(event.seq, currentPhase ? "derived" : "unknown");
-      }
+  if (validatedOrder || orderedSequences(events)) {
+    for (const event of events) {
+      const step = phaseStep(event, currentPhase);
+      currentPhase = step.phase;
+      yield { event, ...step };
     }
-    phaseBySequence.set(event.seq, currentPhase);
+    return;
   }
-  return { phaseBySequence, qualityBySequence };
+  // Legacy duplicate sequence keys retain the original last-write projection.
+  const phases = new Map();
+  for (const event of events) {
+    const step = phaseStep(event, currentPhase);
+    currentPhase = step.phase;
+    phases.set(event.seq, step);
+  }
+  for (const event of events) yield { event, ...phases.get(event.seq) };
 }
 
 export function historyQualityFor({ snapshot, normalizedEvents }) {
+  return historyQualityFromSummary(snapshot, normalizedEvents.length,
+    normalizedEvents.some((event) => event.timestampQuality !== "authoritative"));
+}
+
+function historyQualityFromSummary(snapshot, eventCount, hasLegacyTimestamp) {
   const reasons = [];
-  const hasLedger = normalizedEvents.length > 0;
+  const hasLedger = eventCount > 0;
   if (!hasLedger) reasons.push("LEDGER_ABSENT");
-  if (normalizedEvents.some((event) => event.timestampQuality !== "authoritative")) {
+  if (hasLegacyTimestamp) {
     reasons.push("LEGACY_PHASE_TIMESTAMPS_UNAVAILABLE");
   }
   if (snapshot.state && Number.isInteger(snapshot.state.verificationCycle) && snapshot.state.verificationCycle > 1
@@ -392,54 +398,69 @@ export function historyQualityFor({ snapshot, normalizedEvents }) {
   return { level, reasons };
 }
 
-export async function buildTaskTrace({ target, packageRoot, taskId = null, eventsPath = null } = {}) {
-  const snapshot = await buildTaskSnapshot({ target, packageRoot, taskId, eventsPath });
-  const artifactPath = eventsPath ?? ".forgeloop/task-state/<task-key>/events.ndjson";
+// History supplies an output collector only. Complete snapshot auditing and
+// every diagnostic/action projection below remain independent of its selection.
+export async function buildTaskTrace({ target, packageRoot, taskId = null, eventsPath = null } = {}, eventProjection = null) {
+  return withTaskSnapshot({ target, packageRoot, taskId, eventsPath }, snapshot =>
+    buildTraceFromSnapshot({ target, packageRoot, taskId, eventsPath, snapshot, eventProjection }));
+}
 
-  const taskEvents = taskId ? snapshot.events.filter((event) => !event.taskId || event.taskId === taskId) : snapshot.events;
-  const { phaseBySequence, qualityBySequence } = reconstructPhaseChronology(taskEvents);
+function projectTraceEvents(taskEvents, artifactPath, eventProjection, validatedOrder) {
   const normalizedEvents = [];
-  for (const event of taskEvents) {
-    normalizedEvents.push(normalizeProtocolEvent(event, {
-      phase: phaseBySequence.get(event.seq) ?? null,
-      artifactPath,
-      phaseQuality: qualityBySequence.get(event.seq) ?? "unknown",
-    }));
-  }
-
-  const integrity = {
-    valid: snapshot.integrity.valid,
-    errors: snapshot.integrity.errors,
-  };
-  const historyQuality = historyQualityFor({ snapshot, normalizedEvents });
-  const diagnostics = structuredDiagnostics(taskEvents);
-
-  const failureSignatures = projectFailureSignatures({ state: snapshot.state, events: taskEvents });
-  const failureSurfaces = projectFailureSurfaces({ state: snapshot.state, events: taskEvents });
-
+  const transitions = [];
+  let lastPhaseEvent = null;
   const executions = [];
   const seenExecutions = new Set();
-  for (const event of taskEvents) {
-    const d = event.details ?? {};
-    const executionId = d.executionId ?? d.executionRef ?? null;
-    if (!executionId || seenExecutions.has(executionId)) continue;
-    seenExecutions.add(executionId);
-    executions.push({
-      executionId,
-      sequence: event.seq,
-      at: event.at,
-      status: d.status ?? null,
-      exitCode: d.exitCode ?? null,
-      resolution: d.resolution ?? null,
+  const evidenceSources = new Map();
+  const recovery = [];
+  const completionAttempts = [];
+  const continuity = [];
+  let validatedAt = null;
+  let rejectedAt = null;
+  let actionEventCount = 0;
+  let reconciliationCount = 0;
+  let totalEventCount = 0;
+  let hasLegacyTimestamp = false;
+  for (const { event, phase, quality } of phasedEvents(taskEvents, validatedOrder)) {
+    const normalized = normalizeProtocolEvent(event, {
+      phase: phase ?? null,
+      artifactPath,
+      phaseQuality: quality ?? "unknown",
     });
-  }
+    totalEventCount += 1;
+    hasLegacyTimestamp ||= normalized.timestampQuality !== "authoritative";
+    if (eventProjection) eventProjection.add(normalized);
+    else normalizedEvents.push(normalized);
+
+    if (LIFECYCLE_TRANSITIONS.includes(event.event)) {
+      transitions.push({
+        sequence: event.seq,
+        at: event.at,
+        type: event.event,
+        details: event.details ?? {},
+        previous: lastPhaseEvent?.type ?? null,
+      });
+      lastPhaseEvent = event;
+    }
+
+    const details = event.details ?? {};
+    const executionId = details.executionId ?? details.executionRef ?? null;
+    if (executionId && !seenExecutions.has(executionId)) {
+      seenExecutions.add(executionId);
+      executions.push({
+        executionId,
+        sequence: event.seq,
+        at: event.at,
+        status: details.status ?? null,
+        exitCode: details.exitCode ?? null,
+        resolution: details.resolution ?? null,
+      });
+    }
 
-  const evidenceSources = new Map();
-  for (const event of taskEvents) {
     const refs = [
-      ...(Array.isArray(event.details?.evidenceRefs) ? event.details.evidenceRefs : []),
-      ...(Array.isArray(event.details?.hypotheses)
-        ? event.details.hypotheses.flatMap((hypothesis) => hypothesis.evidenceRefs ?? [])
+      ...(Array.isArray(details.evidenceRefs) ? details.evidenceRefs : []),
+      ...(Array.isArray(details.hypotheses)
+        ? details.hypotheses.flatMap((hypothesis) => hypothesis.evidenceRefs ?? [])
         : []),
     ];
     for (const ref of refs) {
@@ -447,19 +468,59 @@ export async function buildTaskTrace({ target, packageRoot, taskId = null, event
       if (!evidenceSources.has(ref)) evidenceSources.set(ref, { ref, sources: [] });
       if (!evidenceSources.get(ref).sources.includes(event.event)) evidenceSources.get(ref).sources.push(event.event);
     }
+
+    if (["TASK_RECOVERY_RECORDED", "TASK_RECOVERY_RESUMED", "OPERATOR_RECOVERY_RECORDED", "TASK_ABANDONED", "LEGACY_RECOVERY_MIGRATION_RECORDED"].includes(event.event)) {
+      recovery.push({ sequence: event.seq, at: event.at, type: event.event, details });
+    }
+    if (event.event === "COMPLETION_VALIDATED" || event.event === "COMPLETION_REJECTED") {
+      completionAttempts.push({ sequence: event.seq, at: event.at, type: event.event });
+      if (event.event === "COMPLETION_VALIDATED") validatedAt = event.at ?? null;
+      else rejectedAt = event.at ?? null;
+    }
+    if (event.event.startsWith("ACTION_") || event.event.startsWith("APPROVAL_")) actionEventCount += 1;
+    if (event.event === "ACTION_RECONCILED") reconciliationCount += 1;
+    if (event.event === "CONTINUITY_RECORDED" || event.event === "CHECKPOINT_RECONCILED") {
+      continuity.push({ sequence: event.seq, at: event.at, type: event.event });
+    }
   }
-  const evidence = [...evidenceSources.values()].sort((a, b) => a.ref.localeCompare(b.ref));
 
-  const recovery = taskEvents
-    .filter((event) => ["TASK_RECOVERY_RECORDED", "TASK_RECOVERY_RESUMED", "OPERATOR_RECOVERY_RECORDED", "LEGACY_RECOVERY_MIGRATION_RECORDED"].includes(event.event))
-    .map((event) => ({ sequence: event.seq, at: event.at, type: event.event, details: event.details ?? {} }));
+  return {
+    normalizedEvents,
+    totalEventCount,
+    hasLegacyTimestamp,
+    transitions,
+    executions,
+    evidence: [...evidenceSources.values()].sort((a, b) => a.ref.localeCompare(b.ref)),
+    recovery,
+    completion: { validatedAt, rejectedAt, attempts: completionAttempts },
+    continuity,
+    actionEventCount,
+    reconciliationCount,
+  };
+}
+
+async function buildTraceFromSnapshot({ target, packageRoot, taskId, eventsPath, snapshot, eventProjection }) {
+  const artifactPath = eventsPath ?? ".forgeloop/task-state/<task-key>/events.ndjson";
 
-  const completionEvents = taskEvents.filter((event) => ["COMPLETION_VALIDATED", "COMPLETION_REJECTED"].includes(event.event));
-  const completion = {
-    validatedAt: completionEvents.findLast((event) => event.event === "COMPLETION_VALIDATED")?.at ?? null,
-    rejectedAt: completionEvents.findLast((event) => event.event === "COMPLETION_REJECTED")?.at ?? null,
-    attempts: completionEvents.map((event) => ({ sequence: event.seq, at: event.at, type: event.event })),
+  const belongsToTask = event => !event.taskId || event.taskId === taskId;
+  const taskEvents = taskId && !snapshot.events.every(belongsToTask)
+    ? snapshot.events.filter(belongsToTask) : snapshot.events;
+  // The private snapshot audit already proved seq === index + 1. Invalid
+  // ledgers retain the original duplicate/order compatibility projection.
+  const {
+    normalizedEvents, totalEventCount, hasLegacyTimestamp, transitions,
+    executions, evidence, recovery, completion, continuity, actionEventCount, reconciliationCount,
+  } = projectTraceEvents(taskEvents, artifactPath, eventProjection, snapshot.integrity.valid);
+
+  const integrity = {
+    valid: snapshot.integrity.valid,
+    errors: snapshot.integrity.errors,
   };
+  const historyQuality = historyQualityFromSummary(snapshot, totalEventCount, hasLegacyTimestamp);
+  const diagnostics = structuredDiagnostics(taskEvents);
+
+  const failureSignatures = projectFailureSignatures({ state: snapshot.state, events: taskEvents });
+  const failureSurfaces = projectFailureSurfaces({ state: snapshot.state, events: taskEvents });
 
   const actions = snapshot.taskId
     ? await listActions(target, { packageRoot, taskId: snapshot.taskId })
@@ -477,7 +538,6 @@ export async function buildTaskTrace({ target, packageRoot, taskId = null, event
       artifact: action,
     }));
   }
-  const actionEvents = taskEvents.filter((event) => event.event.startsWith("ACTION_") || event.event.startsWith("APPROVAL_"));
   const byState = Object.fromEntries([...new Set(actions.map((action) => action.state))].sort()
     .map((state) => [state, actions.filter((action) => action.state === state).length]));
   const byCapability = Object.fromEntries([...new Set(actions.map((action) => action.capability))].sort()
@@ -501,8 +561,8 @@ export async function buildTaskTrace({ target, packageRoot, taskId = null, event
       || (projection.state === "VERIFIED" && !(projection.authorization.valid && projection.verification.valid))
     ).length,
     repeatedIdempotencyAttempts,
-    reconciliationCount: taskEvents.filter((event) => event.event === "ACTION_RECONCILED").length,
-    eventCount: actionEvents.length,
+    reconciliationCount,
+    eventCount: actionEventCount,
   };
 
   return {
@@ -526,8 +586,9 @@ export async function buildTaskTrace({ target, packageRoot, taskId = null, event
     historyQuality,
     integrity,
     artifacts: {},
-    events: normalizedEvents,
-    transitions: lifecycleTransitions(taskEvents),
+    events: eventProjection ? eventProjection.result() : normalizedEvents,
+    ...(eventProjection ? { totalEventCount } : {}),
+    transitions,
     executions,
     checks: projectChecks(snapshot),
     evidence,
@@ -537,9 +598,7 @@ export async function buildTaskTrace({ target, packageRoot, taskId = null, event
     },
     failureSignatures,
     failureSurfaces,
-    continuity: taskEvents
-      .filter((event) => ["CONTINUITY_RECORDED", "CHECKPOINT_RECONCILED"].includes(event.event))
-      .map((event) => ({ sequence: event.seq, at: event.at, type: event.event })),
+    continuity,
     recovery,
     policy: {},
     audit: {},