sdd-agent-platform 0.3.0 → 0.4.0

package/node_modules/@sdd-agent-platform/core/src/router/team-mode.ts

@@ -0,0 +1,170 @@
+import { TEAM_MODE_POLICY_VERSION } from '../contracts.js';
+import type { LifecycleAutonomyCeiling } from '../lifecycle/decision-gate.js';
+import type { TeamModeActivation } from './route-cache.js';
+import { BUILT_IN_DELEGATION_WAVES } from './runtime-registry.js';
+import type {
+  AgentProfileId,
+  AgentRouterCategory,
+  DelegationWavePolicy,
+  TeamModeCostClass,
+  TeamModeCostRoute,
+  TeamModeDecisionStatus,
+  TeamModePolicy,
+  TeamModeSelection
+} from './agent-runtime.js';
+import type { SddTask } from '../sdd-docs/task-parser.js';
+import { buildTaskRiskProfile } from '../task-risk-profile.js';
+import { taskAutonomyCeiling } from './risk-policy.js';
+
+export function resolveTeamModeActivation(options: { teamModeEnabled?: boolean; teamModeActivation?: TeamModeActivation }, defaultActivation: TeamModeActivation): TeamModeActivation {
+  if (options.teamModeActivation) {
+    return options.teamModeActivation;
+  }
+  if (options.teamModeEnabled === true) {
+    return 'force';
+  }
+  if (options.teamModeEnabled === false) {
+    return 'off';
+  }
+  return defaultActivation;
+}
+
+function baseTeamModePolicy(input: {
+  activation: TeamModeActivation;
+  mode: TeamModeSelection;
+  enabled: boolean;
+  decision: TeamModeDecisionStatus;
+  costClass: TeamModeCostClass;
+  reason: string;
+  costRoute?: TeamModeCostRoute;
+  downgradeReason?: string | null;
+  trustPolicyEnforced?: boolean;
+  allowedWaves?: DelegationWavePolicy[];
+  memberProfiles?: AgentProfileId[];
+  maxMembers?: number;
+  blockedReason?: string | null;
+}): TeamModePolicy {
+  const allowedWaves = input.allowedWaves ?? [];
+  const memberProfiles = (input.memberProfiles ?? [...new Set(allowedWaves.flatMap((wave) => wave.memberProfiles))]).slice(0, input.maxMembers ?? 0);
+  return {
+    version: TEAM_MODE_POLICY_VERSION,
+    enabled: input.enabled,
+    decision: input.decision,
+    mode: input.mode,
+    activation: input.activation,
+    costClass: input.costClass,
+    reason: input.reason,
+    costRoute: input.costRoute ?? 'not_applicable',
+    downgradeReason: input.downgradeReason ?? null,
+    trustPolicyEnforced: input.trustPolicyEnforced ?? true,
+    chiefProfile: 'orchestrator',
+    memberProfiles,
+    allowedWaves,
+    maxMembers: input.maxMembers ?? memberProfiles.length,
+    requireArtifacts: true,
+    blockedReason: input.blockedReason ?? null,
+    waveRecommendation: allowedWaves.map((wave) => wave.id)
+  };
+}
+
+function selectTeamWaves(ids: Array<DelegationWavePolicy['id']>): DelegationWavePolicy[] {
+  return ids.map((id) => BUILT_IN_DELEGATION_WAVES.find((wave) => wave.id === id)).filter((wave): wave is DelegationWavePolicy => Boolean(wave));
+}
+
+
+export function buildTeamModePolicy(options: { activation: TeamModeActivation; task?: SddTask | null; category?: AgentRouterCategory; risk?: string[]; autonomyCeiling?: LifecycleAutonomyCeiling; blockedReason?: string | null }): TeamModePolicy {
+  const activation = options.activation;
+  if (options.blockedReason) {
+    return baseTeamModePolicy({
+      activation,
+      mode: 'off',
+      enabled: false,
+      decision: 'blocked',
+      costClass: 'none',
+      reason: options.blockedReason,
+      blockedReason: options.blockedReason,
+      costRoute: 'blocked',
+      trustPolicyEnforced: true
+    });
+  }
+  if (activation === 'off') {
+    return baseTeamModePolicy({
+      activation,
+      mode: 'off',
+      enabled: false,
+      decision: 'disabled',
+      costClass: 'none',
+      reason: 'Team-mode automation disabled for this route.',
+      costRoute: 'not_applicable',
+      trustPolicyEnforced: true
+    });
+  }
+
+  const task = options.task ?? null;
+  const profile = buildTaskRiskProfile(task ? { ...task, risk: options.risk ?? task.risk } : null);
+  const category = options.category ?? 'planning';
+  const autonomyCeiling = options.autonomyCeiling ?? (task ? taskAutonomyCeiling(task) : 'direct_execution_allowed');
+  const highRisk = profile.riskLevel === 'high' || autonomyCeiling === 'full_sdd_with_checkpoint' || autonomyCeiling === 'research_before_implementation';
+  const reviewNeeded = category === 'implementation_review' || category === 'validation' || profile.teamRecommendation === 'review-lite';
+
+  if (profile.securitySensitive || category === 'security_research') {
+    return baseTeamModePolicy({
+      activation,
+      mode: 'security-research',
+      enabled: true,
+      decision: 'enabled',
+      costClass: 'high',
+      reason: 'Security-sensitive task automatically requires bounded security-research team evidence.',
+      costRoute: 'no_downgrade',
+      trustPolicyEnforced: true,
+      allowedWaves: selectTeamWaves(['security_research', 'validation']),
+      memberProfiles: ['security', 'reviewer', 'validator'],
+      maxMembers: 3
+    });
+  }
+
+  if (highRisk || category === 'external_research') {
+    return baseTeamModePolicy({
+      activation,
+      mode: 'hyperplan',
+      enabled: true,
+      decision: 'enabled',
+      costClass: highRisk ? 'high' : 'medium',
+      reason: profile.sourceBoundary ? 'Source-boundary or high-risk task requires adversarial planning/review evidence.' : 'High-risk or research-before-implementation task automatically requires adversarial planning/review evidence.',
+      costRoute: 'no_downgrade',
+      trustPolicyEnforced: true,
+      allowedWaves: selectTeamWaves(['hyperplan', 'implementation_review', 'validation']),
+      memberProfiles: ['architect', 'reviewer', 'security', 'validator'],
+      maxMembers: 4
+    });
+  }
+
+  if (reviewNeeded || activation === 'force') {
+    return baseTeamModePolicy({
+      activation,
+      mode: 'review-lite',
+      enabled: true,
+      decision: 'enabled',
+      costClass: 'low',
+      reason: activation === 'force' ? 'Team-mode was forced, so router selects the lowest-cost review-lite team.' : 'Task metadata indicates review or validation evidence is useful, so router selects review-lite.',
+      costRoute: activation === 'force' ? 'no_downgrade' : 'downgraded',
+      downgradeReason: activation === 'force' ? null : 'Low-cost review-lite route keeps reviewer/validator artifacts and policy-backed verify mandatory.',
+      trustPolicyEnforced: true,
+      allowedWaves: selectTeamWaves(['implementation_review', 'validation']),
+      memberProfiles: ['reviewer', 'validator'],
+      maxMembers: 2
+    });
+  }
+
+  return baseTeamModePolicy({
+    activation,
+    mode: 'off',
+    enabled: false,
+    decision: 'disabled',
+    costClass: 'none',
+    reason: 'No shared task risk profile signals require an agent team.',
+    costRoute: 'downgraded',
+    downgradeReason: 'Shared risk profile is low; artifact trust policy and policy-backed verify remain mandatory.',
+    trustPolicyEnforced: true
+  });
+}

