@devflow-tools/database 0.17.0 → 0.17.2

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");
@@ -13,6 +14,7 @@ const host_actions_1 = require("./host-actions");
 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 CONTEXT_REQUIRED_SKILLS = new Set([
     'react', 'vue', 'nest', 'nextjs', 'graphql', 'typescript',
 ]);
@@ -61,28 +63,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(`
@@ -329,6 +362,119 @@ class DevFlowDatabase {
         project_root, session_id, execution_id, request_id, context_receipt, source_type, source_id, created_at
       );
 
+      CREATE TABLE IF NOT EXISTS devflow_task_intent_artifacts (
+        artifact_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,
+        execution_id TEXT,
+        version INTEGER NOT NULL CHECK(version > 0),
+        supersedes_hash TEXT,
+        raw_prompt TEXT NOT NULL,
+        normalized_prompt TEXT NOT NULL,
+        command TEXT,
+        slash_args_json TEXT NOT NULL DEFAULT '[]',
+        active_skill TEXT,
+        intent TEXT NOT NULL,
+        action TEXT NOT NULL,
+        entities_json TEXT NOT NULL DEFAULT '[]',
+        target_anchors_json TEXT NOT NULL DEFAULT '[]',
+        policy_constraints_json TEXT NOT NULL DEFAULT '[]',
+        classification_evidence_json TEXT NOT NULL DEFAULT '[]',
+        source_event_ids_json TEXT NOT NULL DEFAULT '[]',
+        source_hash TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        UNIQUE(project_root, session_id, turn_id, version),
+        UNIQUE(project_root, session_id, request_id, version)
+      );
+      CREATE INDEX IF NOT EXISTS idx_task_intent_active
+        ON devflow_task_intent_artifacts(project_root, session_id, turn_id, version DESC);
+      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_channel_query_plans (
+        plan_hash TEXT PRIMARY KEY,
+        source_intent_hash 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,
+        code_queries_json TEXT NOT NULL DEFAULT '[]',
+        memory_queries_json TEXT NOT NULL DEFAULT '[]',
+        knowledge_queries_json TEXT NOT NULL DEFAULT '[]',
+        generated_by TEXT NOT NULL
+          CHECK(generated_by IN ('deterministic', 'host_semantic', 'hybrid')),
+        degradation_json TEXT,
+        created_at INTEGER NOT NULL,
+        UNIQUE(project_root, session_id, turn_id, source_intent_hash)
+      );
+      CREATE INDEX IF NOT EXISTS idx_channel_query_plan_request
+        ON devflow_channel_query_plans(project_root, session_id, request_id, created_at DESC);
+
+      CREATE TABLE IF NOT EXISTS devflow_tool_name_resolutions (
+        id TEXT PRIMARY KEY,
+        source_hash TEXT NOT NULL UNIQUE,
+        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,
+        requested_name TEXT NOT NULL,
+        canonical_name TEXT,
+        projected_name TEXT,
+        status TEXT NOT NULL CHECK(status IN ('canonical', 'alias', 'unsupported')),
+        attempt INTEGER NOT NULL CHECK(attempt >= 0),
+        capability_mechanism TEXT,
+        reason TEXT,
+        created_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_tool_resolution_request
+        ON devflow_tool_name_resolutions(project_root, session_id, request_id, created_at);
+
+      CREATE TABLE IF NOT EXISTS devflow_terminal_transitions (
+        receipt_id 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,
+        execution_id TEXT,
+        sequence INTEGER NOT NULL CHECK(sequence > 0),
+        from_state TEXT,
+        to_state TEXT NOT NULL,
+        source_receipt_id TEXT,
+        reason 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_terminal_transition_turn
+        ON devflow_terminal_transitions(project_root, session_id, turn_id, sequence);
+
+      CREATE TABLE IF NOT EXISTS devflow_transcript_checkpoints (
+        id TEXT PRIMARY KEY,
+        project_root TEXT NOT NULL,
+        host_id TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        source_path TEXT NOT NULL,
+        source_hash TEXT NOT NULL,
+        byte_offset INTEGER NOT NULL CHECK(byte_offset >= 0),
+        event_count INTEGER NOT NULL CHECK(event_count >= 0),
+        created_at INTEGER NOT NULL,
+        UNIQUE(project_root, host_id, session_id, source_path, source_hash)
+      );
+      CREATE INDEX IF NOT EXISTS idx_transcript_checkpoint_latest
+        ON devflow_transcript_checkpoints(project_root, host_id, session_id, source_path, created_at DESC);
+
       CREATE TABLE IF NOT EXISTS devflow_policy_verification_baselines (
         project_root TEXT NOT NULL,
         kind TEXT NOT NULL,
@@ -1180,14 +1326,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) {
@@ -2343,7 +2495,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(`
@@ -2404,6 +2557,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)) {
@@ -2411,9 +2566,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(`
@@ -2426,9 +2585,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(`
@@ -2600,28 +2760,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) {
@@ -2950,6 +3093,232 @@ class DevFlowDatabase {
       ) 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;
     }
+    appendTaskIntentArtifact(record) {
+        (0, task_semantic_control_1.assertTaskIdentity)(record);
+        if (!Number.isSafeInteger(record.version) || record.version <= 0) {
+            throw new Error('TASK_INTENT_INVALID_VERSION');
+        }
+        const existingByHash = this.getTaskIntentArtifact(record.artifactHash);
+        if (existingByHash) {
+            if ((0, task_semantic_control_1.stableSemanticJson)(existingByHash) !== (0, task_semantic_control_1.stableSemanticJson)(record)) {
+                throw new Error(`TASK_INTENT_HASH_CONFLICT:${record.artifactHash}`);
+            }
+            return existingByHash;
+        }
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const conflicting = this.db.prepare(`
+        SELECT * FROM devflow_task_intent_artifacts
+        WHERE project_root = ? AND session_id = ? AND turn_id = ? AND version = ?
+      `).get(record.projectRoot, record.sessionId, record.turnId, record.version);
+            if (conflicting)
+                throw new Error(`TASK_INTENT_VERSION_CONFLICT:${record.turnId}:${record.version}`);
+            if (record.supersedesHash && !this.getTaskIntentArtifact(record.supersedesHash)) {
+                throw new Error(`TASK_INTENT_SUPERSEDED_NOT_FOUND:${record.supersedesHash}`);
+            }
+            this.db.prepare(`
+        INSERT INTO devflow_task_intent_artifacts (
+          artifact_hash, project_root, project_id, host_id, session_id, turn_id, request_id,
+          execution_id, version, supersedes_hash, raw_prompt, normalized_prompt, command,
+          slash_args_json, active_skill, intent, action, entities_json, target_anchors_json,
+          policy_constraints_json, classification_evidence_json, source_event_ids_json,
+          source_hash, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(record.artifactHash, record.projectRoot, record.projectId, record.hostId, record.sessionId, record.turnId, record.requestId, record.executionId ?? null, record.version, record.supersedesHash ?? null, record.rawPrompt, record.normalizedPrompt, record.command ?? null, (0, task_semantic_control_1.stableSemanticJson)(record.slashArgs), record.activeSkill ?? null, record.intent, record.action, (0, task_semantic_control_1.stableSemanticJson)(record.entities), (0, task_semantic_control_1.stableSemanticJson)(record.targetAnchors), (0, task_semantic_control_1.stableSemanticJson)(record.policyConstraints), (0, task_semantic_control_1.stableSemanticJson)(record.classificationEvidence), (0, task_semantic_control_1.stableSemanticJson)(record.sourceEventIds), record.sourceHash, record.createdAt);
+            const created = this.getTaskIntentArtifact(record.artifactHash);
+            this.db.exec('COMMIT');
+            return created;
+        }
+        catch (error) {
+            try {
+                this.db.exec('ROLLBACK');
+            }
+            catch { }
+            throw error;
+        }
+    }
+    getTaskIntentArtifact(artifactHash) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_task_intent_artifacts WHERE artifact_hash = ?
+    `).get(artifactHash);
+        return row ? (0, task_semantic_control_1.mapTaskIntentArtifactRow)(row) : null;
+    }
+    getLatestTaskIntentArtifact(input) {
+        if (!input.turnId && !input.requestId)
+            throw new Error('TASK_INTENT_LOOKUP_IDENTITY_REQUIRED');
+        const predicates = ['project_root = ?', 'session_id = ?'];
+        const params = [input.projectRoot, input.sessionId];
+        if (input.turnId) {
+            predicates.push('turn_id = ?');
+            params.push(input.turnId);
+        }
+        if (input.requestId) {
+            predicates.push('request_id = ?');
+            params.push(input.requestId);
+        }
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_task_intent_artifacts
+      WHERE ${predicates.join(' AND ')} ORDER BY version DESC, created_at DESC LIMIT 1
+    `).get(...params);
+        return row ? (0, task_semantic_control_1.mapTaskIntentArtifactRow)(row) : null;
+    }
+    getTaskIntentArtifactBySource(input) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_task_intent_artifacts
+      WHERE project_root = ? AND session_id = ? AND source_hash = ?
+      ORDER BY version DESC, created_at DESC LIMIT 1
+    `).get(input.projectRoot, input.sessionId, input.sourceHash);
+        return row ? (0, task_semantic_control_1.mapTaskIntentArtifactRow)(row) : null;
+    }
+    listLatestTaskIntentArtifacts(projectRoot, sessionId) {
+        return this.db.prepare(`
+      SELECT artifact.* FROM devflow_task_intent_artifacts artifact
+      JOIN (
+        SELECT turn_id, MAX(version) AS version
+        FROM devflow_task_intent_artifacts
+        WHERE project_root = ? AND session_id = ? GROUP BY turn_id
+      ) latest ON latest.turn_id = artifact.turn_id AND latest.version = artifact.version
+      WHERE artifact.project_root = ? AND artifact.session_id = ?
+      ORDER BY artifact.created_at ASC, artifact.turn_id ASC
+    `).all(projectRoot, sessionId, projectRoot, sessionId)
+            .map(task_semantic_control_1.mapTaskIntentArtifactRow);
+    }
+    appendChannelQueryPlan(record) {
+        (0, task_semantic_control_1.assertTaskIdentity)(record);
+        const source = this.getTaskIntentArtifact(record.sourceIntentHash);
+        if (!source)
+            throw new Error(`QUERY_PLAN_INTENT_NOT_FOUND:${record.sourceIntentHash}`);
+        if (!sameTaskIdentity(source, record))
+            throw new Error('QUERY_PLAN_IDENTITY_MISMATCH');
+        const existing = this.getChannelQueryPlan(record.planHash);
+        if (existing) {
+            if ((0, task_semantic_control_1.stableSemanticJson)(existing) !== (0, task_semantic_control_1.stableSemanticJson)(record)) {
+                throw new Error(`QUERY_PLAN_HASH_CONFLICT:${record.planHash}`);
+            }
+            return existing;
+        }
+        try {
+            this.db.prepare(`
+        INSERT INTO devflow_channel_query_plans (
+          plan_hash, source_intent_hash, project_root, project_id, host_id, session_id,
+          turn_id, request_id, execution_id, code_queries_json, memory_queries_json,
+          knowledge_queries_json, generated_by, degradation_json, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(record.planHash, record.sourceIntentHash, record.projectRoot, record.projectId, record.hostId, record.sessionId, record.turnId, record.requestId, record.executionId ?? null, (0, task_semantic_control_1.stableSemanticJson)(record.code), (0, task_semantic_control_1.stableSemanticJson)(record.memory), (0, task_semantic_control_1.stableSemanticJson)(record.knowledge), record.generatedBy, record.degradation ? (0, task_semantic_control_1.stableSemanticJson)(record.degradation) : null, record.createdAt);
+        }
+        catch (error) {
+            if (String(error).includes('UNIQUE constraint failed')) {
+                throw new Error(`QUERY_PLAN_SOURCE_CONFLICT:${record.sourceIntentHash}`);
+            }
+            throw error;
+        }
+        return this.getChannelQueryPlan(record.planHash);
+    }
+    getChannelQueryPlan(planHash) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_channel_query_plans WHERE plan_hash = ?
+    `).get(planHash);
+        return row ? (0, task_semantic_control_1.mapChannelQueryPlanRow)(row) : null;
+    }
+    getChannelQueryPlanForIntent(input) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_channel_query_plans
+      WHERE project_root = ? AND session_id = ? AND turn_id = ? AND source_intent_hash = ?
+      ORDER BY created_at DESC LIMIT 1
+    `).get(input.projectRoot, input.sessionId, input.turnId, input.sourceIntentHash);
+        return row ? (0, task_semantic_control_1.mapChannelQueryPlanRow)(row) : null;
+    }
+    appendToolNameResolution(record) {
+        (0, task_semantic_control_1.assertTaskIdentity)(record);
+        if (!Number.isSafeInteger(record.attempt) || record.attempt < 0) {
+            throw new Error('TOOL_RESOLUTION_INVALID_ATTEMPT');
+        }
+        return this.db.prepare(`
+      INSERT OR IGNORE INTO devflow_tool_name_resolutions (
+        id, source_hash, project_root, project_id, host_id, session_id, turn_id,
+        request_id, execution_id, requested_name, canonical_name, projected_name,
+        status, attempt, capability_mechanism, reason, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(record.id, record.sourceHash, record.projectRoot, record.projectId, record.hostId, record.sessionId, record.turnId, record.requestId, record.executionId ?? null, record.requestedName, record.canonicalName ?? null, record.projectedName ?? null, record.status, record.attempt, record.capabilityMechanism ?? null, record.reason ?? null, record.createdAt).changes > 0;
+    }
+    listToolNameResolutions(input) {
+        const predicates = ['project_root = ?', 'session_id = ?'];
+        const params = [input.projectRoot, input.sessionId];
+        if (input.requestId) {
+            predicates.push('request_id = ?');
+            params.push(input.requestId);
+        }
+        return this.db.prepare(`
+      SELECT * FROM devflow_tool_name_resolutions WHERE ${predicates.join(' AND ')}
+      ORDER BY created_at ASC, attempt ASC, id ASC
+    `).all(...params).map(task_semantic_control_1.mapToolNameResolutionRow);
+    }
+    appendTerminalTransition(record) {
+        (0, task_semantic_control_1.assertTaskIdentity)(record);
+        if (!Number.isSafeInteger(record.sequence) || record.sequence <= 0) {
+            throw new Error('TERMINAL_TRANSITION_INVALID_SEQUENCE');
+        }
+        const existing = this.getTerminalTransition(record.receiptId);
+        if (existing) {
+            if ((0, task_semantic_control_1.stableSemanticJson)(existing) !== (0, task_semantic_control_1.stableSemanticJson)(record)) {
+                throw new Error(`TERMINAL_RECEIPT_CONFLICT:${record.receiptId}`);
+            }
+            return existing;
+        }
+        const latest = this.getLatestTerminalTransition(record.projectRoot, record.sessionId, record.turnId);
+        if (record.sequence !== (latest?.sequence ?? 0) + 1) {
+            throw new Error(`TERMINAL_TRANSITION_SEQUENCE:${latest?.sequence ?? 0}->${record.sequence}`);
+        }
+        if ((latest?.toState ?? undefined) !== record.fromState) {
+            throw new Error(`TERMINAL_TRANSITION_FROM_MISMATCH:${record.fromState ?? 'none'}`);
+        }
+        this.db.prepare(`
+      INSERT INTO devflow_terminal_transitions (
+        receipt_id, project_root, project_id, host_id, session_id, turn_id, request_id,
+        execution_id, sequence, from_state, to_state, source_receipt_id, reason,
+        payload_json, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).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);
+    }
+    getTerminalTransition(receiptId) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_terminal_transitions WHERE receipt_id = ?
+    `).get(receiptId);
+        return row ? (0, task_semantic_control_1.mapTerminalTransitionRow)(row) : null;
+    }
+    getLatestTerminalTransition(projectRoot, sessionId, turnId) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_terminal_transitions
+      WHERE project_root = ? AND session_id = ? AND turn_id = ?
+      ORDER BY sequence DESC LIMIT 1
+    `).get(projectRoot, sessionId, turnId);
+        return row ? (0, task_semantic_control_1.mapTerminalTransitionRow)(row) : null;
+    }
+    appendTranscriptCheckpoint(record) {
+        if (!record.id || !record.projectRoot || !record.hostId || !record.sessionId
+            || !record.sourcePath || !record.sourceHash) {
+            throw new Error('TRANSCRIPT_CHECKPOINT_INVALID_IDENTITY');
+        }
+        if (!Number.isSafeInteger(record.byteOffset) || record.byteOffset < 0
+            || !Number.isSafeInteger(record.eventCount) || record.eventCount < 0) {
+            throw new Error('TRANSCRIPT_CHECKPOINT_INVALID_POSITION');
+        }
+        return this.db.prepare(`
+      INSERT OR IGNORE INTO devflow_transcript_checkpoints (
+        id, project_root, host_id, session_id, source_path, source_hash,
+        byte_offset, event_count, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(record.id, record.projectRoot, record.hostId, record.sessionId, record.sourcePath, record.sourceHash, record.byteOffset, record.eventCount, record.createdAt).changes > 0;
+    }
+    getLatestTranscriptCheckpoint(input) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_transcript_checkpoints
+      WHERE project_root = ? AND host_id = ? AND session_id = ? AND source_path = ?
+      ORDER BY created_at DESC, byte_offset DESC LIMIT 1
+    `).get(input.projectRoot, input.hostId, input.sessionId, input.sourcePath);
+        return row ? (0, task_semantic_control_1.mapTranscriptCheckpointRow)(row) : null;
+    }
     listRetrievalLedgerEvents(options) {
         const predicates = ['project_root = ?'];
         const params = [options.projectRoot];
@@ -3119,6 +3488,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)
@@ -3177,6 +3555,19 @@ 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(`
@@ -3922,3 +4313,12 @@ function canonicalWorkflowProjectRoot(projectRoot) {
         return resolved;
     }
 }
