sdd-agent-platform 0.4.2 → 0.5.1

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

@@ -1,26 +1,23 @@
-import { DELEGATION_LIVENESS_CONTRACT, DELEGATION_LIVENESS_VERSION } from '../contracts.js';
-import type { DelegationStatus } from './state-machine.js';
-
-export type { DelegationStatus } from './state-machine.js';
-export type DelegationRunMode = 'foreground' | 'background';
-
-export interface DelegationRecord {
-  contract: typeof DELEGATION_LIVENESS_CONTRACT;
-  version: typeof DELEGATION_LIVENESS_VERSION;
-  delegationId: string;
-  task: string;
-  agent: string;
-  runMode: DelegationRunMode;
-  blocking: boolean;
-  requiredForPhaseExit: boolean;
-  status: DelegationStatus;
-  startedAt: string;
-  lastHeartbeatAt: string | null;
-  timeoutSeconds: number;
-  expectedArtifact: string;
-  terminalEventRequired: boolean;
-  terminalEventAt?: string | null;
-  attempt?: number;
-  retryOf?: string | null;
-  replayReason?: 'document_contract_refresh' | 'artifact_reingest' | 'validation_replay' | 'manual_retry' | 'runtime_recovery' | null;
-}
+import { DELEGATION_LIVENESS_CONTRACT, DELEGATION_LIVENESS_VERSION } from '../contracts.js';
+import type { DelegationStatus } from './state-machine.js';
+
+export type { DelegationStatus } from './state-machine.js';
+export type DelegationRunMode = 'foreground' | 'background';
+
+export interface DelegationRecord {
+  contract: typeof DELEGATION_LIVENESS_CONTRACT;
+  version: typeof DELEGATION_LIVENESS_VERSION;
+  delegationId: string;
+  task: string;
+  agent: string;
+  runMode: DelegationRunMode;
+  blocking: boolean;
+  requiredForPhaseExit: boolean;
+  status: DelegationStatus;
+  startedAt: string;
+  lastHeartbeatAt: string | null;
+  timeoutSeconds: number;
+  expectedArtifact: string;
+  terminalEventRequired: boolean;
+  terminalEventAt?: string | null;
+}

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

