@devflow-tools/database 0.16.10 → 0.16.12

package/dist/database.js

@@ -7,6 +7,7 @@ const node_sqlite_1 = require("./node-sqlite");
 const path_1 = require("path");
 const fs_1 = require("fs");
 const os_1 = require("os");
+const crypto_1 = require("crypto");
 const CONTEXT_REQUIRED_SKILLS = new Set([
     'react', 'vue', 'nest', 'nextjs', 'graphql', 'typescript',
 ]);
@@ -293,6 +294,7 @@ class DevFlowDatabase {
         trigger TEXT NOT NULL CHECK(trigger IN ('pre_compact', 'session_end')),
         pending_events INTEGER NOT NULL DEFAULT 0,
         released_leases INTEGER NOT NULL DEFAULT 0,
+        details TEXT NOT NULL DEFAULT '{}',
         created_at INTEGER NOT NULL
       );
 
@@ -335,6 +337,52 @@ class DevFlowDatabase {
       );
       CREATE INDEX IF NOT EXISTS idx_hook_fallbacks_session
         ON devflow_hook_fallbacks(project_root, session_id, created_at DESC);
+
+      CREATE TABLE IF NOT EXISTS devflow_work_items (
+        id TEXT PRIMARY KEY,
+        idempotency_key TEXT NOT NULL UNIQUE,
+        kind TEXT NOT NULL,
+        project_root TEXT NOT NULL,
+        session_id TEXT,
+        turn_id TEXT,
+        payload TEXT NOT NULL,
+        state TEXT NOT NULL DEFAULT 'pending'
+          CHECK(state IN ('pending', 'leased', 'completed', 'failed', 'dead_letter')),
+        attempts INTEGER NOT NULL DEFAULT 0 CHECK(attempts >= 0),
+        max_attempts INTEGER NOT NULL DEFAULT 5 CHECK(max_attempts > 0),
+        lease_owner TEXT,
+        lease_expires_at INTEGER,
+        next_attempt_at INTEGER NOT NULL,
+        error_category TEXT,
+        error_message TEXT,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        completed_at INTEGER
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_work_items_ready
+        ON devflow_work_items(project_root, state, next_attempt_at, created_at);
+      CREATE INDEX IF NOT EXISTS idx_work_items_expired_leases
+        ON devflow_work_items(project_root, state, lease_expires_at);
+      CREATE INDEX IF NOT EXISTS idx_work_items_completed
+        ON devflow_work_items(project_root, completed_at DESC);
+
+      CREATE TABLE IF NOT EXISTS devflow_session_closures (
+        session_id TEXT NOT NULL,
+        project_root TEXT NOT NULL,
+        state TEXT NOT NULL DEFAULT 'active'
+          CHECK(state IN ('active', 'closing', 'closed', 'closed_with_pending_work')),
+        receipt_id TEXT NOT NULL UNIQUE,
+        work_item_id TEXT,
+        pending_work_count INTEGER NOT NULL DEFAULT 0 CHECK(pending_work_count >= 0),
+        requested_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        closed_at INTEGER,
+        PRIMARY KEY (project_root, session_id)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_session_closures_state
+        ON devflow_session_closures(project_root, state, updated_at DESC);
     `);
         // Migration: add session_id to skill_executions (SQLite compat — ignore if exists)
         try {
@@ -377,6 +425,10 @@ class DevFlowDatabase {
             this.db.exec('ALTER TABLE skill_executions ADD COLUMN metadata TEXT');
         }
         catch { }
+        try {
+            this.db.exec("ALTER TABLE devflow_memory_distill_checkpoints ADD COLUMN details TEXT NOT NULL DEFAULT '{}'");
+        }
+        catch { }
         try {
             this.db.exec('ALTER TABLE skill_executions ADD COLUMN failed_tool_calls INTEGER DEFAULT 0');
         }
@@ -840,6 +892,15 @@ class DevFlowDatabase {
             metadata: row.metadata ? JSON.parse(row.metadata) : null,
         };
     }
+    getLatestSkillExecutionForSession(sessionId) {
+        const row = this.db.prepare(`
+      SELECT execution_id FROM skill_executions
+      WHERE session_id = ?
+      ORDER BY started_at DESC, execution_id DESC
+      LIMIT 1
+    `).get(sessionId);
+        return row?.execution_id ? this.getSkillExecution(row.execution_id) : null;
+    }
     updateSkillExecution(executionId, updates) {
         const sets = [];
         const values = [];
@@ -904,6 +965,17 @@ class DevFlowDatabase {
             this.db.prepare(`UPDATE skill_executions SET ${sets.join(', ')} WHERE execution_id = ?`).run(...values);
         }
     }
+    mergeSkillExecutionMetadata(executionId, incoming) {
+        const execution = this.getSkillExecution(executionId);
+        if (!execution)
+            return null;
+        const existing = execution.metadata && typeof execution.metadata === 'object'
+            ? execution.metadata
+            : {};
+        const merged = mergeExecutionMetadata(existing, incoming);
+        this.updateSkillExecution(executionId, { metadata: merged });
+        return merged;
+    }
     listSkillExecutions(limit, skillName) {
         let query = 'SELECT * FROM skill_executions';
         const params = [];
@@ -1048,23 +1120,38 @@ class DevFlowDatabase {
         const blocked = events.filter(event => event.blocked);
         const directFallbacks = events.filter(event => event.mcpFallback);
         const hookFallbacks = execution?.sessionId
-            ? this.listHookFallbacks({
-                sessionId: execution.sessionId,
-                from: execution.startedAt,
-                to: finishedAt,
-            })
+            ? this.db.prepare(`
+          SELECT * FROM devflow_hook_fallbacks
+          WHERE session_id = ? AND created_at >= ? AND created_at <= ?
+          ORDER BY created_at ASC
+        `).all(execution.sessionId, execution.startedAt, finishedAt).map(row => ({
+                id: row.id,
+                projectRoot: row.project_root,
+                sessionId: row.session_id ?? undefined,
+                toolUseId: row.tool_use_id ?? undefined,
+                requestType: row.request_type,
+                tool: row.tool,
+                reason: row.reason,
+                durationMs: row.duration_ms,
+                attempts: row.attempts,
+                createdAt: row.created_at,
+            }))
             : [];
         const fallbackReasons = [...new Set([
                 ...directFallbacks.map(() => 'direct_tool_during_context'),
                 ...hookFallbacks.map(fallback => `daemon_${fallback.reason}`),
             ])];
         const eventReceiptIds = collectCanonicalReceiptIds(events.map(event => event.output));
-        const suppliedMemoryReceiptIds = Array.isArray(metadata?.memoryReceiptIds)
-            ? metadata.memoryReceiptIds.filter((id) => typeof id === 'string')
-            : [];
-        const suppliedDistillReceiptIds = Array.isArray(metadata?.distillReceiptIds)
-            ? metadata.distillReceiptIds.filter((id) => typeof id === 'string')
-            : [];
+        const existingMetadata = execution?.metadata && typeof execution.metadata === 'object'
+            ? execution.metadata
+            : {};
+        const mergedMetadata = mergeExecutionMetadata(existingMetadata, metadata ?? {});
+        const suppliedMemoryReceiptIds = [existingMetadata.memoryReceiptIds, metadata?.memoryReceiptIds]
+            .flatMap(value => Array.isArray(value) ? value : [])
+            .filter((id) => typeof id === 'string');
+        const suppliedDistillReceiptIds = [existingMetadata.distillReceiptIds, metadata?.distillReceiptIds]
+            .flatMap(value => Array.isArray(value) ? value : [])
+            .filter((id) => typeof id === 'string');
         const memoryReceiptIds = [...new Set([
                 ...suppliedMemoryReceiptIds,
                 ...eventReceiptIds.filter(id => id.startsWith('memory-receipt:')),
@@ -1090,7 +1177,7 @@ class DevFlowDatabase {
             fallbackCount: directFallbacks.length + hookFallbacks.length,
             fallbackReasons,
             metadata: {
-                ...(metadata ?? {}),
+                ...mergedMetadata,
                 applicableObligations: obligation.applicable,
                 satisfiedObligations: obligation.satisfied,
                 missedTools: obligation.missedTools,
@@ -1103,6 +1190,22 @@ class DevFlowDatabase {
             },
         });
     }
+    reconcileRunningSkillExecutionsForSession(sessionId, finishedAt = Date.now(), metadata) {
+        const rows = this.db.prepare(`
+      SELECT execution_id
+      FROM skill_executions
+      WHERE session_id = ? AND status = 'running'
+      ORDER BY started_at ASC
+    `).all(sessionId);
+        const reconciled = [];
+        for (const row of rows) {
+            this.reconcileSkillExecution(row.execution_id, 'completed', finishedAt, metadata);
+            const execution = this.getSkillExecution(row.execution_id);
+            if (execution)
+                reconciled.push(execution);
+        }
+        return reconciled;
+    }
     getExecutionObligationCompliance(executionId) {
         const execution = this.getSkillExecution(executionId);
         const events = this.listToolCallEvents(executionId);
@@ -1526,6 +1629,351 @@ class DevFlowDatabase {
             total: Number(count?.total ?? 0),
         };
     }
+    // ---- Durable Work Queue ----
+    enqueueWork(input) {
+        if (!input.idempotencyKey.trim())
+            throw new Error('Work idempotency key is required');
+        if (!input.projectRoot.trim())
+            throw new Error('Work project root is required');
+        const maxAttempts = input.maxAttempts ?? 5;
+        if (!Number.isSafeInteger(maxAttempts) || maxAttempts <= 0) {
+            throw new Error('Work maxAttempts must be a positive safe integer');
+        }
+        const createdAt = Date.now();
+        const nextAttemptAt = input.nextAttemptAt ?? createdAt;
+        if (!Number.isSafeInteger(nextAttemptAt)) {
+            throw new Error('Work nextAttemptAt must be a safe integer');
+        }
+        const row = this.db.prepare(`
+      INSERT INTO devflow_work_items (
+        id, idempotency_key, kind, project_root, session_id, turn_id, 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)
+      ON CONFLICT(idempotency_key) DO UPDATE SET
+        state = CASE
+          WHEN devflow_work_items.state = 'dead_letter'
+            AND excluded.max_attempts > devflow_work_items.attempts
+          THEN 'failed'
+          ELSE devflow_work_items.state
+        END,
+        max_attempts = MAX(devflow_work_items.max_attempts, excluded.max_attempts),
+        next_attempt_at = CASE
+          WHEN devflow_work_items.state = 'dead_letter'
+            AND excluded.max_attempts > devflow_work_items.attempts
+          THEN excluded.next_attempt_at
+          ELSE devflow_work_items.next_attempt_at
+        END,
+        error_category = CASE
+          WHEN devflow_work_items.state = 'dead_letter'
+            AND excluded.max_attempts > devflow_work_items.attempts
+          THEN NULL
+          ELSE devflow_work_items.error_category
+        END,
+        error_message = CASE
+          WHEN devflow_work_items.state = 'dead_letter'
+            AND excluded.max_attempts > devflow_work_items.attempts
+          THEN NULL
+          ELSE devflow_work_items.error_message
+        END,
+        updated_at = CASE
+          WHEN devflow_work_items.state = 'dead_letter'
+            AND excluded.max_attempts > devflow_work_items.attempts
+          THEN excluded.updated_at
+          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);
+        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;
+    }
+    requestSessionClosure(input) {
+        if (!input.sessionId.trim())
+            throw new Error('Session closure requires a session ID');
+        if (!input.projectRoot.trim())
+            throw new Error('Session closure requires a project root');
+        if (!input.receiptId.trim())
+            throw new Error('Session closure requires a receipt ID');
+        return this.db.transaction(() => {
+            const now = Date.now();
+            this.db.prepare(`
+        INSERT INTO devflow_session_closures (
+          session_id, project_root, state, receipt_id, pending_work_count,
+          requested_at, updated_at
+        ) VALUES (?, ?, 'active', ?, 0, ?, ?)
+        ON CONFLICT(project_root, session_id) DO NOTHING
+      `).run(input.sessionId, input.projectRoot, input.receiptId, now, now);
+            const work = this.enqueueWork({
+                idempotencyKey: input.receiptId,
+                kind: 'session.finalize',
+                projectRoot: input.projectRoot,
+                sessionId: input.sessionId,
+                payload: input.payload,
+                maxAttempts: input.maxAttempts,
+            });
+            const pending = this.db.prepare(`
+        SELECT COUNT(*) AS count
+        FROM devflow_work_items
+        WHERE project_root = ? AND session_id = ?
+          AND state IN ('pending', 'leased', 'failed', 'dead_letter')
+      `).get(input.projectRoot, input.sessionId);
+            const pendingWorkCount = Number(pending?.count ?? 0);
+            this.db.prepare(`
+        UPDATE devflow_session_closures
+        SET state = CASE
+              WHEN state IN ('closed', 'closed_with_pending_work')
+                THEN CASE WHEN ? > 0 THEN 'closed_with_pending_work' ELSE 'closed' END
+              WHEN ? = 'completed'
+                THEN CASE WHEN ? > 0 THEN 'closed_with_pending_work' ELSE 'closed' END
+              WHEN ? = 'dead_letter' THEN 'closed_with_pending_work'
+              ELSE 'closing'
+            END,
+            work_item_id = COALESCE(work_item_id, ?),
+            pending_work_count = ?,
+            closed_at = CASE WHEN ? = 'completed' THEN ? ELSE closed_at END,
+            updated_at = ?
+        WHERE project_root = ? AND session_id = ?
+      `).run(pendingWorkCount, work.state, pendingWorkCount, work.state, work.id, pendingWorkCount, work.state, now, now, input.projectRoot, input.sessionId);
+            return this.getSessionClosure(input.projectRoot, input.sessionId);
+        });
+    }
+    getSessionClosure(projectRoot, sessionId) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_session_closures
+      WHERE project_root = ? AND session_id = ?
+    `).get(projectRoot, sessionId);
+        return row ? this.mapSessionClosure(row) : null;
+    }
+    completeSessionClosure(projectRoot, sessionId, excludingWorkItemId, closedAt = Date.now()) {
+        const pending = this.db.prepare(`
+      SELECT COUNT(*) AS count
+      FROM devflow_work_items
+      WHERE project_root = ? AND session_id = ?
+        AND state IN ('pending', 'leased', 'failed', 'dead_letter')
+        AND (? IS NULL OR id <> ?)
+    `).get(projectRoot, sessionId, excludingWorkItemId ?? null, excludingWorkItemId ?? null);
+        const pendingWorkCount = Number(pending?.count ?? 0);
+        const state = pendingWorkCount > 0 ? 'closed_with_pending_work' : 'closed';
+        this.db.prepare(`
+      UPDATE devflow_session_closures
+      SET state = ?, pending_work_count = ?, closed_at = ?, updated_at = ?
+      WHERE project_root = ? AND session_id = ? AND state = 'closing'
+    `).run(state, pendingWorkCount, closedAt, closedAt, projectRoot, sessionId);
+        const closure = this.getSessionClosure(projectRoot, sessionId);
+        if (!closure)
+            throw new Error(`Session closure ${sessionId} does not exist`);
+        return closure;
+    }
+    listSessionClosures(projectRoot, limit = 100) {
+        const rows = this.db.prepare(`
+      SELECT * FROM devflow_session_closures
+      WHERE project_root = ?
+      ORDER BY updated_at DESC
+      LIMIT ?
+    `).all(projectRoot, Math.max(1, Math.min(limit, 1000)));
+        return rows.map(row => this.mapSessionClosure(row));
+    }
+    leaseWork(input) {
+        if (!input.owner.trim())
+            throw new Error('Work lease owner is required');
+        if (!Number.isFinite(input.limit) || input.limit <= 0)
+            return [];
+        if (!Number.isSafeInteger(input.leaseMs) || input.leaseMs <= 0) {
+            throw new Error('Work leaseMs must be a positive safe integer');
+        }
+        if (input.kinds?.length === 0)
+            return [];
+        const now = input.now ?? Date.now();
+        const leaseExpiresAt = now + input.leaseMs;
+        if (!Number.isSafeInteger(now) || !Number.isSafeInteger(leaseExpiresAt)) {
+            throw new Error('Work lease timestamps must be safe integers');
+        }
+        const limit = Math.min(Math.floor(input.limit), 1000);
+        const kinds = input.kinds ? [...new Set(input.kinds)] : undefined;
+        const kindClause = kinds
+            ? `AND kind IN (${kinds.map(() => '?').join(', ')})`
+            : '';
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const candidates = this.db.prepare(`
+        SELECT id, state
+        FROM devflow_work_items
+        WHERE project_root = ?
+          AND state IN ('pending', 'failed')
+          AND lease_owner IS NULL
+          AND lease_expires_at IS NULL
+          AND next_attempt_at <= ?
+          AND attempts < max_attempts
+          ${kindClause}
+        ORDER BY next_attempt_at ASC, created_at ASC, id ASC
+        LIMIT ?
+      `).all(input.projectRoot, now, ...(kinds ?? []), limit);
+            const leased = [];
+            for (const candidate of candidates) {
+                const result = this.db.prepare(`
+          UPDATE devflow_work_items
+          SET state = 'leased', attempts = attempts + 1, lease_owner = ?,
+              lease_expires_at = ?, updated_at = ?
+          WHERE id = ? AND project_root = ? AND state = ?
+            AND lease_owner IS NULL AND lease_expires_at IS NULL
+            AND next_attempt_at <= ? AND attempts < max_attempts
+        `).run(input.owner, leaseExpiresAt, now, candidate.id, input.projectRoot, candidate.state, now);
+                if (result.changes === 1) {
+                    const row = this.db.prepare('SELECT * FROM devflow_work_items WHERE id = ?')
+                        .get(candidate.id);
+                    leased.push(this.mapWorkItem(row));
+                }
+            }
+            this.db.exec('COMMIT');
+            return leased;
+        }
+        catch (error) {
+            try {
+                this.db.exec('ROLLBACK');
+            }
+            catch { }
+            throw error;
+        }
+    }
+    completeWork(id, owner, now = Date.now()) {
+        const work = this.db.prepare(`
+      SELECT project_root, session_id FROM devflow_work_items WHERE id = ?
+    `).get(id);
+        const completed = this.db.prepare(`
+      UPDATE devflow_work_items
+      SET state = 'completed', lease_owner = NULL, lease_expires_at = NULL,
+          updated_at = ?, completed_at = ?
+      WHERE id = ? AND state = 'leased' AND lease_owner = ?
+    `).run(now, now, id, owner).changes === 1;
+        if (completed && work?.project_root && work.session_id) {
+            this.refreshClosedSessionClosure(work.project_root, work.session_id, now);
+        }
+        return completed;
+    }
+    retryWork(id, owner, error, nextAttemptAt) {
+        const updatedAt = Date.now();
+        return this.db.prepare(`
+      UPDATE devflow_work_items
+      SET state = CASE WHEN attempts >= max_attempts THEN 'dead_letter' ELSE 'failed' END,
+          lease_owner = NULL, lease_expires_at = NULL, next_attempt_at = ?,
+          error_category = ?, error_message = ?, updated_at = ?
+      WHERE id = ? AND state = 'leased' AND lease_owner = ?
+    `).run(nextAttemptAt, error.category, error.message, updatedAt, id, owner).changes === 1;
+    }
+    deferWork(id, owner, error, nextAttemptAt) {
+        const updatedAt = Date.now();
+        return this.db.prepare(`
+      UPDATE devflow_work_items
+      SET state = 'pending', attempts = MAX(0, attempts - 1),
+          lease_owner = NULL, lease_expires_at = NULL, next_attempt_at = ?,
+          error_category = ?, error_message = ?, updated_at = ?
+      WHERE id = ? AND state = 'leased' AND lease_owner = ?
+    `).run(nextAttemptAt, error.category, error.message, updatedAt, id, owner).changes === 1;
+    }
+    deadLetterWork(id, owner, error) {
+        return this.db.prepare(`
+      UPDATE devflow_work_items
+      SET state = 'dead_letter', lease_owner = NULL, lease_expires_at = NULL,
+          error_category = ?, error_message = ?, updated_at = ?
+      WHERE id = ? AND state = 'leased' AND lease_owner = ?
+    `).run(error.category, error.message, Date.now(), id, owner).changes === 1;
+    }
+    recoverExpiredWork(projectRoot, now = Date.now()) {
+        return this.db.prepare(`
+      UPDATE devflow_work_items
+      SET state = CASE WHEN attempts >= max_attempts THEN 'dead_letter' ELSE 'failed' END,
+          lease_owner = NULL, lease_expires_at = NULL, next_attempt_at = ?,
+          error_category = 'lease_expired',
+          error_message = 'Work lease expired before completion',
+          updated_at = ?
+      WHERE project_root = ? AND state = 'leased' AND lease_expires_at <= ?
+    `).run(now, now, projectRoot, now).changes;
+    }
+    getWorkQueueHealth(projectRoot, now = Date.now()) {
+        const row = this.db.prepare(`
+      SELECT
+        COALESCE(SUM(CASE WHEN state IN ('pending', 'leased', 'failed') THEN 1 ELSE 0 END), 0) AS queue_depth,
+        COALESCE(SUM(CASE WHEN state = 'pending' THEN 1 ELSE 0 END), 0) AS pending,
+        COALESCE(SUM(CASE WHEN state = 'leased' THEN 1 ELSE 0 END), 0) AS leased,
+        COALESCE(SUM(CASE WHEN state = 'failed' THEN 1 ELSE 0 END), 0) AS failed,
+        COALESCE(SUM(CASE WHEN state = 'leased' AND lease_expires_at <= ? THEN 1 ELSE 0 END), 0) AS expired_leases,
+        COALESCE(SUM(CASE WHEN state = 'dead_letter' THEN 1 ELSE 0 END), 0) AS dead_letters,
+        MIN(CASE WHEN state IN ('pending', 'leased', 'failed') THEN created_at END) AS oldest_pending_at,
+        MAX(CASE WHEN state = 'completed' THEN completed_at END) AS last_successful_drain_at
+      FROM devflow_work_items
+      WHERE project_root = ?
+    `).get(now, projectRoot);
+        const oldestPendingAt = row.oldest_pending_at == null
+            ? undefined
+            : Number(row.oldest_pending_at);
+        return {
+            projectRoot,
+            queueDepth: Number(row.queue_depth),
+            pending: Number(row.pending),
+            leased: Number(row.leased),
+            failed: Number(row.failed),
+            expiredLeases: Number(row.expired_leases),
+            deadLetters: Number(row.dead_letters),
+            oldestPendingAgeMs: oldestPendingAt === undefined ? 0 : Math.max(0, now - oldestPendingAt),
+            lastSuccessfulDrainAt: row.last_successful_drain_at == null
+                ? undefined
+                : Number(row.last_successful_drain_at),
+        };
+    }
+    mapWorkItem(row) {
+        return {
+            id: row.id,
+            idempotencyKey: row.idempotency_key,
+            kind: row.kind,
+            projectRoot: row.project_root,
+            sessionId: row.session_id ?? undefined,
+            turnId: row.turn_id ?? undefined,
+            payload: parseJson(row.payload),
+            state: row.state,
+            attempts: Number(row.attempts),
+            maxAttempts: Number(row.max_attempts),
+            leaseOwner: row.lease_owner ?? undefined,
+            leaseExpiresAt: row.lease_expires_at == null ? undefined : Number(row.lease_expires_at),
+            nextAttemptAt: Number(row.next_attempt_at),
+            errorCategory: row.error_category ?? undefined,
+            errorMessage: row.error_message ?? undefined,
+            createdAt: Number(row.created_at),
+            updatedAt: Number(row.updated_at),
+            completedAt: row.completed_at == null ? undefined : Number(row.completed_at),
+        };
+    }
+    mapSessionClosure(row) {
+        return {
+            sessionId: row.session_id,
+            projectRoot: row.project_root,
+            state: row.state,
+            receiptId: row.receipt_id,
+            workItemId: row.work_item_id ?? undefined,
+            pendingWorkCount: Number(row.pending_work_count),
+            requestedAt: Number(row.requested_at),
+            updatedAt: Number(row.updated_at),
+            closedAt: row.closed_at == null ? undefined : Number(row.closed_at),
+        };
+    }
+    refreshClosedSessionClosure(projectRoot, sessionId, now) {
+        const pending = this.db.prepare(`
+      SELECT COUNT(*) AS count
+      FROM devflow_work_items
+      WHERE project_root = ? AND session_id = ?
+        AND state IN ('pending', 'leased', 'failed', 'dead_letter')
+    `).get(projectRoot, sessionId);
+        const pendingWorkCount = Number(pending?.count ?? 0);
+        this.db.prepare(`
+      UPDATE devflow_session_closures
+      SET state = CASE WHEN ? = 0 THEN 'closed' ELSE 'closed_with_pending_work' END,
+          pending_work_count = ?, updated_at = ?
+      WHERE project_root = ? AND session_id = ?
+        AND state IN ('closed', 'closed_with_pending_work')
+    `).run(pendingWorkCount, pendingWorkCount, now, projectRoot, sessionId);
+    }
     // ---- Hook Lifecycle ----
     getHookReceipt(projectRoot) {
         const row = this.db.prepare(`