+function sameTaskIdentity(left, right) {
+    return left.projectRoot === right.projectRoot
+        && left.projectId === right.projectId
+        && left.hostId === right.hostId
+        && left.sessionId === right.sessionId
+        && left.turnId === right.turnId
+        && left.requestId === right.requestId
+        && left.executionId === right.executionId;
+}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-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 { RetrievalLedgerEventRecord, RetrievalLedgerSourceType, RetrievalLedgerStage, } from './retrieval-ledger';
@@ -7,6 +7,8 @@ export { RETRIEVAL_MAX_CYCLES, isRetrievalSessionState } from './retrieval-sessi
 export type { AppendRetrievalCycleInput, CreateRetrievalSessionInput, RetrievalCycleRecord, RetrievalGapKind, RetrievalGapRecord, RetrievalSessionRecord, RetrievalSessionState, } from './retrieval-sessions';
 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 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';
 export { mapLearningCandidateRow, mapLearningEvidenceRow, mapLearningVersionRow, stableLearningJson, } from './learning-candidates';

package/dist/index.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stableLearningJson = exports.mapLearningVersionRow = exports.mapLearningEvidenceRow = exports.mapLearningCandidateRow = exports.mapWorkflowWorkerRow = exports.mapWorkflowWorkerEventRow = exports.mapWorkflowMergeRow = exports.TERMINAL_WORKFLOW_WORKER_STATES = exports.LEGAL_WORKFLOW_WORKER_TRANSITIONS = exports.normalizeTurnId = exports.mapSessionObligationRow = exports.isRetrievalSessionState = exports.RETRIEVAL_MAX_CYCLES = exports.serializeHostActionReport = exports.mapHostActionRow = exports.isHostActionState = exports.hostActionReportsEqual = exports.openGlobalDevFlowDatabase = exports.getGlobalDevFlowDbPath = exports.DevFlowDatabase = void 0;
+exports.stableLearningJson = exports.mapLearningVersionRow = exports.mapLearningEvidenceRow = exports.mapLearningCandidateRow = exports.mapWorkflowWorkerRow = exports.mapWorkflowWorkerEventRow = exports.mapWorkflowMergeRow = exports.TERMINAL_WORKFLOW_WORKER_STATES = exports.LEGAL_WORKFLOW_WORKER_TRANSITIONS = exports.stableSemanticJson = exports.mapTranscriptCheckpointRow = exports.mapToolNameResolutionRow = exports.mapTerminalTransitionRow = exports.mapTaskIntentArtifactRow = exports.mapChannelQueryPlanRow = exports.assertTaskIdentity = exports.normalizeTurnId = exports.mapSessionObligationRow = exports.isRetrievalSessionState = exports.RETRIEVAL_MAX_CYCLES = exports.serializeHostActionReport = exports.mapHostActionRow = exports.isHostActionState = exports.hostActionReportsEqual = exports.openGlobalDevFlowReadOnlyDatabase = exports.openGlobalDevFlowDatabase = exports.getGlobalDevFlowDbPath = exports.DevFlowDatabase = void 0;
 var database_1 = require("./database");
 Object.defineProperty(exports, "DevFlowDatabase", { enumerable: true, get: function () { return database_1.DevFlowDatabase; } });
 Object.defineProperty(exports, "getGlobalDevFlowDbPath", { enumerable: true, get: function () { return database_1.getGlobalDevFlowDbPath; } });
 Object.defineProperty(exports, "openGlobalDevFlowDatabase", { enumerable: true, get: function () { return database_1.openGlobalDevFlowDatabase; } });
