@devflow-tools/database 0.17.2 → 0.17.4

package/CHANGELOG.md

@@ -3,6 +3,36 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [0.17.4](https://github.com/shilongfeicool/dev-flow/compare/v0.17.3...v0.17.4) (2026-08-04)
+
+
+### Features
+
+* **semantic:** persist resolution revisions ([cffa6ca](https://github.com/shilongfeicool/dev-flow/commit/cffa6ca24fb08b54bdd8e516167895e660c6eacc))
+
+
+
+
+
+## [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)
 
 

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.semantic-resolution.test.ts

@@ -0,0 +1,87 @@
+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 type { SemanticResolutionRecord } from '../src/semantic-resolution';
+
+describe('DevFlowDatabase semantic resolution persistence', () => {
+  let directory: string;
+  let database: DevFlowDatabase;
+
+  beforeEach(() => {
+    directory = mkdtempSync(join(tmpdir(), 'devflow-semantic-resolution-'));
+    database = new DevFlowDatabase(directory);
+  });
+
+  afterEach(() => {
+    database.close();
+    rmSync(directory, { recursive: true, force: true });
+  });
+
+  it('appends, lists, and returns the latest immutable revision', () => {
+    const provisional = resolution();
+    const resolved = resolution({
+      frameHash: 'b'.repeat(64),
+      artifactHash: 'artifact:2',
+      artifactRevision: 2,
+      supersedesFrameHash: provisional.frameHash,
+      state: 'resolved',
+      frame: { frameHash: 'b'.repeat(64), state: 'resolved' },
+      createdAt: 2,
+    });
+    expect(database.appendSemanticResolution(provisional)).toBe(true);
+    expect(database.appendSemanticResolution(resolved)).toBe(true);
+    expect(database.listSemanticResolutions('/project', 'session:1', 'turn:1'))
+      .toEqual([provisional, resolved]);
+    expect(database.getLatestSemanticResolution('/project', 'session:1', 'turn:1'))
+      .toEqual(resolved);
+  });
+
+  it('makes identical replay idempotent and rejects hash conflicts', () => {
+    const record = resolution();
+    expect(database.appendSemanticResolution(record)).toBe(true);
+    expect(database.appendSemanticResolution(record)).toBe(false);
+    expect(() => database.appendSemanticResolution({
+      ...record,
+      durationMs: 9,
+    })).toThrow(`SEMANTIC_RESOLUTION_HASH_CONFLICT:${record.frameHash}`);
+  });
+
+  it('rejects another frame at the same artifact revision', () => {
+    const record = resolution();
+    database.appendSemanticResolution(record);
+    expect(() => database.appendSemanticResolution({
+      ...record,
+      frameHash: 'c'.repeat(64),
+      frame: { frameHash: 'c'.repeat(64), state: 'provisional' },
+    })).toThrow('SEMANTIC_RESOLUTION_REVISION_CONFLICT:turn:1:1');
+  });
+});
+
+function resolution(overrides: Partial<SemanticResolutionRecord> = {}): SemanticResolutionRecord {
+  const frameHash = overrides.frameHash ?? 'a'.repeat(64);
+  return {
+    frameHash,
+    projectRoot: '/project',
+    projectId: 'project:1',
+    hostId: 'claude-code',
+    sessionId: 'session:1',
+    turnId: 'turn:1',
+    requestId: 'request:1',
+    sourceHash: 'source:1',
+    artifactHash: 'artifact:1',
+    artifactRevision: 1,
+    state: 'provisional',
+    generatedBy: 'deterministic',
+    routeCatalogVersion: 'catalog.v1',
+    thresholdVersion: 'threshold.v1',
+    route: { status: 'unavailable' },
+    sampling: { attempted: false, status: 'not_needed' },
+    conflicts: [],
+    frame: { frameHash, state: 'provisional' },
+    durationMs: 0,
+    createdAt: 1,
+    ...overrides,
+  };
+}

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,8 @@ 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';
+import { type SemanticResolutionRecord } from './semantic-resolution';
 export interface BenchmarkReportRecord {
     runId: string;
     suiteId: string;
@@ -389,6 +391,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;
@@ -426,6 +452,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;
@@ -441,6 +468,10 @@ export declare class DevFlowDatabase {
         sessionId: string;
         sourceHash: string;
     }): TaskIntentArtifactRecord | null;
+    appendSemanticResolution(record: SemanticResolutionRecord): boolean;
+    getSemanticResolution(frameHash: string): SemanticResolutionRecord | null;
+    getLatestSemanticResolution(projectRoot: string, sessionId: string, turnId: string): SemanticResolutionRecord | null;
+    listSemanticResolutions(projectRoot: string, sessionId: string, turnId: string): SemanticResolutionRecord[];
     listLatestTaskIntentArtifacts(projectRoot: string, sessionId: string): TaskIntentArtifactRecord[];
     appendChannelQueryPlan(record: ChannelQueryPlanRecord): ChannelQueryPlanRecord;
     getChannelQueryPlan(planHash: string): ChannelQueryPlanRecord | null;
@@ -457,6 +488,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;
@@ -515,6 +553,7 @@ export declare class DevFlowDatabase {
         turnId: string;
         receiptId: string;
         reason: string;
+        source?: string;
         decidedAt?: number;
     }): MemoryTurnRecord;
     markMemoryTurnStopPrompted(turnId: string, promptedAt?: number): boolean;