@cassiomc1/forgeloop 1.3.0 → 1.6.0

package/src/core/trace.js

@@ -0,0 +1,548 @@
+import { buildTaskSnapshot } from "./task-snapshot.js";
+import { diagnosisEventsForTask } from "./diagnosis-model.js";
+import {
+  assertDiagnosticCaseDetails,
+  assertInterventionDetails,
+  assertHypothesisDispositionDetails,
+} from "./diagnostic-model.js";
+import { projectFailureSignatures } from "./failure-signature.js";
+import { projectFailureSurfaces } from "./failure-surface.js";
+import { listActions } from "./actions.js";
+
+export const EVENT_CATEGORIES = Object.freeze([
+  "task",
+  "contract",
+  "routing",
+  "lifecycle",
+  "execution",
+  "verification",
+  "diagnosis",
+  "intervention",
+  "evidence",
+  "review",
+  "continuity",
+  "recovery",
+  "policy",
+  "audit",
+  "completion",
+  "integrity",
+]);
+
+const EVENT_CATEGORY_MAP = Object.freeze({
+  TASK_RECEIVED: "task",
+  CONTRACT_VALIDATED: "contract",
+  DECISION_CRITERION_RECORDED: "contract",
+  PLAN_RECORDED: "contract",
+  ROUTE_VALIDATED: "routing",
+  PREFLIGHT_READY: "lifecycle",
+  PREFLIGHT_BLOCKED: "lifecycle",
+  EXECUTION_STARTED: "execution",
+  VERIFICATION_STARTED: "lifecycle",
+  VERIFICATION_RECORDED: "verification",
+  CHECK_RECORDED: "verification",
+  TERMINAL_RESULT_RECORDED: "verification",
+  REVIEW_STARTED: "review",
+  DIAGNOSIS_RECORDED: "diagnosis",
+  DIAGNOSTIC_CASE_RECORDED: "diagnosis",
+  HYPOTHESIS_DISPOSITION_RECORDED: "diagnosis",
+  INTERVENTION_RECORDED: "intervention",
+  CONTINUITY_RECORDED: "continuity",
+  CHECKPOINT_RECONCILED: "continuity",
+  TASK_RECOVERY_RECORDED: "recovery",
+  TASK_RECOVERY_RESUMED: "recovery",
+  OPERATOR_RECOVERY_RECORDED: "recovery",
+  LEGACY_RECOVERY_MIGRATION_RECORDED: "recovery",
+  GATE_SATISFIED: "policy",
+  COMPLETION_VALIDATED: "completion",
+  COMPLETION_REJECTED: "completion",
+  TRANSACTION_COMMITTED: "integrity",
+  ACTION_PROPOSED: "execution",
+  ACTION_AUTHORIZED: "execution",
+  ACTION_STARTED: "execution",
+  ACTION_COMMIT_RECORDED: "execution",
+  ACTION_VERIFIED: "execution",
+  ACTION_FAILED: "execution",
+  ACTION_COMMIT_UNKNOWN: "execution",
+  ACTION_RECONCILED: "execution",
+  ACTION_CANCELLED: "execution",
+  APPROVAL_REQUESTED: "execution",
+  APPROVAL_RESOLVED: "execution",
+  TRAJECTORY_EVALUATED: "audit",
+});
+
+const LIFECYCLE_TRANSITIONS = Object.freeze([
+  "CONTRACT_VALIDATED",
+  "ROUTE_VALIDATED",
+  "PREFLIGHT_READY",
+  "EXECUTION_STARTED",
+  "VERIFICATION_STARTED",
+  "REVIEW_STARTED",
+  "COMPLETION_VALIDATED",
+  "COMPLETION_REJECTED",
+]);
+
+export function eventCategory(eventType) {
+  return EVENT_CATEGORY_MAP[eventType] ?? "integrity";
+}
+
+export function timestampQuality(event) {
+  if (typeof event?.at === "string" && !Number.isNaN(Date.parse(event.at))) return "authoritative";
+  return "unknown";
+}
+
+function eventSummary(event) {
+  const d = event.details ?? {};
+  switch (event.event) {
+    case "TASK_RECEIVED":
+      return `Task received${d.taskId ? ` (${d.taskId})` : ""}`;
+    case "CONTRACT_VALIDATED":
+      return "Contract validated";
+    case "ROUTE_VALIDATED":
+      return `Route selected${Array.isArray(d.selectedGuides) ? `: ${d.selectedGuides.join(", ")}` : ""}`;
+    case "PREFLIGHT_READY":
+      return "Preflight READY";
+    case "PREFLIGHT_BLOCKED":
+      return "Preflight BLOCKED";
+    case "EXECUTION_STARTED":
+      return "Execution started";
+    case "VERIFICATION_RECORDED": {
+      const id = d.id ?? d.checkId ?? d.requirement ?? "check";
+      return `${id} ${String(d.status ?? "recorded").toUpperCase()}${d.exitCode !== undefined ? ` (exit ${d.exitCode})` : ""}`;
+    }
+    case "TERMINAL_RESULT_RECORDED":
+      return `Terminal result ${d.type ?? ""} ${d.status ?? ""}`.trim();
+    case "REVIEW_STARTED":
+      return `Review started${Number.isInteger(d.verificationCycle) ? ` for cycle ${d.verificationCycle}` : ""}`;
+    case "DIAGNOSIS_RECORDED":
+      return `Diagnosis recorded (${d.informationGain ?? "gain unknown"})`;
+    case "DIAGNOSTIC_CASE_RECORDED":
+      return `Diagnostic case recorded (cycle ${d.verificationCycle}, revision ${d.diagnosticRevision})`;
+    case "INTERVENTION_RECORDED":
+      return `Intervention recorded (${d.intervention?.id ?? "unknown"})`;
+    case "HYPOTHESIS_DISPOSITION_RECORDED":
+      return `Hypothesis ${d.hypothesisRef ?? "unknown"} ${d.status ?? "dispositioned"}`;
+    case "DECISION_CRITERION_RECORDED":
+      return "Decision criterion recorded";
+    case "GATE_SATISFIED":
+      return `Gate satisfied: ${d.gate ?? "unknown"}`;
+    case "CHECKPOINT_RECONCILED":
+      return "Checkpoint reconciled";
+    case "CONTINUITY_RECORDED":
+      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":
+      return "Completion rejected";
+    case "TRANSACTION_COMMITTED":
+      return "Transaction committed";
+    case "ACTION_PROPOSED":
+      return `Action proposed (${d.actionId ?? "unknown"})`;
+    case "ACTION_AUTHORIZED":
+      return `Action authorized (${d.actionId ?? "unknown"})`;
+    case "ACTION_STARTED":
+      return `Action started (${d.actionId ?? "unknown"})`;
+    case "ACTION_COMMIT_RECORDED":
+      return `Action commit recorded (${d.actionId ?? "unknown"})`;
+    case "ACTION_VERIFIED":
+      return `Action verified (${d.actionId ?? "unknown"})`;
+    case "ACTION_FAILED":
+      return `Action failed (${d.actionId ?? "unknown"})`;
+    case "ACTION_COMMIT_UNKNOWN":
+      return `Action commit unknown (${d.actionId ?? "unknown"})`;
+    case "ACTION_RECONCILED":
+      return `Action reconciled (${d.actionId ?? "unknown"})`;
+    case "ACTION_CANCELLED":
+      return `Action cancelled (${d.actionId ?? "unknown"})`;
+    default:
+      return event.event;
+  }
+}
+
+export function normalizeProtocolEvent(event, context = {}) {
+  const phase = typeof context.phase === "string" ? context.phase : null;
+  return {
+    sequence: event.seq,
+    timestamp: event.at ?? null,
+    timestampSource: "ledger",
+    timestampQuality: timestampQuality(event),
+    type: event.event,
+    category: eventCategory(event.event),
+    phase,
+    phaseQuality: context.phaseQuality ?? "unknown",
+    source: {
+      kind: "ledger",
+      artifact: context.artifactPath ?? ".forgeloop/task-state/<task-key>/events.ndjson",
+    },
+    summary: eventSummary(event),
+    data: event.details ?? {},
+    references: {
+      checkIds: [event.details?.id, event.details?.checkId].filter((v) => typeof v === "string"),
+      evidenceRefs: Array.isArray(event.details?.evidenceRefs) ? event.details.evidenceRefs : [],
+      hypothesisRefs: Array.isArray(event.details?.hypothesisRefs)
+        ? event.details.hypothesisRefs
+        : [event.details?.hypothesisRef].filter((v) => typeof v === "string"),
+      interventionRefs: [event.details?.intervention?.id].filter((v) => typeof v === "string"),
+      relatedSequences: [],
+    },
+    hash: event.hash,
+  };
+}
+
+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();
+  const pushAttempt = (key, attempt) => {
+    if (!attemptsByCheck.has(key)) attemptsByCheck.set(key, []);
+    attemptsByCheck.get(key).push(attempt);
+  };
+
+  // Ledger chronology is the primary source of historical attempts.
+  const ledgerIdentityKeys = new Set();
+  for (const event of snapshot.events) {
+    if (event.event !== "VERIFICATION_RECORDED") continue;
+    const d = event.details ?? {};
+    const key = d.id ?? d.checkId ?? d.requirement ?? null;
+    if (!key) continue;
+    ledgerIdentityKeys.add(`${key}@@${d.verificationCycle ?? "*"}`);
+    pushAttempt(key, {
+      sequence: event.seq,
+      at: event.at,
+      status: d.status ?? null,
+      exitCode: d.exitCode ?? null,
+      requirement: d.requirement ?? null,
+      verificationCycle: d.verificationCycle ?? null,
+      provenance: d.provenance ?? null,
+      executionMode: d.provenance === "FORGELOOP_EXECUTED"
+        ? "executed"
+        : (d.provenance === "ACTOR_REPORTED" || d.provenance === "MANUAL_OBSERVATION" ? "observed" : (d.executionId ? "executed" : "unknown")),
+      failureToken: d.failureToken ?? d.details?.failureToken ?? null,
+      source: "ledger",
+    });
+  }
+
+  // State checks only enrich or fill legacy gaps; never duplicate ledger attempts.
+  for (const check of state?.checks ?? []) {
+    const key = check.id ?? check.checkId ?? null;
+    if (!key) continue;
+    const identityKey = `${key}@@${check.details?.verificationCycle ?? "*"}`;
+    if (ledgerIdentityKeys.has(identityKey) || ledgerIdentityKeys.has(`${key}@@*`)) continue;
+    pushAttempt(key, {
+      sequence: null,
+      at: check.at ?? check.lastUpdatedAt ?? null,
+      status: check.status,
+      exitCode: check.exitCode ?? null,
+      requirement: check.requirement ?? null,
+      verificationCycle: check.details?.verificationCycle ?? null,
+      provenance: check.provenance ?? null,
+      executionMode: check.provenance === "ACTOR_REPORTED" || check.provenance === "MANUAL_OBSERVATION" ? "observed" : "executed",
+      failureToken: check.details?.failureToken ?? null,
+      source: "state-fallback",
+    });
+  }
+
+  const checks = [];
+  const MAX = Number.MAX_SAFE_INTEGER;
+  for (const [id, attempts] of [...attemptsByCheck.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    attempts.sort((a, b) =>
+      ((a.verificationCycle ?? MAX) - (b.verificationCycle ?? MAX))
+      || ((a.sequence ?? MAX) - (b.sequence ?? MAX)));
+    checks.push({
+      id,
+      requirement: attempts.findLast((a) => a.requirement)?.requirement ?? null,
+      attemptCount: attempts.length,
+      failedAttempts: attempts.filter((a) => a.status === "failed" || a.status === "blocked").length,
+      currentResult: attempts.at(-1)?.status ?? null,
+      attempts,
+    });
+  }
+  return checks;
+}
+
+function legacyDiagnoses(events, taskId) {
+  return diagnosisEventsForTask(events, taskId).map((event) => ({
+    sequence: event.seq,
+    at: event.at,
+    sourceModel: "LEGACY_DIAGNOSIS_V1",
+    ...event.details,
+  }));
+}
+
+function structuredDiagnostics(events) {
+  const cases = [];
+  const interventions = [];
+  const dispositions = [];
+  const invalidRevisions = [];
+  const lastCaseByCycle = new Map();
+  for (const event of events) {
+    try {
+      if (event.event === "DIAGNOSTIC_CASE_RECORDED") {
+        assertDiagnosticCaseDetails(event.details);
+        const cycle = event.details?.verificationCycle;
+        const previous = lastCaseByCycle.get(cycle);
+        if (Number.isInteger(event.details?.diagnosticRevision) && event.details.diagnosticRevision > 1 && previous) {
+          if (event.details.previousDiagnosticFingerprint !== previous.diagnosticFingerprint) {
+            invalidRevisions.push({
+              sequence: event.seq,
+              verificationCycle: cycle,
+              code: "E_DIAGNOSTIC_CASE_INVALID",
+              message: "Revision chain broken: previousDiagnosticFingerprint does not match the prior case fingerprint.",
+            });
+            continue;
+          }
+        }
+        lastCaseByCycle.set(cycle, event.details);
+        cases.push({ sequence: event.seq, at: event.at, ...event.details });
+      } else if (event.event === "INTERVENTION_RECORDED") {
+        assertInterventionDetails(event.details);
+        interventions.push({ sequence: event.seq, at: event.at, ...event.details });
+      } else if (event.event === "HYPOTHESIS_DISPOSITION_RECORDED") {
+        assertHypothesisDispositionDetails(event.details);
+        dispositions.push({ sequence: event.seq, at: event.at, ...event.details });
+      }
+    } catch {
+      // Invalid diagnostic details surface through ledger integrity errors;
+      // projections must not crash on them.
+    }
+  }
+  return { cases, interventions, dispositions, invalidRevisions };
+}
+
+const PHASE_MILESTONES = Object.freeze({
+  TASK_RECEIVED: { phase: "RECEIVED", quality: "authoritative" },
+  CONTRACT_VALIDATED: { phase: "CONTRACT_READY", quality: "authoritative" },
+  ROUTE_VALIDATED: { phase: "ROUTED", quality: "authoritative" },
+  DESIGN_GATE_STARTED: { phase: "DESIGNING", quality: "authoritative" },
+  PLAN_RECORDED: { phase: "PLANNED", quality: "authoritative" },
+  EXECUTION_STARTED: { phase: "EXECUTING", quality: "authoritative" },
+  VERIFICATION_STARTED: { phase: "VERIFYING", quality: "authoritative" },
+  REVIEW_STARTED: { phase: "REVIEWING", quality: "authoritative" },
+  COMPLETION_VALIDATED: { phase: "COMPLETE", quality: "authoritative" },
+});
+
+const PHASE_DERIVATIONS = Object.freeze({
+  VERIFICATION_RECORDED: (details) => (["failed", "blocked"].includes(details?.status) ? "DIAGNOSING" : null),
+  DIAGNOSIS_RECORDED: () => "DIAGNOSING",
+  DIAGNOSTIC_CASE_RECORDED: () => "DIAGNOSING",
+  HYPOTHESIS_DISPOSITION_RECORDED: () => "CORRECTING",
+  INTERVENTION_RECORDED: () => "CORRECTING",
+});
+
+function reconstructPhaseChronology(events) {
+  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");
+      }
+    }
+    phaseBySequence.set(event.seq, currentPhase);
+  }
+  return { phaseBySequence, qualityBySequence };
+}
+
+export function historyQualityFor({ snapshot, normalizedEvents }) {
+  const reasons = [];
+  const hasLedger = normalizedEvents.length > 0;
+  if (!hasLedger) reasons.push("LEDGER_ABSENT");
+  if (normalizedEvents.some((event) => event.timestampQuality !== "authoritative")) {
+    reasons.push("LEGACY_PHASE_TIMESTAMPS_UNAVAILABLE");
+  }
+  if (snapshot.state && Number.isInteger(snapshot.state.verificationCycle) && snapshot.state.verificationCycle > 1
+    && !snapshot.events.some((event) => event.event === "DIAGNOSIS_RECORDED" || event.event === "DIAGNOSTIC_CASE_RECORDED")) {
+    reasons.push("STRUCTURED_DIAGNOSTICS_UNAVAILABLE");
+  }
+  const level = reasons.length === 0 ? "COMPLETE" : (hasLedger ? "PARTIAL" : "MINIMAL");
+  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";
+
+  const taskEvents = taskId ? snapshot.events.filter((event) => !event.taskId || event.taskId === taskId) : snapshot.events;
+  const { phaseBySequence, qualityBySequence } = reconstructPhaseChronology(taskEvents);
+  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 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();
+  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 ?? [])
+        : []),
+    ];
+    for (const ref of refs) {
+      if (!ref) continue;
+      if (!evidenceSources.has(ref)) evidenceSources.set(ref, { ref, sources: [] });
+      if (!evidenceSources.get(ref).sources.includes(event.event)) evidenceSources.get(ref).sources.push(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 ?? {} }));
+
+  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 actions = snapshot.taskId
+    ? await listActions(target, { packageRoot, taskId: snapshot.taskId })
+    : [];
+  // Artifacts are the current-state materialization; chronology comes from
+  // the canonical ledger replay projection, never from artifacts alone.
+  const { projectActionLedger } = await import("./action-ledger-projection.js");
+  const projections = [];
+  for (const action of actions) {
+    projections.push(await projectActionLedger({
+      target,
+      packageRoot,
+      taskId: snapshot.taskId,
+      actionId: action.actionId,
+      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()
+    .map((capability) => [capability, actions.filter((action) => action.capability === capability).length]));
+  const idempotencyAttempts = actions.map((action) => action.idempotencyKey).filter(Boolean);
+  const repeatedIdempotencyAttempts = idempotencyAttempts.length - new Set(idempotencyAttempts).size;
+  const actionProjection = {
+    total: actions.length,
+    byState,
+    byCapability,
+    required: actions.filter((action) => action.requiredForCompletion).length,
+    ambiguous: actions.filter((action) => action.state === "COMMIT_UNKNOWN").length,
+    failed: actions.filter((action) => action.state === "FAILED").length,
+    verified: actions.filter((action) => action.state === "VERIFIED").length,
+    trustedSatisfied: projections.filter(
+      (projection) => projection.valid && projection.state === "VERIFIED"
+        && projection.authorization.valid && projection.verification.valid,
+    ).length,
+    untrustedRequired: projections.filter((projection) =>
+      !projection.valid
+      || (projection.state === "VERIFIED" && !(projection.authorization.valid && projection.verification.valid))
+    ).length,
+    repeatedIdempotencyAttempts,
+    reconciliationCount: taskEvents.filter((event) => event.event === "ACTION_RECONCILED").length,
+    eventCount: actionEvents.length,
+  };
+
+  return {
+    schemaVersion: 1,
+    protocolVersion: 1,
+    command: "trace",
+    task: {
+      id: snapshot.taskId,
+      phase: snapshot.state?.phase ?? null,
+      status: snapshot.state?.status ?? null,
+      revision: snapshot.state?.revision ?? null,
+      verificationCycle: snapshot.state?.verificationCycle ?? null,
+      present: Boolean(snapshot.state),
+    },
+    snapshot: {
+      consistent: snapshot.consistent,
+      stateRevision: snapshot.anchors.stateRevision,
+      ledgerTailSequence: snapshot.anchors.sequence,
+      capturedAt: snapshot.capturedAt,
+    },
+    historyQuality,
+    integrity,
+    artifacts: {},
+    events: normalizedEvents,
+    transitions: lifecycleTransitions(taskEvents),
+    executions,
+    checks: projectChecks(snapshot),
+    evidence,
+    diagnostics: {
+      legacyDiagnoses: legacyDiagnoses(taskEvents, snapshot.taskId),
+      ...diagnostics,
+    },
+    failureSignatures,
+    failureSurfaces,
+    continuity: taskEvents
+      .filter((event) => ["CONTINUITY_RECORDED", "CHECKPOINT_RECONCILED"].includes(event.event))
+      .map((event) => ({ sequence: event.seq, at: event.at, type: event.event })),
+    recovery,
+    policy: {},
+    audit: {},
+    completion,
+    actions: actionProjection,
+  };
+}

package/src/core/trajectory-evaluation.js

@@ -0,0 +1,71 @@
+import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { canonicalFingerprint, writeJsonArtifact } from "./artifacts.js";
+import { buildTaskTrace } from "./trace.js";
+import { buildTrajectoryMetrics } from "./trajectory-metrics.js";
+import { assertSchema, readSchema } from "./schema-validation.js";
+import { taskEvaluationPath } from "./task-paths.js";
+import { appendProtocolEvent } from "./events.js";
+import { assertSafePath, ensureWithin } from "./filesystem.js";
+import { withTaskTransaction } from "./transaction.js";
+
+function evaluationError(code, message) { const error = new Error(message); error.code = code; return error; }
+
+export async function evaluateTrajectory({ target, packageRoot, taskId, scenarioPath, evaluationId = `eval-${randomUUID()}` }) {
+  if (typeof scenarioPath !== "string" || !scenarioPath || path.isAbsolute(scenarioPath) || scenarioPath.includes("..")) {
+    throw evaluationError("E_TRAJECTORY_SCENARIO_INVALID", "scenario path must be a relative project-local file");
+  }
+  let scenario;
+  try {
+    await assertSafePath(target, scenarioPath);
+    scenario = JSON.parse(await readFile(ensureWithin(target, scenarioPath), "utf8"));
+  } catch (error) {
+    throw evaluationError("E_TRAJECTORY_SCENARIO_INVALID", `unable to read scenario safely: ${error.message}`);
+  }
+  assertSchema(scenario, await readSchema("trajectory-scenario", packageRoot), "trajectory scenario");
+  if (!/^eval-[A-Za-z0-9_-]+$/.test(evaluationId)) throw evaluationError("E_TRAJECTORY_SCENARIO_INVALID", "evaluationId is invalid");
+  const trace = await buildTaskTrace({ target, packageRoot, taskId });
+  const metrics = await buildTrajectoryMetrics({ target, packageRoot, taskId });
+  const milestoneSet = new Set(trace.events.map((event) => event.type));
+  const missingMilestones = (scenario.requiredMilestones ?? []).filter((milestone) => !milestoneSet.has(milestone));
+  const completionEvent = trace.events.find((event) => event.type === "COMPLETION_VALIDATED");
+  const verificationEvent = trace.events.find((event) => event.type === "VERIFICATION_STARTED" || event.type === "VERIFICATION_RECORDED");
+  const completionBeforeVerification = Boolean(completionEvent && (!verificationEvent || completionEvent.sequence < verificationEvent.sequence));
+  // Canonical truth: ambiguous actions or unresolved trusted-readiness items
+  // block safety. A raw VERIFIED label alone never resolves a required action.
+  const unresolvedRequiredAction = (trace.actions?.ambiguous ?? 0) > 0
+    || ((metrics.actions.unresolvedRequired ?? null) !== null
+      ? metrics.actions.unresolvedRequired > 0
+      : (trace.actions?.required ?? 0) > (trace.actions?.verified ?? 0));
+  const limit = (name, actual, max) => ({ actual, ...(max === undefined ? {} : { max, pass: actual <= max }) });
+  const limits = {
+    verificationCycles: limit("verificationCycles", metrics.trajectory.verificationCycles, scenario.limits?.maxVerificationCycles),
+    nonInformativeInterventions: limit("nonInformativeInterventions", metrics.trajectory.interventions.nonInformative, scenario.limits?.maxNonInformativeInterventions),
+    ambiguousActions: limit("ambiguousActions", metrics.actions.ambiguous, scenario.limits?.maxAmbiguousActions),
+  };
+  const safetyValid = !(scenario.forbidden?.completionBeforeVerification && completionBeforeVerification)
+    && !(scenario.forbidden?.unresolvedRequiredAction && unresolvedRequiredAction);
+  const completionValid = metrics.completion.validated && missingMilestones.length === 0;
+  const limitsValid = Object.values(limits).every((item) => item.pass !== false);
+  // Comparable steps have exactly one owner: buildTrajectoryMetrics.
+  const efficiency = Number.isInteger(scenario.reference?.comparableSteps) && scenario.reference.comparableSteps > 0
+    ? { referenceComparableSteps: scenario.reference.comparableSteps, actualComparableSteps: metrics.comparableSteps,
+      ratio: scenario.reference.comparableSteps / Math.max(1, metrics.comparableSteps) }
+    : null;
+  const base = {
+    schemaVersion: 1, evaluationId, scenarioId: scenario.scenarioId,
+    scenarioFingerprint: canonicalFingerprint(scenario), taskId,
+    result: completionValid && safetyValid && limitsValid ? "PASS" : "FAIL",
+    completionValid, safetyValid, missingMilestones, limits, efficiency,
+    computedAt: new Date().toISOString(), source: "PROJECT_LOCAL_REFERENCE",
+  };
+  const evaluation = { ...base, evaluationFingerprint: canonicalFingerprint(base) };
+  assertSchema(evaluation, await readSchema("trajectory-evaluation", packageRoot), "trajectory evaluation");
+  await withTaskTransaction({ target, taskId, operation: "trajectory-evaluated" }, async () => {
+    await writeJsonArtifact(target, taskEvaluationPath(taskId, evaluationId), evaluation, "trajectory-evaluation", packageRoot);
+    await appendProtocolEvent(target, { taskId, event: "TRAJECTORY_EVALUATED", fingerprint: evaluation.evaluationFingerprint,
+      details: { evaluationId, scenarioId: scenario.scenarioId, evaluationFingerprint: evaluation.evaluationFingerprint } }, packageRoot, { taskId });
+  });
+  return evaluation;
+}