sdd-agent-platform 0.4.1 → 0.5.0

package/node_modules/@sdd-agent-platform/core/src/run-state/model.ts

@@ -1,231 +1,253 @@
-import type {
-  ARTIFACT_RESULT_INGESTION_CONTRACT_VERSION,
-  DELEGATION_LIVENESS_CONTRACT,
-  DELEGATION_LIVENESS_VERSION,
-  EVENT_LOG_CONTRACT,
-  INVOCATION_LEDGER_CONTRACT_VERSION,
-  LEGACY_LIFECYCLE_DECISION_CONTRACT,
-  LIFECYCLE_DECISION_CONTRACT,
-  LIFECYCLE_DECISION_VERSION,
-  RUN_STATE_CONTRACT,
-  RUNTIME_VERSION
-} from '../contracts.js';
-
-export type RunStatus = 'created' | 'running' | 'completed' | 'blocked' | 'failed' | 'archived';
-
-export interface ArtifactIndexEntry {
-  path: string;
-  kind: string;
-  task: string | null;
-  agent: string | null;
-  createdAt: string;
-}
-
-export interface RunDocumentSnapshot {
-  specHash: string | null;
-  planHash: string | null;
-  tasksHash: string | null;
-  specContractHash: string | null;
-  planContractHash: string | null;
-  tasksContractHash: string | null;
-  planBasedOnSpecHash: string | null;
-  tasksBasedOnPlanHash: string | null;
-  planBasedOnSpecContractHash: string | null;
-  tasksBasedOnPlanContractHash: string | null;
-}
-
-export interface RunStateContractValidationIssue {
-  field: string;
-  message: string;
-  recommendation: string;
-}
-
-export interface RunStateTaskGap {
-  type: 'Document Gap' | 'Task Gap' | 'Dependency Gap';
-  severity: 'blocking' | 'warning';
-  taskId: string | null;
-  field: string;
-  message: string;
-  recommendation: string;
-}
-
-export interface RunStateLifecycleDecisionRecord {
-  contract: typeof LIFECYCLE_DECISION_CONTRACT | typeof LEGACY_LIFECYCLE_DECISION_CONTRACT;
-  version?: typeof LIFECYCLE_DECISION_VERSION;
-  model_version: string;
-  input_summary: Record<string, unknown>;
-  decision: {
-    profile: string | null;
-    confidence: string | null;
-    hard_gate_hits: string[];
-    required_stages: string[];
-    skipped_stages: string[];
-    human_checkpoint_required: boolean;
-  };
-  reasons: string[];
-  escalation_triggers: string[];
-  downgrade_reason: string | null;
-  audit: {
-    decided_at: string | null;
-    decided_by: string | null;
-    policy_version: string;
-    source_artifacts: string[];
-  };
-}
-
-export interface RunStateDelegationRecord {
-  contract: typeof DELEGATION_LIVENESS_CONTRACT;
-  version: typeof DELEGATION_LIVENESS_VERSION;
-  delegationId: string;
-  task: string;
-  agent: string;
-  runMode: 'foreground' | 'background';
-  blocking: boolean;
-  requiredForPhaseExit: boolean;
-  status: 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'TIMED_OUT' | 'CANCELLED' | 'RECOVERABLE' | 'STALE';
-  startedAt: string;
-  lastHeartbeatAt: string | null;
-  timeoutSeconds: number;
-  expectedArtifact: string;
-  terminalEventRequired: boolean;
-  terminalEventAt?: string | null;
-}
-
-export interface RunStateArtifactIngestionRecord {
-  contract: typeof ARTIFACT_RESULT_INGESTION_CONTRACT_VERSION;
-  runId: string;
-  delegationId: string;
-  task: string;
-  agent: string;
-  artifactPath: string;
-  status: 'accepted' | 'rejected';
-  resultStatus: 'PASS' | 'PASS_WITH_GAPS' | 'FAIL' | 'BLOCKED' | 'TIMED_OUT' | 'CANCELLED' | null;
-  delegationStatus: RunStateDelegationRecord['status'] | null;
-  ingestedAt: string;
-  issues: RunStateContractValidationIssue[];
-  gaps: RunStateTaskGap[];
-}
-
-export interface RunStateWorktreeLifecycleRecord {
-  contract: 'phase-3.8-worktree-lifecycle-v1';
-  runId: string;
-  taskId: string;
-  worktreeId: string;
-  status: 'created' | 'kept' | 'removed';
-  branchName: string;
-  worktreePath: string;
-  baseRef: string;
-  createdAt: string;
-  updatedAt: string;
-  removedAt: string | null;
-  keepReason: string | null;
-  dirty: boolean;
-}
-
-export type RunTaskImplementationStatus = 'not_started' | 'running' | 'implemented' | 'blocked' | 'failed';
-
-export type RunTaskVerificationStatus = 'not_run' | 'pending_batch' | 'ready_for_validation' | 'running' | 'pass' | 'pass_with_gaps' | 'blocked' | 'failed';
-
-export interface RunStateTaskRuntime {
-  status: string;
-  implementationStatus?: RunTaskImplementationStatus;
-  verificationStatus?: RunTaskVerificationStatus;
-  validationBatch?: string | null;
-  validationTiming?: 'task_end' | 'batch_end' | 'wave_end';
-  requiresVerifyBeforeNext?: boolean;
-  gaps?: unknown[];
-  artifacts?: string[];
-  testStatus?: string;
-  validationStatus?: string;
-  verifyStatus?: string;
-  workflowGateStatus?: string;
-  workflowGateDecisionId?: string;
-  evidence?: string[];
-  acceptanceCoverage?: unknown[];
-}
-
-export interface RunState {
-  contract: typeof RUN_STATE_CONTRACT;
-  runtimeVersion: typeof RUNTIME_VERSION;
-  runId: string;
-  status: RunStatus;
-  phase: string | null;
-  currentTask: string | null;
-  partition: string | null;
-  gitBranch: string | null;
-  taskId: string | null;
-  affectedFiles: string[];
-  documentSnapshot: RunDocumentSnapshot;
-  createdAt: string;
-  updatedAt: string;
-  projectRoot: string;
-  projectConfigPath: string;
-  eventLogPath: string;
-  artifactRoot: string;
-  lifecycleDecision: RunStateLifecycleDecisionRecord | null;
-  tasks: Record<string, RunStateTaskRuntime>;
-  agents: Record<string, unknown>;
-  delegations: Record<string, RunStateDelegationRecord>;
-  artifacts: ArtifactIndexEntry[];
-  artifactIngestions: Record<string, RunStateArtifactIngestionRecord>;
-  worktrees: Record<string, RunStateWorktreeLifecycleRecord>;
-  validation: {
-    status: 'not_run' | 'pass' | 'pass_with_gaps' | 'fail' | 'blocked';
-    commands: string[];
-    evidence: string[];
-  };
-  syncBack: {
-    mode: 'proposal';
-    proposalPath: string | null;
-    proposalDigest?: string | null;
-    sourceVerifyStatus?: 'PASS' | 'PASS_WITH_GAPS' | 'FAIL' | 'BLOCKED' | 'completed' | 'blocked' | 'failed' | null;
-    status: 'not_created' | 'proposed' | 'applied';
-  };
-}
-
-export interface RunSummary {
-  runId: string;
-  status: RunStatus;
-  phase: string | null;
-  currentTask: string | null;
-  partition: string | null;
-  gitBranch: string | null;
-  taskId: string | null;
-  affectedFiles: string[];
-  documentSnapshot: RunDocumentSnapshot;
-  createdAt: string;
-  updatedAt: string;
-  validationStatus: RunState['validation']['status'];
-  syncBackStatus: RunState['syncBack']['status'];
-  taskIds: string[];
-  artifactCount: number;
-}
-
-export interface RuntimeEvent {
-  contract: typeof EVENT_LOG_CONTRACT;
-  time: string;
-  event: string;
-  runId: string;
-  summary?: string;
-  data?: Record<string, unknown>;
-}
-
-export type InvocationLedgerKind = 'command' | 'tool_invocation' | 'agent' | 'skill' | 'material' | 'policy_evaluation' | 'cache' | 'artifact_hash';
-
-export interface InvocationLedgerEntry {
-  contract: 'sdd-invocation-ledger-v1';
-  version: typeof INVOCATION_LEDGER_CONTRACT_VERSION;
-  entryId: string;
-  runId: string;
-  taskId: string | null;
-  branch: string | null;
-  kind: InvocationLedgerKind;
-  ref: string;
-  status: string;
-  timestamp: string;
-  artifactPath?: string | null;
-  inputHash?: string | null;
-  outputHash?: string | null;
-  materialRefs: string[];
-  metadata: Record<string, string | number | boolean | null>;
+import type {
+  ARTIFACT_RESULT_INGESTION_CONTRACT_VERSION,
+  DELEGATION_LIVENESS_CONTRACT,
+  DELEGATION_LIVENESS_VERSION,
+  EVENT_LOG_CONTRACT,
+  INVOCATION_LEDGER_CONTRACT_VERSION,
+  LEGACY_LIFECYCLE_DECISION_CONTRACT,
+  LIFECYCLE_DECISION_CONTRACT,
+  LIFECYCLE_DECISION_VERSION,
+  RUN_STATE_CONTRACT,
+  RUNTIME_VERSION
+} from '../contracts.js';
+
+export type RunStatus = 'created' | 'running' | 'completed' | 'blocked' | 'failed' | 'archived';
+
+export interface ArtifactIndexEntry {
+  path: string;
+  kind: string;
+  task: string | null;
+  agent: string | null;
+  createdAt: string;
+}
+
+export interface RunDocumentSnapshot {
+  specHash: string | null;
+  planHash: string | null;
+  tasksHash: string | null;
+  specContractHash: string | null;
+  planContractHash: string | null;
+  tasksContractHash: string | null;
+  planBasedOnSpecHash: string | null;
+  tasksBasedOnPlanHash: string | null;
+  planBasedOnSpecContractHash: string | null;
+  tasksBasedOnPlanContractHash: string | null;
+}
+
+export interface RunStateContractValidationIssue {
+  field: string;
+  message: string;
+  recommendation: string;
+}
+
+export interface RunStateTaskGap {
+  type: 'Document Gap' | 'Task Gap' | 'Dependency Gap';
+  severity: 'blocking' | 'warning';
+  taskId: string | null;
+  field: string;
+  message: string;
+  recommendation: string;
+}
+
+export interface RunStateLifecycleDecisionRecord {
+  contract: typeof LIFECYCLE_DECISION_CONTRACT | typeof LEGACY_LIFECYCLE_DECISION_CONTRACT;
+  version?: typeof LIFECYCLE_DECISION_VERSION;
+  model_version: string;
+  input_summary: Record<string, unknown>;
+  decision: {
+    profile: string | null;
+    confidence: string | null;
+    hard_gate_hits: string[];
+    required_stages: string[];
+    skipped_stages: string[];
+    human_checkpoint_required: boolean;
+  };
+  reasons: string[];
+  escalation_triggers: string[];
+  downgrade_reason: string | null;
+  audit: {
+    decided_at: string | null;
+    decided_by: string | null;
+    policy_version: string;
+    source_artifacts: string[];
+  };
+}
+
+export interface RunStateDelegationRecord {
+  contract: typeof DELEGATION_LIVENESS_CONTRACT;
+  version: typeof DELEGATION_LIVENESS_VERSION;
+  delegationId: string;
+  task: string;
+  agent: string;
+  runMode: 'foreground' | 'background';
+  blocking: boolean;
+  requiredForPhaseExit: boolean;
+  status: 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'TIMED_OUT' | 'CANCELLED' | 'RECOVERABLE' | 'STALE';
+  startedAt: string;
+  lastHeartbeatAt: string | null;
+  timeoutSeconds: number;
+  expectedArtifact: string;
+  terminalEventRequired: boolean;
+  terminalEventAt?: string | null;
+}
+
+export interface RunStateArtifactIngestionRecord {
+  contract: typeof ARTIFACT_RESULT_INGESTION_CONTRACT_VERSION;
+  runId: string;
+  delegationId: string;
+  task: string;
+  agent: string;
+  artifactPath: string;
+  status: 'accepted' | 'rejected';
+  resultStatus: 'PASS' | 'PASS_WITH_GAPS' | 'FAIL' | 'BLOCKED' | 'TIMED_OUT' | 'CANCELLED' | null;
+  delegationStatus: RunStateDelegationRecord['status'] | null;
+  ingestedAt: string;
+  issues: RunStateContractValidationIssue[];
+  gaps: RunStateTaskGap[];
+}
+
+export interface RunStateWorktreeLifecycleRecord {
+  contract: 'phase-3.8-worktree-lifecycle-v1';
+  runId: string;
+  taskId: string;
+  worktreeId: string;
+  status: 'created' | 'kept' | 'removed';
+  branchName: string;
+  worktreePath: string;
+  baseRef: string;
+  createdAt: string;
+  updatedAt: string;
+  removedAt: string | null;
+  keepReason: string | null;
+  dirty: boolean;
+}
+
+export type RunTaskImplementationStatus = 'not_started' | 'running' | 'implemented' | 'blocked' | 'failed';
+
+export type RunTaskVerificationStatus = 'not_run' | 'pending_batch' | 'ready_for_validation' | 'running' | 'pass' | 'pass_with_gaps' | 'blocked' | 'failed';
+
+export interface RunStateTaskRuntime {
+  status: string;
+  implementationStatus?: RunTaskImplementationStatus;
+  verificationStatus?: RunTaskVerificationStatus;
+  validationBatch?: string | null;
+  validationTiming?: 'task_end' | 'batch_end' | 'wave_end';
+  requiresVerifyBeforeNext?: boolean;
+  gaps?: unknown[];
+  artifacts?: string[];
+  testStatus?: string;
+  validationStatus?: string;
+  verifyStatus?: string;
+  workflowGateStatus?: string;
+  workflowGateDecisionId?: string;
+  evidence?: string[];
+  acceptanceCoverage?: unknown[];
+}
+
+export interface RunState {
+  contract: typeof RUN_STATE_CONTRACT;
+  runtimeVersion: typeof RUNTIME_VERSION;
+  runId: string;
+  status: RunStatus;
+  phase: string | null;
+  currentTask: string | null;
+  partition: string | null;
+  gitBranch: string | null;
+  taskId: string | null;
+  affectedFiles: string[];
+  documentSnapshot: RunDocumentSnapshot;
+  createdAt: string;
+  updatedAt: string;
+  projectRoot: string;
+  projectConfigPath: string;
+  eventLogPath: string;
+  artifactRoot: string;
+  lifecycleDecision: RunStateLifecycleDecisionRecord | null;
+  tasks: Record<string, RunStateTaskRuntime>;
+  agents: Record<string, unknown>;
+  delegations: Record<string, RunStateDelegationRecord>;
+  artifacts: ArtifactIndexEntry[];
+  artifactIngestions: Record<string, RunStateArtifactIngestionRecord>;
+  worktrees: Record<string, RunStateWorktreeLifecycleRecord>;
+  validation: {
+    status: 'not_run' | 'pass' | 'pass_with_gaps' | 'fail' | 'blocked';
+    commands: string[];
+    evidence: string[];
+  };
+  syncBack: {
+    mode: 'proposal';
+    proposalPath: string | null;
+    proposalDigest?: string | null;
+    sourceVerifyStatus?: 'PASS' | 'PASS_WITH_GAPS' | 'FAIL' | 'BLOCKED' | 'completed' | 'blocked' | 'failed' | null;
+    status: 'not_created' | 'proposed' | 'applied';
+  };
+}
+
+export interface RunSummary {
+  runId: string;
+  status: RunStatus;
+  phase: string | null;
+  currentTask: string | null;
+  partition: string | null;
+  gitBranch: string | null;
+  taskId: string | null;
+  affectedFiles: string[];
+  documentSnapshot: RunDocumentSnapshot;
+  createdAt: string;
+  updatedAt: string;
+  validationStatus: RunState['validation']['status'];
+  syncBackStatus: RunState['syncBack']['status'];
+  taskIds: string[];
+  artifactCount: number;
+}
+
+export interface RuntimeEvent {
+  contract: typeof EVENT_LOG_CONTRACT;
+  time: string;
+  event: string;
+  runId: string;
+  summary?: string;
+  data?: Record<string, unknown>;
+}
+
+export interface RunDurationContributor {
+  kind: 'active_runtime' | 'validation' | 'blocked' | 'queue_or_bind' | 'unknown_gap' | 'host_waiting' | 'none';
+  durationMs: number;
+  startedAt: string;
+  endedAt: string;
+  reason: string;
+  refs: string[];
+}
+
+export interface RunDurationBreakdown {
+  elapsedDurationMs: number;
+  activeRuntimeDurationMs: number;
+  validationDurationMs: number;
+  waitingDurationMs: number;
+  blockedDurationMs: number;
+  queueOrBindDurationMs: number;
+  unknownGapDurationMs: number;
+  hostWaitingDurationMs: number;
+  slowReason: RunDurationContributor['kind'];
+  topContributors: RunDurationContributor[];
+}
+
+export type InvocationLedgerKind = 'command' | 'tool_invocation' | 'agent' | 'skill' | 'material' | 'policy_evaluation' | 'cache' | 'artifact_hash';
+
+export interface InvocationLedgerEntry {
+  contract: 'sdd-invocation-ledger-v1';
+  version: typeof INVOCATION_LEDGER_CONTRACT_VERSION;
+  entryId: string;
+  runId: string;
+  taskId: string | null;
+  branch: string | null;
+  kind: InvocationLedgerKind;
+  ref: string;
+  status: string;
+  timestamp: string;
+  artifactPath?: string | null;
+  inputHash?: string | null;
+  outputHash?: string | null;
+  materialRefs: string[];
+  metadata: Record<string, string | number | boolean | null>;
 }

package/node_modules/@sdd-agent-platform/core/src/run-state/run-index.test.ts

@@ -1,52 +1,52 @@
-import test from 'node:test';
-import assert from 'node:assert/strict';
-import { mkdtemp, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import path from 'node:path';
-
-import { initProject } from '../config/init-project.js';
-import { createDelegationRecord } from '../delegation/validation.js';
-import { validResultArtifact } from '../test-support/fixtures.js';
-import { writeArtifact } from './artifacts.js';
-import { appendEvent } from './events.js';
-import { createRun, writeRunState } from './run-state.js';
-import { inspectLocalRunIndex, queryLocalRunIndex, rebuildLocalRunIndex } from './run-index.js';
-
-test('local run index rebuilds and queries derived run evidence', async () => {
-  const root = await mkdtemp(path.join(tmpdir(), 'sdd-local-run-index-'));
-  try {
-    await initProject(root);
-    const run = await createRun(root, { runId: 'run-index' });
-    const delegation = createDelegationRecord({
-      delegationId: 'D-T1-implementer-001',
-      task: 'T1',
-      agent: 'implementer',
-      expectedArtifact: 'artifacts/implementer-T1.md'
-    });
-    await writeArtifact(root, run.runId, 'implementer-T1.md', validResultArtifact('implementer', 'T1', 'PASS', 'artifacts/implementer-T1.md'));
-    await writeRunState(root, {
-      ...run,
-      status: 'completed',
-      currentTask: 'T1',
-      tasks: { T1: { status: 'completed' } },
-      delegations: { [delegation.delegationId]: { ...delegation, status: 'COMPLETED', terminalEventAt: '2026-05-07T00:00:00.000Z' } },
-      artifacts: [{ path: 'artifacts/implementer-T1.md', kind: 'sdd-result', task: 'T1', agent: 'implementer', createdAt: '2026-05-07T00:00:00.000Z' }]
-    });
-    await appendEvent(root, run.runId, { event: 'wave_executor_started', runId: run.runId });
-
-    const index = await rebuildLocalRunIndex(root);
-    const queried = await queryLocalRunIndex(root, { taskId: 'T1', status: 'completed', artifact: 'artifacts/implementer-T1.md' });
-    const inspection = await inspectLocalRunIndex(root);
-
-    assert.equal(index.contract, 'phase-3.13-local-run-index-v1');
-    assert.deepEqual(index.runs.map((entry) => entry.runId), ['run-index']);
-    assert.deepEqual(index.tasks.map((entry) => `${entry.runId}:${entry.taskId}:${entry.status}`), ['run-index:T1:completed']);
-    assert.equal(index.delegations.length, 1);
-    assert.equal(index.artifacts[0]?.path, 'artifacts/implementer-T1.md');
-    assert.equal(index.waves[0]?.lastEvent, 'wave_executor_started');
-    assert.deepEqual(queried.runs.map((entry) => entry.runId), ['run-index']);
-    assert.equal(inspection.valid, true);
-  } finally {
-    await rm(root, { recursive: true, force: true });
-  }
-});
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { initProject } from '../config/init-project.js';
+import { createDelegationRecord } from '../delegation/validation.js';
+import { validResultArtifact } from '../test-support/fixtures.js';
+import { writeArtifact } from './artifacts.js';
+import { appendEvent } from './events.js';
+import { createRun, writeRunState } from './run-state.js';
+import { inspectLocalRunIndex, queryLocalRunIndex, rebuildLocalRunIndex } from './run-index.js';
+
+test('local run index rebuilds and queries derived run evidence', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-local-run-index-'));
+  try {
+    await initProject(root);
+    const run = await createRun(root, { runId: 'run-index' });
+    const delegation = createDelegationRecord({
+      delegationId: 'D-T1-implementer-001',
+      task: 'T1',
+      agent: 'implementer',
+      expectedArtifact: 'artifacts/implementer-T1.md'
+    });
+    await writeArtifact(root, run.runId, 'implementer-T1.md', validResultArtifact('implementer', 'T1', 'PASS', 'artifacts/implementer-T1.md'));
+    await writeRunState(root, {
+      ...run,
+      status: 'completed',
+      currentTask: 'T1',
+      tasks: { T1: { status: 'completed' } },
+      delegations: { [delegation.delegationId]: { ...delegation, status: 'COMPLETED', terminalEventAt: '2026-05-07T00:00:00.000Z' } },
+      artifacts: [{ path: 'artifacts/implementer-T1.md', kind: 'sdd-result', task: 'T1', agent: 'implementer', createdAt: '2026-05-07T00:00:00.000Z' }]
+    });
+    await appendEvent(root, run.runId, { event: 'wave_executor_started', runId: run.runId });
+
+    const index = await rebuildLocalRunIndex(root);
+    const queried = await queryLocalRunIndex(root, { taskId: 'T1', status: 'completed', artifact: 'artifacts/implementer-T1.md' });
+    const inspection = await inspectLocalRunIndex(root);
+
+    assert.equal(index.contract, 'phase-3.13-local-run-index-v1');
+    assert.deepEqual(index.runs.map((entry) => entry.runId), ['run-index']);
+    assert.deepEqual(index.tasks.map((entry) => `${entry.runId}:${entry.taskId}:${entry.status}`), ['run-index:T1:completed']);
+    assert.equal(index.delegations.length, 1);
+    assert.equal(index.artifacts[0]?.path, 'artifacts/implementer-T1.md');
+    assert.equal(index.waves[0]?.lastEvent, 'wave_executor_started');
+    assert.deepEqual(queried.runs.map((entry) => entry.runId), ['run-index']);
+    assert.equal(inspection.valid, true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});