sdd-agent-platform 0.4.2 → 0.5.0

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

@@ -1,172 +1,172 @@
-import { TASK_RUN_EVIDENCE_CONTRACT_VERSION } from '../contracts.js';
-import { listAgentExecutionRecords as listRuntimeBackedAgentExecutionRecords, listTeamSessionRecords as listRuntimeBackedTeamSessionRecords } from '../execution/agent-execution-records.js';
-import { listResidentWorkerRuntimeRecords as listRuntimeBackedResidentWorkerRuntimeRecords } from '../execution/resident-worker.js';
-import { listRuntimeTestRuns, listRuntimeTestSteps } from '../storage/runtime-store.js';
-import type { ArtifactIndexEntry, InvocationLedgerEntry, RunState, RunStateArtifactIngestionRecord, RunStateWorktreeLifecycleRecord, RunStatus, RunSummary, RuntimeEvent } from './model.js';
-import { readRunEvents } from './events.js';
-import { listInvocationLedgerEntries } from './invocation-ledger.js';
-import { readRunState, summarizeRunState } from './run-state.js';
-import { readTaskEvidenceView, type TaskEvidenceView } from './task-evidence.js';
-import { buildRunDurationBreakdown } from './timing.js';
-
-export interface TaskRunEvidenceGap {
-  type: string;
-  severity: string;
-  taskId?: string | null;
-  field: string;
-  message: string;
-  recommendation: string;
-}
-
-export interface AgentExecutionRecordView {
-  executionId: string;
-  runId?: string;
-  taskId: string;
-  profile: string;
-  status: string;
-  artifacts: string[];
-  toolPermission: { profile?: string } | null;
-  routeId: string;
-  routeDecision: { recommendedProfile?: string | null };
-  createdAt: string;
-  [key: string]: unknown;
-}
-
-export interface TeamSessionRecordView {
-  teamId: string;
-  runId?: string;
-  taskId?: string | null;
-  status: string;
-  teamMode: { mode: string; activation: string; costClass: string; reason: string };
-  chiefProfile: string;
-  memberProfiles: string[];
-  artifacts: string[];
-  createdAt: string;
-  [key: string]: unknown;
-}
-
-export interface ResidentWorkerRuntimeRecordView {
-  runtimeId: string;
-  runId?: string;
-  taskId: string;
-  agent: string;
-  delegationId: string;
-  status: string;
-  leaseExpiresAt: string;
-  updatedAt: string;
-  [key: string]: unknown;
-}
-
-export interface TaskRunEvidenceContract {
-  version: typeof TASK_RUN_EVIDENCE_CONTRACT_VERSION;
-  runId: string;
-  state: { status: RunStatus; phase: string | null; currentTask: string | null };
-  events: Array<{ event: string; summary: string | null; task: string | null; agent: string | null; gate: string | null; validation: string | null; gap: string | null }>;
-  artifacts: ArtifactIndexEntry[];
-  validation: RunState['validation'];
-  gaps: TaskRunEvidenceGap[];
-  invocationLedger: InvocationLedgerEntry[];
-  agentExecutions: AgentExecutionRecordView[];
-  teamSessions: TeamSessionRecordView[];
-  workerRuntimes: ResidentWorkerRuntimeRecordView[];
-}
-
-export interface RunInspection {
-  summary: RunSummary;
-  state: RunState;
-  events: RuntimeEvent[];
-  eventCount: number;
-  recentEvents: RuntimeEvent[];
-  artifacts: ArtifactIndexEntry[];
-  artifactIngestions: RunStateArtifactIngestionRecord[];
-  worktrees: RunStateWorktreeLifecycleRecord[];
-  validation: RunState['validation'];
-  tasks: Record<string, unknown>;
-  taskRunEvidence: TaskRunEvidenceContract;
-  taskEvidenceView: TaskEvidenceView | null;
-  agentExecutions: AgentExecutionRecordView[];
-  invocationLedger: InvocationLedgerEntry[];
-  teamSessions: TeamSessionRecordView[];
-  workerRuntimes: ResidentWorkerRuntimeRecordView[];
-}
-
-export async function inspectRun(projectRoot: string, runId: string): Promise<RunInspection> {
-  const state = await readRunState(projectRoot, runId);
-  const [events, agentExecutions, teamSessions, workerRuntimes, invocationLedger, testRuns, testSteps] = await Promise.all([
-    readRunEvents(projectRoot, runId),
-    listRuntimeBackedAgentExecutionRecords(projectRoot, runId),
-    listRuntimeBackedTeamSessionRecords(projectRoot, runId),
-    listRuntimeBackedResidentWorkerRuntimeRecords(projectRoot, runId),
-    listInvocationLedgerEntries(projectRoot, runId),
-    listRuntimeTestRuns(projectRoot, runId),
-    listRuntimeTestSteps(projectRoot, { runId })
-  ]);
-  const agentExecutionViews = agentExecutions.map((record) => ({ ...record }) as AgentExecutionRecordView);
-  const teamSessionViews = teamSessions.map((record) => ({ ...record }) as TeamSessionRecordView);
-  const workerRuntimeViews = workerRuntimes.map((record) => ({ ...record }) as ResidentWorkerRuntimeRecordView);
-  const taskEvidenceView = state.partition && state.taskId ? await readTaskEvidenceView(projectRoot, { branch: state.partition, taskId: state.taskId }) : null;
-  return {
-    summary: { ...summarizeRunState(state), durationBreakdown: buildRunDurationBreakdown(state, { events, testRuns, testSteps }) },
-    state,
-    events,
-    eventCount: events.length,
-    recentEvents: events.slice(-10),
-    artifacts: state.artifacts,
-    artifactIngestions: Object.values(state.artifactIngestions ?? {}),
-    worktrees: Object.values(state.worktrees ?? {}),
-    validation: state.validation,
-    taskRunEvidence: buildTaskRunEvidence(state, events, agentExecutionViews, teamSessionViews, workerRuntimeViews, invocationLedger),
-    taskEvidenceView,
-    tasks: state.tasks,
-    agentExecutions: agentExecutionViews,
-    teamSessions: teamSessionViews,
-    workerRuntimes: workerRuntimeViews,
-    invocationLedger
-  };
-}
-
-
-function buildTaskRunEvidence(state: RunState, events: RuntimeEvent[], agentExecutions: AgentExecutionRecordView[] = [], teamSessions: TeamSessionRecordView[] = [], workerRuntimes: ResidentWorkerRuntimeRecordView[] = [], invocationLedger: InvocationLedgerEntry[] = []): TaskRunEvidenceContract {
-  return {
-    version: TASK_RUN_EVIDENCE_CONTRACT_VERSION,
-    runId: state.runId,
-    state: { status: state.status, phase: state.phase, currentTask: state.currentTask },
-    events: events.map((event) => ({
-      event: event.event,
-      summary: event.summary ?? null,
-      task: stringData(event.data, 'task'),
-      agent: stringData(event.data, 'agent'),
-      gate: stringData(event.data, 'gate'),
-      validation: stringData(event.data, 'status') ?? stringData(event.data, 'validation'),
-      gap: stringData(event.data, 'gap')
-    })),
-    artifacts: state.artifacts,
-    validation: state.validation,
-    gaps: Object.values(state.tasks).flatMap(extractTaskGaps),
-    agentExecutions,
-    teamSessions,
-    workerRuntimes,
-    invocationLedger
-  };
-}
-
-function stringData(data: Record<string, unknown> | undefined, key: string): string | null {
-  const value = data?.[key];
-  return typeof value === 'string' ? value : null;
-}
-
-function extractTaskGaps(taskState: unknown): TaskRunEvidenceGap[] {
-  if (!taskState || typeof taskState !== 'object' || !('gaps' in taskState)) {
-    return [];
-  }
-  const gaps = (taskState as { gaps?: unknown }).gaps;
-  return Array.isArray(gaps) ? gaps.filter(isTaskRunEvidenceGap) : [];
-}
-
-function isTaskRunEvidenceGap(value: unknown): value is TaskRunEvidenceGap {
-  if (!value || typeof value !== 'object') {
-    return false;
-  }
-  const gap = value as Partial<TaskRunEvidenceGap>;
-  return typeof gap.type === 'string' && typeof gap.severity === 'string' && typeof gap.field === 'string' && typeof gap.message === 'string' && typeof gap.recommendation === 'string';
-}
+import { TASK_RUN_EVIDENCE_CONTRACT_VERSION } from '../contracts.js';
+import { listAgentExecutionRecords as listRuntimeBackedAgentExecutionRecords, listTeamSessionRecords as listRuntimeBackedTeamSessionRecords } from '../execution/agent-execution-records.js';
+import { listResidentWorkerRuntimeRecords as listRuntimeBackedResidentWorkerRuntimeRecords } from '../execution/resident-worker.js';
+import type { ArtifactIndexEntry, InvocationLedgerEntry, RunState, RunStateArtifactIngestionRecord, RunStateWorktreeLifecycleRecord, RunStatus, RunSummary, RuntimeEvent } from './model.js';
+import { readRunEvents } from './events.js';
+import { listInvocationLedgerEntries } from './invocation-ledger.js';
+import { readRunState, summarizeRunState } from './run-state.js';
+import { readTaskEvidenceView, type TaskEvidenceView } from './task-evidence.js';
+
+export interface TaskRunEvidenceGap {
+  type: string;
+  severity: string;
+  taskId?: string | null;
+  field: string;
+  message: string;
+  recommendation: string;
+}
+
+export interface AgentExecutionRecordView {
+  executionId: string;
+  runId?: string;
+  taskId: string;
+  profile: string;
+  status: string;
+  artifacts: string[];
+  toolPermission: { profile?: string } | null;
+  routeId: string;
+  routeDecision: { recommendedProfile?: string | null };
+  createdAt: string;
+  [key: string]: unknown;
+}
+
+export interface TeamSessionRecordView {
+  teamId: string;
+  runId?: string;
+  taskId?: string | null;
+  status: string;
+  teamMode: { mode: string; activation: string; costClass: string; reason: string };
+  chiefProfile: string;
+  memberProfiles: string[];
+  artifacts: string[];
+  createdAt: string;
+  [key: string]: unknown;
+}
+
+export interface ResidentWorkerRuntimeRecordView {
+  runtimeId: string;
+  runId?: string;
+  taskId: string;
+  agent: string;
+  delegationId: string;
+  status: string;
+  leaseExpiresAt: string;
+  updatedAt: string;
+  [key: string]: unknown;
+}
+
+export interface TaskRunEvidenceContract {
+  version: typeof TASK_RUN_EVIDENCE_CONTRACT_VERSION;
+  runId: string;
+  state: { status: RunStatus; phase: string | null; currentTask: string | null };
+  events: Array<{ event: string; summary: string | null; task: string | null; agent: string | null; gate: string | null; validation: string | null; gap: string | null }>;
+  artifacts: ArtifactIndexEntry[];
+  validation: RunState['validation'];
+  gaps: TaskRunEvidenceGap[];
+  syncBackProposal: string | null;
+  invocationLedger: InvocationLedgerEntry[];
+  agentExecutions: AgentExecutionRecordView[];
+  teamSessions: TeamSessionRecordView[];
+  workerRuntimes: ResidentWorkerRuntimeRecordView[];
+}
+
+export interface RunInspection {
+  summary: RunSummary;
+  state: RunState;
+  events: RuntimeEvent[];
+  eventCount: number;
+  recentEvents: RuntimeEvent[];
+  artifacts: ArtifactIndexEntry[];
+  artifactIngestions: RunStateArtifactIngestionRecord[];
+  worktrees: RunStateWorktreeLifecycleRecord[];
+  validation: RunState['validation'];
+  syncBack: RunState['syncBack'];
+  tasks: Record<string, unknown>;
+  taskRunEvidence: TaskRunEvidenceContract;
+  taskEvidenceView: TaskEvidenceView | null;
+  agentExecutions: AgentExecutionRecordView[];
+  invocationLedger: InvocationLedgerEntry[];
+  teamSessions: TeamSessionRecordView[];
+  workerRuntimes: ResidentWorkerRuntimeRecordView[];
+}
+
+export async function inspectRun(projectRoot: string, runId: string): Promise<RunInspection> {
+  const state = await readRunState(projectRoot, runId);
+  const [events, agentExecutions, teamSessions, workerRuntimes, invocationLedger] = await Promise.all([
+    readRunEvents(projectRoot, runId),
+    listRuntimeBackedAgentExecutionRecords(projectRoot, runId),
+    listRuntimeBackedTeamSessionRecords(projectRoot, runId),
+    listRuntimeBackedResidentWorkerRuntimeRecords(projectRoot, runId),
+    listInvocationLedgerEntries(projectRoot, runId)
+  ]);
+  const agentExecutionViews = agentExecutions.map((record) => ({ ...record }) as AgentExecutionRecordView);
+  const teamSessionViews = teamSessions.map((record) => ({ ...record }) as TeamSessionRecordView);
+  const workerRuntimeViews = workerRuntimes.map((record) => ({ ...record }) as ResidentWorkerRuntimeRecordView);
+  const taskEvidenceView = state.partition && state.taskId ? await readTaskEvidenceView(projectRoot, { branch: state.partition, taskId: state.taskId }) : null;
+  return {
+    summary: summarizeRunState(state),
+    state,
+    events,
+    eventCount: events.length,
+    recentEvents: events.slice(-10),
+    artifacts: state.artifacts,
+    artifactIngestions: Object.values(state.artifactIngestions ?? {}),
+    worktrees: Object.values(state.worktrees ?? {}),
+    validation: state.validation,
+    syncBack: state.syncBack,
+    taskRunEvidence: buildTaskRunEvidence(state, events, agentExecutionViews, teamSessionViews, workerRuntimeViews, invocationLedger),
+    taskEvidenceView,
+    tasks: state.tasks,
+    agentExecutions: agentExecutionViews,
+    teamSessions: teamSessionViews,
+    workerRuntimes: workerRuntimeViews,
+    invocationLedger
+  };
+}
+
+
+function buildTaskRunEvidence(state: RunState, events: RuntimeEvent[], agentExecutions: AgentExecutionRecordView[] = [], teamSessions: TeamSessionRecordView[] = [], workerRuntimes: ResidentWorkerRuntimeRecordView[] = [], invocationLedger: InvocationLedgerEntry[] = []): TaskRunEvidenceContract {
+  return {
+    version: TASK_RUN_EVIDENCE_CONTRACT_VERSION,
+    runId: state.runId,
+    state: { status: state.status, phase: state.phase, currentTask: state.currentTask },
+    events: events.map((event) => ({
+      event: event.event,
+      summary: event.summary ?? null,
+      task: stringData(event.data, 'task'),
+      agent: stringData(event.data, 'agent'),
+      gate: stringData(event.data, 'gate'),
+      validation: stringData(event.data, 'status') ?? stringData(event.data, 'validation'),
+      gap: stringData(event.data, 'gap')
+    })),
+    artifacts: state.artifacts,
+    validation: state.validation,
+    gaps: Object.values(state.tasks).flatMap(extractTaskGaps),
+    syncBackProposal: state.syncBack.proposalPath,
+    agentExecutions,
+    teamSessions,
+    workerRuntimes,
+    invocationLedger
+  };
+}
+
+function stringData(data: Record<string, unknown> | undefined, key: string): string | null {
+  const value = data?.[key];
+  return typeof value === 'string' ? value : null;
+}
+
+function extractTaskGaps(taskState: unknown): TaskRunEvidenceGap[] {
+  if (!taskState || typeof taskState !== 'object' || !('gaps' in taskState)) {
+    return [];
+  }
+  const gaps = (taskState as { gaps?: unknown }).gaps;
+  return Array.isArray(gaps) ? gaps.filter(isTaskRunEvidenceGap) : [];
+}
+
+function isTaskRunEvidenceGap(value: unknown): value is TaskRunEvidenceGap {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+  const gap = value as Partial<TaskRunEvidenceGap>;
+  return typeof gap.type === 'string' && typeof gap.severity === 'string' && typeof gap.field === 'string' && typeof gap.message === 'string' && typeof gap.recommendation === 'string';
+}

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