package/node_modules/@sdd-agent-platform/core/src/router.ts

@@ -0,0 +1,4 @@
+export * from './router/agent-runtime-config.js';
+export * from './router/agent-runtime.js';
+export * from './router/route-cache.js';
+export * from './router/route-sdd-task.js';

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

@@ -0,0 +1,85 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { getArtifactPath, getEvidenceAttachmentPath, getRunRelativeArtifactPath, normalizeArtifactRootRelativePath } from '../runtime-paths.js';
+import { readRuntimeRunState, recordRuntimeEvidenceAttachment, runtimeScopedId, withRuntimeStore } from '../storage/runtime-store.js';
+import { exists } from '../storage/json-io.js';
+import { appendArtifactHashLedgerEntry } from './invocation-ledger.js';
+
+export async function writeArtifact(projectRoot: string, runId: string, artifactRootRelativePath: string, content: string): Promise<{ absolutePath: string; runRelativePath: string }> {
+  const normalized = normalizeArtifactRootRelativePath(artifactRootRelativePath);
+  const runRelativePath = getRunRelativeArtifactPath(normalized);
+  const branchSlug = await resolveRunBranchSlug(projectRoot, runId);
+  const absolutePath = getEvidenceAttachmentPath(projectRoot, branchSlug, runRelativePath);
+  await mkdir(path.dirname(absolutePath), { recursive: true });
+  await writeFile(absolutePath, content, 'utf8');
+  await appendArtifactHashLedgerEntry(projectRoot, {
+    runId,
+    artifactPath: runRelativePath,
+    content,
+    status: 'written'
+  });
+  await recordRuntimeArtifact(projectRoot, { runId, path: runRelativePath, content, status: 'written' });
+  await recordRuntimeEvidenceAttachment(projectRoot, {
+    branchSlug,
+    runId,
+    kind: artifactKind(runRelativePath),
+    relativePath: runRelativePath,
+    contentHash: hashDocumentContent(content),
+    bytes: Buffer.byteLength(content, 'utf8'),
+    payload: { artifactPath: runRelativePath, status: 'written' }
+  });
+  return { absolutePath, runRelativePath };
+}
+
+export async function readArtifact(projectRoot: string, runId: string, artifactRootRelativePath: string): Promise<string> {
+  const normalized = normalizeArtifactRootRelativePath(artifactRootRelativePath);
+  const runRelativePath = getRunRelativeArtifactPath(normalized);
+  const evidencePath = getEvidenceAttachmentPath(projectRoot, await resolveRunBranchSlug(projectRoot, runId), runRelativePath);
+  if (await exists(evidencePath)) {
+    return readFile(evidencePath, 'utf8');
+  }
+  return readFile(getArtifactPath(projectRoot, runId, normalized), 'utf8');
+}
+
+export function artifactKind(artifactPath: string): string {
+  const fileName = path.posix.basename(artifactPath.replace(/\\/g, '/'));
+  if (fileName.startsWith('implement-')) {
+    return 'implement';
+  }
+  if (fileName.startsWith('review-')) {
+    return 'review';
+  }
+  if (fileName.startsWith('debug-')) {
+    return 'debug';
+  }
+  if (fileName.startsWith('validation-')) {
+    return 'validation';
+  }
+  if (fileName.startsWith('gap-report-')) {
+    return 'gap-report';
+  }
+  if (fileName === 'sync-back-proposal.md') {
+    return 'sync-back-proposal';
+  }
+  return 'artifact';
+}
+
+async function recordRuntimeArtifact(projectRoot: string, input: { runId: string; path: string; content: string; status: string; taskId?: string | null; agent?: string | null }): Promise<void> {
+  const contentHash = hashDocumentContent(input.content);
+  const now = new Date().toISOString();
+  const payload = JSON.stringify({ path: input.path, status: input.status, taskId: input.taskId ?? null, agent: input.agent ?? null });
+  await withRuntimeStore(projectRoot, ({ db }) => {
+    db.prepare('INSERT OR REPLACE INTO artifacts (artifact_id, run_id, path, kind, task_id, agent, content_hash, bytes, status, created_at, payload_json) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)')
+      .run(runtimeScopedId(input.runId, input.path, contentHash), input.runId, input.path, artifactKind(input.path), input.taskId ?? null, input.agent ?? null, contentHash, Buffer.byteLength(input.content, 'utf8'), input.status, now, payload);
+  });
+}
+
+async function resolveRunBranchSlug(projectRoot: string, runId: string): Promise<string> {
+  const state = await readRuntimeRunState(projectRoot, runId);
+  return state?.gitBranch ?? state?.partition ?? 'unscoped';
+}
+
+function hashDocumentContent(raw: string): string {
+  return createHash('sha256').update(raw.replace(/\r\n/g, '\n'), 'utf8').digest('hex');
+}

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

