@devflow-tools/database 0.17.2 → 0.17.3

package/dist/task-runtime.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stableTaskRuntimeJson = stableTaskRuntimeJson;
+exports.stableTaskRuntimeHash = stableTaskRuntimeHash;
+exports.mapTaskRuntimeEventRow = mapTaskRuntimeEventRow;
+exports.mapTaskRuntimeSnapshotRow = mapTaskRuntimeSnapshotRow;
+const node_crypto_1 = require("node:crypto");
+function stableTaskRuntimeJson(value) {
+    return JSON.stringify(canonicalize(value));
+}
+function stableTaskRuntimeHash(value) {
+    return (0, node_crypto_1.createHash)('sha256').update(stableTaskRuntimeJson(value)).digest('hex');
+}
+function mapTaskRuntimeEventRow(row) {
+    return {
+        schemaVersion: requiredLiteral(row.schema_version, 'task-runtime-event.v1'),
+        producer: requiredString(row.producer, 'producer'),
+        producerVersion: requiredString(row.producer_version, 'producer_version'),
+        eventId: requiredString(row.event_id, 'event_id'),
+        sequence: requiredPositiveInteger(row.sequence, 'sequence'),
+        identity: mapIdentity(row),
+        taskSpecHash: requiredString(row.task_spec_hash, 'task_spec_hash'),
+        kind: requiredString(row.kind, 'kind'),
+        payload: parseObject(row.payload_json, 'payload_json'),
+        createdAt: requiredNonNegativeInteger(row.created_at, 'created_at'),
+    };
+}
+function mapTaskRuntimeSnapshotRow(row) {
+    const snapshot = parseObject(row.snapshot_json, 'snapshot_json');
+    if (snapshot.schemaVersion !== 'task-runtime-snapshot.v1') {
+        throw new Error(`TASK_RUNTIME_SCHEMA_UNSUPPORTED:${String(snapshot.schemaVersion)}`);
+    }
+    if (snapshot.snapshotHash !== requiredString(row.snapshot_hash, 'snapshot_hash')) {
+        throw new Error('TASK_RUNTIME_SNAPSHOT_HASH_MISMATCH');
+    }
+    const { snapshotHash: _snapshotHash, ...body } = snapshot;
+    if (stableTaskRuntimeHash(body) !== snapshot.snapshotHash) {
+        throw new Error('TASK_RUNTIME_SNAPSHOT_HASH_MISMATCH');
+    }
+    return snapshot;
+}
+function mapIdentity(row) {
+    return {
+        projectRoot: requiredString(row.project_root, 'project_root'),
+        projectId: requiredString(row.project_id, 'project_id'),
+        hostId: requiredString(row.host_id, 'host_id'),
+        sessionId: requiredString(row.session_id, 'session_id'),
+        turnId: requiredString(row.turn_id, 'turn_id'),
+        requestId: requiredString(row.request_id, 'request_id'),
+        ...(optionalString(row.execution_id) ? { executionId: optionalString(row.execution_id) } : {}),
+    };
+}
+function requiredLiteral(value, literal) {
+    if (value !== literal)
+        throw new Error(`TASK_RUNTIME_SCHEMA_UNSUPPORTED:${String(value)}`);
+    return literal;
+}
+function requiredString(value, field) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new Error(`TASK_RUNTIME_ROW_INVALID:${field}`);
+    return value;
+}
+function optionalString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function requiredPositiveInteger(value, field) {
+    const result = Number(value);
+    if (!Number.isSafeInteger(result) || result < 1)
+        throw new Error(`TASK_RUNTIME_ROW_INVALID:${field}`);
+    return result;
+}
+function requiredNonNegativeInteger(value, field) {
+    const result = Number(value);
+    if (!Number.isSafeInteger(result) || result < 0)
+        throw new Error(`TASK_RUNTIME_ROW_INVALID:${field}`);
+    return result;
+}
+function parseObject(value, field) {
+    if (typeof value !== 'string')
+        throw new Error(`TASK_RUNTIME_ROW_INVALID:${field}`);
+    try {
+        const parsed = JSON.parse(value);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            throw new Error('not object');
+        return parsed;
+    }
+    catch {
+        throw new Error(`TASK_RUNTIME_ROW_INVALID:${field}`);
+    }
+}
+function canonicalize(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value) || Object.is(value, -0))
+            throw new Error('TASK_RUNTIME_JSON_INVALID');
+        return value;
+    }
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (!value || typeof value !== 'object' || Object.getPrototypeOf(value) !== Object.prototype) {
+        throw new Error('TASK_RUNTIME_JSON_INVALID');
+    }
+    return Object.fromEntries(Object.keys(value).sort()
+        .map(key => [key, canonicalize(value[key])]));
+}