@@ -1,58 +1,58 @@
-import { readFile } from 'node:fs/promises';
-import { parseProjectConfig } from '../config/project-config.js';
-import { getProjectConfigPath } from '../runtime-paths.js';
-import { readAllRunStates, readRunState } from '../run-state/run-state.js';
-import type { DelegationQueueItem } from '../run-state/run-index.js';
-import type { RunState, RunStateDelegationRecord } from '../run-state/model.js';
-
-export const DELEGATION_QUEUE_CONTRACT_VERSION = 'phase-3.3-delegation-queue-contract-v1';
-
-export interface DelegationQueueSnapshot {
-  version: string;
-  items: DelegationQueueItem[];
-}
-
-export async function listDelegationQueueItems(projectRoot: string, options: { runId?: string } = {}): Promise<DelegationQueueSnapshot> {
-  await assertProjectConfigReadable(projectRoot);
-  const states = options.runId
-    ? [await readRunState(projectRoot, options.runId)]
-    : await readAllRunStates(projectRoot);
-  const items = states
-    .filter((state) => state.status !== 'archived')
-    .flatMap((state) => Object.values(state.delegations).map((delegation) => delegationQueueItemFromRunState(state, delegation)))
-    .sort((left, right) => left.id.localeCompare(right.id));
-  return {
-    version: DELEGATION_QUEUE_CONTRACT_VERSION,
-    items
-  };
-}
-
-export async function inspectDelegationQueueItem(projectRoot: string, queueItemId: string): Promise<DelegationQueueItem | null> {
-  const snapshot = await listDelegationQueueItems(projectRoot);
-  return snapshot.items.find((item) => item.id === queueItemId) ?? null;
-}
-
-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
-  };
-}
-
-async function assertProjectConfigReadable(projectRoot: string): Promise<void> {
-  const configPath = getProjectConfigPath(projectRoot);
-  const raw = await readFile(configPath, 'utf8');
-  parseProjectConfig(raw, configPath);
-}
+import { readFile } from 'node:fs/promises';
+import { parseProjectConfig } from '../config/project-config.js';
+import { getProjectConfigPath } from '../runtime-paths.js';
+import { readAllRunStates, readRunState } from '../run-state/run-state.js';
+import type { DelegationQueueItem } from '../run-state/run-index.js';
+import type { RunState, RunStateDelegationRecord } from '../run-state/model.js';
+
+export const DELEGATION_QUEUE_CONTRACT_VERSION = 'phase-3.3-delegation-queue-contract-v1';
+
+export interface DelegationQueueSnapshot {
+  version: string;
+  items: DelegationQueueItem[];
+}
+
+export async function listDelegationQueueItems(projectRoot: string, options: { runId?: string } = {}): Promise<DelegationQueueSnapshot> {
+  await assertProjectConfigReadable(projectRoot);
+  const states = options.runId
+    ? [await readRunState(projectRoot, options.runId)]
+    : await readAllRunStates(projectRoot);
+  const items = states
+    .filter((state) => state.status !== 'archived')
+    .flatMap((state) => Object.values(state.delegations).map((delegation) => delegationQueueItemFromRunState(state, delegation)))
+    .sort((left, right) => left.id.localeCompare(right.id));
+  return {
+    version: DELEGATION_QUEUE_CONTRACT_VERSION,
+    items
+  };
+}
+
+export async function inspectDelegationQueueItem(projectRoot: string, queueItemId: string): Promise<DelegationQueueItem | null> {
+  const snapshot = await listDelegationQueueItems(projectRoot);
+  return snapshot.items.find((item) => item.id === queueItemId) ?? null;
+}
+
+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
+  };
+}
+
+async function assertProjectConfigReadable(projectRoot: string): Promise<void> {
+  const configPath = getProjectConfigPath(projectRoot);
+  const raw = await readFile(configPath, 'utf8');
+  parseProjectConfig(raw, configPath);
+}

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

@@ -1,14 +1,14 @@
-import { readRunState, writeRunState } from '../run-state/run-state.js';
-import type { DelegationRecord } from './model.js';
-
-export async function persistDelegation(projectRoot: string, runId: string, delegation: DelegationRecord): Promise<void> {
-  const state = await readRunState(projectRoot, runId);
-  await writeRunState(projectRoot, {
-    ...state,
-    status: delegation.status === 'RUNNING' ? 'running' : state.status,
-    delegations: {
-      ...state.delegations,
-      [delegation.delegationId]: delegation
-    }
-  });
-}
+import { readRunState, writeRunState } from '../run-state/run-state.js';
+import type { DelegationRecord } from './model.js';
+
+export async function persistDelegation(projectRoot: string, runId: string, delegation: DelegationRecord): Promise<void> {
+  const state = await readRunState(projectRoot, runId);
+  await writeRunState(projectRoot, {
+    ...state,
+    status: delegation.status === 'RUNNING' ? 'running' : state.status,
+    delegations: {
+      ...state.delegations,
+      [delegation.delegationId]: delegation
+    }
+  });
+}

package/node_modules/@sdd-agent-platform/core/src/delegation/state-machine.ts

