sdd-agent-platform 0.3.0 → 0.4.1

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

@@ -0,0 +1,356 @@
+import { createHash } from 'node:crypto';
+import { readFile, writeFile } from 'node:fs/promises';
+import { LOCAL_RUN_INDEX_CONTRACT_VERSION } from '../contracts.js';
+import { getLocalRunIndexPath } from '../runtime-paths.js';
+import { exists } from '../storage/json-io.js';
+import { recordRuntimeProjection } from '../storage/runtime-store.js';
+import { readRunEvents } from './events.js';
+import type { RunState, RunStateDelegationRecord, RunStatus, RunSummary } from './model.js';
+import { readAllRunStates, summarizeRunState } from './run-state.js';
+
+export interface ContractValidationIssue {
+  field: string;
+  message: string;
+  recommendation: string;
+}
+
+export type DelegationQueueStatusSource = 'run_state_delegation';
+
+export interface DelegationQueueItem {
+  id: string;
+  runId: string;
+  delegationId: string;
+  taskId: string;
+  agent: string;
+  requestedCapabilityId: string;
+  dedupeKey: string;
+  status: RunStateDelegationRecord['status'];
+  statusSource: DelegationQueueStatusSource;
+  runMode: RunStateDelegationRecord['runMode'];
+  expectedArtifact: string;
+  requiredEvidence: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface LocalRunIndexTaskEntry {
+  taskId: string;
+  partition: string | null;
+  gitBranch: string | null;
+  affectedFiles: string[];
+  status: string | null;
+  runId: string;
+  runStatus: RunStatus;
+  updatedAt: string;
+}
+
+export interface LocalRunIndexArtifactEntry {
+  path: string;
+  kind: string;
+  task: string | null;
+  agent: string | null;
+  runId: string;
+  createdAt: string;
+}
+
+export interface LocalRunIndexWaveSummary {
+  runId: string;
+  eventCount: number;
+  lastEvent: string | null;
+}
+
+export interface LocalRunIndexPartitionTaskEntry {
+  partition: string;
+  gitBranch: string | null;
+  taskId: string;
+  runId: string;
+  runStatus: RunStatus;
+  validationStatus: RunState['validation']['status'];
+  syncBackStatus: RunState['syncBack']['status'];
+  affectedFiles: string[];
+  updatedAt: string;
+}
+
+export interface LocalRunIndexAffectedFileEntry {
+  file: string;
+  partition: string;
+  gitBranch: string | null;
+  taskId: string;
+  runId: string;
+  runStatus: RunStatus;
+  syncBackStatus: RunState['syncBack']['status'];
+  updatedAt: string;
+}
+
+export interface LocalRunIndexQuery {
+  runId?: string;
+  taskId?: string;
+  partition?: string;
+  status?: RunStatus;
+  artifact?: string;
+}
+
+export interface LocalRunIndex {
+  contract: typeof LOCAL_RUN_INDEX_CONTRACT_VERSION;
+  generatedAt: string;
+  runs: RunSummary[];
+  tasks: LocalRunIndexTaskEntry[];
+  delegations: DelegationQueueItem[];
+  artifacts: LocalRunIndexArtifactEntry[];
+  waves: LocalRunIndexWaveSummary[];
+  latestByPartitionTask: LocalRunIndexPartitionTaskEntry[];
+  activeByAffectedFile: LocalRunIndexAffectedFileEntry[];
+}
+
+export interface LocalRunIndexInspection {
+  valid: boolean;
+  exists: boolean;
+  indexPath: string;
+  index: LocalRunIndex | null;
+  issues: ContractValidationIssue[];
+}
+
+export async function rebuildLocalRunIndex(projectRoot: string): Promise<LocalRunIndex> {
+  const index = await buildLocalRunIndexSnapshot(projectRoot);
+  await writeFile(getLocalRunIndexPath(projectRoot), `${JSON.stringify(index, null, 2)}\n`, 'utf8');
+  await recordRuntimeProjection(projectRoot, 'local_run_index', 'all', index);
+  return index;
+}
+
+export async function readLocalRunIndex(projectRoot: string): Promise<LocalRunIndex> {
+  const raw = await readFile(getLocalRunIndexPath(projectRoot), 'utf8');
+  return normalizeLocalRunIndex(JSON.parse(raw) as Partial<LocalRunIndex>);
+}
+
+export async function queryLocalRunIndex(projectRoot: string, query: LocalRunIndexQuery = {}): Promise<LocalRunIndex> {
+  const index = await readLocalRunIndex(projectRoot);
+  const runIds = new Set(index.runs
+    .filter((run) => !query.runId || run.runId === query.runId)
+    .filter((run) => !query.status || run.status === query.status)
+    .filter((run) => !query.taskId || run.taskIds.includes(query.taskId))
+    .filter((run) => !query.artifact || index.artifacts.some((artifact) => artifact.runId === run.runId && artifact.path === query.artifact))
+    .map((run) => run.runId));
+  const result = {
+    ...index,
+    runs: index.runs.filter((run) => runIds.has(run.runId)),
+    tasks: index.tasks.filter((task) => runIds.has(task.runId) && (!query.taskId || task.taskId === query.taskId) && (!query.partition || task.partition === query.partition)),
+    delegations: index.delegations.filter((delegation) => runIds.has(delegation.runId) && (!query.taskId || delegation.taskId === query.taskId)),
+    artifacts: index.artifacts.filter((artifact) => runIds.has(artifact.runId) && (!query.taskId || artifact.task === query.taskId) && (!query.artifact || artifact.path === query.artifact)),
+    waves: index.waves.filter((wave) => runIds.has(wave.runId)),
+    latestByPartitionTask: index.latestByPartitionTask.filter((entry) => runIds.has(entry.runId) && (!query.partition || entry.partition === query.partition) && (!query.taskId || entry.taskId === query.taskId)),
+    activeByAffectedFile: index.activeByAffectedFile.filter((entry) => runIds.has(entry.runId) && (!query.partition || entry.partition === query.partition) && (!query.taskId || entry.taskId === query.taskId))
+  };
+  await recordRuntimeProjection(projectRoot, 'local_run_index_query', hashDocumentContent(JSON.stringify(query)), result);
+  return result;
+}
+
+export async function inspectLocalRunIndex(projectRoot: string): Promise<LocalRunIndexInspection> {
+  const indexPath = getLocalRunIndexPath(projectRoot);
+  if (!await exists(indexPath)) {
+    return {
+      valid: false,
+      exists: false,
+      indexPath,
+      index: null,
+      issues: [contractIssue('run_index', 'Local run index projection is missing.', 'Run sdd run index rebuild to recreate the derived index from runtime.sqlite.')]
+    };
+  }
+
+  try {
+    const index = await readLocalRunIndex(projectRoot);
+    const rebuilt = await buildLocalRunIndexSnapshot(projectRoot);
+    const issues: ContractValidationIssue[] = [];
+    if (index.contract !== LOCAL_RUN_INDEX_CONTRACT_VERSION) {
+      issues.push(contractIssue('contract', `Local run index contract is ${index.contract}.`, 'Run sdd run index rebuild to refresh the index contract.'));
+    }
+    if (JSON.stringify(index.runs) !== JSON.stringify(rebuilt.runs)) {
+      issues.push(contractIssue('runs', 'Local run index run summaries differ from runtime.sqlite state.', 'Run sdd run index rebuild.'));
+    }
+    if (JSON.stringify(index.tasks) !== JSON.stringify(rebuilt.tasks)) {
+      issues.push(contractIssue('tasks', 'Local run index task entries differ from runtime.sqlite state.', 'Run sdd run index rebuild.'));
+    }
+    if (JSON.stringify(index.delegations) !== JSON.stringify(rebuilt.delegations)) {
+      issues.push(contractIssue('delegations', 'Local run index delegation entries differ from runtime.sqlite state.', 'Run sdd run index rebuild.'));
+    }
+    if (JSON.stringify(index.artifacts) !== JSON.stringify(rebuilt.artifacts)) {
+      issues.push(contractIssue('artifacts', 'Local run index artifact entries differ from runtime.sqlite state.', 'Run sdd run index rebuild.'));
+    }
+    if (JSON.stringify(index.waves) !== JSON.stringify(rebuilt.waves)) {
+      issues.push(contractIssue('waves', 'Local run index wave summaries differ from runtime.sqlite events.', 'Run sdd run index rebuild.'));
+    }
+    if (JSON.stringify(index.latestByPartitionTask) !== JSON.stringify(rebuilt.latestByPartitionTask)) {
+      issues.push(contractIssue('latestByPartitionTask', 'Local run index partition/task latest view differs from runtime.sqlite state.', 'Run sdd run index rebuild.'));
+    }
+    if (JSON.stringify(index.activeByAffectedFile) !== JSON.stringify(rebuilt.activeByAffectedFile)) {
+      issues.push(contractIssue('activeByAffectedFile', 'Local run index affected-file active view differs from runtime.sqlite state.', 'Run sdd run index rebuild.'));
+    }
+    return {
+      valid: issues.length === 0,
+      exists: true,
+      indexPath,
+      index,
+      issues
+    };
+  } catch (error) {
+    return {
+      valid: false,
+      exists: true,
+      indexPath,
+      index: null,
+      issues: [contractIssue('run_index', `Cannot read local run index: ${messageFromError(error)}`, 'Run sdd run index rebuild to recreate the derived index.')]
+    };
+  }
+}
+
+async function buildLocalRunIndexSnapshot(projectRoot: string): Promise<LocalRunIndex> {
+  const states = await readAllRunStates(projectRoot);
+  const tasks: LocalRunIndexTaskEntry[] = [];
+  const artifacts: LocalRunIndexArtifactEntry[] = [];
+  const delegations: DelegationQueueItem[] = [];
+  const waves: LocalRunIndexWaveSummary[] = [];
+  const latestByPartitionTask = new Map<string, LocalRunIndexPartitionTaskEntry>();
+  const activeByAffectedFile: LocalRunIndexAffectedFileEntry[] = [];
+
+  for (const state of states) {
+    for (const [taskId, taskState] of Object.entries(state.tasks)) {
+      tasks.push({
+        taskId,
+        partition: state.partition,
+        gitBranch: state.gitBranch,
+        affectedFiles: state.affectedFiles,
+        status: runtimeTaskStatus(taskState),
+        runId: state.runId,
+        runStatus: state.status,
+        updatedAt: state.updatedAt
+      });
+    }
+    if (state.partition && state.taskId && state.status !== 'archived') {
+      const entry: LocalRunIndexPartitionTaskEntry = {
+        partition: state.partition,
+        gitBranch: state.gitBranch,
+        taskId: state.taskId,
+        runId: state.runId,
+        runStatus: state.status,
+        validationStatus: state.validation.status,
+        syncBackStatus: state.syncBack.status,
+        affectedFiles: state.affectedFiles,
+        updatedAt: state.updatedAt
+      };
+      const key = partitionTaskKey(state.partition, state.taskId);
+      const existing = latestByPartitionTask.get(key);
+      if (!existing || Date.parse(entry.updatedAt) > Date.parse(existing.updatedAt) || (entry.updatedAt === existing.updatedAt && entry.runId.localeCompare(existing.runId) > 0)) {
+        latestByPartitionTask.set(key, entry);
+      }
+      if (isActiveRunForAffectedFile(state)) {
+        for (const file of state.affectedFiles) {
+          activeByAffectedFile.push({
+            file,
+            partition: state.partition,
+            gitBranch: state.gitBranch,
+            taskId: state.taskId,
+            runId: state.runId,
+            runStatus: state.status,
+            syncBackStatus: state.syncBack.status,
+            updatedAt: state.updatedAt
+          });
+        }
+      }
+    }
+    for (const artifact of state.artifacts) {
+      artifacts.push({
+        ...artifact,
+        runId: state.runId
+      });
+    }
+    delegations.push(...Object.values(state.delegations).map((delegation) => delegationQueueItemFromRunState(state, delegation)));
+    const waveEvents = (await readRunEvents(projectRoot, state.runId)).filter((event) => event.event.startsWith('wave_executor_'));
+    if (waveEvents.length > 0) {
+      waves.push({
+        runId: state.runId,
+        eventCount: waveEvents.length,
+        lastEvent: waveEvents[waveEvents.length - 1]?.event ?? null
+      });
+    }
+  }
+
+  return {
+    contract: LOCAL_RUN_INDEX_CONTRACT_VERSION,
+    generatedAt: new Date().toISOString(),
+    runs: states.map((state) => summarizeRunState(state)).sort((left, right) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt)),
+    tasks: tasks.sort((left, right) => (left.partition ?? '').localeCompare(right.partition ?? '') || left.taskId.localeCompare(right.taskId) || left.runId.localeCompare(right.runId)),
+    delegations: delegations.sort((left, right) => left.id.localeCompare(right.id)),
+    artifacts: artifacts.sort((left, right) => left.path.localeCompare(right.path) || left.runId.localeCompare(right.runId)),
+    waves: waves.sort((left, right) => left.runId.localeCompare(right.runId)),
+    latestByPartitionTask: Array.from(latestByPartitionTask.values()).sort((left, right) => left.partition.localeCompare(right.partition) || left.taskId.localeCompare(right.taskId)),
+    activeByAffectedFile: activeByAffectedFile.sort((left, right) => left.file.localeCompare(right.file) || left.partition.localeCompare(right.partition) || left.taskId.localeCompare(right.taskId) || left.runId.localeCompare(right.runId))
+  };
+}
+
+function normalizeLocalRunIndex(index: Partial<LocalRunIndex>): LocalRunIndex {
+  return {
+    contract: index.contract ?? LOCAL_RUN_INDEX_CONTRACT_VERSION,
+    generatedAt: index.generatedAt ?? new Date().toISOString(),
+    runs: index.runs ?? [],
+    tasks: index.tasks ?? [],
+    delegations: index.delegations ?? [],
+    artifacts: index.artifacts ?? [],
+    waves: index.waves ?? [],
+    latestByPartitionTask: index.latestByPartitionTask ?? [],
+    activeByAffectedFile: index.activeByAffectedFile ?? []
+  };
+}
+
+function delegationQueueItemFromRunState(state: RunState, delegation: RunStateDelegationRecord): DelegationQueueItem {
+  return {
+    id: `${state.runId}:${delegation.delegationId}`,
+    runId: state.runId,
+    delegationId: delegation.delegationId,
+    taskId: delegation.task,
+    agent: delegation.agent,
+    requestedCapabilityId: 'sdd-cli',
+    dedupeKey: `${state.runId}:${delegation.task}:${delegation.agent}`,
+    status: delegation.status,
+    statusSource: 'run_state_delegation',
+    runMode: delegation.runMode,
+    expectedArtifact: delegation.expectedArtifact,
+    requiredEvidence: [delegation.expectedArtifact, state.eventLogPath],
+    createdAt: delegation.startedAt,
+    updatedAt: delegation.terminalEventAt ?? delegation.lastHeartbeatAt ?? state.updatedAt
+  };
+}
+
+function runtimeTaskStatus(value: unknown): string | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  const status = value.status;
+  const verifyStatus = value.verifyStatus;
+  if (typeof verifyStatus === 'string') {
+    return verifyStatus;
+  }
+  return typeof status === 'string' ? status : null;
+}
+
+function partitionTaskKey(partition: string, taskId: string): string {
+  return `${partition}::${taskId}`;
+}
+
+function isActiveRunForAffectedFile(state: RunState): boolean {
+  return state.status !== 'archived' && state.syncBack.status !== 'applied' && state.affectedFiles.length > 0;
+}
+
+function contractIssue(field: string, message: string, recommendation: string): ContractValidationIssue {
+  return { field, message, recommendation };
+}
+
+function hashDocumentContent(raw: string): string {
+  return createHash('sha256').update(raw.replace(/\r\n/g, '\n'), 'utf8').digest('hex');
+}
+
+function messageFromError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

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

