@devflow-tools/database 0.16.9 → 0.16.11

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [0.16.10](https://github.com/shilongfeicool/dev-flow/compare/v0.16.9...v0.16.10) (2026-07-24)
+
+
+### Bug Fixes
+
+* **telemetry:** persist compliance failure facts ([fcb5a8b](https://github.com/shilongfeicool/dev-flow/commit/fcb5a8b4db37fc545927262ae841669395491b06))
+
+
+### Features
+
+* **memory:** add canonical turn and explicit receipts ([eb3e178](https://github.com/shilongfeicool/dev-flow/commit/eb3e1786e17f5dbc2c4e12e4fa788af7095d335e))
+
+
+
+
+
 ## [0.16.9](https://github.com/shilongfeicool/dev-flow/compare/v0.16.8...v0.16.9) (2026-07-23)
 
 **Note:** Version bump only for package @devflow-tools/database

package/__tests__/database.memory-turn-receipts.test.ts

@@ -0,0 +1,71 @@
+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';
+
+describe('DevFlowDatabase memory turn receipts', () => {
+  let directory: string;
+  let database: DevFlowDatabase;
+
+  beforeEach(() => {
+    directory = mkdtempSync(join(tmpdir(), 'devflow-memory-turn-'));
+    database = new DevFlowDatabase(directory);
+  });
+
+  afterEach(() => {
+    database.close();
+    rmSync(directory, { recursive: true, force: true });
+  });
+
+  it('commits a pending turn with one canonical receipt', () => {
+    database.beginMemoryTurn({
+      turnId: 'turn:1',
+      projectRoot: '/project',
+      sessionId: 'session-1',
+      promptHash: 'hash',
+      eventId: 'event-1',
+      createdAt: 100,
+    });
+
+    const committed = database.commitMemoryTurn({
+      turnId: 'turn:1',
+      receiptId: 'memory-receipt:1',
+      memoryIds: ['memory-1'],
+      source: 'explicit_intent',
+      decidedAt: 200,
+    });
+
+    expect(committed).toMatchObject({
+      status: 'committed',
+      receiptId: 'memory-receipt:1',
+      memoryIds: ['memory-1'],
+      stopPromptedAt: undefined,
+    });
+    expect(database.getPendingMemoryTurn('/project', 'session-1')).toBeNull();
+  });
+
+  it('marks a pending Stop prompt only once and supports skip receipts', () => {
+    database.beginMemoryTurn({
+      turnId: 'turn:2',
+      projectRoot: '/project',
+      sessionId: 'session-1',
+      promptHash: 'hash-2',
+      eventId: 'event-2',
+      createdAt: 300,
+    });
+
+    expect(database.markMemoryTurnStopPrompted('turn:2', 350)).toBe(true);
+    expect(database.markMemoryTurnStopPrompted('turn:2', 360)).toBe(false);
+    expect(database.skipMemoryTurn({
+      turnId: 'turn:2',
+      receiptId: 'memory-receipt:2',
+      reason: 'transient request',
+      decidedAt: 400,
+    })).toMatchObject({
+      status: 'skipped',
+      reason: 'transient request',
+      stopPromptedAt: 350,
+    });
+  });
+});

package/__tests__/database.skill-executions.test.ts

@@ -154,19 +154,19 @@ describe('DevFlowDatabase - Skill Executions', () => {
       eventId: 'evt_context_1', executionId: 'exec_001', timestamp: Date.now(),
       toolName: 'mcp__devflow__get_project_context', toolType: 'mcp',
       isMcpTool: true, mcpToolName: 'get_project_context', mcpEnforced: true,
-      mcpFallback: false, input: {}, duration: 20, blocked: false,
+      mcpFallback: false, input: {}, output: { files: ['src/App.tsx'] }, duration: 20, blocked: false,
     });
     db.insertToolCallEvent({
       eventId: 'evt_001', executionId: 'exec_001', timestamp: Date.now(),
       toolName: 'mcp__devflow__react_diagnose_bug', toolType: 'mcp',
       isMcpTool: true, mcpEnforced: true, mcpFallback: false,
-      input: {}, tokensUsed: 100, duration: 500, blocked: false,
+      input: {}, output: { findings: [{ id: 'finding-1' }] }, tokensUsed: 100, duration: 500, blocked: false,
     });
     db.insertToolCallEvent({
       eventId: 'evt_002', executionId: 'exec_001', timestamp: Date.now(),
       toolName: 'mcp__devflow__react_review_hooks', toolType: 'mcp',
       isMcpTool: true, mcpEnforced: true, mcpFallback: false,
-      input: {}, tokensUsed: 100, duration: 500, blocked: false,
+      input: {}, output: { findings: [{ id: 'finding-2' }] }, tokensUsed: 100, duration: 500, blocked: false,
     });
     db.insertToolCallEvent({
       eventId: 'evt_003', executionId: 'exec_001', timestamp: Date.now(),
@@ -186,13 +186,13 @@ describe('DevFlowDatabase - Skill Executions', () => {
       eventId: 'evt_context_2', executionId: 'exec_002', timestamp: Date.now(),
       toolName: 'mcp__devflow__get_project_context', toolType: 'mcp',
       isMcpTool: true, mcpToolName: 'get_project_context', mcpEnforced: true,
-      mcpFallback: false, input: {}, duration: 20, blocked: false,
+      mcpFallback: false, input: {}, output: { files: ['src/App.vue'] }, duration: 20, blocked: false,
     });
     db.insertToolCallEvent({
       eventId: 'evt_004', executionId: 'exec_002', timestamp: Date.now(),
       toolName: 'mcp__devflow__vue_diagnose_bug', toolType: 'mcp',
       isMcpTool: true, mcpEnforced: true, mcpFallback: false,
-      input: {}, tokensUsed: 100, duration: 500, blocked: false,
+      input: {}, output: { findings: [{ id: 'finding-vue' }] }, tokensUsed: 100, duration: 500, blocked: false,
     });
 
     const compliance = db.getMcpCompliance();
@@ -204,6 +204,61 @@ describe('DevFlowDatabase - Skill Executions', () => {
     expect(compliance.mcpCallShare).toBeCloseTo(83.33, 1);
   });
 
+  it('persists missed tools, actual failures, and fallback reasons on reconciliation', () => {
+    db.ensureSession({ id: 'session-facts', projectRoot: '/project', startedAt: 100 });
+    db.insertSkillExecution({
+      executionId: 'exec-facts',
+      sessionId: 'session-facts',
+      skillName: 'devflow:react',
+      startedAt: 100,
+      status: 'running',
+    });
+    db.insertToolCallEvent({
+      eventId: 'event-failed', executionId: 'exec-facts', sessionId: 'session-facts', timestamp: 150,
+      toolName: 'mcp__devflow__get_project_context', toolType: 'mcp', isMcpTool: true,
+      mcpToolName: 'get_project_context', mcpEnforced: true, mcpFallback: false,
+      input: {}, error: 'route failed', duration: 20, blocked: false,
+    });
+    db.insertToolCallEvent({
+      eventId: 'event-fallback', executionId: 'exec-facts', sessionId: 'session-facts', timestamp: 160,
+      toolName: 'Read', toolType: 'direct', isMcpTool: false, mcpEnforced: false,
+      mcpFallback: true, input: {}, output: { content: 'fallback' }, duration: 10, blocked: false,
+    });
+    db.insertToolCallEvent({
+      eventId: 'event-memory-receipt', executionId: 'exec-facts', sessionId: 'session-facts', timestamp: 165,
+      toolName: 'mcp__devflow__memory_commit_turn', toolType: 'mcp', isMcpTool: true,
+      mcpToolName: 'memory_commit_turn', mcpEnforced: true, mcpFallback: false,
+      input: {}, output: { receiptId: 'memory-receipt:host-commit' }, duration: 5, blocked: false,
+    });
+    db.insertToolCallEvent({
+      eventId: 'event-distill-receipt', executionId: 'exec-facts', sessionId: 'session-facts', timestamp: 166,
+      toolName: 'mcp__devflow__memory_save_distilled', toolType: 'mcp', isMcpTool: true,
+      mcpToolName: 'memory_save_distilled', mcpEnforced: true, mcpFallback: false,
+      input: {}, output: { receipt: { receiptId: 'distill-receipt:batch-1' } }, duration: 5, blocked: false,
+    });
+    db.insertHookFallback({
+      id: 'hook-fallback-1', projectRoot: '/project', sessionId: 'session-facts',
+      requestType: 'post-tool-use', tool: 'Read', reason: 'timeout', durationMs: 1_000,
+      attempts: 1, createdAt: 170,
+    });
+
+    db.reconcileSkillExecution('exec-facts', 'completed', 200);
+
+    expect(db.getSkillExecution('exec-facts')).toMatchObject({
+      missedMcpTools: ['react:context', 'react:domain'],
+      failedToolCalls: 1,
+      blockedToolCalls: 0,
+      fallbackCount: 2,
+      fallbackReasons: ['direct_tool_during_context', 'daemon_timeout'],
+      metadata: expect.objectContaining({
+        actualFailureCount: 1,
+        fallbackCount: 2,
+        memoryReceiptIds: ['memory-receipt:host-commit'],
+        distillReceiptIds: ['distill-receipt:batch-1'],
+      }),
+    });
+  });
+
   it('aggregates an empty findings collection as an empty result', () => {
     db.insertSkillExecution({
       executionId: 'exec_empty_findings',
@@ -305,4 +360,36 @@ describe('DevFlowDatabase - Skill Executions', () => {
       }),
     );
   });
+
+  it('reconciles every running execution owned by a closing session', () => {
+    for (const executionId of ['exec_implicit_a', 'exec_implicit_b']) {
+      db.insertSkillExecution({
+        executionId,
+        sessionId: 'session-closing',
+        skillName: 'devflow:implicit',
+        startedAt: 1_000,
+        status: 'running',
+      });
+    }
+    db.insertSkillExecution({
+      executionId: 'exec_other_session',
+      sessionId: 'session-other',
+      skillName: 'devflow:implicit',
+      startedAt: 1_000,
+      status: 'running',
+    });
+
+    const reconciled = db.reconcileRunningSkillExecutionsForSession(
+      'session-closing',
+      5_000,
+      { closureReason: 'session_finalize' },
+    );
+
+    expect(reconciled.map(execution => execution.executionId)).toEqual([
+      'exec_implicit_a',
+      'exec_implicit_b',
+    ]);
+    expect(reconciled.every(execution => execution.status === 'completed')).toBe(true);
+    expect(db.getSkillExecution('exec_other_session')).toMatchObject({ status: 'running' });
+  });
 });

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

@@ -0,0 +1,240 @@
+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';
+
+describe('DevFlowDatabase durable work queue', () => {
+  let directory: string;
+  let database: DevFlowDatabase;
+  const projectRoot = '/project';
+
+  beforeEach(() => {
+    directory = mkdtempSync(join(tmpdir(), 'devflow-work-queue-'));
+    database = new DevFlowDatabase(directory);
+  });
+
+  afterEach(() => {
+    database.close();
+    rmSync(directory, { recursive: true, force: true });
+  });
+
+  it('returns the existing item for an idempotency conflict without resetting completed work', () => {
+    const first = database.enqueueWork({
+      idempotencyKey: 'memory:session-1:turn-1',
+      kind: 'memory.explicit_commit',
+      projectRoot,
+      sessionId: 'session-1',
+      turnId: 'turn-1',
+      payload: { text: 'remember this' },
+      nextAttemptAt: 10,
+    });
+    const [leased] = database.leaseWork({
+      projectRoot,
+      owner: 'worker-a',
+      limit: 1,
+      leaseMs: 100,
+      now: 10,
+    });
+    expect(leased?.id).toBe(first.id);
+    expect(database.completeWork(first.id, 'worker-a', 20)).toBe(true);
+
+    const duplicate = database.enqueueWork({
+      idempotencyKey: 'memory:session-1:turn-1',
+      kind: 'telemetry.reconcile',
+      projectRoot: '/different-project',
+      payload: { replacement: true },
+      maxAttempts: 1,
+      nextAttemptAt: 999,
+    });
+
+    expect(duplicate).toMatchObject({
+      id: first.id,
+      kind: 'memory.explicit_commit',
+      projectRoot,
+      payload: { text: 'remember this' },
+      state: 'completed',
+      attempts: 1,
+      maxAttempts: 5,
+      completedAt: 20,
+    });
+    expect(database.all('SELECT id FROM devflow_work_items')).toHaveLength(1);
+  });
+
+  it('leases atomically across database connections and requires the lease owner to complete', () => {
+    database.enqueueWork({
+      idempotencyKey: 'session:finalize:1',
+      kind: 'session.finalize',
+      projectRoot,
+      payload: { sessionId: 'session-1' },
+      nextAttemptAt: 100,
+    });
+    const secondConnection = new DevFlowDatabase(directory);
+    try {
+      const firstLease = database.leaseWork({
+        projectRoot,
+        owner: 'worker-a',
+        kinds: ['session.finalize'],
+        limit: 1,
+        leaseMs: 1_000,
+        now: 100,
+      });
+      const competingLease = secondConnection.leaseWork({
+        projectRoot,
+        owner: 'worker-b',
+        limit: 1,
+        leaseMs: 1_000,
+        now: 100,
+      });
+
+      expect(firstLease).toHaveLength(1);
+      expect(firstLease[0]).toMatchObject({
+        state: 'leased',
+        attempts: 1,
+        leaseOwner: 'worker-a',
+        leaseExpiresAt: 1_100,
+      });
+      expect(competingLease).toEqual([]);
+      expect(secondConnection.completeWork(firstLease[0]!.id, 'worker-b', 200)).toBe(false);
+      expect(database.completeWork(firstLease[0]!.id, 'worker-a', 200)).toBe(true);
+      expect(database.completeWork(firstLease[0]!.id, 'worker-a', 201)).toBe(false);
+    } finally {
+      secondConnection.close();
+    }
+  });
+
+  it('applies owner and state predicates to retries and dead letters', () => {
+    const item = database.enqueueWork({
+      idempotencyKey: 'telemetry:reconcile:1',
+      kind: 'telemetry.reconcile',
+      projectRoot,
+      payload: {},
+      nextAttemptAt: 50,
+    });
+    database.leaseWork({
+      projectRoot,
+      owner: 'worker-a',
+      limit: 1,
+      leaseMs: 100,
+      now: 50,
+    });
+
+    expect(database.retryWork(
+      item.id,
+      'worker-b',
+      { category: 'temporary', message: 'try again' },
+      75,
+    )).toBe(false);
+    expect(database.retryWork(
+      item.id,
+      'worker-a',
+      { category: 'temporary', message: 'try again' },
+      75,
+    )).toBe(true);
+    expect(database.getWorkQueueHealth(projectRoot, 75)).toMatchObject({
+      queueDepth: 1,
+      failed: 1,
+      deadLetters: 0,
+    });
+
+    const [retried] = database.leaseWork({
+      projectRoot,
+      owner: 'worker-b',
+      limit: 1,
+      leaseMs: 100,
+      now: 75,
+    });
+    expect(retried).toMatchObject({ attempts: 2, errorCategory: 'temporary' });
+    expect(database.deadLetterWork(
+      item.id,
+      'worker-a',
+      { category: 'invalid_schema', message: 'payload is invalid' },
+    )).toBe(false);
+    expect(database.deadLetterWork(
+      item.id,
+      'worker-b',
+      { category: 'invalid_schema', message: 'payload is invalid' },
+    )).toBe(true);
+    expect(database.deadLetterWork(
+      item.id,
+      'worker-b',
+      { category: 'invalid_schema', message: 'payload is invalid' },
+    )).toBe(false);
+    expect(database.getWorkQueueHealth(projectRoot, 80)).toMatchObject({
+      queueDepth: 0,
+      deadLetters: 1,
+    });
+  });
+
+  it('recovers expired leases and dead-letters exhausted work', () => {
+    database.enqueueWork({
+      idempotencyKey: 'memory:distill:retryable',
+      kind: 'memory.turn_distill',
+      projectRoot,
+      payload: {},
+      maxAttempts: 2,
+      nextAttemptAt: 100,
+    });
+    database.enqueueWork({
+      idempotencyKey: 'memory:vector:exhausted',
+      kind: 'memory.vector_backfill',
+      projectRoot,
+      payload: {},
+      maxAttempts: 1,
+      nextAttemptAt: 100,
+    });
+    database.leaseWork({
+      projectRoot,
+      owner: 'worker-a',
+      limit: 2,
+      leaseMs: 10,
+      now: 100,
+    });
+
+    expect(database.getWorkQueueHealth(projectRoot, 110)).toMatchObject({
+      queueDepth: 2,
+      leased: 2,
+      expiredLeases: 2,
+    });
+    expect(database.recoverExpiredWork(projectRoot, 110)).toBe(2);
+    expect(database.getWorkQueueHealth(projectRoot, 110)).toMatchObject({
+      queueDepth: 1,
+      leased: 0,
+      failed: 1,
+      expiredLeases: 0,
+      deadLetters: 1,
+    });
+
+    const recovered = database.leaseWork({
+      projectRoot,
+      owner: 'worker-b',
+      limit: 2,
+      leaseMs: 20,
+      now: 110,
+    });
+    expect(recovered).toHaveLength(1);
+    expect(recovered[0]).toMatchObject({
+      idempotencyKey: 'memory:distill:retryable',
+      state: 'leased',
+      attempts: 2,
+      leaseOwner: 'worker-b',
+      errorCategory: 'lease_expired',
+    });
+
+    const revived = database.enqueueWork({
+      idempotencyKey: 'memory:vector:exhausted',
+      kind: 'memory.vector_backfill',
+      projectRoot,
+      payload: {},
+      maxAttempts: 20,
+      nextAttemptAt: 120,
+    });
+    expect(revived).toMatchObject({
+      state: 'failed',
+      attempts: 1,
+      maxAttempts: 20,
+      nextAttemptAt: 120,
+      errorCategory: undefined,
+    });
+  });
+});

package/dist/database.d.ts

@@ -1,3 +1,4 @@
+import type { EnqueueWorkInput, LeaseWorkInput, RequestSessionClosureInput, SessionClosureRecord, WorkError, WorkItemRecord, WorkQueueHealth } from './work-queue';
 export interface BenchmarkReportRecord {
     runId: string;
     suiteId: string;
@@ -83,6 +84,34 @@ export interface MemoryDistillCheckpointRecord {
     releasedLeases: number;
     createdAt: number;
 }
+export type MemoryTurnStatus = 'pending' | 'committed' | 'skipped';
+export interface MemoryTurnRecord {
+    turnId: string;
+    projectRoot: string;
+    sessionId: string;
+    promptHash: string;
+    eventId: string;
+    status: MemoryTurnStatus;
+    receiptId?: string;
+    memoryIds: string[];
+    source?: string;
+    reason?: string;
+    stopPromptedAt?: number;
+    createdAt: number;
+    decidedAt?: number;
+}
+export interface HookFallbackRecord {
+    id: string;
+    projectRoot: string;
+    sessionId?: string;
+    toolUseId?: string;
+    requestType: string;
+    tool: string;
+    reason: 'timeout' | 'unreachable' | 'protocol' | 'unknown';
+    durationMs: number;
+    attempts: number;
+    createdAt: number;
+}
 export declare function getGlobalDevFlowDbPath(home?: string): string;
 export declare function openGlobalDevFlowDatabase(home?: string, options?: {
     busyTimeoutMs?: number;
@@ -145,6 +174,10 @@ export declare class DevFlowDatabase {
         totalDuration?: number;
         mcpComplianceRate?: number;
         missedMcpTools?: string[];
+        failedToolCalls?: number;
+        blockedToolCalls?: number;
+        fallbackCount?: number;
+        fallbackReasons?: string[];
         totalToolCalls?: number;
         mcpToolCalls?: number;
         directToolCalls?: number;
@@ -185,6 +218,7 @@ export declare class DevFlowDatabase {
     }): boolean;
     markToolCallBlocked(eventId: string, reason: string): boolean;
     reconcileSkillExecution(executionId: string, status: 'completed' | 'failed', finishedAt?: number, metadata?: Record<string, unknown>): void;
+    reconcileRunningSkillExecutionsForSession(sessionId: string, finishedAt?: number, metadata?: Record<string, unknown>): any[];
     getExecutionObligationCompliance(executionId: string): {
         rate: number;
         applicable: number;
@@ -268,6 +302,21 @@ export declare class DevFlowDatabase {
         items: GovernanceAuditRecord[];
         total: number;
     };
+    enqueueWork(input: EnqueueWorkInput): WorkItemRecord;
+    getWorkByIdempotencyKey(idempotencyKey: string): WorkItemRecord | null;
+    requestSessionClosure(input: RequestSessionClosureInput): SessionClosureRecord;
+    getSessionClosure(projectRoot: string, sessionId: string): SessionClosureRecord | null;
+    completeSessionClosure(projectRoot: string, sessionId: string, excludingWorkItemId?: string, closedAt?: number): SessionClosureRecord;
+    listSessionClosures(projectRoot: string, limit?: number): SessionClosureRecord[];
+    leaseWork(input: LeaseWorkInput): WorkItemRecord[];
+    completeWork(id: string, owner: string, now?: number): boolean;
+    retryWork(id: string, owner: string, error: WorkError, nextAttemptAt: number): boolean;
+    deadLetterWork(id: string, owner: string, error: WorkError): boolean;
+    recoverExpiredWork(projectRoot: string, now?: number): number;
+    getWorkQueueHealth(projectRoot: string, now?: number): WorkQueueHealth;
+    private mapWorkItem;
+    private mapSessionClosure;
+    private refreshClosedSessionClosure;
     getHookReceipt(projectRoot: string): HookReceiptRecord | null;
     updateHookReceipt(projectRoot: string, updater: (current: HookReceiptRecord | null) => Omit<HookReceiptRecord, 'projectRoot' | 'updatedAt'>): HookReceiptRecord;
     deleteHookReceipt(projectRoot: string): boolean;
@@ -275,6 +324,34 @@ export declare class DevFlowDatabase {
     getContextReceipt(projectRoot: string, sessionId: string, executionId: string): ContextReceiptRecord | null;
     deleteContextReceipt(projectRoot: string, sessionId: string, executionId?: string): number;
     purgeExpiredContextReceipts(now?: number): number;
+    beginMemoryTurn(input: Omit<MemoryTurnRecord, 'status' | 'memoryIds'>): MemoryTurnRecord;
+    getMemoryTurn(turnId: string): MemoryTurnRecord | null;
+    getPendingMemoryTurn(projectRoot: string, sessionId: string): MemoryTurnRecord | null;
+    commitMemoryTurn(input: {
+        turnId: string;
+        receiptId: string;
+        memoryIds: string[];
+        source: string;
+        reason?: string;
+        decidedAt?: number;
+    }): MemoryTurnRecord;
+    skipMemoryTurn(input: {
+        turnId: string;
+        receiptId: string;
+        reason: string;
+        decidedAt?: number;
+    }): MemoryTurnRecord;
+    markMemoryTurnStopPrompted(turnId: string, promptedAt?: number): boolean;
+    listMemoryTurns(projectRoot: string, sessionId?: string, limit?: number): MemoryTurnRecord[];
+    insertHookFallback(record: HookFallbackRecord): boolean;
+    listHookFallbacks(filter?: {
+        projectRoot?: string;
+        sessionId?: string;
+        from?: number;
+        to?: number;
+        limit?: number;
+    }): HookFallbackRecord[];
+    private mapMemoryTurn;
     recordMemoryDistillCheckpoint(checkpoint: MemoryDistillCheckpointRecord): void;
     listMemoryDistillCheckpoints(projectRoot: string, limit?: number): MemoryDistillCheckpointRecord[];
     all(sql: string, ...params: unknown[]): unknown[];