@@ -1,90 +1,90 @@
-export const DELEGATION_STATE_MACHINE_VERSION = 'phase-3.4-delegation-state-machine-v1';
-
-export type DelegationStatus = 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'TIMED_OUT' | 'CANCELLED' | 'RECOVERABLE' | 'STALE';
-
-export interface ContractValidationIssue {
-  field: string;
-  message: string;
-  recommendation: string;
-}
-
-export interface DelegationStateTransition {
-  from: DelegationStatus;
-  to: DelegationStatus;
-  event: string;
-  terminal: boolean;
-}
-
-export interface DelegationStateMachine {
-  version: string;
-  statuses: DelegationStatus[];
-  terminalStatuses: DelegationStatus[];
-  transitions: DelegationStateTransition[];
-}
-
-export interface DelegationStateTransitionValidation {
-  valid: boolean;
-  from: DelegationStatus;
-  to: DelegationStatus;
-  event: string | null;
-  issues: ContractValidationIssue[];
-}
-
-export const DELEGATION_STATUSES: DelegationStatus[] = ['PENDING', 'RUNNING', 'COMPLETED', 'FAILED', 'TIMED_OUT', 'CANCELLED', 'RECOVERABLE', 'STALE'];
-export const TERMINAL_DELEGATION_STATUSES: DelegationStatus[] = ['COMPLETED', 'FAILED', 'TIMED_OUT', 'CANCELLED'];
-
-const DELEGATION_STATE_TRANSITIONS: DelegationStateTransition[] = [
-  { from: 'PENDING', to: 'RUNNING', event: 'delegation_started', terminal: false },
-  { from: 'PENDING', to: 'CANCELLED', event: 'delegation_cancelled', terminal: true },
-  { from: 'RUNNING', to: 'COMPLETED', event: 'delegation_completed', terminal: true },
-  { from: 'RUNNING', to: 'FAILED', event: 'delegation_failed', terminal: true },
-  { from: 'RUNNING', to: 'TIMED_OUT', event: 'delegation_timeout', terminal: true },
-  { from: 'RUNNING', to: 'CANCELLED', event: 'delegation_cancelled', terminal: true },
-  { from: 'RUNNING', to: 'RECOVERABLE', event: 'artifact_invalid', terminal: false },
-  { from: 'RUNNING', to: 'STALE', event: 'delegation_stale', terminal: false },
-  { from: 'RECOVERABLE', to: 'RUNNING', event: 'delegation_retry_started', terminal: false },
-  { from: 'RECOVERABLE', to: 'FAILED', event: 'delegation_failed', terminal: true },
-  { from: 'RECOVERABLE', to: 'CANCELLED', event: 'delegation_cancelled', terminal: true },
-  { from: 'STALE', to: 'RUNNING', event: 'delegation_heartbeat', terminal: false },
-  { from: 'STALE', to: 'TIMED_OUT', event: 'delegation_timeout', terminal: true },
-  { from: 'STALE', to: 'FAILED', event: 'delegation_failed', terminal: true },
-  { from: 'STALE', to: 'CANCELLED', event: 'delegation_cancelled', terminal: true }
-];
-
-export function getDelegationStateMachine(): DelegationStateMachine {
-  return {
-    version: DELEGATION_STATE_MACHINE_VERSION,
-    statuses: [...DELEGATION_STATUSES],
-    terminalStatuses: [...TERMINAL_DELEGATION_STATUSES],
-    transitions: DELEGATION_STATE_TRANSITIONS.map((transition) => ({ ...transition }))
-  };
-}
-
-export function validateDelegationStateTransition(from: DelegationStatus, to: DelegationStatus, event: string | null = null): DelegationStateTransitionValidation {
-  const issues: ContractValidationIssue[] = [];
-  if (!DELEGATION_STATUSES.includes(from)) {
-    issues.push(contractIssue('from', `Unsupported delegation status ${from}.`, 'Use a status declared by the Phase 3.4 delegation state machine.'));
-  }
-  if (!DELEGATION_STATUSES.includes(to)) {
-    issues.push(contractIssue('to', `Unsupported delegation status ${to}.`, 'Use a status declared by the Phase 3.4 delegation state machine.'));
-  }
-  if (TERMINAL_DELEGATION_STATUSES.includes(from)) {
-    issues.push(contractIssue('from', `Terminal delegation status ${from} cannot transition to ${to}.`, 'Create a new delegation id for retry instead of reopening a terminal delegation.'));
-  }
-  const transition = DELEGATION_STATE_TRANSITIONS.find((candidate) => candidate.from === from && candidate.to === to && (event === null || candidate.event === event));
-  if (!transition) {
-    const eventText = event === null ? '' : ` on ${event}`;
-    issues.push(contractIssue('transition', `Transition ${from} -> ${to}${eventText} is not allowed.`, 'Use one of the declared Phase 3.4 delegation state machine transitions.'));
-  }
-  return {
-    valid: issues.length === 0,
-    from,
-    to,
-    event,
-    issues
-  };
-}
-
-function contractIssue(field: string, message: string, recommendation: string): ContractValidationIssue {
-  return { field, message, recommendation };
-}
+export const DELEGATION_STATE_MACHINE_VERSION = 'phase-3.4-delegation-state-machine-v1';
+
+export type DelegationStatus = 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'TIMED_OUT' | 'CANCELLED' | 'RECOVERABLE' | 'STALE';
+
+export interface ContractValidationIssue {
+  field: string;
+  message: string;
+  recommendation: string;
+}
+
+export interface DelegationStateTransition {
+  from: DelegationStatus;
+  to: DelegationStatus;
+  event: string;
+  terminal: boolean;
+}
+
+export interface DelegationStateMachine {
+  version: string;
+  statuses: DelegationStatus[];
+  terminalStatuses: DelegationStatus[];
+  transitions: DelegationStateTransition[];
+}
+
+export interface DelegationStateTransitionValidation {
+  valid: boolean;
+  from: DelegationStatus;
+  to: DelegationStatus;
+  event: string | null;
+  issues: ContractValidationIssue[];
+}
+
+export const DELEGATION_STATUSES: DelegationStatus[] = ['PENDING', 'RUNNING', 'COMPLETED', 'FAILED', 'TIMED_OUT', 'CANCELLED', 'RECOVERABLE', 'STALE'];
+export const TERMINAL_DELEGATION_STATUSES: DelegationStatus[] = ['COMPLETED', 'FAILED', 'TIMED_OUT', 'CANCELLED'];
+
+const DELEGATION_STATE_TRANSITIONS: DelegationStateTransition[] = [
+  { from: 'PENDING', to: 'RUNNING', event: 'delegation_started', terminal: false },
+  { from: 'PENDING', to: 'CANCELLED', event: 'delegation_cancelled', terminal: true },
+  { from: 'RUNNING', to: 'COMPLETED', event: 'delegation_completed', terminal: true },
+  { from: 'RUNNING', to: 'FAILED', event: 'delegation_failed', terminal: true },
+  { from: 'RUNNING', to: 'TIMED_OUT', event: 'delegation_timeout', terminal: true },
+  { from: 'RUNNING', to: 'CANCELLED', event: 'delegation_cancelled', terminal: true },
+  { from: 'RUNNING', to: 'RECOVERABLE', event: 'artifact_invalid', terminal: false },
+  { from: 'RUNNING', to: 'STALE', event: 'delegation_stale', terminal: false },
+  { from: 'RECOVERABLE', to: 'RUNNING', event: 'delegation_retry_started', terminal: false },
+  { from: 'RECOVERABLE', to: 'FAILED', event: 'delegation_failed', terminal: true },
+  { from: 'RECOVERABLE', to: 'CANCELLED', event: 'delegation_cancelled', terminal: true },
+  { from: 'STALE', to: 'RUNNING', event: 'delegation_heartbeat', terminal: false },
+  { from: 'STALE', to: 'TIMED_OUT', event: 'delegation_timeout', terminal: true },
+  { from: 'STALE', to: 'FAILED', event: 'delegation_failed', terminal: true },
+  { from: 'STALE', to: 'CANCELLED', event: 'delegation_cancelled', terminal: true }
+];
+
+export function getDelegationStateMachine(): DelegationStateMachine {
+  return {
+    version: DELEGATION_STATE_MACHINE_VERSION,
+    statuses: [...DELEGATION_STATUSES],
+    terminalStatuses: [...TERMINAL_DELEGATION_STATUSES],
+    transitions: DELEGATION_STATE_TRANSITIONS.map((transition) => ({ ...transition }))
+  };
+}
+
+export function validateDelegationStateTransition(from: DelegationStatus, to: DelegationStatus, event: string | null = null): DelegationStateTransitionValidation {
+  const issues: ContractValidationIssue[] = [];
+  if (!DELEGATION_STATUSES.includes(from)) {
+    issues.push(contractIssue('from', `Unsupported delegation status ${from}.`, 'Use a status declared by the Phase 3.4 delegation state machine.'));
+  }
+  if (!DELEGATION_STATUSES.includes(to)) {
+    issues.push(contractIssue('to', `Unsupported delegation status ${to}.`, 'Use a status declared by the Phase 3.4 delegation state machine.'));
+  }
+  if (TERMINAL_DELEGATION_STATUSES.includes(from)) {
+    issues.push(contractIssue('from', `Terminal delegation status ${from} cannot transition to ${to}.`, 'Create a new delegation id for retry instead of reopening a terminal delegation.'));
+  }
+  const transition = DELEGATION_STATE_TRANSITIONS.find((candidate) => candidate.from === from && candidate.to === to && (event === null || candidate.event === event));
+  if (!transition) {
+    const eventText = event === null ? '' : ` on ${event}`;
+    issues.push(contractIssue('transition', `Transition ${from} -> ${to}${eventText} is not allowed.`, 'Use one of the declared Phase 3.4 delegation state machine transitions.'));
+  }
+  return {
+    valid: issues.length === 0,
+    from,
+    to,
+    event,
+    issues
+  };
+}
+
+function contractIssue(field: string, message: string, recommendation: string): ContractValidationIssue {
+  return { field, message, recommendation };
+}

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

