sdd-agent-platform 0.4.2 → 0.5.0

package/node_modules/@sdd-agent-platform/core/src/workflow-gate/evidence-packet.ts

@@ -1,425 +1,190 @@
-import { createHash } from 'node:crypto';
-import { readFile } from 'node:fs/promises';
-import { WORKFLOW_GATE_RUNTIME_CONTRACT_VERSION, type SddStage } from '../contracts.js';
-import { createRuntimeEvidenceSet, listRuntimeArtifactPayloads, listRuntimeDurableGaps, listRuntimeFanInEvidenceSets, listRuntimeLlmAdvisorAssessments, listRuntimeRepairs, recordRuntimeRepair, recordRuntimeWorkflowGateDecision, resolveRuntimeSelectedEvidence, runtimeScopedId, updateRuntimeSelectionPointer, type RuntimeArtifactPayloadRecord, type RuntimeEvidenceSetScopeKind, type RuntimeRepairRecord } from '../storage/runtime-store.js';
-import { getBranchStageEvidencePathFromRef, getEvidenceAttachmentPath, isBranchStageEvidenceRef, toBranchStageEvidenceRef } from '../runtime-paths.js';
-import { readAllRunStates } from '../run-state/run-state.js';
-import { affectedFileConflictsForSelectedRuns } from '../workflow-state/affected-file-conflicts.js';
-import { resolveWorkflowState } from '../workflow-state/resolve.js';
-import { evaluateWorkflowGateHardChecks } from './hard-checks.js';
-import { synthesizeWorkflowGateDecision } from './policy.js';
-import type { WorkflowGateDecision, WorkflowGateDecisionKind, WorkflowGateEvidencePacket } from './types.js';
-
-export async function buildWorkflowGateEvidencePacket(projectRoot: string, input: { branch?: string | null; taskId?: string | null; runId?: string | null; decisionKind: WorkflowGateDecisionKind; waveRunId?: string | null; taskIds?: string[]; runIds?: string[]; evidenceRefs?: string[] }): Promise<WorkflowGateEvidencePacket> {
-  const workflow = await resolveWorkflowState(projectRoot, { branch: input.branch, branchSource: input.branch ? 'cli_option' : undefined, taskId: input.taskId ?? null });
-  const taskId = input.taskId ?? workflow.latestRun?.taskId ?? workflow.model.tasks[0]?.id ?? null;
-  const selection = taskId ? workflow.latestEligibleRunsByTask.find((candidate) => candidate.taskId === taskId) ?? null : null;
-  const runId = input.runId ?? selection?.selected?.runId ?? workflow.latestRun?.runId ?? null;
-  const defaultTaskIds = input.decisionKind === 'ship'
-    ? workflow.model.tasks.filter((task) => task.status !== 'deferred').map((task) => task.id)
-    : taskId ? [taskId] : [];
-  const scopedTaskIds = sortedUnique(input.taskIds ?? defaultTaskIds);
-  const scopedLatestEligibleSelections = scopedTaskIds.length > 0
-    ? scopedTaskIds.map((scopedTaskId) => workflow.latestEligibleRunsByTask.find((candidate) => candidate.taskId === scopedTaskId) ?? emptyLatestEligibleSelection(workflow.branch, scopedTaskId))
-    : (selection ? [selection] : []);
-  const scopedRunIds = sortedUnique(input.runIds ?? (input.runId ? [input.runId] : scopedLatestEligibleSelections.flatMap((candidate) => candidate.selected ? [candidate.selected.runId] : [])));
-  const workflowScope = {
-    waveRunId: input.waveRunId ?? null,
-    taskIds: scopedTaskIds,
-    runIds: scopedRunIds.length > 0 ? scopedRunIds : sortedUnique(runId ? [runId] : []),
-    evidenceRefs: sortedUnique(input.evidenceRefs ?? [])
-  };
-  const scopedTasks = workflowScope.taskIds.length > 0
-    ? workflow.model.tasks.filter((candidate) => workflowScope.taskIds.includes(candidate.id))
-    : workflow.model.tasks.filter((candidate) => candidate.id === taskId);
-  const runtimeInputs = await loadRuntimeGateInputs(projectRoot, workflow.branch, workflowScope.taskIds, workflowScope.runIds);
-  const selectedEvidence = normalizeSelectedEvidenceRefs(workflow.branch, await resolveRuntimeSelectedEvidence(projectRoot, { branchSlug: workflow.branch, scopeKind: evidenceScopeKind(input.decisionKind), scopeId: evidenceScopeId(input.decisionKind, workflowScope.taskIds, input.waveRunId), fallbackRunIds: workflowScope.runIds, fallbackTaskIds: workflowScope.taskIds, fallbackLogicalRefPrefixes: fallbackLogicalRefPrefixes(workflow.branch, input.decisionKind), allowCandidateFallback: true }));
-  const scopedAffectedFileConflicts = await loadScopedAffectedFileConflicts(projectRoot, workflow.affectedFileConflicts, workflowScope.runIds);
-  const scopedDependencyBlockers = input.decisionKind === 'ship'
-    ? workflow.dependencyBlockers
-    : workflow.dependencyBlockers.filter((blocker) => workflowScope.taskIds.includes(blocker.taskId));
-  const packetBase = {
-    packetId: runtimeScopedId(WORKFLOW_GATE_RUNTIME_CONTRACT_VERSION, workflow.branch, taskId ?? 'none', runId ?? 'none', input.decisionKind),
-    generatedAt: new Date().toISOString(),
-    decisionKind: input.decisionKind,
-    partition: workflow.branch,
-    taskId,
-    runId,
-    documents: workflow.documents,
-    latestEligibleSelection: selection,
-    latestEligibleSelections: scopedLatestEligibleSelections,
-    workflowScope,
-    runtimeHealth: runtimeInputs.runtimeHealth,
-    durableGaps: runtimeInputs.durableGaps,
-    dependencyBlockers: scopedDependencyBlockers,
-    affectedFileConflicts: scopedAffectedFileConflicts,
-    fanInEvidenceSets: runtimeInputs.fanInEvidenceSets,
-    advisorAssessments: runtimeInputs.advisorAssessments,
-    selectedEvidence,
-    canonicalEvidenceRefs: sortedUnique([...workflowScope.evidenceRefs, ...selectedEvidence.payloads.map((payload) => payload.logicalRef)]),
-    requiredArtifactRefs: sortedUnique(scopedTasks.flatMap((task) => task.requiredArtifacts)),
-    artifactPayloadHealth: await inspectArtifactPayloadHealth(projectRoot, selectedEvidence.payloads)
-  };
-  return {
-    ...packetBase,
-    hardChecks: evaluateWorkflowGateHardChecks(packetBase)
-  };
-}
-
-function evidenceScopeKind(decisionKind: WorkflowGateDecisionKind): RuntimeEvidenceSetScopeKind {
-  return decisionKind === 'ship' ? 'ship' : decisionKind === 'validation_wave' ? 'wave' : 'task';
-}
-
-function evidenceScopeId(decisionKind: WorkflowGateDecisionKind, taskIds: string[], waveRunId?: string | null): string {
-  if (decisionKind === 'ship') {
-    return 'workflow';
-  }
-  if (decisionKind === 'validation_wave') {
-    return waveRunId ?? 'wave';
-  }
-  return taskIds.length === 1 ? taskIds[0] : taskIds.join('+') || 'none';
-}
-
-function fallbackLogicalRefPrefixes(branch: string, decisionKind: WorkflowGateDecisionKind): string[] {
-  if (decisionKind === 'ship') {
-    return [`.sdd/runs/${branch}/ship/`, `.sdd/runs/${branch}/goal-verify/`, `.sdd/runs/${branch}/test/`];
-  }
-  if (decisionKind === 'validation_wave') {
-    return [`.sdd/runs/${branch}/test/`];
-  }
-  if (decisionKind === 'test') {
-    return [`.sdd/runs/${branch}/test/`];
-  }
-  if (decisionKind === 'stage_transition') {
-    return [`.sdd/runs/${branch}/do/`];
-  }
-  return [`.sdd/runs/${branch}/do/`];
-}
-
-
-function emptyLatestEligibleSelection(partition: string, taskId: string): WorkflowGateEvidencePacket['latestEligibleSelections'][number] {
-  return {
-    partition,
-    taskId,
-    selected: null,
-    candidates: [],
-    rejected: []
-  };
-}
-
-async function loadScopedAffectedFileConflicts(projectRoot: string, fallback: WorkflowGateEvidencePacket['affectedFileConflicts'], runIds: string[]): Promise<WorkflowGateEvidencePacket['affectedFileConflicts']> {
-  if (runIds.length === 0) {
-    return fallback;
-  }
-  const states = await readAllRunStates(projectRoot);
-  const selectedRuns = states.filter((state) => runIds.includes(state.runId));
-  return affectedFileConflictsForSelectedRuns(states, selectedRuns);
-}
-
-async function loadRuntimeGateInputs(projectRoot: string, partition: string, taskIds: string[], runIds: string[]): Promise<{
-  runtimeHealth: WorkflowGateEvidencePacket['runtimeHealth'];
-  durableGaps: WorkflowGateEvidencePacket['durableGaps'];
-  fanInEvidenceSets: WorkflowGateEvidencePacket['fanInEvidenceSets'];
-  advisorAssessments: WorkflowGateEvidencePacket['advisorAssessments'];
-  payloads: RuntimeArtifactPayloadRecord[];
-}> {
-  try {
-    const runtimeScopes = scopedRuntimeQueries(taskIds, runIds);
-    const [durableGapResults, fanInEvidenceSetResults, advisorAssessmentResults, payloadResults] = await Promise.all([
-      Promise.all(runtimeScopes.map((scope) => listRuntimeDurableGaps(projectRoot, { partition, taskId: scope.taskId, runId: scope.runId, status: 'open_terminal' }))),
-      Promise.all(runtimeScopes.map((scope) => listRuntimeFanInEvidenceSets(projectRoot, { partition, taskId: scope.taskId, runId: scope.runId }))),
-      Promise.all(runtimeScopes.map((scope) => listRuntimeLlmAdvisorAssessments(projectRoot, { partition, taskId: scope.taskId, runId: scope.runId }))),
-      Promise.all(runIds.map((scopedRunId) => listRuntimeArtifactPayloads(projectRoot, { runId: scopedRunId })))
-    ]);
-    return {
-      runtimeHealth: { status: 'ok', issues: [] },
-      durableGaps: uniqueBy(durableGapResults.flat(), (gap) => gap.gapId),
-      fanInEvidenceSets: uniqueBy(fanInEvidenceSetResults.flat(), (evidenceSet) => evidenceSet.fanInId),
-      advisorAssessments: uniqueBy(advisorAssessmentResults.flat(), (assessment) => assessment.assessmentId),
-      payloads: uniqueBy(payloadResults.flat(), (payload) => payload.payloadId)
-    };
-  } catch (error) {
-    return {
-      runtimeHealth: { status: 'unavailable', issues: [messageFromError(error)] },
-      durableGaps: [],
-      fanInEvidenceSets: [],
-      advisorAssessments: [],
-      payloads: []
-    };
-  }
-}
-
-function scopedRuntimeQueries(taskIds: string[], runIds: string[]): Array<{ taskId: string | null; runId: string | null }> {
-  if (taskIds.length === 0 && runIds.length === 0) {
-    return [{ taskId: null, runId: null }];
-  }
-  if (taskIds.length === 0) {
-    return runIds.map((scopedRunId) => ({ taskId: null, runId: scopedRunId }));
-  }
-  if (runIds.length === 0) {
-    return taskIds.map((scopedTaskId) => ({ taskId: scopedTaskId, runId: null }));
-  }
-  return uniqueBy([
-    ...taskIds.flatMap((scopedTaskId) => runIds.map((scopedRunId) => ({ taskId: scopedTaskId, runId: scopedRunId }))),
-    ...taskIds.map((scopedTaskId) => ({ taskId: scopedTaskId, runId: null })),
-    ...runIds.map((scopedRunId) => ({ taskId: null, runId: scopedRunId }))
-  ], (scope) => `${scope.taskId ?? 'none'}:${scope.runId ?? 'none'}`);
-}
-
-function uniqueBy<T>(items: T[], keyOf: (item: T) => string): T[] {
-  const seen = new Set<string>();
-  return items.filter((item) => {
-    const key = keyOf(item);
-    if (seen.has(key)) {
-      return false;
-    }
-    seen.add(key);
-    return true;
-  });
-}
-
-function normalizeSelectedEvidenceRefs(branch: string, selectedEvidence: Awaited<ReturnType<typeof resolveRuntimeSelectedEvidence>>): Awaited<ReturnType<typeof resolveRuntimeSelectedEvidence>> {
-  return {
-    ...selectedEvidence,
-    payloads: selectedEvidence.payloads.map((payload) => normalizeArtifactPayloadRef(branch, payload))
-  };
-}
-
-function normalizeArtifactPayloadRef(branch: string, payload: RuntimeArtifactPayloadRecord): RuntimeArtifactPayloadRecord {
-  const fileName = payload.logicalRef.replace(/\\/g, '/').split('/').filter(Boolean).pop();
-  if (!fileName || isBranchStageEvidenceRef(payload.logicalRef)) {
-    return payload;
-  }
-  const logicalRef = toBranchStageEvidenceRef(branch, stageForPayload(payload, fileName), fileName);
-  return {
-    ...payload,
-    logicalRef,
-    payload: normalizeArtifactPayloadMetadata(payload.payload, logicalRef)
-  };
-}
-
-function normalizeArtifactPayloadMetadata(value: unknown, logicalRef: string): unknown {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) {
-    return value;
-  }
-  return {
-    ...value,
-    logicalRef,
-    artifactPath: logicalRef
-  };
-}
-
-function stageForPayload(payload: RuntimeArtifactPayloadRecord, fileName: string): SddStage {
-  const role = payload.artifactRole.toLowerCase();
-  if (role.includes('goal') || fileName.startsWith('acceptance-coverage-')) {
-    return 'goal-verify';
-  }
-  if (role.includes('validation') || fileName.startsWith('validation-') || fileName.startsWith('test-validation-') || fileName.startsWith('test-')) {
-    return 'test';
-  }
-  if (role.includes('ship') || fileName.startsWith('ship-') || fileName.startsWith('release-')) {
-    return 'ship';
-  }
-  return 'do';
-}
-
-async function inspectArtifactPayloadHealth(projectRoot: string, payloads: RuntimeArtifactPayloadRecord[]): Promise<WorkflowGateEvidencePacket['artifactPayloadHealth']> {
-  return Promise.all(payloads.map(async (payload) => {
-    try {
-      const raw = await payloadPhysicalContent(projectRoot, payload);
-      const actualDigest = hashDocumentContent(raw);
-      return {
-        payloadId: payload.payloadId,
-        logicalRef: payload.logicalRef,
-        physicalPayloadPath: payload.physicalPayloadPath,
-        expectedDigest: payload.digest,
-        actualDigest,
-        status: actualDigest === payload.digest ? 'ok' as const : 'digest_drift' as const
-      };
-    } catch {
-      return {
-        payloadId: payload.payloadId,
-        logicalRef: payload.logicalRef,
-        physicalPayloadPath: payload.physicalPayloadPath,
-        expectedDigest: payload.digest,
-        actualDigest: null,
-        status: 'missing' as const
-      };
-    }
-  }));
-}
-
-async function payloadPhysicalContent(projectRoot: string, payload: RuntimeArtifactPayloadRecord): Promise<string> {
-  const runtimeContent = runtimePayloadContent(payload);
-  if (runtimeContent !== null) {
-    return runtimeContent;
-  }
-  if (isBranchStageEvidenceRef(payload.physicalPayloadPath)) {
-    return readFile(getBranchStageEvidencePathFromRef(projectRoot, payload.physicalPayloadPath), 'utf8');
-  }
-  return readFile(getEvidenceAttachmentPath(projectRoot, payload.branchSlug, payload.physicalPayloadPath), 'utf8');
-}
-
-function runtimePayloadContent(payload: RuntimeArtifactPayloadRecord): string | null {
-  if (!payload.payload || typeof payload.payload !== 'object' || Array.isArray(payload.payload)) {
-    return null;
-  }
-  const content = (payload.payload as { content?: unknown }).content;
-  return typeof content === 'string' ? content : null;
-}
-
-function hashDocumentContent(raw: string): string {
-  return createHash('sha256').update(raw.replace(/\r\n/g, '\n'), 'utf8').digest('hex');
-}
-
-export async function evaluateAndRecordWorkflowGateDecision(projectRoot: string, input: { branch?: string | null; taskId?: string | null; runId?: string | null; decisionKind: WorkflowGateDecisionKind; waveRunId?: string | null; taskIds?: string[]; runIds?: string[]; evidenceRefs?: string[] }): Promise<{ packet: WorkflowGateEvidencePacket; decision: WorkflowGateDecision }> {
-  let packet = await buildWorkflowGateEvidencePacket(projectRoot, input);
-  if (canBootstrapCandidateEvidenceSelection(packet)) {
-    await selectCandidateEvidenceForGateEvaluation(projectRoot, packet);
-    packet = await buildWorkflowGateEvidencePacket(projectRoot, input);
-  }
-  const decision = synthesizeWorkflowGateDecision(packet);
-  try {
-    await recordRuntimeWorkflowGateDecision(projectRoot, decision);
-    if (decision.status === 'PASS') {
-      await acceptRuntimeEvidenceSelection(projectRoot, packet, decision);
-      await closeOpenRepairsWithGatePass(projectRoot, packet, decision);
-    }
-  } catch (error) {
-    if (packet.runtimeHealth.status === 'ok') {
-      throw error;
-    }
-  }
-  return { packet, decision };
-}
-
-function canBootstrapCandidateEvidenceSelection(packet: WorkflowGateEvidencePacket): boolean {
-  const hardBlocks = packet.hardChecks.filter((check) => check.severity === 'blocked');
-  return packet.selectedEvidence.source === 'candidate_payloads'
-    && packet.selectedEvidence.payloads.length > 0
-    && hardBlocks.length > 0
-    && hardBlocks.every((check) => check.code === 'missing_evidence_selection');
-}
-
-async function selectCandidateEvidenceForGateEvaluation(projectRoot: string, packet: WorkflowGateEvidencePacket): Promise<void> {
-  const scopeKind = evidenceScopeKind(packet.decisionKind);
-  const scopeId = evidenceScopeId(packet.decisionKind, packet.workflowScope.taskIds, packet.workflowScope.waveRunId);
-  const selectedAt = new Date().toISOString();
-  const evidenceSetId = runtimeScopedId(WORKFLOW_GATE_RUNTIME_CONTRACT_VERSION, packet.partition, scopeKind, scopeId, packet.packetId, 'candidate-evidence-selection');
-  const evidenceSet = await createRuntimeEvidenceSet(projectRoot, {
-    evidenceSetId,
-    branchSlug: packet.partition,
-    scopeKind,
-    scopeId,
-    sourceRunId: packet.runId,
-    documentContractHashes: documentContractHashes(packet),
-    gateDecisionId: null,
-    status: 'accepted',
-    items: packet.selectedEvidence.payloads.map((payload) => ({
-      evidenceSetId,
-      payloadId: payload.payloadId,
-      logicalRef: payload.logicalRef,
-      role: payload.artifactRole,
-      required: packet.requiredArtifactRefs.includes(payload.logicalRef),
-      digestAtSelection: payload.digest
-    })),
-    payload: {
-      decisionKind: packet.decisionKind,
-      source: packet.selectedEvidence.source,
-      canonicalEvidenceRefs: packet.canonicalEvidenceRefs,
-      workflowScope: packet.workflowScope
-    }
-  });
-  await updateRuntimeSelectionPointer(projectRoot, {
-    branchSlug: packet.partition,
-    scopeKind,
-    scopeId,
-    selectedEvidenceSetId: evidenceSet.evidenceSetId,
-    selectedAt,
-    selectedByGateDecisionId: null,
-    reason: `Selected candidate ${packet.decisionKind} evidence for runtime gate evaluation.`
-  });
-}
-
-async function acceptRuntimeEvidenceSelection(projectRoot: string, packet: WorkflowGateEvidencePacket, decision: WorkflowGateDecision): Promise<void> {
-  const scopeKind = evidenceScopeKind(packet.decisionKind);
-  const scopeId = evidenceScopeId(packet.decisionKind, packet.workflowScope.taskIds, packet.workflowScope.waveRunId);
-  const evidenceSetId = runtimeScopedId(WORKFLOW_GATE_RUNTIME_CONTRACT_VERSION, packet.partition, scopeKind, scopeId, decision.decisionId, 'accepted-evidence-set');
-  const evidenceSet = await createRuntimeEvidenceSet(projectRoot, {
-    evidenceSetId,
-    branchSlug: packet.partition,
-    scopeKind,
-    scopeId,
-    sourceRunId: packet.runId,
-    documentContractHashes: documentContractHashes(packet),
-    gateDecisionId: decision.decisionId,
-    status: 'accepted',
-    items: packet.selectedEvidence.payloads.map((payload) => ({
-      evidenceSetId,
-      payloadId: payload.payloadId,
-      logicalRef: payload.logicalRef,
-      role: payload.artifactRole,
-      required: packet.requiredArtifactRefs.includes(payload.logicalRef),
-      digestAtSelection: payload.digest
-    })),
-    payload: {
-      decisionKind: packet.decisionKind,
-      source: packet.selectedEvidence.source,
-      canonicalEvidenceRefs: packet.canonicalEvidenceRefs,
-      workflowScope: packet.workflowScope
-    }
-  });
-  await updateRuntimeSelectionPointer(projectRoot, {
-    branchSlug: packet.partition,
-    scopeKind,
-    scopeId,
-    selectedEvidenceSetId: evidenceSet.evidenceSetId,
-    selectedAt: decision.generatedAt,
-    selectedByGateDecisionId: decision.decisionId,
-    reason: `Accepted ${packet.decisionKind} gate PASS evidence.`
-  });
-}
-
-async function closeOpenRepairsWithGatePass(projectRoot: string, packet: WorkflowGateEvidencePacket, decision: WorkflowGateDecision): Promise<void> {
-  const openRepairs = await listRuntimeRepairs(projectRoot, { branchSlug: packet.partition, status: 'open' });
-  for (const repair of openRepairs.filter((candidate) => repairClosedByGatePacket(candidate, packet))) {
-    await recordRuntimeRepair(projectRoot, {
-      ...repair,
-      status: 'resolved',
-      resolvedAt: decision.generatedAt,
-      payload: {
-        ...objectPayload(repair.payload),
-        resolvedByGateDecisionId: decision.decisionId,
-        resolvedByDecisionKind: packet.decisionKind
-      }
-    });
-  }
-}
-
-function repairClosedByGatePacket(repair: RuntimeRepairRecord, packet: WorkflowGateEvidencePacket): boolean {
-  if (packet.decisionKind === 'ship') {
-    return true;
-  }
-  return Boolean(repair.taskId && packet.workflowScope.taskIds.includes(repair.taskId))
-    || repair.affectedTasks.some((taskId) => packet.workflowScope.taskIds.includes(taskId));
-}
-
-function objectPayload(payload: unknown): Record<string, unknown> {
-  return payload && typeof payload === 'object' && !Array.isArray(payload) ? payload as Record<string, unknown> : { previousPayload: payload };
-}
-
-function documentContractHashes(packet: WorkflowGateEvidencePacket): Record<string, string | null> {
-  return {
-    spec: packet.documents.specContractHash ?? null,
-    plan: packet.documents.planContractHash ?? null,
-    tasks: packet.documents.tasksContractHash ?? null,
-    verify: packet.documents.verifyContractHash ?? null
-  };
-}
-function sortedUnique(values: string[]): string[] {
-  return [...new Set(values.filter(Boolean))].sort();
-}
-
-function messageFromError(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { WORKFLOW_GATE_RUNTIME_CONTRACT_VERSION } from '../contracts.js';
+import { listRuntimeArtifactPayloads, listRuntimeDurableGaps, listRuntimeFanInEvidenceSets, listRuntimeLlmAdvisorAssessments, recordRuntimeWorkflowGateDecision, runtimeScopedId, type RuntimeArtifactPayloadRecord } from '../storage/runtime-store.js';
+import { getEvidenceAttachmentPath } from '../runtime-paths.js';
+import { readAllRunStates } from '../run-state/run-state.js';
+import { affectedFileConflictsForSelectedRuns } from '../workflow-state/affected-file-conflicts.js';
+import { resolveWorkflowState } from '../workflow-state/resolve.js';
+import { evaluateWorkflowGateHardChecks } from './hard-checks.js';
+import { synthesizeWorkflowGateDecision } from './policy.js';
+import type { WorkflowGateDecision, WorkflowGateDecisionKind, WorkflowGateEvidencePacket } from './types.js';
+
+export async function buildWorkflowGateEvidencePacket(projectRoot: string, input: { branch?: string | null; taskId?: string | null; runId?: string | null; decisionKind: WorkflowGateDecisionKind; waveRunId?: string | null; taskIds?: string[]; runIds?: string[]; evidenceRefs?: string[] }): Promise<WorkflowGateEvidencePacket> {
+  const workflow = await resolveWorkflowState(projectRoot, { branch: input.branch, branchSource: input.branch ? 'cli_option' : undefined, taskId: input.taskId ?? null });
+  const taskId = input.taskId ?? workflow.latestRun?.taskId ?? workflow.model.tasks[0]?.id ?? null;
+  const selection = taskId ? workflow.latestEligibleRunsByTask.find((candidate) => candidate.taskId === taskId) ?? null : null;
+  const runId = input.runId ?? selection?.selected?.runId ?? workflow.latestRun?.runId ?? null;
+  const scopedTaskIds = sortedUnique(input.taskIds ?? (taskId ? [taskId] : []));
+  const scopedLatestEligibleSelections = scopedTaskIds.length > 0
+    ? scopedTaskIds.map((scopedTaskId) => workflow.latestEligibleRunsByTask.find((candidate) => candidate.taskId === scopedTaskId) ?? emptyLatestEligibleSelection(workflow.branch, scopedTaskId))
+    : (selection ? [selection] : []);
+  const scopedRunIds = sortedUnique(input.runIds ?? scopedLatestEligibleSelections.flatMap((candidate) => candidate.selected ? [candidate.selected.runId] : []));
+  const workflowScope = {
+    waveRunId: input.waveRunId ?? null,
+    taskIds: scopedTaskIds,
+    runIds: scopedRunIds.length > 0 ? scopedRunIds : sortedUnique(runId ? [runId] : []),
+    evidenceRefs: sortedUnique(input.evidenceRefs ?? [])
+  };
+  const scopedTasks = workflowScope.taskIds.length > 0
+    ? workflow.model.tasks.filter((candidate) => workflowScope.taskIds.includes(candidate.id))
+    : workflow.model.tasks.filter((candidate) => candidate.id === taskId);
+  const runtimeInputs = await loadRuntimeGateInputs(projectRoot, workflow.branch, workflowScope.taskIds, workflowScope.runIds);
+  const scopedAffectedFileConflicts = await loadScopedAffectedFileConflicts(projectRoot, workflow.affectedFileConflicts, workflowScope.runIds);
+  const packetBase = {
+    packetId: runtimeScopedId(WORKFLOW_GATE_RUNTIME_CONTRACT_VERSION, workflow.branch, taskId ?? 'none', runId ?? 'none', input.decisionKind),
+    generatedAt: new Date().toISOString(),
+    decisionKind: input.decisionKind,
+    partition: workflow.branch,
+    taskId,
+    runId,
+    documents: workflow.documents,
+    latestEligibleSelection: selection,
+    latestEligibleSelections: scopedLatestEligibleSelections,
+    workflowScope,
+    runtimeHealth: runtimeInputs.runtimeHealth,
+    durableGaps: runtimeInputs.durableGaps,
+    dependencyBlockers: workflow.dependencyBlockers,
+    affectedFileConflicts: scopedAffectedFileConflicts,
+    fanInEvidenceSets: runtimeInputs.fanInEvidenceSets,
+    advisorAssessments: runtimeInputs.advisorAssessments,
+    canonicalEvidenceRefs: sortedUnique([...workflowScope.evidenceRefs, ...runtimeInputs.payloads.filter((payload) => payload.status === 'active').map((payload) => payload.logicalRef)]),
+    requiredArtifactRefs: sortedUnique(scopedTasks.flatMap((task) => task.requiredArtifacts)),
+    artifactPayloadHealth: await inspectArtifactPayloadHealth(projectRoot, runtimeInputs.payloads.filter((payload) => payload.status === 'active'))
+  };
+  return {
+    ...packetBase,
+    hardChecks: evaluateWorkflowGateHardChecks(packetBase)
+  };
+}
+
+function emptyLatestEligibleSelection(partition: string, taskId: string): WorkflowGateEvidencePacket['latestEligibleSelections'][number] {
+  return {
+    partition,
+    taskId,
+    selected: null,
+    candidates: [],
+    rejected: []
+  };
+}
+
+async function loadScopedAffectedFileConflicts(projectRoot: string, fallback: WorkflowGateEvidencePacket['affectedFileConflicts'], runIds: string[]): Promise<WorkflowGateEvidencePacket['affectedFileConflicts']> {
+  if (runIds.length === 0) {
+    return fallback;
+  }
+  const states = await readAllRunStates(projectRoot);
+  const selectedRuns = states.filter((state) => runIds.includes(state.runId));
+  return affectedFileConflictsForSelectedRuns(states, selectedRuns);
+}
+
+async function loadRuntimeGateInputs(projectRoot: string, partition: string, taskIds: string[], runIds: string[]): Promise<{
+  runtimeHealth: WorkflowGateEvidencePacket['runtimeHealth'];
+  durableGaps: WorkflowGateEvidencePacket['durableGaps'];
+  fanInEvidenceSets: WorkflowGateEvidencePacket['fanInEvidenceSets'];
+  advisorAssessments: WorkflowGateEvidencePacket['advisorAssessments'];
+  payloads: RuntimeArtifactPayloadRecord[];
+}> {
+  try {
+    const runtimeScopes = scopedRuntimeQueries(taskIds, runIds);
+    const [durableGapResults, fanInEvidenceSetResults, advisorAssessmentResults, payloadResults] = await Promise.all([
+      Promise.all(runtimeScopes.map((scope) => listRuntimeDurableGaps(projectRoot, { partition, taskId: scope.taskId, runId: scope.runId, status: 'open_terminal' }))),
+      Promise.all(runtimeScopes.map((scope) => listRuntimeFanInEvidenceSets(projectRoot, { partition, taskId: scope.taskId, runId: scope.runId }))),
+      Promise.all(runtimeScopes.map((scope) => listRuntimeLlmAdvisorAssessments(projectRoot, { partition, taskId: scope.taskId, runId: scope.runId }))),
+      Promise.all(runIds.map((scopedRunId) => listRuntimeArtifactPayloads(projectRoot, { runId: scopedRunId })))
+    ]);
+    return {
+      runtimeHealth: { status: 'ok', issues: [] },
+      durableGaps: uniqueBy(durableGapResults.flat(), (gap) => gap.gapId),
+      fanInEvidenceSets: uniqueBy(fanInEvidenceSetResults.flat(), (evidenceSet) => evidenceSet.fanInId),
+      advisorAssessments: uniqueBy(advisorAssessmentResults.flat(), (assessment) => assessment.assessmentId),
+      payloads: uniqueBy(payloadResults.flat(), (payload) => payload.payloadId)
+    };
+  } catch (error) {
+    return {
+      runtimeHealth: { status: 'unavailable', issues: [messageFromError(error)] },
+      durableGaps: [],
+      fanInEvidenceSets: [],
+      advisorAssessments: [],
+      payloads: []
+    };
+  }
+}
+
+function scopedRuntimeQueries(taskIds: string[], runIds: string[]): Array<{ taskId: string | null; runId: string | null }> {
+  if (taskIds.length === 0 && runIds.length === 0) {
+    return [{ taskId: null, runId: null }];
+  }
+  if (taskIds.length === 0) {
+    return runIds.map((scopedRunId) => ({ taskId: null, runId: scopedRunId }));
+  }
+  if (runIds.length === 0) {
+    return taskIds.map((scopedTaskId) => ({ taskId: scopedTaskId, runId: null }));
+  }
+  return uniqueBy([
+    ...taskIds.flatMap((scopedTaskId) => runIds.map((scopedRunId) => ({ taskId: scopedTaskId, runId: scopedRunId }))),
+    ...taskIds.map((scopedTaskId) => ({ taskId: scopedTaskId, runId: null })),
+    ...runIds.map((scopedRunId) => ({ taskId: null, runId: scopedRunId }))
+  ], (scope) => `${scope.taskId ?? 'none'}:${scope.runId ?? 'none'}`);
+}
+
+function uniqueBy<T>(items: T[], keyOf: (item: T) => string): T[] {
+  const seen = new Set<string>();
+  return items.filter((item) => {
+    const key = keyOf(item);
+    if (seen.has(key)) {
+      return false;
+    }
+    seen.add(key);
+    return true;
+  });
+}
+
+async function inspectArtifactPayloadHealth(projectRoot: string, payloads: RuntimeArtifactPayloadRecord[]): Promise<WorkflowGateEvidencePacket['artifactPayloadHealth']> {
+  return Promise.all(payloads.map(async (payload) => {
+    try {
+      const raw = await readFile(getEvidenceAttachmentPath(projectRoot, payload.branchSlug, payload.physicalPayloadPath), 'utf8');
+      const actualDigest = hashDocumentContent(raw);
+      return {
+        payloadId: payload.payloadId,
+        logicalRef: payload.logicalRef,
+        physicalPayloadPath: payload.physicalPayloadPath,
+        expectedDigest: payload.digest,
+        actualDigest,
+        status: actualDigest === payload.digest ? 'ok' as const : 'digest_drift' as const
+      };
+    } catch {
+      return {
+        payloadId: payload.payloadId,
+        logicalRef: payload.logicalRef,
+        physicalPayloadPath: payload.physicalPayloadPath,
+        expectedDigest: payload.digest,
+        actualDigest: null,
+        status: 'missing' as const
+      };
+    }
+  }));
+}
+
+function hashDocumentContent(raw: string): string {
+  return createHash('sha256').update(raw.replace(/\r\n/g, '\n'), 'utf8').digest('hex');
+}
+
+export async function evaluateAndRecordWorkflowGateDecision(projectRoot: string, input: { branch?: string | null; taskId?: string | null; runId?: string | null; decisionKind: WorkflowGateDecisionKind; waveRunId?: string | null; taskIds?: string[]; runIds?: string[]; evidenceRefs?: string[] }): Promise<{ packet: WorkflowGateEvidencePacket; decision: WorkflowGateDecision }> {
+  const packet = await buildWorkflowGateEvidencePacket(projectRoot, input);
+  const decision = synthesizeWorkflowGateDecision(packet);
+  try {
+    await recordRuntimeWorkflowGateDecision(projectRoot, decision);
+  } catch (error) {
+    if (packet.runtimeHealth.status === 'ok') {
+      throw error;
+    }
+  }
+  return { packet, decision };
+}
+function sortedUnique(values: string[]): string[] {
+  return [...new Set(values.filter(Boolean))].sort();
+}
+
+function messageFromError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}