package/dist/work-queue.d.ts

@@ -1,5 +1,5 @@
-export type WorkKind = 'memory.explicit_commit' | 'memory.explicit_enrichment' | 'memory.turn_capture' | 'memory.turn_distill' | 'memory.vector_backfill' | 'context.prefetch' | 'verification.policy' | 'learning.analyze_session' | 'workflow.worker_start' | 'workflow.worker_monitor' | 'workflow.worker_verify' | 'workflow.worker_merge' | 'workflow.worker_cleanup' | 'session.bootstrap' | 'session.finalize' | 'telemetry.reconcile';
-export type WorkState = 'pending' | 'leased' | 'completed' | 'failed' | 'dead_letter';
+export type WorkKind = 'memory.explicit_commit' | 'memory.explicit_enrichment' | 'memory.turn_capture' | 'memory.turn_distill' | 'memory.vector_backfill' | 'knowledge.ingest' | 'knowledge.index_refresh' | 'context.prefetch' | 'verification.policy' | 'learning.analyze_session' | 'workflow.worker_start' | 'workflow.worker_monitor' | 'workflow.worker_verify' | 'workflow.worker_merge' | 'workflow.worker_cleanup' | 'session.bootstrap' | 'session.finalize' | 'telemetry.reconcile';
+export type WorkState = 'pending' | 'leased' | 'completed' | 'failed' | 'dead_letter' | 'cancelled';
 export interface WorkError {
     category: string;
     message: string;
@@ -11,6 +11,8 @@ export interface WorkItemRecord {
     projectRoot: string;
     sessionId?: string;
     turnId?: string;
+    sourceHash?: string;
+    taskSpecHash?: string;
     payload: unknown;
     state: WorkState;
     attempts: number;
@@ -23,6 +25,10 @@ export interface WorkItemRecord {
     createdAt: number;
     updatedAt: number;
     completedAt?: number;
+    cancelledAt?: number;
+    cancellationReason?: string;
+    replayOfId?: string;
+    replayCount: number;
 }
 export interface EnqueueWorkInput {
     idempotencyKey: string;
@@ -30,10 +36,20 @@ export interface EnqueueWorkInput {
     projectRoot: string;
     sessionId?: string;
     turnId?: string;
+    sourceHash?: string;
+    taskSpecHash?: string;
     payload: unknown;
     maxAttempts?: number;
     nextAttemptAt?: number;
 }
+export interface ProjectMutationLeaseRecord {
+    projectRoot: string;
+    mutationKind: string;
+    owner: string;
+    leaseExpiresAt: number;
+    sourceHash?: string;
+    updatedAt: number;
+}
 export interface LeaseWorkInput {
     projectRoot: string;
     owner: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devflow-tools/database",
-  "version": "0.17.2",
+  "version": "0.17.3",
   "description": "DevFlow SQLite database package",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/database.ts

@@ -12,6 +12,7 @@ import type {
   WorkItemRecord,
   WorkQueueHealth,
   WorkState,
+  ProjectMutationLeaseRecord,
 } from './work-queue';
 import {
   mapSessionObligationRow,
@@ -84,6 +85,13 @@ import {
   type ToolNameResolutionRecord,
   type TranscriptCheckpointRecord,
 } from './task-semantic-control';
+import {
+  mapTaskRuntimeEventRow,
+  mapTaskRuntimeSnapshotRow,
+  stableTaskRuntimeJson,
+  type TaskRuntimeEventRecord,
+  type TaskRuntimeSnapshotRecord,
+} from './task-runtime';
 
 export interface BenchmarkReportRecord {
   runId: string;
@@ -612,6 +620,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(
@@ -716,6 +727,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 +914,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 +928,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 +942,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 +1223,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 +3084,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 +3098,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 +3142,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 +3161,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 +3511,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 +3525,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 +3940,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 +4004,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 +4013,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;
   }
 
@@ -4085,6 +4251,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 +4439,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 +4788,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,

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;