@@ -1,127 +1,124 @@
-import { DELEGATION_LIVENESS_CONTRACT, DELEGATION_LIVENESS_VERSION } from '../contracts.js';
-import { normalizeStageEvidenceOrLegacyArtifactRef } from '../runtime-paths.js';
-import { validateSddResultArtifact } from '../artifacts/sdd-result.js';
-import type { DelegationRecord, DelegationStatus } from './model.js';
-
-export interface ContractValidationIssue {
-  field: string;
-  message: string;
-  recommendation: string;
-}
-
-export interface DelegationValidationReport {
-  valid: boolean;
-  delegation: DelegationRecord;
-  terminal: boolean;
-  stale: boolean;
-  issues: ContractValidationIssue[];
-}
-
-export function createDelegationRecord(input: { delegationId: string; task: string; agent: string; expectedArtifact: string; runMode?: DelegationRecord['runMode']; blocking?: boolean; requiredForPhaseExit?: boolean; startedAt?: string; timeoutSeconds?: number; status?: DelegationStatus; attempt?: number; retryOf?: string | null; replayReason?: DelegationRecord['replayReason'] }): DelegationRecord {
-  return {
-    contract: DELEGATION_LIVENESS_CONTRACT,
-    version: DELEGATION_LIVENESS_VERSION,
-    delegationId: input.delegationId,
-    task: input.task,
-    agent: input.agent,
-    runMode: input.runMode ?? 'foreground',
-    blocking: input.blocking ?? true,
-    requiredForPhaseExit: input.requiredForPhaseExit ?? true,
-    status: input.status ?? 'RUNNING',
-    startedAt: input.startedAt ?? new Date().toISOString(),
-    lastHeartbeatAt: null,
-    timeoutSeconds: input.timeoutSeconds ?? 900,
-    expectedArtifact: input.expectedArtifact,
-    terminalEventRequired: true,
-    terminalEventAt: null,
-    attempt: input.attempt,
-    retryOf: input.retryOf ?? null,
-    replayReason: input.replayReason ?? null
-  };
-}
-
-export function isDelegationTerminal(status: DelegationStatus): boolean {
-  return status === 'COMPLETED' || status === 'FAILED' || status === 'TIMED_OUT' || status === 'CANCELLED';
-}
-
-export function isDelegationStale(delegation: DelegationRecord, now = new Date()): boolean {
-  if (delegation.status !== 'RUNNING') {
-    return false;
-  }
-  const heartbeatOrStart = delegation.lastHeartbeatAt ?? delegation.startedAt;
-  const timestamp = Date.parse(heartbeatOrStart);
-  if (Number.isNaN(timestamp) || delegation.timeoutSeconds <= 0) {
-    return true;
-  }
-  return now.getTime() - timestamp > delegation.timeoutSeconds * 1000;
-}
-
-export async function validateDelegationRecord(projectRoot: string, runId: string, delegation: DelegationRecord, now = new Date()): Promise<DelegationValidationReport> {
-  const issues: ContractValidationIssue[] = [];
-  const terminal = isDelegationTerminal(delegation.status);
-  const stale = isDelegationStale(delegation, now);
-  issues.push(...validateDelegationShape(delegation));
-
-  if (stale) {
-    issues.push(contractIssue('status', `Delegation ${delegation.delegationId} is RUNNING but stale.`, 'Record TIMED_OUT/FAILED/CANCELLED or heartbeat before phase exit.'));
-  }
-  if (delegation.requiredForPhaseExit && delegation.terminalEventRequired && terminal && !delegation.terminalEventAt) {
-    issues.push(contractIssue('terminalEventAt', `Delegation ${delegation.delegationId} is terminal without a terminal event timestamp.`, 'Append and persist the terminal delegation event timestamp.'));
-  }
-  if (delegation.status === 'COMPLETED') {
-    const resultReport = await validateSddResultArtifact(projectRoot, runId, delegation.expectedArtifact, { expectedTask: delegation.task, expectedAgent: delegation.agent });
-    issues.push(...resultReport.issues);
-  }
-
-  return { valid: issues.length === 0, delegation, terminal, stale, issues };
-}
-
-function validateDelegationShape(delegation: DelegationRecord): ContractValidationIssue[] {
-  const issues: ContractValidationIssue[] = [];
-  if (delegation.contract !== DELEGATION_LIVENESS_CONTRACT) {
-    issues.push(contractIssue('contract', `Expected ${DELEGATION_LIVENESS_CONTRACT}, got ${delegation.contract}.`, 'Use the delegation liveness contract id.'));
-  }
-  if (delegation.version !== DELEGATION_LIVENESS_VERSION) {
-    issues.push(contractIssue('version', `Expected ${DELEGATION_LIVENESS_VERSION}, got ${delegation.version}.`, 'Use version: 1.3.0 until a new contract version is introduced.'));
-  }
-  if (!delegation.delegationId) {
-    issues.push(contractIssue('delegationId', 'delegationId is required.', 'Persist a stable delegation id.'));
-  }
-  if (!delegation.task) {
-    issues.push(contractIssue('task', 'delegation task is required.', 'Persist the delegated task id.'));
-  }
-  if (!delegation.agent) {
-    issues.push(contractIssue('agent', 'delegation agent is required.', 'Persist the delegated agent name.'));
-  }
-  if (delegation.runMode !== 'foreground' && delegation.runMode !== 'background') {
-    issues.push(contractIssue('runMode', `Unsupported runMode ${delegation.runMode}.`, 'Use foreground or background.'));
-  }
-  if (!isDelegationStatus(delegation.status)) {
-    issues.push(contractIssue('status', `Unsupported delegation status ${delegation.status}.`, 'Use a status from the delegation liveness contract.'));
-  }
-  if (!Number.isInteger(delegation.timeoutSeconds) || delegation.timeoutSeconds <= 0) {
-    issues.push(contractIssue('timeoutSeconds', 'timeoutSeconds must be a positive integer.', 'Set an explicit positive timeout.'));
-  }
-  validateRunRelativeArtifactReference(delegation.expectedArtifact, issues, 'expectedArtifact');
-  return issues;
-}
-
-function validateRunRelativeArtifactReference(value: string, issues: ContractValidationIssue[], field = 'artifacts'): void {
-  try {
-    normalizeStageEvidenceOrLegacyArtifactRef(value);
-  } catch (error) {
-    issues.push(contractIssue(field, messageFromError(error), 'Use repo-relative .sdd/runs/<branch>/<stage>/*.md stage evidence refs for new delegation evidence.'));
-  }
-}
-
-function isDelegationStatus(value: string): value is DelegationStatus {
-  return value === 'PENDING' || value === 'RUNNING' || value === 'COMPLETED' || value === 'FAILED' || value === 'TIMED_OUT' || value === 'CANCELLED' || value === 'RECOVERABLE' || value === 'STALE';
-}
-
-function contractIssue(field: string, message: string, recommendation: string): ContractValidationIssue {
-  return { field, message, recommendation };
-}
-
-function messageFromError(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
+import { DELEGATION_LIVENESS_CONTRACT, DELEGATION_LIVENESS_VERSION } from '../contracts.js';
+import { toArtifactRootRelativePath } from '../runtime-paths.js';
+import { validateSddResultArtifact } from '../artifacts/sdd-result.js';
+import type { DelegationRecord, DelegationStatus } from './model.js';
+
+export interface ContractValidationIssue {
+  field: string;
+  message: string;
+  recommendation: string;
+}
+
+export interface DelegationValidationReport {
+  valid: boolean;
+  delegation: DelegationRecord;
+  terminal: boolean;
+  stale: boolean;
+  issues: ContractValidationIssue[];
+}
+
+export function createDelegationRecord(input: { delegationId: string; task: string; agent: string; expectedArtifact: string; runMode?: DelegationRecord['runMode']; blocking?: boolean; requiredForPhaseExit?: boolean; startedAt?: string; timeoutSeconds?: number; status?: DelegationStatus }): DelegationRecord {
+  return {
+    contract: DELEGATION_LIVENESS_CONTRACT,
+    version: DELEGATION_LIVENESS_VERSION,
+    delegationId: input.delegationId,
+    task: input.task,
+    agent: input.agent,
+    runMode: input.runMode ?? 'foreground',
+    blocking: input.blocking ?? true,
+    requiredForPhaseExit: input.requiredForPhaseExit ?? true,
+    status: input.status ?? 'RUNNING',
+    startedAt: input.startedAt ?? new Date().toISOString(),
+    lastHeartbeatAt: null,
+    timeoutSeconds: input.timeoutSeconds ?? 900,
+    expectedArtifact: input.expectedArtifact,
+    terminalEventRequired: true,
+    terminalEventAt: null
+  };
+}
+
+export function isDelegationTerminal(status: DelegationStatus): boolean {
+  return status === 'COMPLETED' || status === 'FAILED' || status === 'TIMED_OUT' || status === 'CANCELLED';
+}
+
+export function isDelegationStale(delegation: DelegationRecord, now = new Date()): boolean {
+  if (delegation.status !== 'RUNNING') {
+    return false;
+  }
+  const heartbeatOrStart = delegation.lastHeartbeatAt ?? delegation.startedAt;
+  const timestamp = Date.parse(heartbeatOrStart);
+  if (Number.isNaN(timestamp) || delegation.timeoutSeconds <= 0) {
+    return true;
+  }
+  return now.getTime() - timestamp > delegation.timeoutSeconds * 1000;
+}
+
+export async function validateDelegationRecord(projectRoot: string, runId: string, delegation: DelegationRecord, now = new Date()): Promise<DelegationValidationReport> {
+  const issues: ContractValidationIssue[] = [];
+  const terminal = isDelegationTerminal(delegation.status);
+  const stale = isDelegationStale(delegation, now);
+  issues.push(...validateDelegationShape(delegation));
+
+  if (stale) {
+    issues.push(contractIssue('status', `Delegation ${delegation.delegationId} is RUNNING but stale.`, 'Record TIMED_OUT/FAILED/CANCELLED or heartbeat before phase exit.'));
+  }
+  if (delegation.requiredForPhaseExit && delegation.terminalEventRequired && terminal && !delegation.terminalEventAt) {
+    issues.push(contractIssue('terminalEventAt', `Delegation ${delegation.delegationId} is terminal without a terminal event timestamp.`, 'Append and persist the terminal delegation event timestamp.'));
+  }
+  if (delegation.status === 'COMPLETED') {
+    const resultReport = await validateSddResultArtifact(projectRoot, runId, delegation.expectedArtifact, { expectedTask: delegation.task, expectedAgent: delegation.agent });
+    issues.push(...resultReport.issues);
+  }
+
+  return { valid: issues.length === 0, delegation, terminal, stale, issues };
+}
+
+function validateDelegationShape(delegation: DelegationRecord): ContractValidationIssue[] {
+  const issues: ContractValidationIssue[] = [];
+  if (delegation.contract !== DELEGATION_LIVENESS_CONTRACT) {
+    issues.push(contractIssue('contract', `Expected ${DELEGATION_LIVENESS_CONTRACT}, got ${delegation.contract}.`, 'Use the delegation liveness contract id.'));
+  }
+  if (delegation.version !== DELEGATION_LIVENESS_VERSION) {
+    issues.push(contractIssue('version', `Expected ${DELEGATION_LIVENESS_VERSION}, got ${delegation.version}.`, 'Use version: 1.3.0 until a new contract version is introduced.'));
+  }
+  if (!delegation.delegationId) {
+    issues.push(contractIssue('delegationId', 'delegationId is required.', 'Persist a stable delegation id.'));
+  }
+  if (!delegation.task) {
+    issues.push(contractIssue('task', 'delegation task is required.', 'Persist the delegated task id.'));
+  }
+  if (!delegation.agent) {
+    issues.push(contractIssue('agent', 'delegation agent is required.', 'Persist the delegated agent name.'));
+  }
+  if (delegation.runMode !== 'foreground' && delegation.runMode !== 'background') {
+    issues.push(contractIssue('runMode', `Unsupported runMode ${delegation.runMode}.`, 'Use foreground or background.'));
+  }
+  if (!isDelegationStatus(delegation.status)) {
+    issues.push(contractIssue('status', `Unsupported delegation status ${delegation.status}.`, 'Use a status from the delegation liveness contract.'));
+  }
+  if (!Number.isInteger(delegation.timeoutSeconds) || delegation.timeoutSeconds <= 0) {
+    issues.push(contractIssue('timeoutSeconds', 'timeoutSeconds must be a positive integer.', 'Set an explicit positive timeout.'));
+  }
+  validateRunRelativeArtifactReference(delegation.expectedArtifact, issues, 'expectedArtifact');
+  return issues;
+}
+
+function validateRunRelativeArtifactReference(value: string, issues: ContractValidationIssue[], field = 'artifacts'): void {
+  try {
+    toArtifactRootRelativePath(value);
+  } catch (error) {
+    issues.push(contractIssue(field, messageFromError(error), 'Use run-relative artifacts/<file> paths that stay under the run artifact directory.'));
+  }
+}
+
+function isDelegationStatus(value: string): value is DelegationStatus {
+  return value === 'PENDING' || value === 'RUNNING' || value === 'COMPLETED' || value === 'FAILED' || value === 'TIMED_OUT' || value === 'CANCELLED' || value === 'RECOVERABLE' || value === 'STALE';
+}
+
+function contractIssue(field: string, message: string, recommendation: string): ContractValidationIssue {
+  return { field, message, recommendation };
+}
+
+function messageFromError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}