@devflow-tools/database 0.17.2 → 0.17.4

package/dist/database.js

@@ -15,6 +15,8 @@ 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 semantic_resolution_1 = require("./semantic-resolution");
 const CONTEXT_REQUIRED_SKILLS = new Set([
     'react', 'vue', 'nest', 'nextjs', 'graphql', 'typescript',
 ]);
@@ -356,6 +358,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(
@@ -395,6 +400,35 @@ class DevFlowDatabase {
       CREATE UNIQUE INDEX IF NOT EXISTS idx_task_intent_source
         ON devflow_task_intent_artifacts(project_root, session_id, source_hash, version);
 
+      CREATE TABLE IF NOT EXISTS devflow_semantic_resolutions (
+        frame_hash TEXT PRIMARY KEY,
+        project_root TEXT NOT NULL,
+        project_id TEXT NOT NULL,
+        host_id TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        turn_id TEXT NOT NULL,
+        request_id TEXT NOT NULL,
+        source_hash TEXT NOT NULL,
+        artifact_hash TEXT NOT NULL,
+        artifact_revision INTEGER NOT NULL CHECK(artifact_revision > 0),
+        supersedes_frame_hash TEXT,
+        state TEXT NOT NULL CHECK(state IN ('provisional', 'resolved', 'abstained', 'unavailable')),
+        generated_by TEXT NOT NULL CHECK(generated_by IN ('deterministic', 'embedding_router', 'host_semantic', 'hybrid')),
+        model_id TEXT,
+        model_revision TEXT,
+        route_catalog_version TEXT NOT NULL,
+        threshold_version TEXT NOT NULL,
+        route_json TEXT NOT NULL,
+        sampling_json TEXT NOT NULL,
+        conflicts_json TEXT NOT NULL,
+        frame_json TEXT NOT NULL,
+        duration_ms INTEGER NOT NULL CHECK(duration_ms >= 0),
+        created_at INTEGER NOT NULL,
+        UNIQUE(project_root, session_id, turn_id, artifact_revision)
+      );
+      CREATE INDEX IF NOT EXISTS idx_semantic_resolution_latest
+        ON devflow_semantic_resolutions(project_root, session_id, turn_id, artifact_revision DESC);
+
       CREATE TABLE IF NOT EXISTS devflow_channel_query_plans (
         plan_hash TEXT PRIMARY KEY,
         source_intent_hash TEXT NOT NULL,
@@ -460,6 +494,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,
@@ -613,9 +681,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,
@@ -625,7 +695,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
@@ -635,6 +709,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,
@@ -978,6 +1062,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
@@ -2412,7 +2548,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');
         }
@@ -2423,10 +2560,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'
@@ -2460,13 +2597,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');
@@ -2718,8 +2900,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,
@@ -2730,6 +2914,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) {
@@ -3070,6 +3258,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
@@ -3090,8 +3305,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);
@@ -3170,6 +3386,77 @@ class DevFlowDatabase {
     `).get(input.projectRoot, input.sessionId, input.sourceHash);
         return row ? (0, task_semantic_control_1.mapTaskIntentArtifactRow)(row) : null;
     }
+    appendSemanticResolution(record) {
+        (0, semantic_resolution_1.assertSemanticResolutionRecord)(record);
+        const existing = this.getSemanticResolution(record.frameHash);
+        if (existing) {
+            if ((0, semantic_resolution_1.stableSemanticResolutionJson)(existing) !== (0, semantic_resolution_1.stableSemanticResolutionJson)(record)) {
+                throw new Error(`SEMANTIC_RESOLUTION_HASH_CONFLICT:${record.frameHash}`);
+            }
+            return false;
+        }
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const conflicting = this.db.prepare(`
+        SELECT frame_hash FROM devflow_semantic_resolutions
+        WHERE project_root = ? AND session_id = ? AND turn_id = ? AND artifact_revision = ?
+      `).get(record.projectRoot, record.sessionId, record.turnId, record.artifactRevision);
+            if (conflicting) {
+                throw new Error(`SEMANTIC_RESOLUTION_REVISION_CONFLICT:${record.turnId}:${record.artifactRevision}`);
+            }
+            if (record.supersedesFrameHash) {
+                const superseded = this.getSemanticResolution(record.supersedesFrameHash);
+                if (!superseded) {
+                    throw new Error(`SEMANTIC_RESOLUTION_SUPERSEDED_NOT_FOUND:${record.supersedesFrameHash}`);
+                }
+                if (superseded.projectRoot !== record.projectRoot
+                    || superseded.sessionId !== record.sessionId
+                    || superseded.turnId !== record.turnId
+                    || superseded.artifactRevision >= record.artifactRevision) {
+                    throw new Error('SEMANTIC_RESOLUTION_SUPERSEDES_INVALID');
+                }
+            }
+            this.db.prepare(`
+        INSERT INTO devflow_semantic_resolutions (
+          frame_hash, project_root, project_id, host_id, session_id, turn_id, request_id,
+          source_hash, artifact_hash, artifact_revision, supersedes_frame_hash, state,
+          generated_by, model_id, model_revision, route_catalog_version, threshold_version,
+          route_json, sampling_json, conflicts_json, frame_json, duration_ms, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(record.frameHash, record.projectRoot, record.projectId, record.hostId, record.sessionId, record.turnId, record.requestId, record.sourceHash, record.artifactHash, record.artifactRevision, record.supersedesFrameHash ?? null, record.state, record.generatedBy, record.modelId ?? null, record.modelRevision ?? null, record.routeCatalogVersion, record.thresholdVersion, (0, semantic_resolution_1.stableSemanticResolutionJson)(record.route), (0, semantic_resolution_1.stableSemanticResolutionJson)(record.sampling), (0, semantic_resolution_1.stableSemanticResolutionJson)(record.conflicts), (0, semantic_resolution_1.stableSemanticResolutionJson)(record.frame), record.durationMs, record.createdAt);
+            this.db.exec('COMMIT');
+            return true;
+        }
+        catch (error) {
+            try {
+                this.db.exec('ROLLBACK');
+            }
+            catch { }
+            throw error;
+        }
+    }
+    getSemanticResolution(frameHash) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_semantic_resolutions WHERE frame_hash = ?
+    `).get(frameHash);
+        return row ? (0, semantic_resolution_1.mapSemanticResolutionRow)(row) : null;
+    }
+    getLatestSemanticResolution(projectRoot, sessionId, turnId) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_semantic_resolutions
+      WHERE project_root = ? AND session_id = ? AND turn_id = ?
+      ORDER BY artifact_revision DESC, created_at DESC LIMIT 1
+    `).get(projectRoot, sessionId, turnId);
+        return row ? (0, semantic_resolution_1.mapSemanticResolutionRow)(row) : null;
+    }
+    listSemanticResolutions(projectRoot, sessionId, turnId) {
+        return this.db.prepare(`
+      SELECT * FROM devflow_semantic_resolutions
+      WHERE project_root = ? AND session_id = ? AND turn_id = ?
+      ORDER BY artifact_revision ASC, created_at ASC
+    `).all(projectRoot, sessionId, turnId)
+            .map(semantic_resolution_1.mapSemanticResolutionRow);
+    }
     listLatestTaskIntentArtifacts(projectRoot, sessionId) {
         return this.db.prepare(`
       SELECT artifact.* FROM devflow_task_intent_artifacts artifact
@@ -3281,6 +3568,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 = ?
@@ -3336,7 +3715,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,
@@ -3572,10 +3955,10 @@ class DevFlowDatabase {
         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, 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,9 +8,13 @@ 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';
 export { mapLearningCandidateRow, mapLearningEvidenceRow, mapLearningVersionRow, stableLearningJson, } from './learning-candidates';
 export type { AddLearningCandidateEvidenceInput, LearningCandidateEvidenceRecord, LearningCandidateKind, LearningCandidateRecord, LearningCandidateState, LearningCandidateVersionRecord, LearningEvidencePolarity, LearningOutcomeState, TransitionLearningCandidateInput, UpsertLearningCandidateInput, } from './learning-candidates';
 export type { SessionObligationKind, SessionObligationRecord, SessionObligationState, } from './obligation-ledger';
+export { assertSemanticResolutionRecord, mapSemanticResolutionRow, stableSemanticResolutionJson, } from './semantic-resolution';
+export type { PersistedSemanticGeneratedBy, PersistedSemanticResolutionState, SemanticResolutionRecord, } from './semantic-resolution';

package/dist/index.js

@@ -1,6 +1,6 @@
 "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.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;
+exports.stableSemanticResolutionJson = exports.mapSemanticResolutionRow = exports.assertSemanticResolutionRecord = 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.stableTaskRuntimeJson = exports.stableTaskRuntimeHash = exports.mapTaskRuntimeSnapshotRow = exports.mapTaskRuntimeEventRow = 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; } });
@@ -25,6 +25,11 @@ Object.defineProperty(exports, "mapTerminalTransitionRow", { enumerable: true, g
 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 task_runtime_1 = require("./task-runtime");
+Object.defineProperty(exports, "mapTaskRuntimeEventRow", { enumerable: true, get: function () { return task_runtime_1.mapTaskRuntimeEventRow; } });
+Object.defineProperty(exports, "mapTaskRuntimeSnapshotRow", { enumerable: true, get: function () { return task_runtime_1.mapTaskRuntimeSnapshotRow; } });
+Object.defineProperty(exports, "stableTaskRuntimeHash", { enumerable: true, get: function () { return task_runtime_1.stableTaskRuntimeHash; } });
+Object.defineProperty(exports, "stableTaskRuntimeJson", { enumerable: true, get: function () { return task_runtime_1.stableTaskRuntimeJson; } });
 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; } });
@@ -36,3 +41,7 @@ Object.defineProperty(exports, "mapLearningCandidateRow", { enumerable: true, ge
 Object.defineProperty(exports, "mapLearningEvidenceRow", { enumerable: true, get: function () { return learning_candidates_1.mapLearningEvidenceRow; } });
 Object.defineProperty(exports, "mapLearningVersionRow", { enumerable: true, get: function () { return learning_candidates_1.mapLearningVersionRow; } });
 Object.defineProperty(exports, "stableLearningJson", { enumerable: true, get: function () { return learning_candidates_1.stableLearningJson; } });
+var semantic_resolution_1 = require("./semantic-resolution");
+Object.defineProperty(exports, "assertSemanticResolutionRecord", { enumerable: true, get: function () { return semantic_resolution_1.assertSemanticResolutionRecord; } });
+Object.defineProperty(exports, "mapSemanticResolutionRow", { enumerable: true, get: function () { return semantic_resolution_1.mapSemanticResolutionRow; } });
+Object.defineProperty(exports, "stableSemanticResolutionJson", { enumerable: true, get: function () { return semantic_resolution_1.stableSemanticResolutionJson; } });

package/dist/retrieval-ledger.d.ts

@@ -1,6 +1,7 @@
-export type RetrievalLedgerStage = 'eligible' | 'candidate' | 'selected' | 'exposed' | 'adopted' | 'positive_outcome' | 'negative_outcome' | 'unknown' | 'rejected';
+export type RetrievalLedgerStage = '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;
@@ -10,6 +11,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;