sdd-agent-platform 0.4.0 → 0.4.2

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

@@ -0,0 +1,425 @@
+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);
+}