@devflow-tools/database 0.17.2 → 0.17.4

package/src/database.ts

@@ -12,6 +12,7 @@ import type {
   WorkItemRecord,
   WorkQueueHealth,
   WorkState,
+  ProjectMutationLeaseRecord,
 } from './work-queue';
 import {
   mapSessionObligationRow,
@@ -84,6 +85,19 @@ import {
   type ToolNameResolutionRecord,
   type TranscriptCheckpointRecord,
 } from './task-semantic-control';
+import {
+  mapTaskRuntimeEventRow,
+  mapTaskRuntimeSnapshotRow,
+  stableTaskRuntimeJson,
+  type TaskRuntimeEventRecord,
+  type TaskRuntimeSnapshotRecord,
+} from './task-runtime';
+import {
+  assertSemanticResolutionRecord,
+  mapSemanticResolutionRow,
+  stableSemanticResolutionJson,
+  type SemanticResolutionRecord,
+} from './semantic-resolution';
 
 export interface BenchmarkReportRecord {
   runId: string;
@@ -612,6 +626,9 @@ export class DevFlowDatabase {
         source_id TEXT NOT NULL, stage TEXT NOT NULL, rank INTEGER, raw_score REAL,
         normalized_score REAL, final_score REAL, applicability TEXT NOT NULL DEFAULT '[]',
         reason TEXT, tool_evidence TEXT NOT NULL DEFAULT '[]', verification_receipt TEXT,
+        schema_version TEXT NOT NULL DEFAULT 'retrieval-ledger-event.v1', task_spec_hash TEXT,
+        actor TEXT, source_version TEXT, source_content_hash TEXT,
+        evidence_ids TEXT NOT NULL DEFAULT '[]', reason_code TEXT,
         payload TEXT NOT NULL DEFAULT '{}', created_at INTEGER NOT NULL
       );
       CREATE INDEX IF NOT EXISTS idx_retrieval_ledger_identity ON devflow_retrieval_ledger(
@@ -651,6 +668,35 @@ export class DevFlowDatabase {
       CREATE UNIQUE INDEX IF NOT EXISTS idx_task_intent_source
         ON devflow_task_intent_artifacts(project_root, session_id, source_hash, version);
 
+      CREATE TABLE IF NOT EXISTS devflow_semantic_resolutions (
+        frame_hash TEXT PRIMARY KEY,
+        project_root TEXT NOT NULL,
+        project_id TEXT NOT NULL,
+        host_id TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        turn_id TEXT NOT NULL,
+        request_id TEXT NOT NULL,
+        source_hash TEXT NOT NULL,
+        artifact_hash TEXT NOT NULL,
+        artifact_revision INTEGER NOT NULL CHECK(artifact_revision > 0),
+        supersedes_frame_hash TEXT,
+        state TEXT NOT NULL CHECK(state IN ('provisional', 'resolved', 'abstained', 'unavailable')),
+        generated_by TEXT NOT NULL CHECK(generated_by IN ('deterministic', 'embedding_router', 'host_semantic', 'hybrid')),
+        model_id TEXT,
+        model_revision TEXT,
+        route_catalog_version TEXT NOT NULL,
+        threshold_version TEXT NOT NULL,
+        route_json TEXT NOT NULL,
+        sampling_json TEXT NOT NULL,
+        conflicts_json TEXT NOT NULL,
+        frame_json TEXT NOT NULL,
+        duration_ms INTEGER NOT NULL CHECK(duration_ms >= 0),
+        created_at INTEGER NOT NULL,
+        UNIQUE(project_root, session_id, turn_id, artifact_revision)
+      );
+      CREATE INDEX IF NOT EXISTS idx_semantic_resolution_latest
+        ON devflow_semantic_resolutions(project_root, session_id, turn_id, artifact_revision DESC);
+
       CREATE TABLE IF NOT EXISTS devflow_channel_query_plans (
         plan_hash TEXT PRIMARY KEY,
         source_intent_hash TEXT NOT NULL,
@@ -716,6 +762,40 @@ export class DevFlowDatabase {
       CREATE INDEX IF NOT EXISTS idx_terminal_transition_turn
         ON devflow_terminal_transitions(project_root, session_id, turn_id, sequence);
 
+      CREATE TABLE IF NOT EXISTS devflow_task_runtime_events (
+        event_id TEXT PRIMARY KEY,
+        schema_version TEXT NOT NULL,
+        producer TEXT NOT NULL,
+        producer_version TEXT NOT NULL,
+        project_root TEXT NOT NULL,
+        project_id TEXT NOT NULL,
+        host_id TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        turn_id TEXT NOT NULL,
+        request_id TEXT NOT NULL,
+        execution_id TEXT,
+        task_spec_hash TEXT NOT NULL,
+        sequence INTEGER NOT NULL CHECK(sequence > 0),
+        kind TEXT NOT NULL,
+        payload_json TEXT NOT NULL DEFAULT '{}',
+        created_at INTEGER NOT NULL,
+        UNIQUE(project_root, session_id, turn_id, sequence)
+      );
+      CREATE INDEX IF NOT EXISTS idx_task_runtime_event_identity
+        ON devflow_task_runtime_events(project_root, session_id, turn_id, sequence);
+
+      CREATE TABLE IF NOT EXISTS devflow_task_runtime_snapshots (
+        project_root TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        turn_id TEXT NOT NULL,
+        last_event_sequence INTEGER NOT NULL,
+        schema_version TEXT NOT NULL,
+        snapshot_json TEXT NOT NULL,
+        snapshot_hash TEXT NOT NULL,
+        updated_at INTEGER NOT NULL,
+        PRIMARY KEY(project_root, session_id, turn_id)
+      );
+
       CREATE TABLE IF NOT EXISTS devflow_transcript_checkpoints (
         id TEXT PRIMARY KEY,
         project_root TEXT NOT NULL,
@@ -869,9 +949,11 @@ export class DevFlowDatabase {
         project_root TEXT NOT NULL,
         session_id TEXT,
         turn_id TEXT,
+        source_hash TEXT,
+        task_spec_hash TEXT,
         payload TEXT NOT NULL,
         state TEXT NOT NULL DEFAULT 'pending'
-          CHECK(state IN ('pending', 'leased', 'completed', 'failed', 'dead_letter')),
+          CHECK(state IN ('pending', 'leased', 'completed', 'failed', 'dead_letter', 'cancelled')),
         attempts INTEGER NOT NULL DEFAULT 0 CHECK(attempts >= 0),
         max_attempts INTEGER NOT NULL DEFAULT 5 CHECK(max_attempts > 0),
         lease_owner TEXT,
@@ -881,7 +963,11 @@ export class DevFlowDatabase {
         error_message TEXT,
         created_at INTEGER NOT NULL,
         updated_at INTEGER NOT NULL,
-        completed_at INTEGER
+        completed_at INTEGER,
+        cancelled_at INTEGER,
+        cancellation_reason TEXT,
+        replay_of_id TEXT,
+        replay_count INTEGER NOT NULL DEFAULT 0
       );
 
       CREATE INDEX IF NOT EXISTS idx_work_items_ready
@@ -891,6 +977,16 @@ export class DevFlowDatabase {
       CREATE INDEX IF NOT EXISTS idx_work_items_completed
         ON devflow_work_items(project_root, completed_at DESC);
 
+      CREATE TABLE IF NOT EXISTS devflow_project_mutation_leases (
+        project_root TEXT NOT NULL,
+        mutation_kind TEXT NOT NULL,
+        owner TEXT NOT NULL,
+        lease_expires_at INTEGER NOT NULL,
+        source_hash TEXT,
+        updated_at INTEGER NOT NULL,
+        PRIMARY KEY(project_root, mutation_kind)
+      );
+
       CREATE TABLE IF NOT EXISTS devflow_session_closures (
         session_id TEXT NOT NULL,
         project_root TEXT NOT NULL,
@@ -1162,6 +1258,19 @@ export class DevFlowDatabase {
     try { this.db.exec('ALTER TABLE devflow_context_receipts ADD COLUMN action_satisfied_at INTEGER'); } catch {}
     try { this.db.exec('ALTER TABLE devflow_context_receipts ADD COLUMN action_degradation_json TEXT'); } catch {}
     try { this.db.exec('ALTER TABLE devflow_context_receipts ADD COLUMN request_id TEXT'); } catch {}
+    try { this.db.exec("ALTER TABLE devflow_retrieval_ledger ADD COLUMN schema_version TEXT NOT NULL DEFAULT 'retrieval-ledger-event.v1'"); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_retrieval_ledger ADD COLUMN task_spec_hash TEXT'); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_retrieval_ledger ADD COLUMN actor TEXT'); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_retrieval_ledger ADD COLUMN source_version TEXT'); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_retrieval_ledger ADD COLUMN source_content_hash TEXT'); } catch {}
+    try { this.db.exec("ALTER TABLE devflow_retrieval_ledger ADD COLUMN evidence_ids TEXT NOT NULL DEFAULT '[]'"); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_retrieval_ledger ADD COLUMN reason_code TEXT'); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_work_items ADD COLUMN source_hash TEXT'); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_work_items ADD COLUMN task_spec_hash TEXT'); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_work_items ADD COLUMN cancelled_at INTEGER'); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_work_items ADD COLUMN cancellation_reason TEXT'); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_work_items ADD COLUMN replay_of_id TEXT'); } catch {}
+    try { this.db.exec('ALTER TABLE devflow_work_items ADD COLUMN replay_count INTEGER NOT NULL DEFAULT 0'); } catch {}
     this.db.exec('UPDATE devflow_rules SET updated_at = created_at WHERE updated_at IS NULL');
     this.db.exec('CREATE INDEX IF NOT EXISTS idx_devflow_rules_gate ON devflow_rules(gate, enabled)');
 
@@ -3010,7 +3119,8 @@ export class DevFlowDatabase {
   enqueueWork(input: EnqueueWorkInput): WorkItemRecord {
     if (!input.idempotencyKey.trim()) throw new Error('Work idempotency key is required');
     if (!input.projectRoot.trim()) throw new Error('Work project root is required');
-    const maxAttempts = input.maxAttempts ?? 5;
+    const maxAttempts = input.maxAttempts
+      ?? (input.kind === 'knowledge.ingest' || input.kind === 'knowledge.index_refresh' ? 3 : 5);
     if (!Number.isSafeInteger(maxAttempts) || maxAttempts <= 0) {
       throw new Error('Work maxAttempts must be a positive safe integer');
     }
@@ -3023,10 +3133,10 @@ export class DevFlowDatabase {
 
     const row = this.db.prepare(`
       INSERT INTO devflow_work_items (
-        id, idempotency_key, kind, project_root, session_id, turn_id, payload,
+        id, idempotency_key, kind, project_root, session_id, turn_id, source_hash, task_spec_hash, payload,
         state, attempts, max_attempts, lease_owner, lease_expires_at,
         next_attempt_at, error_category, error_message, created_at, updated_at, completed_at
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, 'pending', 0, ?, NULL, NULL, ?, NULL, NULL, ?, ?, NULL)
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', 0, ?, NULL, NULL, ?, NULL, NULL, ?, ?, NULL)
       ON CONFLICT(idempotency_key) DO UPDATE SET
         state = CASE
           WHEN devflow_work_items.state = 'dead_letter'
@@ -3067,6 +3177,8 @@ export class DevFlowDatabase {
       input.projectRoot,
       input.sessionId ?? null,
       input.turnId ?? null,
+      input.sourceHash ?? null,
+      input.taskSpecHash ?? null,
       JSON.stringify(input.payload ?? null),
       maxAttempts,
       nextAttemptAt,
@@ -3084,6 +3196,53 @@ export class DevFlowDatabase {
     return row ? this.mapWorkItem(row) : null;
   }
 
+  getWorkById(id: string): WorkItemRecord | null {
+    const row = this.db.prepare('SELECT * FROM devflow_work_items WHERE id = ?').get(id) as any;
+    return row ? this.mapWorkItem(row) : null;
+  }
+
+  acquireProjectMutationLease(input: { projectRoot: string; mutationKind: string; owner: string; leaseMs: number; sourceHash?: string; now?: number }): boolean {
+    const now = input.now ?? Date.now();
+    return this.db.prepare(`
+      INSERT INTO devflow_project_mutation_leases
+        (project_root, mutation_kind, owner, lease_expires_at, source_hash, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT(project_root, mutation_kind) DO UPDATE SET
+        owner = excluded.owner, lease_expires_at = excluded.lease_expires_at,
+        source_hash = excluded.source_hash, updated_at = excluded.updated_at
+      WHERE devflow_project_mutation_leases.lease_expires_at <= ? OR devflow_project_mutation_leases.owner = excluded.owner
+    `).run(input.projectRoot, input.mutationKind, input.owner, now + input.leaseMs, input.sourceHash ?? null, now, now).changes > 0;
+  }
+
+  releaseProjectMutationLease(projectRoot: string, mutationKind: string, owner: string): boolean {
+    return this.db.prepare('DELETE FROM devflow_project_mutation_leases WHERE project_root = ? AND mutation_kind = ? AND owner = ?')
+      .run(projectRoot, mutationKind, owner).changes > 0;
+  }
+
+  cancelStaleWork(input: { id: string; owner: string; sourceHash?: string; taskSpecHash?: string; reason?: string; now?: number }): boolean {
+    const current = this.getWorkById(input.id);
+    const stale = current && current.state === 'leased' && current.leaseOwner === input.owner
+      && ((input.sourceHash !== undefined && current.sourceHash !== input.sourceHash)
+        || (input.taskSpecHash !== undefined && current.taskSpecHash !== input.taskSpecHash));
+    if (!stale) return false;
+    const now = input.now ?? Date.now();
+    try {
+      return this.db.prepare(`UPDATE devflow_work_items SET state = 'cancelled', lease_owner = NULL, lease_expires_at = NULL, cancelled_at = ?, cancellation_reason = ?, updated_at = ? WHERE id = ? AND state = 'leased' AND lease_owner = ?`)
+        .run(now, input.reason ?? 'stale_source_or_task_spec', now, input.id, input.owner).changes === 1;
+    } catch {
+      return this.db.prepare(`UPDATE devflow_work_items SET state = 'completed', lease_owner = NULL, lease_expires_at = NULL, cancelled_at = ?, cancellation_reason = ?, updated_at = ? WHERE id = ? AND state = 'leased' AND lease_owner = ?`)
+        .run(now, input.reason ?? 'stale_source_or_task_spec', now, input.id, input.owner).changes === 1;
+    }
+  }
+
+  replayDeadLetterWork(id: string, input: { idempotencyKey: string; sourceHash?: string; taskSpecHash?: string; now?: number }): WorkItemRecord | null {
+    const original = this.getWorkById(id);
+    if (!original || original.state !== 'dead_letter') return null;
+    const replay = this.enqueueWork({ idempotencyKey: input.idempotencyKey, kind: original.kind, projectRoot: original.projectRoot, sessionId: original.sessionId, turnId: original.turnId, payload: original.payload, sourceHash: input.sourceHash ?? original.sourceHash, taskSpecHash: input.taskSpecHash ?? original.taskSpecHash, maxAttempts: original.maxAttempts, nextAttemptAt: input.now ?? Date.now() });
+    this.db.prepare('UPDATE devflow_work_items SET replay_of_id = ?, replay_count = replay_count + 1 WHERE id = ?').run(original.id, replay.id);
+    return this.getWorkById(replay.id);
+  }
+
   requestSessionClosure(input: RequestSessionClosureInput): SessionClosureRecord {
     if (!input.sessionId.trim()) throw new Error('Session closure requires a session ID');
     if (!input.projectRoot.trim()) throw new Error('Session closure requires a project root');
@@ -3387,8 +3546,10 @@ export class DevFlowDatabase {
       projectRoot: row.project_root,
       sessionId: row.session_id ?? undefined,
       turnId: row.turn_id ?? undefined,
+      sourceHash: row.source_hash ?? undefined,
+      taskSpecHash: row.task_spec_hash ?? undefined,
       payload: parseJson(row.payload),
-      state: row.state,
+      state: row.cancelled_at != null ? 'cancelled' : row.state,
       attempts: Number(row.attempts),
       maxAttempts: Number(row.max_attempts),
       leaseOwner: row.lease_owner ?? undefined,
@@ -3399,6 +3560,10 @@ export class DevFlowDatabase {
       createdAt: Number(row.created_at),
       updatedAt: Number(row.updated_at),
       completedAt: row.completed_at == null ? undefined : Number(row.completed_at),
+      cancelledAt: row.cancelled_at == null ? undefined : Number(row.cancelled_at),
+      cancellationReason: row.cancellation_reason ?? undefined,
+      replayOfId: row.replay_of_id ?? undefined,
+      replayCount: Number(row.replay_count ?? 0),
     };
   }
 
@@ -3810,6 +3975,38 @@ export class DevFlowDatabase {
     } : null;
   }
 
+  getContextReceiptForRequest(
+    projectRoot: string,
+    sessionId: string,
+    requestId: string,
+  ): ContextReceiptRecord | null {
+    const row = this.db.prepare(`
+      SELECT project_root, session_id, execution_id, context_hash, issued_at, expires_at,
+             selected_files, memory_ids, canonical_next_action, canonical_action_json,
+             action_attempts, action_satisfied_at, action_degradation_json, request_id
+      FROM devflow_context_receipts
+      WHERE project_root = ? AND session_id = ? AND request_id = ?
+      ORDER BY issued_at DESC
+      LIMIT 1
+    `).get(projectRoot, sessionId, requestId) as any;
+    return row ? {
+      projectRoot: row.project_root,
+      sessionId: row.session_id,
+      executionId: row.execution_id,
+      contextHash: row.context_hash,
+      issuedAt: row.issued_at,
+      expiresAt: row.expires_at,
+      selectedFiles: parseJsonStringArray(row.selected_files),
+      memoryIds: parseJsonStringArray(row.memory_ids),
+      canonicalNextAction: row.canonical_next_action ?? undefined,
+      canonicalAction: parseJsonObject(row.canonical_action_json),
+      actionAttempts: parseJsonArray(row.action_attempts),
+      actionSatisfiedAt: row.action_satisfied_at ?? undefined,
+      actionDegradation: parseJsonObject(row.action_degradation_json),
+      requestId: row.request_id ?? undefined,
+    } : null;
+  }
+
   recordContextSelectionEvent(event: ContextSelectionEventRecord): boolean {
     return this.db.prepare(`
       INSERT OR IGNORE INTO devflow_context_selection_events
@@ -3842,7 +4039,8 @@ export class DevFlowDatabase {
         id, project_root, session_id, execution_id, turn_id, request_id, context_receipt,
         source_type, source_id, stage, rank, raw_score, normalized_score, final_score,
         applicability, reason, tool_evidence, verification_receipt, payload, created_at
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        , schema_version, task_spec_hash, actor, source_version, source_content_hash, evidence_ids, reason_code
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `).run(
       event.id, event.projectRoot, event.sessionId, event.executionId ?? null, event.turnId ?? null,
       event.requestId, event.contextReceipt, event.sourceType, event.sourceId, event.stage,
@@ -3850,6 +4048,9 @@ export class DevFlowDatabase {
       event.finalScore ?? null, JSON.stringify(event.applicability), event.reason ?? null,
       JSON.stringify(event.toolEvidence), event.verificationReceipt ?? null,
       JSON.stringify(event.payload), event.createdAt,
+      event.schemaVersion ?? 'retrieval-ledger-event.v1', event.taskSpecHash ?? null,
+      event.actor ?? null, event.sourceVersion ?? null, event.sourceContentHash ?? null,
+      JSON.stringify(event.evidenceIds ?? []), event.reasonCode ?? null,
     ).changes > 0;
   }
 
@@ -3940,6 +4141,96 @@ export class DevFlowDatabase {
     return row ? mapTaskIntentArtifactRow(row) : null;
   }
 
+  appendSemanticResolution(record: SemanticResolutionRecord): boolean {
+    assertSemanticResolutionRecord(record);
+    const existing = this.getSemanticResolution(record.frameHash);
+    if (existing) {
+      if (stableSemanticResolutionJson(existing) !== stableSemanticResolutionJson(record)) {
+        throw new Error(`SEMANTIC_RESOLUTION_HASH_CONFLICT:${record.frameHash}`);
+      }
+      return false;
+    }
+    this.db.exec('BEGIN IMMEDIATE');
+    try {
+      const conflicting = this.db.prepare(`
+        SELECT frame_hash FROM devflow_semantic_resolutions
+        WHERE project_root = ? AND session_id = ? AND turn_id = ? AND artifact_revision = ?
+      `).get(
+        record.projectRoot, record.sessionId, record.turnId, record.artifactRevision,
+      ) as Record<string, unknown> | undefined;
+      if (conflicting) {
+        throw new Error(`SEMANTIC_RESOLUTION_REVISION_CONFLICT:${record.turnId}:${record.artifactRevision}`);
+      }
+      if (record.supersedesFrameHash) {
+        const superseded = this.getSemanticResolution(record.supersedesFrameHash);
+        if (!superseded) {
+          throw new Error(`SEMANTIC_RESOLUTION_SUPERSEDED_NOT_FOUND:${record.supersedesFrameHash}`);
+        }
+        if (superseded.projectRoot !== record.projectRoot
+          || superseded.sessionId !== record.sessionId
+          || superseded.turnId !== record.turnId
+          || superseded.artifactRevision >= record.artifactRevision) {
+          throw new Error('SEMANTIC_RESOLUTION_SUPERSEDES_INVALID');
+        }
+      }
+      this.db.prepare(`
+        INSERT INTO devflow_semantic_resolutions (
+          frame_hash, project_root, project_id, host_id, session_id, turn_id, request_id,
+          source_hash, artifact_hash, artifact_revision, supersedes_frame_hash, state,
+          generated_by, model_id, model_revision, route_catalog_version, threshold_version,
+          route_json, sampling_json, conflicts_json, frame_json, duration_ms, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        record.frameHash, record.projectRoot, record.projectId, record.hostId,
+        record.sessionId, record.turnId, record.requestId, record.sourceHash,
+        record.artifactHash, record.artifactRevision, record.supersedesFrameHash ?? null,
+        record.state, record.generatedBy, record.modelId ?? null, record.modelRevision ?? null,
+        record.routeCatalogVersion, record.thresholdVersion,
+        stableSemanticResolutionJson(record.route), stableSemanticResolutionJson(record.sampling),
+        stableSemanticResolutionJson(record.conflicts), stableSemanticResolutionJson(record.frame),
+        record.durationMs, record.createdAt,
+      );
+      this.db.exec('COMMIT');
+      return true;
+    } catch (error) {
+      try { this.db.exec('ROLLBACK'); } catch {}
+      throw error;
+    }
+  }
+
+  getSemanticResolution(frameHash: string): SemanticResolutionRecord | null {
+    const row = this.db.prepare(`
+      SELECT * FROM devflow_semantic_resolutions WHERE frame_hash = ?
+    `).get(frameHash) as Record<string, unknown> | undefined;
+    return row ? mapSemanticResolutionRow(row) : null;
+  }
+
+  getLatestSemanticResolution(
+    projectRoot: string,
+    sessionId: string,
+    turnId: string,
+  ): SemanticResolutionRecord | null {
+    const row = this.db.prepare(`
+      SELECT * FROM devflow_semantic_resolutions
+      WHERE project_root = ? AND session_id = ? AND turn_id = ?
+      ORDER BY artifact_revision DESC, created_at DESC LIMIT 1
+    `).get(projectRoot, sessionId, turnId) as Record<string, unknown> | undefined;
+    return row ? mapSemanticResolutionRow(row) : null;
+  }
+
+  listSemanticResolutions(
+    projectRoot: string,
+    sessionId: string,
+    turnId: string,
+  ): SemanticResolutionRecord[] {
+    return (this.db.prepare(`
+      SELECT * FROM devflow_semantic_resolutions
+      WHERE project_root = ? AND session_id = ? AND turn_id = ?
+      ORDER BY artifact_revision ASC, created_at ASC
+    `).all(projectRoot, sessionId, turnId) as Array<Record<string, unknown>>)
+      .map(mapSemanticResolutionRow);
+  }
+
   listLatestTaskIntentArtifacts(projectRoot: string, sessionId: string): TaskIntentArtifactRecord[] {
     return (this.db.prepare(`
       SELECT artifact.* FROM devflow_task_intent_artifacts artifact
@@ -4085,6 +4376,123 @@ export class DevFlowDatabase {
     return this.getTerminalTransition(record.receiptId)!;
   }
 
+  appendTaskRuntimeEvent(event: TaskRuntimeEventRecord): TaskRuntimeEventRecord {
+    const existing = this.getTaskRuntimeEvent(event.eventId);
+    if (existing) {
+      if (stableTaskRuntimeJson(existing) !== stableTaskRuntimeJson(event)) {
+        throw new Error(`TASK_RUNTIME_EVENT_CONFLICT:${event.eventId}`);
+      }
+      return existing;
+    }
+    const atSequence = this.db.prepare(`
+      SELECT event_id FROM devflow_task_runtime_events
+      WHERE project_root = ? AND session_id = ? AND turn_id = ? AND sequence = ?
+    `).get(event.identity.projectRoot, event.identity.sessionId, event.identity.turnId, event.sequence) as
+      { event_id?: string } | undefined;
+    if (atSequence) throw new Error(`TASK_RUNTIME_SEQUENCE_CONFLICT:${event.sequence}`);
+    try {
+      this.db.prepare(`
+        INSERT INTO devflow_task_runtime_events (
+          event_id, schema_version, producer, producer_version, project_root, project_id,
+          host_id, session_id, turn_id, request_id, execution_id, task_spec_hash,
+          sequence, kind, payload_json, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        event.eventId, event.schemaVersion, event.producer, event.producerVersion,
+        event.identity.projectRoot, event.identity.projectId, event.identity.hostId,
+        event.identity.sessionId, event.identity.turnId, event.identity.requestId,
+        event.identity.executionId ?? null, event.taskSpecHash, event.sequence,
+        event.kind, stableTaskRuntimeJson(event.payload), event.createdAt,
+      );
+    } catch (error) {
+      const concurrentEvent = this.getTaskRuntimeEvent(event.eventId);
+      if (concurrentEvent) {
+        if (stableTaskRuntimeJson(concurrentEvent) === stableTaskRuntimeJson(event)) return concurrentEvent;
+        throw new Error(`TASK_RUNTIME_EVENT_CONFLICT:${event.eventId}`);
+      }
+      const concurrentSequence = this.db.prepare(`
+        SELECT event_id FROM devflow_task_runtime_events
+        WHERE project_root = ? AND session_id = ? AND turn_id = ? AND sequence = ?
+      `).get(event.identity.projectRoot, event.identity.sessionId, event.identity.turnId, event.sequence);
+      if (concurrentSequence) throw new Error(`TASK_RUNTIME_SEQUENCE_CONFLICT:${event.sequence}`);
+      throw error;
+    }
+    return this.getTaskRuntimeEvent(event.eventId)!;
+  }
+
+  getTaskRuntimeEvent(eventId: string): TaskRuntimeEventRecord | null {
+    const row = this.db.prepare('SELECT * FROM devflow_task_runtime_events WHERE event_id = ?')
+      .get(eventId) as Record<string, unknown> | undefined;
+    return row ? mapTaskRuntimeEventRow(row) : null;
+  }
+
+  listTaskRuntimeEvents(projectRoot: string, sessionId: string, turnId: string): TaskRuntimeEventRecord[] {
+    return (this.db.prepare(`
+      SELECT * FROM devflow_task_runtime_events
+      WHERE project_root = ? AND session_id = ? AND turn_id = ?
+      ORDER BY sequence ASC
+    `).all(projectRoot, sessionId, turnId) as Array<Record<string, unknown>>)
+      .map(mapTaskRuntimeEventRow);
+  }
+
+  putTaskRuntimeSnapshot(snapshot: TaskRuntimeSnapshotRecord): TaskRuntimeSnapshotRecord {
+    const current = this.getTaskRuntimeSnapshot(
+      snapshot.identity.projectRoot, snapshot.identity.sessionId, snapshot.identity.turnId,
+    );
+    if (current && current.lastEventSequence > snapshot.lastEventSequence) {
+      throw new Error('TASK_RUNTIME_SNAPSHOT_REGRESSION');
+    }
+    this.db.prepare(`
+      INSERT INTO devflow_task_runtime_snapshots (
+        project_root, session_id, turn_id, last_event_sequence, schema_version,
+        snapshot_json, snapshot_hash, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(project_root, session_id, turn_id) DO UPDATE SET
+        last_event_sequence = excluded.last_event_sequence,
+        schema_version = excluded.schema_version,
+        snapshot_json = excluded.snapshot_json,
+        snapshot_hash = excluded.snapshot_hash,
+        updated_at = excluded.updated_at
+      WHERE excluded.last_event_sequence >= devflow_task_runtime_snapshots.last_event_sequence
+    `).run(
+      snapshot.identity.projectRoot, snapshot.identity.sessionId, snapshot.identity.turnId,
+      snapshot.lastEventSequence, snapshot.schemaVersion, stableTaskRuntimeJson(snapshot),
+      snapshot.snapshotHash, snapshot.updatedAt,
+    );
+    return this.getTaskRuntimeSnapshot(
+      snapshot.identity.projectRoot, snapshot.identity.sessionId, snapshot.identity.turnId,
+    )!;
+  }
+
+  appendTaskRuntimeEventAndSnapshot(
+    event: TaskRuntimeEventRecord,
+    snapshot: TaskRuntimeSnapshotRecord,
+  ): TaskRuntimeSnapshotRecord {
+    return this.db.transaction(() => {
+      this.appendTaskRuntimeEvent(event);
+      return this.putTaskRuntimeSnapshot(snapshot);
+    });
+  }
+
+  getTaskRuntimeSnapshot(
+    projectRoot: string,
+    sessionId: string,
+    turnId: string,
+  ): TaskRuntimeSnapshotRecord | null {
+    const row = this.db.prepare(`
+      SELECT * FROM devflow_task_runtime_snapshots
+      WHERE project_root = ? AND session_id = ? AND turn_id = ?
+    `).get(projectRoot, sessionId, turnId) as Record<string, unknown> | undefined;
+    return row ? mapTaskRuntimeSnapshotRow(row) : null;
+  }
+
+  deleteTaskRuntimeSnapshot(projectRoot: string, sessionId: string, turnId: string): boolean {
+    return this.db.prepare(`
+      DELETE FROM devflow_task_runtime_snapshots
+      WHERE project_root = ? AND session_id = ? AND turn_id = ?
+    `).run(projectRoot, sessionId, turnId).changes > 0;
+  }
+
   getTerminalTransition(receiptId: string): TerminalTransitionRecord | null {
     const row = this.db.prepare(`
       SELECT * FROM devflow_terminal_transitions WHERE receipt_id = ?
@@ -4156,7 +4564,11 @@ export class DevFlowDatabase {
         id: row.id, projectRoot: row.project_root, sessionId: row.session_id,
         executionId: row.execution_id ?? undefined, turnId: row.turn_id ?? undefined,
         requestId: row.request_id, contextReceipt: row.context_receipt,
-        sourceType: row.source_type, sourceId: row.source_id, stage: row.stage,
+        schemaVersion: row.schema_version ?? 'retrieval-ledger-event.v1',
+        sourceType: row.source_type, sourceId: row.source_id, stage: row.stage === 'adopted' ? 'consumed' : row.stage,
+        taskSpecHash: row.task_spec_hash ?? undefined, actor: row.actor ?? undefined,
+        sourceVersion: row.source_version ?? undefined, sourceContentHash: row.source_content_hash ?? undefined,
+        evidenceIds: parseJsonStringArray(row.evidence_ids), reasonCode: row.reason_code ?? undefined,
         rank: row.rank ?? undefined, rawScore: row.raw_score ?? undefined,
         normalizedScore: row.normalized_score ?? undefined, finalScore: row.final_score ?? undefined,
         applicability: parseJsonStringArray(row.applicability), reason: row.reason ?? undefined,
@@ -4501,16 +4913,18 @@ export class DevFlowDatabase {
     turnId: string;
     receiptId: string;
     reason: string;
+    source?: string;
     decidedAt?: number;
   }): MemoryTurnRecord {
     const turnId = normalizeTurnId(input.turnId);
     this.db.prepare(`
       UPDATE devflow_memory_turns
-      SET status = 'skipped', receipt_id = ?, memory_ids = '[]', source = 'host_skip',
+      SET status = 'skipped', receipt_id = ?, memory_ids = '[]', source = ?,
           reason = ?, decided_at = ?
       WHERE turn_id = ? AND status = 'pending'
     `).run(
       input.receiptId,
+      input.source ?? 'host_skip',
       input.reason,
       input.decidedAt ?? Date.now(),
       turnId,

package/src/index.ts

@@ -31,6 +31,7 @@ export type {
   WorkKind,
   WorkQueueHealth,
   WorkState,
+  ProjectMutationLeaseRecord,
 } from './work-queue';
 export type {
   RetrievalLedgerEventRecord,
@@ -75,6 +76,22 @@ export {
   mapTranscriptCheckpointRow,
   stableSemanticJson,
 } from './task-semantic-control';
+export {
+  mapTaskRuntimeEventRow,
+  mapTaskRuntimeSnapshotRow,
+  stableTaskRuntimeHash,
+  stableTaskRuntimeJson,
+} from './task-runtime';
+export type {
+  TaskRuntimeChannelRecord,
+  TaskRuntimeChannelRequirement,
+  TaskRuntimeChannelStatus,
+  TaskRuntimeEventRecord,
+  TaskRuntimeIdentityRecord,
+  TaskRuntimeObligationRecord,
+  TaskRuntimeObligationState,
+  TaskRuntimeSnapshotRecord,
+} from './task-runtime';
 export type {
   ChannelQueryPlanRecord,
   TaskIdentityRecord,
@@ -124,3 +141,13 @@ export type {
   SessionObligationRecord,
   SessionObligationState,
 } from './obligation-ledger';
+export {
+  assertSemanticResolutionRecord,
+  mapSemanticResolutionRow,
+  stableSemanticResolutionJson,
+} from './semantic-resolution';
+export type {
+  PersistedSemanticGeneratedBy,
+  PersistedSemanticResolutionState,
+  SemanticResolutionRecord,
+} from './semantic-resolution';

package/src/retrieval-ledger.ts

@@ -1,10 +1,11 @@
 export type RetrievalLedgerStage =
-  | 'eligible' | 'candidate' | 'selected' | 'exposed' | 'adopted'
-  | 'positive_outcome' | 'negative_outcome' | 'unknown' | 'rejected';
+  | 'eligible' | 'candidate' | 'selected' | 'exposed' | 'adopted' | 'consumed' | 'verified'
+  | 'positive_outcome' | 'negative_outcome' | 'unknown' | 'unknown_outcome' | 'rejected';
 
 export type RetrievalLedgerSourceType = 'code' | 'memory' | 'knowledge' | 'action';
 
 export interface RetrievalLedgerEventRecord {
+  schemaVersion?: 'retrieval-ledger-event.v1';
   id: string;
   projectRoot: string;
   sessionId: string;
@@ -14,6 +15,12 @@ export interface RetrievalLedgerEventRecord {
   contextReceipt: string;
   sourceType: RetrievalLedgerSourceType;
   sourceId: string;
+  taskSpecHash?: string;
+  actor?: string;
+  sourceVersion?: string;
+  sourceContentHash?: string;
+  evidenceIds?: string[];
+  reasonCode?: string;
   stage: RetrievalLedgerStage;
   rank?: number;
   rawScore?: number;