@devflow-tools/database 0.17.1 → 0.17.3

package/CHANGELOG.md

@@ -3,6 +3,41 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [0.17.3](https://github.com/shilongfeicool/dev-flow/compare/v0.17.2...v0.17.3) (2026-08-03)
+
+
+### Bug Fixes
+
+* **runtime:** enforce evidence-driven task truth ([6a8f84a](https://github.com/shilongfeicool/dev-flow/commit/6a8f84abf62666dfb7b8643fa88a5e9489940fce))
+
+
+### Features
+
+* **evidence:** attribute consumed and verified retrieval ([65e5828](https://github.com/shilongfeicool/dev-flow/commit/65e5828de6d8455a2712ff78ea411aa2bf8be829))
+* **runtime:** persist and reduce task events ([f1966c5](https://github.com/shilongfeicool/dev-flow/commit/f1966c5eaa6c023b88c4c52b3109657b7ad8cca1))
+* **runtime:** shadow online task reduction ([c15088c](https://github.com/shilongfeicool/dev-flow/commit/c15088c9fc9434bba86bcbceeb107da36f2d9606))
+* **semantic:** harden durable memory and knowledge work ([69eab16](https://github.com/shilongfeicool/dev-flow/commit/69eab16012ad7b3cb6a7a38ddcb1c7c1fc30054a))
+
+
+
+
+
+## [0.17.2](https://github.com/shilongfeicool/dev-flow/compare/v0.17.1...v0.17.2) (2026-08-01)
+
+
+### Bug Fixes
+
+* **reliability:** close semantic lifecycle gaps ([08bae87](https://github.com/shilongfeicool/dev-flow/commit/08bae8742c5907dffdd476679e70c86cc373a7e8))
+
+
+### Features
+
+* **reliability:** strengthen semantic retrieval closure ([b979ab3](https://github.com/shilongfeicool/dev-flow/commit/b979ab3ec790e3d7119db512902db90a9567667d))
+
+
+
+
+
 ## [0.17.1](https://github.com/shilongfeicool/dev-flow/compare/v0.16.28...v0.17.1) (2026-07-31)
 
 

package/__tests__/database.retrieval-ledger.test.ts

@@ -35,6 +35,21 @@ describe('retrieval ledger', () => {
     database.close();
   });
 
+  it('persists v1 provenance and reads legacy adopted rows as consumed', () => {
+    const database = createDatabase();
+    database.appendRetrievalLedgerEvent(event({
+      id: 'legacy-adopted', stage: 'adopted', taskSpecHash: 'spec:1', actor: 'tool:read',
+      sourceVersion: 'v1', sourceContentHash: 'sha256:1', evidenceIds: ['memory-a'],
+      reasonCode: 'structural_evidence_ref',
+    }));
+    expect(database.listRetrievalLedgerEvents({ projectRoot: '/project' })[0]).toMatchObject({
+      schemaVersion: 'retrieval-ledger-event.v1', stage: 'consumed', taskSpecHash: 'spec:1',
+      actor: 'tool:read', sourceVersion: 'v1', sourceContentHash: 'sha256:1',
+      evidenceIds: ['memory-a'], reasonCode: 'structural_evidence_ref',
+    });
+    database.close();
+  });
+
   function createDatabase(): DevFlowDatabase {
     const directory = mkdtempSync(join(tmpdir(), 'devflow-retrieval-ledger-'));
     directories.push(directory);

package/__tests__/database.task-runtime.test.ts

@@ -0,0 +1,73 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { DevFlowDatabase } from '../src/database';
+import { stableTaskRuntimeHash, type TaskRuntimeEventRecord, type TaskRuntimeSnapshotRecord } from '../src/task-runtime';
+
+const identity = {
+  projectRoot: '/project', projectId: 'project:1', hostId: 'claude-code',
+  sessionId: 'session:1', turnId: 'turn:1', requestId: 'request:1',
+};
+
+function event(overrides: Partial<TaskRuntimeEventRecord> = {}): TaskRuntimeEventRecord {
+  return {
+    schemaVersion: 'task-runtime-event.v1', producer: 'test', producerVersion: '1.0.0',
+    eventId: 'event:1', sequence: 1, identity, taskSpecHash: 'spec:1',
+    kind: 'task.spec.bound', payload: {}, createdAt: 1, ...overrides,
+  };
+}
+
+function snapshot(lastEventSequence = 1): TaskRuntimeSnapshotRecord {
+  const body = {
+    schemaVersion: 'task-runtime-snapshot.v1' as const,
+    producer: 'test', producerVersion: '1.0.0', identity, taskSpecHash: 'spec:1',
+    lastEventSequence,
+    artifacts: { requiredIdentityIds: [], resolvedIdentityIds: [], ambiguousIdentityIds: [] },
+    channels: {},
+    action: { requirement: 'not_required' as const, state: 'satisfied' as const },
+    verification: { requirement: 'not_required' as const, state: 'satisfied' as const },
+    memory: { requirement: 'required' as const, state: 'satisfied' as const },
+    durableWorkIds: [], terminal: 'completed' as const, runtimeHealth: 'healthy' as const,
+    updatedAt: lastEventSequence,
+  };
+  return { ...body, snapshotHash: stableTaskRuntimeHash(body) };
+}
+
+describe('DevFlowDatabase task runtime persistence', () => {
+  let directory: string;
+  let database: DevFlowDatabase;
+
+  beforeEach(() => {
+    directory = mkdtempSync(join(tmpdir(), 'devflow-task-runtime-'));
+    database = new DevFlowDatabase(directory);
+  });
+
+  afterEach(() => {
+    database.close();
+    rmSync(directory, { recursive: true, force: true });
+  });
+
+  it('makes identical event replay idempotent and rejects conflicting IDs or sequences', () => {
+    const first = database.appendTaskRuntimeEvent(event());
+    expect(database.appendTaskRuntimeEvent(event())).toEqual(first);
+    expect(database.listTaskRuntimeEvents('/project', 'session:1', 'turn:1')).toEqual([first]);
+
+    expect(() => database.appendTaskRuntimeEvent(event({ payload: { changed: true } })))
+      .toThrow('TASK_RUNTIME_EVENT_CONFLICT:event:1');
+    expect(() => database.appendTaskRuntimeEvent(event({ eventId: 'event:2' })))
+      .toThrow('TASK_RUNTIME_SEQUENCE_CONFLICT:1');
+  });
+
+  it('round-trips snapshots, rejects regression, and supports deterministic rebuild deletion', () => {
+    database.appendTaskRuntimeEvent(event());
+    const current = database.putTaskRuntimeSnapshot(snapshot(1));
+    expect(database.getTaskRuntimeSnapshot('/project', 'session:1', 'turn:1')).toEqual(current);
+    expect(() => database.putTaskRuntimeSnapshot(snapshot(0))).toThrow('TASK_RUNTIME_SNAPSHOT_REGRESSION');
+
+    expect(database.deleteTaskRuntimeSnapshot('/project', 'session:1', 'turn:1')).toBe(true);
+    expect(database.getTaskRuntimeSnapshot('/project', 'session:1', 'turn:1')).toBeNull();
+    expect(database.listTaskRuntimeEvents('/project', 'session:1', 'turn:1')).toEqual([event()]);
+    expect(database.putTaskRuntimeSnapshot(snapshot(1))).toEqual(current);
+  });
+});

package/__tests__/database.work-queue.test.ts

@@ -166,6 +166,40 @@ describe('DevFlowDatabase durable work queue', () => {
     });
   });
 
+  it('serializes project mutations, cancels stale work, and preserves dead-letter replay lineage', () => {
+    expect(database.acquireProjectMutationLease({
+      projectRoot, mutationKind: 'knowledge_publish', owner: 'worker-a', leaseMs: 100, now: 10,
+    })).toBe(true);
+    expect(database.acquireProjectMutationLease({
+      projectRoot, mutationKind: 'knowledge_publish', owner: 'worker-b', leaseMs: 100, now: 50,
+    })).toBe(false);
+    expect(database.acquireProjectMutationLease({
+      projectRoot, mutationKind: 'knowledge_publish', owner: 'worker-b', leaseMs: 100, now: 111,
+    })).toBe(true);
+
+    const stale = database.enqueueWork({
+      idempotencyKey: 'knowledge:stale', kind: 'knowledge.ingest', projectRoot,
+      sourceHash: 'source:v1', taskSpecHash: 'spec:v1', payload: {}, nextAttemptAt: 200,
+    });
+    expect(stale.maxAttempts).toBe(3);
+    database.leaseWork({ projectRoot, owner: 'worker-b', workItemIds: [stale.id], limit: 1, leaseMs: 100, now: 200 });
+    expect(database.cancelStaleWork({
+      id: stale.id, owner: 'worker-b', sourceHash: 'source:v2', taskSpecHash: 'spec:v1', now: 210,
+    })).toBe(true);
+    expect(database.getWorkById(stale.id)).toMatchObject({ state: 'cancelled', sourceHash: 'source:v1' });
+
+    const failed = database.enqueueWork({
+      idempotencyKey: 'knowledge:dead', kind: 'knowledge.ingest', projectRoot,
+      sourceHash: 'source:dead', payload: {}, maxAttempts: 1, nextAttemptAt: 300,
+    });
+    database.leaseWork({ projectRoot, owner: 'worker-b', workItemIds: [failed.id], limit: 1, leaseMs: 100, now: 300 });
+    database.retryWork(failed.id, 'worker-b', { category: 'semantic_invalid', message: 'empty' }, 310);
+    const replay = database.replayDeadLetterWork(failed.id, {
+      idempotencyKey: 'knowledge:dead:replay:1', sourceHash: 'source:fixed', now: 320,
+    });
+    expect(replay).toMatchObject({ state: 'pending', replayOfId: failed.id, replayCount: 1, sourceHash: 'source:fixed' });
+  });
+
   it('recovers expired leases and dead-letters exhausted work', () => {
     database.enqueueWork({
       idempotencyKey: 'memory:distill:retryable',

package/dist/database.d.ts

@@ -6,6 +6,7 @@ import { type AddLearningCandidateEvidenceInput, type LearningCandidateEvidenceR
 import { type CreateWorkflowWorkerInput, type EnqueueWorkflowMergeInput, type TransitionWorkflowWorkerInput, type WorkflowMergeRecord, type WorkflowMergeState, type WorkflowWorkerEventRecord, type WorkflowWorkerRecord } from './workflow-workers';
 import type { RetrievalLedgerEventRecord } from './retrieval-ledger';
 import { type ChannelQueryPlanRecord, type TaskIntentArtifactRecord, type TerminalTransitionRecord, type ToolNameResolutionRecord, type TranscriptCheckpointRecord } from './task-semantic-control';
+import { type TaskRuntimeEventRecord, type TaskRuntimeSnapshotRecord } from './task-runtime';
 export interface BenchmarkReportRecord {
     runId: string;
     suiteId: string;
@@ -174,12 +175,17 @@ export interface HookFallbackRecord {
 export declare function getGlobalDevFlowDbPath(home?: string): string;
 export declare function openGlobalDevFlowDatabase(home?: string, options?: {
     busyTimeoutMs?: number;
+    readonly?: boolean;
+}): DevFlowDatabase;
+export declare function openGlobalDevFlowReadOnlyDatabase(home?: string, options?: {
+    busyTimeoutMs?: number;
 }): DevFlowDatabase;
 export declare class DevFlowDatabase {
     private db;
     constructor(projectRoot: string, opts?: {
         dbPath?: string;
         busyTimeoutMs?: number;
+        readonly?: boolean;
     });
     private initializeSchema;
     insertRun(run: any): void;
@@ -213,8 +219,10 @@ export declare class DevFlowDatabase {
     listToolCallEventsBySession(sessionId: string): any[];
     getToolCallEventByToolUseId(sessionId: string, toolUseId: string): {
         eventId: string;
+        executionId: string;
         timestamp: number;
         duration: number;
+        input: Record<string, unknown>;
     } | null;
     listToolCallEventsBySessions(sessionIds: string[]): Record<string, any[]>;
     insertSkillExecution(params: {
@@ -382,6 +390,30 @@ export declare class DevFlowDatabase {
     private insertLearningActivation;
     enqueueWork(input: EnqueueWorkInput): WorkItemRecord;
     getWorkByIdempotencyKey(idempotencyKey: string): WorkItemRecord | null;
+    getWorkById(id: string): WorkItemRecord | null;
+    acquireProjectMutationLease(input: {
+        projectRoot: string;
+        mutationKind: string;
+        owner: string;
+        leaseMs: number;
+        sourceHash?: string;
+        now?: number;
+    }): boolean;
+    releaseProjectMutationLease(projectRoot: string, mutationKind: string, owner: string): boolean;
+    cancelStaleWork(input: {
+        id: string;
+        owner: string;
+        sourceHash?: string;
+        taskSpecHash?: string;
+        reason?: string;
+        now?: number;
+    }): boolean;
+    replayDeadLetterWork(id: string, input: {
+        idempotencyKey: string;
+        sourceHash?: string;
+        taskSpecHash?: string;
+        now?: number;
+    }): WorkItemRecord | null;
     requestSessionClosure(input: RequestSessionClosureInput): SessionClosureRecord;
     getSessionClosure(projectRoot: string, sessionId: string): SessionClosureRecord | null;
     completeSessionClosure(projectRoot: string, sessionId: string, excludingWorkItemId?: string, closedAt?: number): SessionClosureRecord;
@@ -419,6 +451,7 @@ export declare class DevFlowDatabase {
     upsertContextReceipt(receipt: ContextReceiptRecord): void;
     getContextReceipt(projectRoot: string, sessionId: string, executionId: string): ContextReceiptRecord | null;
     getActiveContextReceipt(projectRoot: string, sessionId: string, executionId?: string, now?: number): ContextReceiptRecord | null;
+    getContextReceiptForRequest(projectRoot: string, sessionId: string, requestId: string): ContextReceiptRecord | null;
     recordContextSelectionEvent(event: ContextSelectionEventRecord): boolean;
     appendRetrievalLedgerEvent(event: RetrievalLedgerEventRecord): boolean;
     appendTaskIntentArtifact(record: TaskIntentArtifactRecord): TaskIntentArtifactRecord;
@@ -450,6 +483,13 @@ export declare class DevFlowDatabase {
         requestId?: string;
     }): ToolNameResolutionRecord[];
     appendTerminalTransition(record: TerminalTransitionRecord): TerminalTransitionRecord;
+    appendTaskRuntimeEvent(event: TaskRuntimeEventRecord): TaskRuntimeEventRecord;
+    getTaskRuntimeEvent(eventId: string): TaskRuntimeEventRecord | null;
+    listTaskRuntimeEvents(projectRoot: string, sessionId: string, turnId: string): TaskRuntimeEventRecord[];
+    putTaskRuntimeSnapshot(snapshot: TaskRuntimeSnapshotRecord): TaskRuntimeSnapshotRecord;
+    appendTaskRuntimeEventAndSnapshot(event: TaskRuntimeEventRecord, snapshot: TaskRuntimeSnapshotRecord): TaskRuntimeSnapshotRecord;
+    getTaskRuntimeSnapshot(projectRoot: string, sessionId: string, turnId: string): TaskRuntimeSnapshotRecord | null;
+    deleteTaskRuntimeSnapshot(projectRoot: string, sessionId: string, turnId: string): boolean;
     getTerminalTransition(receiptId: string): TerminalTransitionRecord | null;
     getLatestTerminalTransition(projectRoot: string, sessionId: string, turnId: string): TerminalTransitionRecord | null;
     appendTranscriptCheckpoint(record: TranscriptCheckpointRecord): boolean;
@@ -499,10 +539,16 @@ export declare class DevFlowDatabase {
         reason?: string;
         decidedAt?: number;
     }): MemoryTurnRecord;
+    updateCommittedMemoryTurnProjection(input: {
+        turnId: string;
+        memoryIds: string[];
+        reason?: string;
+    }): MemoryTurnRecord;
     skipMemoryTurn(input: {
         turnId: string;
         receiptId: string;
         reason: string;
+        source?: string;
         decidedAt?: number;
     }): MemoryTurnRecord;
     markMemoryTurnStopPrompted(turnId: string, promptedAt?: number): boolean;