@@ -1676,6 +2124,14 @@ class DevFlowDatabase {
                 .all(projectRoot, limit));
         return rows.map(row => this.mapMemoryTurn(row));
     }
+    listSessionMemoryTurnsForReconciliation(projectRoot, sessionId) {
+        const rows = this.db.prepare(`
+      SELECT * FROM devflow_memory_turns
+      WHERE project_root = ? AND session_id = ?
+      ORDER BY created_at ASC, turn_id ASC
+    `).all(projectRoot, sessionId);
+        return rows.map(row => this.mapMemoryTurn(row));
+    }
     insertHookFallback(record) {
         return this.db.prepare(`
       INSERT OR IGNORE INTO devflow_hook_fallbacks
@@ -1749,13 +2205,18 @@ class DevFlowDatabase {
     recordMemoryDistillCheckpoint(checkpoint) {
         this.db.prepare(`
       INSERT INTO devflow_memory_distill_checkpoints
-        (id, project_root, session_id, trigger, pending_events, released_leases, created_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?)
-    `).run(checkpoint.id, checkpoint.projectRoot, checkpoint.sessionId ?? null, checkpoint.trigger, checkpoint.pendingEvents, checkpoint.releasedLeases, checkpoint.createdAt);
+        (id, project_root, session_id, trigger, pending_events, released_leases, details, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        pending_events = excluded.pending_events,
+        released_leases = MAX(devflow_memory_distill_checkpoints.released_leases, excluded.released_leases),
+        details = excluded.details,
+        created_at = MIN(devflow_memory_distill_checkpoints.created_at, excluded.created_at)
+    `).run(checkpoint.id, checkpoint.projectRoot, checkpoint.sessionId ?? null, checkpoint.trigger, checkpoint.pendingEvents, checkpoint.releasedLeases, JSON.stringify(checkpoint.details ?? {}), checkpoint.createdAt);
     }
     listMemoryDistillCheckpoints(projectRoot, limit = 50) {
         const rows = this.db.prepare(`
-      SELECT id, project_root, session_id, trigger, pending_events, released_leases, created_at
+      SELECT id, project_root, session_id, trigger, pending_events, released_leases, details, created_at
       FROM devflow_memory_distill_checkpoints
       WHERE project_root = ?
       ORDER BY created_at DESC
@@ -1768,6 +2229,7 @@ class DevFlowDatabase {
             trigger: row.trigger,
             pendingEvents: Number(row.pending_events),
             releasedLeases: Number(row.released_leases),
+            details: row.details ? JSON.parse(row.details) : {},
             createdAt: Number(row.created_at),
         }));
     }
@@ -1868,3 +2330,39 @@ function collectCanonicalReceiptIds(values) {
     values.forEach(value => visit(value, 0));
     return [...receiptIds];
 }
+function stableMetadataKey(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? String(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableMetadataKey).join(',')}]`;
+    const record = value;
+    return `{${Object.keys(record).sort()
+        .map(key => `${JSON.stringify(key)}:${stableMetadataKey(record[key])}`)
+        .join(',')}}`;
+}
+function unionMetadataArrays(existing, incoming) {
+    const values = [
+        ...(Array.isArray(existing) ? existing : []),
+        ...(Array.isArray(incoming) ? incoming : []),
+    ];
+    if (values.length === 0 && !Array.isArray(existing) && !Array.isArray(incoming))
+        return undefined;
+    const unique = new Map();
+    for (const value of values)
+        unique.set(stableMetadataKey(value), value);
+    return [...unique.values()];
+}
+function mergeExecutionMetadata(existing, incoming) {
+    const merged = { ...existing, ...incoming };
+    for (const key of [
+        'evidenceDegradations',
+        'evidenceContractOutcomes',
+        'pendingEvidenceContractIds',
+        'sessionFinalizationDegradations',
+    ]) {
+        const union = unionMetadataArrays(existing[key], incoming[key]);
+        if (union !== undefined)
+            merged[key] = union;
+    }
+    return merged;
+}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { DevFlowDatabase, getGlobalDevFlowDbPath, openGlobalDevFlowDatabase, } from './database';
 export type { BenchmarkReportMetaRecord, BenchmarkReportRecord, FeedbackRecord, GovernanceAuditRecord, GovernanceRuleRecord, HookFallbackRecord, HookReceiptRecord, MemoryDistillCheckpointRecord, MemoryTurnRecord, MemoryTurnStatus, TelemetryFailureRecord, } from './database';
+export type { EnqueueWorkInput, LeaseWorkInput, RequestSessionClosureInput, SessionClosureRecord, SessionClosureState, WorkError, WorkItemRecord, WorkKind, WorkQueueHealth, WorkState, } from './work-queue';

package/dist/node-sqlite.js

@@ -1,11 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NodeSqliteDatabase = void 0;
-// node:sqlite is a Node.js 22+ experimental built-in. TypeScript does not
-// resolve `node:` prefixed modules unless @types/node includes them (which
-// requires @types/node >= 22.5). We suppress the TS error here and rely on
-// the ambient types defined below until the project upgrades @types/node.
-// @ts-expect-error - node:sqlite types not available in @types/node@20
 const node_sqlite_1 = require("node:sqlite");
 class NodeSqliteDatabase {
     constructor(path, busyTimeoutMs = 10000) {
@@ -23,7 +18,7 @@ class NodeSqliteDatabase {
             run: (...params) => {
                 const result = stmt.run(...normalizeParams(params));
                 return {
-                    changes: result.changes,
+                    changes: Number(result.changes),
                     lastInsertRowid: result.lastInsertRowid,
                 };
             },