@devflow-tools/database 0.17.1 → 0.17.3

package/dist/database.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DevFlowDatabase = void 0;
 exports.getGlobalDevFlowDbPath = getGlobalDevFlowDbPath;
 exports.openGlobalDevFlowDatabase = openGlobalDevFlowDatabase;
+exports.openGlobalDevFlowReadOnlyDatabase = openGlobalDevFlowReadOnlyDatabase;
 const node_sqlite_1 = require("./node-sqlite");
 const path_1 = require("path");
 const fs_1 = require("fs");
@@ -14,6 +15,7 @@ const retrieval_sessions_1 = require("./retrieval-sessions");
 const learning_candidates_1 = require("./learning-candidates");
 const workflow_workers_1 = require("./workflow-workers");
 const task_semantic_control_1 = require("./task-semantic-control");
+const task_runtime_1 = require("./task-runtime");
 const CONTEXT_REQUIRED_SKILLS = new Set([
     'react', 'vue', 'nest', 'nextjs', 'graphql', 'typescript',
 ]);
@@ -62,28 +64,59 @@ function openGlobalDevFlowDatabase(home = (0, os_1.homedir)(), options) {
     return new DevFlowDatabase(home, {
         dbPath: getGlobalDevFlowDbPath(home),
         busyTimeoutMs: options?.busyTimeoutMs,
+        readonly: options?.readonly,
     });
 }