+Object.defineProperty(exports, "openGlobalDevFlowReadOnlyDatabase", { enumerable: true, get: function () { return database_1.openGlobalDevFlowReadOnlyDatabase; } });
 var host_actions_1 = require("./host-actions");
 Object.defineProperty(exports, "hostActionReportsEqual", { enumerable: true, get: function () { return host_actions_1.hostActionReportsEqual; } });
 Object.defineProperty(exports, "isHostActionState", { enumerable: true, get: function () { return host_actions_1.isHostActionState; } });
@@ -16,6 +17,14 @@ Object.defineProperty(exports, "isRetrievalSessionState", { enumerable: true, ge
 var obligation_ledger_1 = require("./obligation-ledger");
 Object.defineProperty(exports, "mapSessionObligationRow", { enumerable: true, get: function () { return obligation_ledger_1.mapSessionObligationRow; } });
 Object.defineProperty(exports, "normalizeTurnId", { enumerable: true, get: function () { return obligation_ledger_1.normalizeTurnId; } });
+var task_semantic_control_1 = require("./task-semantic-control");
+Object.defineProperty(exports, "assertTaskIdentity", { enumerable: true, get: function () { return task_semantic_control_1.assertTaskIdentity; } });
+Object.defineProperty(exports, "mapChannelQueryPlanRow", { enumerable: true, get: function () { return task_semantic_control_1.mapChannelQueryPlanRow; } });
+Object.defineProperty(exports, "mapTaskIntentArtifactRow", { enumerable: true, get: function () { return task_semantic_control_1.mapTaskIntentArtifactRow; } });
+Object.defineProperty(exports, "mapTerminalTransitionRow", { enumerable: true, get: function () { return task_semantic_control_1.mapTerminalTransitionRow; } });
+Object.defineProperty(exports, "mapToolNameResolutionRow", { enumerable: true, get: function () { return task_semantic_control_1.mapToolNameResolutionRow; } });
+Object.defineProperty(exports, "mapTranscriptCheckpointRow", { enumerable: true, get: function () { return task_semantic_control_1.mapTranscriptCheckpointRow; } });
+Object.defineProperty(exports, "stableSemanticJson", { enumerable: true, get: function () { return task_semantic_control_1.stableSemanticJson; } });
 var workflow_workers_1 = require("./workflow-workers");
 Object.defineProperty(exports, "LEGAL_WORKFLOW_WORKER_TRANSITIONS", { enumerable: true, get: function () { return workflow_workers_1.LEGAL_WORKFLOW_WORKER_TRANSITIONS; } });
 Object.defineProperty(exports, "TERMINAL_WORKFLOW_WORKER_STATES", { enumerable: true, get: function () { return workflow_workers_1.TERMINAL_WORKFLOW_WORKER_STATES; } });

package/dist/node-sqlite.d.ts

@@ -1,7 +1,7 @@
 import type { Database, Statement } from './types';
 export declare class NodeSqliteDatabase implements Database {
     private db;
-    constructor(path: string, busyTimeoutMs?: number);
+    constructor(path: string, busyTimeoutMs?: number, readOnly?: boolean);
     exec(sql: string): void;
     prepare(sql: string): Statement;
     transaction<T>(fn: () => T): T;

package/dist/node-sqlite.js

@@ -3,11 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.NodeSqliteDatabase = void 0;
 const node_sqlite_1 = require("node:sqlite");
 class NodeSqliteDatabase {
-    constructor(path, busyTimeoutMs = 10000) {
-        this.db = new node_sqlite_1.DatabaseSync(path);
+    constructor(path, busyTimeoutMs = 10000, readOnly = false) {
+        this.db = readOnly
+            ? new node_sqlite_1.DatabaseSync(path, { readOnly: true })
+            : new node_sqlite_1.DatabaseSync(path);
         this.db.exec(`PRAGMA busy_timeout = ${Math.max(0, Math.floor(busyTimeoutMs))}`);
-        this.db.exec('PRAGMA journal_mode = WAL');
-        this.db.exec('PRAGMA synchronous = NORMAL');
+        if (!readOnly) {
+            this.db.exec('PRAGMA journal_mode = WAL');
+            this.db.exec('PRAGMA synchronous = NORMAL');
+        }
     }
     exec(sql) {
         this.db.exec(sql);