@@ -0,0 +1,27 @@
+
+import path from 'node:path';
+import { EVENT_LOG_CONTRACT } from '../contracts.js';
+import { getRunDir } from '../runtime-paths.js';
+
+import { importLegacyRunEventsIfNeeded, readRuntimeRunEvents, recordRuntimeEvent } from '../storage/runtime-store.js';
+import type { RuntimeEvent } from './model.js';
+
+export async function appendEvent(projectRoot: string, runId: string, event: Omit<RuntimeEvent, 'contract' | 'time'>): Promise<RuntimeEvent> {
+  const nextEvent: RuntimeEvent = {
+    contract: EVENT_LOG_CONTRACT,
+    time: new Date().toISOString(),
+    ...event
+  };
+  await recordRuntimeEvent(projectRoot, nextEvent);
+  return nextEvent;
+}
+
+export async function readRunEvents(projectRoot: string, runId: string): Promise<RuntimeEvent[]> {
+  const storedEvents = await readRuntimeRunEvents(projectRoot, runId);
+  if (storedEvents.length > 0) {
+    return storedEvents;
+  }
+  const eventPath = path.join(getRunDir(projectRoot, runId), 'events.jsonl');
+  await importLegacyRunEventsIfNeeded(projectRoot, runId, eventPath);
+  return readRuntimeRunEvents(projectRoot, runId);
+}

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