@@ -1,109 +1,109 @@
-import { createHash } from 'node:crypto';
-import { readFile } from 'node:fs/promises';
-import { INVOCATION_LEDGER_CONTRACT_VERSION } from '../contracts.js';
-import { getLegacyInvocationLedgerPath } from '../runtime-paths.js';
-import { exists } from '../storage/json-io.js';
-import { RuntimeStoreError, legacyImportId, readRuntimeActivities, recordLegacyImportFailure, recordRuntimeActivity, withRuntimeStore } from '../storage/runtime-store.js';
-import type { InvocationLedgerEntry } from './model.js';
-
-export async function appendInvocationLedgerEntry(projectRoot: string, input: Omit<InvocationLedgerEntry, 'contract' | 'version' | 'entryId' | 'timestamp'>): Promise<InvocationLedgerEntry> {
-  const timestamp = new Date().toISOString();
-  const entry: InvocationLedgerEntry = {
-    contract: 'sdd-invocation-ledger-v1',
-    version: INVOCATION_LEDGER_CONTRACT_VERSION,
-    entryId: createHash('sha256').update(`${input.runId}:${input.kind}:${input.ref}:${timestamp}`).digest('hex').slice(0, 16),
-    timestamp,
-    ...input
-  };
-  await recordRuntimeActivity(projectRoot, entry);
-  return entry;
-}
-
-export async function listInvocationLedgerEntries(projectRoot: string, runId: string): Promise<InvocationLedgerEntry[]> {
-  const entries = await readRuntimeActivities(projectRoot, runId);
-  if (entries.length > 0) {
-    return entries;
-  }
-  const ledgerPath = getLegacyInvocationLedgerPath(projectRoot, runId);
-  await importLegacyInvocationLedgerIfNeeded(projectRoot, runId, ledgerPath);
-  return readRuntimeActivities(projectRoot, runId);
-}
-
-export async function appendArtifactHashLedgerEntry(projectRoot: string, input: { runId: string; taskId?: string | null; branch?: string | null; artifactPath: string; content: string; status?: string }): Promise<InvocationLedgerEntry> {
-  return appendUniqueInvocationLedgerEntry(projectRoot, {
-    runId: input.runId,
-    taskId: input.taskId ?? null,
-    branch: input.branch ?? null,
-    kind: 'artifact_hash',
-    ref: input.artifactPath,
-    status: input.status ?? 'observed',
-    artifactPath: input.artifactPath,
-    outputHash: hashDocumentContent(input.content),
-    materialRefs: [],
-    metadata: { bytes: Buffer.byteLength(input.content, 'utf8') }
-  });
-}
-
-export async function appendUniqueInvocationLedgerEntry(projectRoot: string, input: Omit<InvocationLedgerEntry, 'contract' | 'version' | 'entryId' | 'timestamp'>): Promise<InvocationLedgerEntry> {
-  const existing = await findMatchingInvocationLedgerEntry(projectRoot, input);
-  if (existing) {
-    return existing;
-  }
-  return appendInvocationLedgerEntry(projectRoot, input);
-}
-
-export async function appendDeclaredCommandLedgerEntries(projectRoot: string, input: { runId: string; taskId: string; branch: string; commands: string[] }): Promise<void> {
-  for (const command of input.commands) {
-    await appendUniqueInvocationLedgerEntry(projectRoot, {
-      runId: input.runId,
-      taskId: input.taskId,
-      branch: input.branch,
-      kind: 'command',
-      ref: command,
-      status: 'declared',
-      materialRefs: [],
-      metadata: { source: 'task.validation' }
-    });
-  }
-}
-
-async function importLegacyInvocationLedgerIfNeeded(projectRoot: string, runId: string, ledgerPath: string): Promise<void> {
-  if (!await exists(ledgerPath)) {
-    return;
-  }
-  try {
-    const raw = await readFile(ledgerPath, 'utf8');
-    const contentHash = hashDocumentContent(raw);
-    await withRuntimeStore(projectRoot, ({ db }) => {
-      const legacy = db.prepare('SELECT content_hash FROM legacy_imports WHERE run_id = ? AND entity_type = ?').get(runId, 'invocations') as { content_hash?: string } | undefined;
-      if (legacy?.content_hash === contentHash) {
-        return;
-      }
-      for (const line of raw.split(/\r?\n/).filter(Boolean)) {
-        const entry = JSON.parse(line) as InvocationLedgerEntry;
-        db.prepare('INSERT OR REPLACE INTO activities (activity_id, run_id, task_id, branch, kind, ref, status, created_at, payload_json) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)')
-          .run(entry.entryId, entry.runId, entry.taskId ?? null, entry.branch ?? null, entry.kind, entry.ref, entry.status ?? null, entry.timestamp, JSON.stringify(entry));
-      }
-      db.prepare('INSERT OR REPLACE INTO legacy_imports (import_id, run_id, entity_type, content_hash, imported_at, status, issue) VALUES (?, ?, ?, ?, ?, ?, ?)')
-        .run(legacyImportId(runId, 'invocations'), runId, 'invocations', contentHash, new Date().toISOString(), 'imported', null);
-    });
-  } catch (error) {
-    await recordLegacyImportFailure(projectRoot, runId, 'invocations', error);
-    throw new RuntimeStoreError('LEGACY_IMPORT_FAILED', `Cannot import legacy invocation ledger for ${runId}: ${messageFromError(error)}`, { cause: error });
-  }
-}
-
-async function findMatchingInvocationLedgerEntry(projectRoot: string, input: Omit<InvocationLedgerEntry, 'contract' | 'version' | 'entryId' | 'timestamp'>): Promise<InvocationLedgerEntry | null> {
-  const entries = await listInvocationLedgerEntries(projectRoot, input.runId);
-  return entries.find((entry) => entry.kind === input.kind && entry.ref === input.ref && entry.status === input.status && entry.outputHash === input.outputHash) ?? null;
-}
-
-
-
-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);
-}
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { INVOCATION_LEDGER_CONTRACT_VERSION } from '../contracts.js';
+import { getLegacyInvocationLedgerPath } from '../runtime-paths.js';
+import { exists } from '../storage/json-io.js';
+import { RuntimeStoreError, legacyImportId, readRuntimeActivities, recordLegacyImportFailure, recordRuntimeActivity, withRuntimeStore } from '../storage/runtime-store.js';
+import type { InvocationLedgerEntry } from './model.js';
+
+export async function appendInvocationLedgerEntry(projectRoot: string, input: Omit<InvocationLedgerEntry, 'contract' | 'version' | 'entryId' | 'timestamp'>): Promise<InvocationLedgerEntry> {
+  const timestamp = new Date().toISOString();
+  const entry: InvocationLedgerEntry = {
+    contract: 'sdd-invocation-ledger-v1',
+    version: INVOCATION_LEDGER_CONTRACT_VERSION,
+    entryId: createHash('sha256').update(`${input.runId}:${input.kind}:${input.ref}:${timestamp}`).digest('hex').slice(0, 16),
+    timestamp,
+    ...input
+  };
+  await recordRuntimeActivity(projectRoot, entry);
+  return entry;
+}
+
+export async function listInvocationLedgerEntries(projectRoot: string, runId: string): Promise<InvocationLedgerEntry[]> {
+  const entries = await readRuntimeActivities(projectRoot, runId);
+  if (entries.length > 0) {
+    return entries;
+  }
+  const ledgerPath = getLegacyInvocationLedgerPath(projectRoot, runId);
+  await importLegacyInvocationLedgerIfNeeded(projectRoot, runId, ledgerPath);
+  return readRuntimeActivities(projectRoot, runId);
+}
+
+export async function appendArtifactHashLedgerEntry(projectRoot: string, input: { runId: string; taskId?: string | null; branch?: string | null; artifactPath: string; content: string; status?: string }): Promise<InvocationLedgerEntry> {
+  return appendUniqueInvocationLedgerEntry(projectRoot, {
+    runId: input.runId,
+    taskId: input.taskId ?? null,
+    branch: input.branch ?? null,
+    kind: 'artifact_hash',
+    ref: input.artifactPath,
+    status: input.status ?? 'observed',
+    artifactPath: input.artifactPath,
+    outputHash: hashDocumentContent(input.content),
+    materialRefs: [],
+    metadata: { bytes: Buffer.byteLength(input.content, 'utf8') }
+  });
+}
+
+export async function appendUniqueInvocationLedgerEntry(projectRoot: string, input: Omit<InvocationLedgerEntry, 'contract' | 'version' | 'entryId' | 'timestamp'>): Promise<InvocationLedgerEntry> {
+  const existing = await findMatchingInvocationLedgerEntry(projectRoot, input);
+  if (existing) {
+    return existing;
+  }
+  return appendInvocationLedgerEntry(projectRoot, input);
+}
+
+export async function appendDeclaredCommandLedgerEntries(projectRoot: string, input: { runId: string; taskId: string; branch: string; commands: string[] }): Promise<void> {
+  for (const command of input.commands) {
+    await appendUniqueInvocationLedgerEntry(projectRoot, {
+      runId: input.runId,
+      taskId: input.taskId,
+      branch: input.branch,
+      kind: 'command',
+      ref: command,
+      status: 'declared',
+      materialRefs: [],
+      metadata: { source: 'task.validation' }
+    });
+  }
+}
+
+async function importLegacyInvocationLedgerIfNeeded(projectRoot: string, runId: string, ledgerPath: string): Promise<void> {
+  if (!await exists(ledgerPath)) {
+    return;
+  }
+  try {
+    const raw = await readFile(ledgerPath, 'utf8');
+    const contentHash = hashDocumentContent(raw);
+    await withRuntimeStore(projectRoot, ({ db }) => {
+      const legacy = db.prepare('SELECT content_hash FROM legacy_imports WHERE run_id = ? AND entity_type = ?').get(runId, 'invocations') as { content_hash?: string } | undefined;
+      if (legacy?.content_hash === contentHash) {
+        return;
+      }
+      for (const line of raw.split(/\r?\n/).filter(Boolean)) {
+        const entry = JSON.parse(line) as InvocationLedgerEntry;
+        db.prepare('INSERT OR REPLACE INTO activities (activity_id, run_id, task_id, branch, kind, ref, status, created_at, payload_json) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)')
+          .run(entry.entryId, entry.runId, entry.taskId ?? null, entry.branch ?? null, entry.kind, entry.ref, entry.status ?? null, entry.timestamp, JSON.stringify(entry));
+      }
+      db.prepare('INSERT OR REPLACE INTO legacy_imports (import_id, run_id, entity_type, content_hash, imported_at, status, issue) VALUES (?, ?, ?, ?, ?, ?, ?)')
+        .run(legacyImportId(runId, 'invocations'), runId, 'invocations', contentHash, new Date().toISOString(), 'imported', null);
+    });
+  } catch (error) {
+    await recordLegacyImportFailure(projectRoot, runId, 'invocations', error);
+    throw new RuntimeStoreError('LEGACY_IMPORT_FAILED', `Cannot import legacy invocation ledger for ${runId}: ${messageFromError(error)}`, { cause: error });
+  }
+}
+
+async function findMatchingInvocationLedgerEntry(projectRoot: string, input: Omit<InvocationLedgerEntry, 'contract' | 'version' | 'entryId' | 'timestamp'>): Promise<InvocationLedgerEntry | null> {
+  const entries = await listInvocationLedgerEntries(projectRoot, input.runId);
+  return entries.find((entry) => entry.kind === input.kind && entry.ref === input.ref && entry.status === input.status && entry.outputHash === input.outputHash) ?? null;
+}
+
+
+
+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);
+}