+function openGlobalDevFlowReadOnlyDatabase(home = (0, os_1.homedir)(), options) {
+    return openGlobalDevFlowDatabase(home, { ...options, readonly: true });
+}
+// Schema setup is process-owned. Hook daemons open short-lived connections for
+// bounded transactions, but replaying the full idempotent DDL on every open is
+// still expensive and serializes concurrent host requests. An inode identity
+// keeps the cache safe when a test, repair, or user replaces the database file.
+const initializedDatabaseFiles = new Map();
+function getDatabaseIdentity(path) {
+    try {
+        const stats = (0, fs_1.statSync)(path);
+        return { dev: stats.dev, ino: stats.ino };
+    }
+    catch {
+        return null;
+    }
+}
 class DevFlowDatabase {
     constructor(projectRoot, opts) {
         let dbPath;
         if (opts?.dbPath) {
             const dir = (0, path_1.dirname)(opts.dbPath);
-            if (!(0, fs_1.existsSync)(dir))
+            if (!(0, fs_1.existsSync)(dir) && !opts.readonly)
                 (0, fs_1.mkdirSync)(dir, { recursive: true });
             dbPath = opts.dbPath;
         }
         else {
             const devflowDir = (0, path_1.join)(projectRoot, '.devflow');
-            if (!(0, fs_1.existsSync)(devflowDir))
+            if (!(0, fs_1.existsSync)(devflowDir) && !opts?.readonly)
                 (0, fs_1.mkdirSync)(devflowDir, { recursive: true });
             dbPath = (0, path_1.join)(devflowDir, 'devflow.db');
         }
-        this.db = new node_sqlite_1.NodeSqliteDatabase(dbPath, opts?.busyTimeoutMs);
-        this.db.exec('PRAGMA journal_mode = WAL');
+        if (opts?.readonly && !(0, fs_1.existsSync)(dbPath))
+            throw new Error(`DEVFLOW_DATABASE_NOT_FOUND:${dbPath}`);
+        this.db = new node_sqlite_1.NodeSqliteDatabase(dbPath, opts?.busyTimeoutMs, opts?.readonly === true);
         this.db.exec(`PRAGMA busy_timeout = ${Math.max(0, Math.floor(opts?.busyTimeoutMs ?? 5000))}`);
+        if (opts?.readonly)
+            return;
         this.db.exec('PRAGMA foreign_keys = OFF');
-        this.initializeSchema();
+        const databaseIdentity = getDatabaseIdentity(dbPath);
+        const initializedIdentity = initializedDatabaseFiles.get(dbPath);
+        const schemaInitialized = databaseIdentity !== null
+            && initializedIdentity?.dev === databaseIdentity.dev
+            && initializedIdentity.ino === databaseIdentity.ino;
+        if (!schemaInitialized) {
+            this.initializeSchema();
+            const currentIdentity = getDatabaseIdentity(dbPath);
+            if (currentIdentity)
+                initializedDatabaseFiles.set(dbPath, currentIdentity);
+        }
     }
     initializeSchema() {
         this.db.exec(`
@@ -324,6 +357,9 @@ 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(
@@ -428,6 +464,40 @@ 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,
@@ -581,9 +651,11 @@ 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,
@@ -593,7 +665,11 @@ 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
@@ -603,6 +679,16 @@ 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,
@@ -946,6 +1032,58 @@ class DevFlowDatabase {
             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)');
         // Migration: tool_metrics table for per-tool metrics collection
@@ -1294,14 +1432,20 @@ class DevFlowDatabase {
     }
     getToolCallEventByToolUseId(sessionId, toolUseId) {
         const row = this.db.prepare(`
-      SELECT event_id, timestamp, duration
+      SELECT event_id, execution_id, timestamp, duration, input
       FROM tool_call_events
       WHERE session_id = ? AND tool_use_id = ?
       ORDER BY timestamp DESC
       LIMIT 1
     `).get(sessionId, toolUseId);
         return row
-            ? { eventId: row.event_id, timestamp: row.timestamp, duration: row.duration ?? 0 }
+            ? {
+                eventId: row.event_id,
+                executionId: row.execution_id,
+                timestamp: row.timestamp,
+                duration: row.duration ?? 0,
+                input: parseJsonObject(row.input) ?? {},
+            }
             : null;
     }
     listToolCallEventsBySessions(sessionIds) {
@@ -2374,7 +2518,8 @@ class DevFlowDatabase {
             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');
         }
@@ -2385,10 +2530,10 @@ 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'
@@ -2422,13 +2567,58 @@ class DevFlowDatabase {
           ELSE devflow_work_items.updated_at
         END
       RETURNING *
-    `).get((0, crypto_1.randomUUID)(), input.idempotencyKey, input.kind, input.projectRoot, input.sessionId ?? null, input.turnId ?? null, JSON.stringify(input.payload ?? null), maxAttempts, nextAttemptAt, createdAt, createdAt);
+    `).get((0, crypto_1.randomUUID)(), input.idempotencyKey, input.kind, input.projectRoot, input.sessionId ?? null, input.turnId ?? null, input.sourceHash ?? null, input.taskSpecHash ?? null, JSON.stringify(input.payload ?? null), maxAttempts, nextAttemptAt, createdAt, createdAt);
         return this.mapWorkItem(row);
     }
     getWorkByIdempotencyKey(idempotencyKey) {
         const row = this.db.prepare('SELECT * FROM devflow_work_items WHERE idempotency_key = ?').get(idempotencyKey);
         return row ? this.mapWorkItem(row) : null;
     }
+    getWorkById(id) {
+        const row = this.db.prepare('SELECT * FROM devflow_work_items WHERE id = ?').get(id);
+        return row ? this.mapWorkItem(row) : null;
+    }
+    acquireProjectMutationLease(input) {
+        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, mutationKind, owner) {
+        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) {
+        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, input) {
+        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) {
         if (!input.sessionId.trim())
             throw new Error('Session closure requires a session ID');
@@ -2457,7 +2647,8 @@ class DevFlowDatabase {
         SELECT COUNT(*) AS count
         FROM devflow_work_items
         WHERE project_root = ? AND session_id = ?
-          AND state IN ('pending', 'leased', 'failed', 'dead_letter')
+          AND state IN ('pending', 'leased', 'failed')
+          AND attempts < max_attempts
       `).get(input.projectRoot, input.sessionId);
             const pendingWorkCount = Number(pending?.count ?? 0);
             this.db.prepare(`
@@ -2518,6 +2709,8 @@ class DevFlowDatabase {
         }
         if (input.kinds?.length === 0)
             return [];
+        if (input.workItemIds?.length === 0)
+            return [];
         const now = input.now ?? Date.now();
         const leaseExpiresAt = now + input.leaseMs;
         if (!Number.isSafeInteger(now) || !Number.isSafeInteger(leaseExpiresAt)) {
@@ -2525,9 +2718,13 @@ class DevFlowDatabase {
         }
         const limit = Math.min(Math.floor(input.limit), 1000);
         const kinds = input.kinds ? [...new Set(input.kinds)] : undefined;
+        const workItemIds = input.workItemIds ? [...new Set(input.workItemIds)] : undefined;
         const kindClause = kinds
             ? `AND kind IN (${kinds.map(() => '?').join(', ')})`
             : '';
+        const workItemClause = workItemIds
+            ? `AND id IN (${workItemIds.map(() => '?').join(', ')})`
+            : '';
         this.db.exec('BEGIN IMMEDIATE');
         try {
             const candidates = this.db.prepare(`
@@ -2540,9 +2737,10 @@ class DevFlowDatabase {
           AND next_attempt_at <= ?
           AND attempts < max_attempts
           ${kindClause}
+          ${workItemClause}
         ORDER BY next_attempt_at ASC, created_at ASC, id ASC
         LIMIT ?
-      `).all(input.projectRoot, now, ...(kinds ?? []), limit);
+      `).all(input.projectRoot, now, ...(kinds ?? []), ...(workItemIds ?? []), limit);
             const leased = [];
             for (const candidate of candidates) {
                 const result = this.db.prepare(`
@@ -2672,8 +2870,10 @@ 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,
@@ -2684,6 +2884,10 @@ 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),
         };
     }
     mapSessionClosure(row) {
@@ -2714,28 +2918,11 @@ class DevFlowDatabase {
       SELECT COUNT(*) AS count
       FROM devflow_work_items
       WHERE project_root = ? AND session_id = ?
-        AND state IN ('pending', 'leased', 'failed', 'dead_letter')
+        AND state IN ('pending', 'leased', 'failed')
+        AND attempts < max_attempts
         AND (? IS NULL OR id <> ?)
     `).get(projectRoot, sessionId, excludingWorkItemId ?? null, excludingWorkItemId ?? null);
-        const obligations = this.db.prepare(`
-      SELECT COUNT(*) AS count
-      FROM devflow_session_obligations
-      WHERE project_root = ? AND session_id = ?
-        AND state IN ('open', 'degraded')
-    `).get(projectRoot, sessionId);
-        const legacyTurns = this.db.prepare(`
-      SELECT COUNT(*) AS count
-      FROM devflow_memory_turns t
-      WHERE t.project_root = ? AND t.session_id = ? AND t.status = 'pending'
-        AND NOT EXISTS (
-          SELECT 1 FROM devflow_session_obligations o
-          WHERE o.project_root = t.project_root AND o.session_id = t.session_id
-            AND o.obligation_id = 'memory:' || t.turn_id
-        )
-    `).get(projectRoot, sessionId);
-        return Number(work?.count ?? 0)
-            + Number(obligations?.count ?? 0)
-            + Number(legacyTurns?.count ?? 0);
+        return Number(work?.count ?? 0);
     }
     // ---- Hook Lifecycle ----
     getHookReceipt(projectRoot) {
@@ -3041,6 +3228,33 @@ class DevFlowDatabase {
             requestId: row.request_id ?? undefined,
         } : null;
     }
+    getContextReceiptForRequest(projectRoot, sessionId, requestId) {
+        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);
+        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) {
         return this.db.prepare(`
       INSERT OR IGNORE INTO devflow_context_selection_events
@@ -3061,8 +3275,9 @@ 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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(event.id, event.projectRoot, event.sessionId, event.executionId ?? null, event.turnId ?? null, event.requestId, event.contextReceipt, event.sourceType, event.sourceId, event.stage, event.rank ?? null, event.rawScore ?? null, event.normalizedScore ?? null, event.finalScore ?? null, JSON.stringify(event.applicability), event.reason ?? null, JSON.stringify(event.toolEvidence), event.verificationReceipt ?? null, JSON.stringify(event.payload), event.createdAt).changes > 0;
+        , 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, event.rank ?? null, event.rawScore ?? null, event.normalizedScore ?? null, 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;
     }
     appendTaskIntentArtifact(record) {
         (0, task_semantic_control_1.assertTaskIdentity)(record);
@@ -3252,6 +3467,98 @@ class DevFlowDatabase {
     `).run(record.receiptId, record.projectRoot, record.projectId, record.hostId, record.sessionId, record.turnId, record.requestId, record.executionId ?? null, record.sequence, record.fromState ?? null, record.toState, record.sourceReceiptId ?? null, record.reason, (0, task_semantic_control_1.stableSemanticJson)(record.payload), record.createdAt);
         return this.getTerminalTransition(record.receiptId);
     }
+    appendTaskRuntimeEvent(event) {
+        const existing = this.getTaskRuntimeEvent(event.eventId);
+        if (existing) {
+            if ((0, task_runtime_1.stableTaskRuntimeJson)(existing) !== (0, task_runtime_1.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);
+        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, (0, task_runtime_1.stableTaskRuntimeJson)(event.payload), event.createdAt);
+        }
+        catch (error) {
+            const concurrentEvent = this.getTaskRuntimeEvent(event.eventId);
+            if (concurrentEvent) {
+                if ((0, task_runtime_1.stableTaskRuntimeJson)(concurrentEvent) === (0, task_runtime_1.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) {
+        const row = this.db.prepare('SELECT * FROM devflow_task_runtime_events WHERE event_id = ?')
+            .get(eventId);
+        return row ? (0, task_runtime_1.mapTaskRuntimeEventRow)(row) : null;
+    }
+    listTaskRuntimeEvents(projectRoot, sessionId, turnId) {
+        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)
+            .map(task_runtime_1.mapTaskRuntimeEventRow);
+    }
+    putTaskRuntimeSnapshot(snapshot) {
+        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, (0, task_runtime_1.stableTaskRuntimeJson)(snapshot), snapshot.snapshotHash, snapshot.updatedAt);
+        return this.getTaskRuntimeSnapshot(snapshot.identity.projectRoot, snapshot.identity.sessionId, snapshot.identity.turnId);
+    }
+    appendTaskRuntimeEventAndSnapshot(event, snapshot) {
+        return this.db.transaction(() => {
+            this.appendTaskRuntimeEvent(event);
+            return this.putTaskRuntimeSnapshot(snapshot);
+        });
+    }
+    getTaskRuntimeSnapshot(projectRoot, sessionId, turnId) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_task_runtime_snapshots
+      WHERE project_root = ? AND session_id = ? AND turn_id = ?
+    `).get(projectRoot, sessionId, turnId);
+        return row ? (0, task_runtime_1.mapTaskRuntimeSnapshotRow)(row) : null;
+    }
+    deleteTaskRuntimeSnapshot(projectRoot, sessionId, turnId) {
+        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) {
         const row = this.db.prepare(`
       SELECT * FROM devflow_terminal_transitions WHERE receipt_id = ?
@@ -3307,7 +3614,11 @@ 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,
@@ -3459,6 +3770,15 @@ class DevFlowDatabase {
             if (!existing)
                 throw new Error(`Session obligation ${input.obligationId} does not exist`);
             if (existing.state !== 'open') {
+                if (existing.state === 'degraded' && input.state === 'satisfied' && input.receiptId) {
+                    const resolvedAt = input.resolvedAt ?? Date.now();
+                    this.db.prepare(`
+            UPDATE devflow_session_obligations
+            SET state = 'satisfied', receipt_id = ?, reason = ?, resolved_at = ?, updated_at = ?
+            WHERE project_root = ? AND session_id = ? AND obligation_id = ? AND state = 'degraded'
+          `).run(input.receiptId, input.reason ?? 'superseded_by_corrected_evidence', resolvedAt, resolvedAt, input.projectRoot, input.sessionId, input.obligationId);
+                    return this.getSessionObligation(input.projectRoot, input.sessionId, input.obligationId);
+                }
                 const sameResolution = existing.state === input.state
                     && (input.receiptId === undefined || existing.receiptId === input.receiptId);
                 if (sameResolution)
@@ -3517,14 +3837,27 @@ class DevFlowDatabase {
         });
         return turn;
     }
+    updateCommittedMemoryTurnProjection(input) {
+        const turnId = (0, obligation_ledger_1.normalizeTurnId)(input.turnId);
+        this.db.prepare(`
+      UPDATE devflow_memory_turns
+      SET memory_ids = ?, reason = COALESCE(?, reason)
+      WHERE turn_id = ? AND status = 'committed' AND source = 'explicit_intent'
+    `).run(JSON.stringify([...new Set(input.memoryIds)]), input.reason ?? null, turnId);
+        const turn = this.getMemoryTurn(turnId);
+        if (!turn || turn.status !== 'committed') {
+            throw new Error(`Committed explicit memory turn ${turnId} does not exist`);
+        }
+        return turn;
+    }
     skipMemoryTurn(input) {
         const turnId = (0, obligation_ledger_1.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.reason, input.decidedAt ?? Date.now(), turnId);
+    `).run(input.receiptId, input.source ?? 'host_skip', input.reason, input.decidedAt ?? Date.now(), turnId);
         const turn = this.getMemoryTurn(turnId);
         if (!turn || turn.status !== 'skipped') {
             throw new Error(`Memory turn ${turnId} is not pending or does not exist`);

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export { DevFlowDatabase, getGlobalDevFlowDbPath, openGlobalDevFlowDatabase, } from './database';
+export { DevFlowDatabase, getGlobalDevFlowDbPath, openGlobalDevFlowDatabase, openGlobalDevFlowReadOnlyDatabase, } from './database';
 export type { BenchmarkReportMetaRecord, BenchmarkReportRecord, FeedbackRecord, GovernanceAuditRecord, GovernanceRuleRecord, HookFallbackRecord, HookReceiptRecord, ContextReceiptRecord, ContextSelectionEventRecord, PolicyVerificationBaselineRecord, MemoryDistillCheckpointRecord, MemoryTurnRecord, MemoryTurnStatus, TelemetryFailureRecord, } from './database';
-export type { EnqueueWorkInput, LeaseWorkInput, RequestSessionClosureInput, SessionClosureRecord, SessionClosureState, WorkError, WorkItemRecord, WorkKind, WorkQueueHealth, WorkState, } from './work-queue';
+export type { EnqueueWorkInput, LeaseWorkInput, RequestSessionClosureInput, SessionClosureRecord, SessionClosureState, WorkError, WorkItemRecord, WorkKind, WorkQueueHealth, WorkState, ProjectMutationLeaseRecord, } from './work-queue';
 export type { RetrievalLedgerEventRecord, RetrievalLedgerSourceType, RetrievalLedgerStage, } from './retrieval-ledger';
 export { hostActionReportsEqual, isHostActionState, mapHostActionRow, serializeHostActionReport, } from './host-actions';
 export { RETRIEVAL_MAX_CYCLES, isRetrievalSessionState } from './retrieval-sessions';
@@ -8,6 +8,8 @@ export type { AppendRetrievalCycleInput, CreateRetrievalSessionInput, RetrievalC
 export type { FailHostActionInput, HostActionRecord, HostActionState, ReportHostActionInput, RequestHostActionInput, StartHostActionInput, VerifyHostActionInput, } from './host-actions';
 export { mapSessionObligationRow, normalizeTurnId, } from './obligation-ledger';
 export { assertTaskIdentity, mapChannelQueryPlanRow, mapTaskIntentArtifactRow, mapTerminalTransitionRow, mapToolNameResolutionRow, 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, TaskIntentArtifactRecord, TerminalTransitionRecord, ToolNameResolutionRecord, ToolNameResolutionStatus, TranscriptCheckpointRecord, } from './task-semantic-control';
 export { LEGAL_WORKFLOW_WORKER_TRANSITIONS, TERMINAL_WORKFLOW_WORKER_STATES, mapWorkflowMergeRow, mapWorkflowWorkerEventRow, mapWorkflowWorkerRow, } from './workflow-workers';
 export type { CreateWorkflowWorkerInput, EnqueueWorkflowMergeInput, TransitionWorkflowWorkerInput, WorkflowMergeRecord, WorkflowMergeState, WorkflowWorkerEventRecord, WorkflowWorkerRecord, WorkflowWorkerState, } from './workflow-workers';