@@ -0,0 +1,207 @@
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { TASK_RUN_EVIDENCE_CONTRACT_VERSION } from '../contracts.js';
+import { getAgentExecutionsDir, getTeamSessionsDir, getWorkerRuntimesDir } from '../runtime-paths.js';
+import { exists } from '../storage/json-io.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';
+
+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 };
+  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;
+  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),
+    listAgentExecutionRecords(projectRoot, runId),
+    listTeamSessionRecords(projectRoot, runId),
+    listResidentWorkerRuntimeRecords(projectRoot, runId),
+    listInvocationLedgerEntries(projectRoot, runId)
+  ]);
+  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, agentExecutions, teamSessions, workerRuntimes, invocationLedger),
+    tasks: state.tasks,
+    agentExecutions,
+    teamSessions,
+    workerRuntimes,
+    invocationLedger
+  };
+}
+
+async function listAgentExecutionRecords(projectRoot: string, runId: string): Promise<AgentExecutionRecordView[]> {
+  const recordsDir = getAgentExecutionsDir(projectRoot, runId);
+  if (!await exists(recordsDir)) {
+    return [];
+  }
+  const records = await readJsonRecords<AgentExecutionRecordView>(recordsDir);
+  return records.sort((left, right) => left.createdAt.localeCompare(right.createdAt) || left.executionId.localeCompare(right.executionId));
+}
+
+async function listTeamSessionRecords(projectRoot: string, runId: string): Promise<TeamSessionRecordView[]> {
+  const recordsDir = getTeamSessionsDir(projectRoot, runId);
+  if (!await exists(recordsDir)) {
+    return [];
+  }
+  const records = await readJsonRecords<TeamSessionRecordView>(recordsDir);
+  return records.sort((left, right) => left.createdAt.localeCompare(right.createdAt) || left.teamId.localeCompare(right.teamId));
+}
+
+async function listResidentWorkerRuntimeRecords(projectRoot: string, runId: string): Promise<ResidentWorkerRuntimeRecordView[]> {
+  const recordsDir = getWorkerRuntimesDir(projectRoot, runId);
+  if (!await exists(recordsDir)) {
+    return [];
+  }
+  const records = await readJsonRecords<ResidentWorkerRuntimeRecordView>(recordsDir);
+  return records.sort((left, right) => left.updatedAt.localeCompare(right.updatedAt) || left.runtimeId.localeCompare(right.runtimeId));
+}
+
+async function readJsonRecords<T>(recordsDir: string): Promise<T[]> {
+  const entries = await readdir(recordsDir, { withFileTypes: true });
+  const records: T[] = [];
+  for (const entry of entries.filter((candidate) => candidate.isFile() && candidate.name.endsWith('.json'))) {
+    try {
+      const raw = await readFile(path.join(recordsDir, entry.name), 'utf8');
+      records.push(JSON.parse(raw) as T);
+    } catch {
+      continue;
+    }
+  }
+  return records;
+}
+
+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

@@ -0,0 +1,109 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { INVOCATION_LEDGER_CONTRACT_VERSION } from '../contracts.js';
+import { getInvocationLedgerPath } 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 = getInvocationLedgerPath(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);
+}