@@ -0,0 +1,70 @@
+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 { readRunEvents } from './events.js';
+import { createRun, listRuns, readRunState, writeRunState } from './run-state.js';
+import { validTaskMarkdown, writeBranchDocs } from '../test-support/fixtures.js';
+import { getRunDir } from '../runtime-paths.js';
+import { exists } from '../storage/json-io.js';
+
+test('createRun writes state and append-only events', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-runtime-'));
+  try {
+    await initProject(root);
+    const state = await createRun(root);
+    const restored = await readRunState(root, state.runId);
+    assert.equal(restored.contract, 'phase-1.2-run-state-contract');
+    assert.equal(restored.lifecycleDecision?.contract, 'sdd-lifecycle-decision-v1');
+    assert.equal(restored.lifecycleDecision?.version, '1.3.0');
+    const events = await readRunEvents(root, state.runId);
+    assert.equal(events.some((event) => event.event === 'run_started'), true);
+    assert.equal(events.some((event) => event.event === 'lifecycle_decision_recorded'), true);
+    assert.equal(await exists(getRunDir(root, state.runId)), false);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('createRun binds scoped branch task metadata', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-runtime-scoped-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+
+    const state = await createRun(root, { branch: 'feature', taskId: 'T1' });
+    const restored = await readRunState(root, state.runId);
+
+    assert.equal(restored.partition, 'feature');
+    assert.equal(restored.gitBranch, 'feature');
+    assert.equal(restored.currentTask, 'T1');
+    assert.equal(restored.taskId, 'T1');
+    assert.deepEqual(restored.affectedFiles, ['packages/core/src/index.ts']);
+    assert.match(restored.artifactRoot, /\.sdd[\\/]runs[\\/]feature[\\/]evidence/);
+    assert.equal(restored.documentSnapshot.tasksHash !== null, true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('listRuns sorts run summaries by updated time descending', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-run-list-'));
+  try {
+    await initProject(root);
+    const older = await createRun(root, { runId: 'run-older' });
+    const newer = await createRun(root, { runId: 'run-newer' });
+    const olderState = { ...older, updatedAt: '2026-05-01T00:00:00.000Z' };
+    const newerState = { ...newer, updatedAt: '2026-05-02T00:00:00.000Z' };
+    await writeRunState(root, olderState);
+    await writeRunState(root, newerState);
+
+    const runs = await listRuns(root);
+
+    assert.deepEqual(runs.map((run) => run.runId), ['run-newer', 'run-older']);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});