@devflow-tools/database 0.16.21 → 0.16.23

package/CHANGELOG.md

@@ -3,6 +3,29 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [0.16.23](https://github.com/shilongfeicool/dev-flow/compare/v0.16.22...v0.16.23) (2026-07-28)
+
+
+### Features
+
+* **database:** persist workflow worker lifecycle ([6f57fc7](https://github.com/shilongfeicool/dev-flow/commit/6f57fc7d7f13915b4f9b7faaa5e37c1a04182cad))
+* **workflow:** execute durable worker lifecycle ([799cc9d](https://github.com/shilongfeicool/dev-flow/commit/799cc9d341b6d4251717e20665654809ed84e29d))
+
+
+
+
+
+## [0.16.22](https://github.com/shilongfeicool/dev-flow/compare/v0.16.21...v0.16.22) (2026-07-28)
+
+
+### Features
+
+* **learning:** add governed overlays and evaluation ([795747d](https://github.com/shilongfeicool/dev-flow/commit/795747db10b3f13dfe5b442e8332673084774d5e))
+
+
+
+
+
 ## [0.16.21](https://github.com/shilongfeicool/dev-flow/compare/v0.16.20...v0.16.21) (2026-07-28)
 
 

package/__tests__/database.learning-candidates.test.ts

@@ -0,0 +1,93 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { DevFlowDatabase } from '../src/index.js';
+
+describe('governed learning candidates', () => {
+  const roots: string[] = [];
+
+  afterEach(() => {
+    for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+  });
+
+  it('requires independent evidence, grader receipt, and rolls active candidates back on contradiction', () => {
+    const root = mkdtempSync(join(tmpdir(), 'devflow-learning-db-'));
+    roots.push(root);
+    const database = new DevFlowDatabase(root);
+    const candidate = database.upsertLearningCandidate({
+      id: 'candidate:install-flag',
+      projectRoot: '/project',
+      scope: 'project',
+      kind: 'tool_preference',
+      trigger: { skills: ['devflow:react'], entities: ['--legacy-peer-deps'] },
+      instruction: 'Use --legacy-peer-deps when installing dependencies.',
+      confidence: 0.95,
+    });
+    expect(candidate.state).toBe('observed');
+
+    for (let index = 1; index <= 3; index += 1) {
+      database.addLearningCandidateEvidence({
+        id: `evidence:${index}`,
+        candidateId: candidate.id,
+        projectRoot: '/project',
+        sessionId: `session:${index}`,
+        sourceType: 'tool_preference',
+        polarity: 'supporting',
+        outcome: index <= 2 ? 'positive' : 'unknown',
+        evidenceHash: `hash:${index}`,
+      });
+    }
+    expect(database.getLearningCandidate(candidate.id)).toMatchObject({
+      state: 'candidate', supportingSessions: 3, successfulOutcomes: 2,
+    });
+    database.transitionLearningCandidate(candidate.id, { target: 'shadow', reason: 'threshold' });
+    database.transitionLearningCandidate(candidate.id, {
+      target: 'evaluated', reason: 'pass^3', graderReceipt: 'grader:receipt:12345678',
+    });
+    expect(database.transitionLearningCandidate(candidate.id, {
+      target: 'active', reason: 'automatic project activation',
+    }).state).toBe('active');
+
+    expect(database.addLearningCandidateEvidence({
+      id: 'evidence:contradiction',
+      candidateId: candidate.id,
+      projectRoot: '/project',
+      sessionId: 'session:4',
+      sourceType: 'correction',
+      polarity: 'contradicting',
+      outcome: 'positive',
+      evidenceHash: 'hash:contradiction',
+    })).toMatchObject({ state: 'shadow', contradictions: 1 });
+    database.close();
+  });
+
+  it('versions changed overlays and requires manual approval for global candidates', () => {
+    const root = mkdtempSync(join(tmpdir(), 'devflow-learning-version-'));
+    roots.push(root);
+    const database = new DevFlowDatabase(root);
+    const id = 'candidate:global';
+    database.upsertLearningCandidate({
+      id, projectRoot: '/project', scope: 'global', kind: 'convention',
+      trigger: {}, instruction: 'Use the first convention.', confidence: 0.8,
+    });
+    database.upsertLearningCandidate({
+      id, projectRoot: '/project', scope: 'global', kind: 'convention',
+      trigger: {}, instruction: 'Use the corrected convention.', confidence: 0.9,
+    });
+    expect(database.listLearningCandidateVersions(id)).toHaveLength(2);
+    for (let index = 1; index <= 3; index += 1) {
+      database.addLearningCandidateEvidence({
+        id: `global:${index}`, candidateId: id, projectRoot: '/project', sessionId: `s:${index}`,
+        sourceType: 'convention', polarity: 'supporting', outcome: 'positive', evidenceHash: `g:${index}`,
+      });
+    }
+    database.transitionLearningCandidate(id, { target: 'shadow', reason: 'threshold' });
+    database.transitionLearningCandidate(id, { target: 'evaluated', reason: 'graded', graderReceipt: 'grader:global:12345678' });
+    expect(() => database.transitionLearningCandidate(id, { target: 'active', reason: 'auto' }))
+      .toThrow('manual approval');
+    expect(database.transitionLearningCandidate(id, { target: 'active', reason: 'manual', manualApproval: true }).state)
+      .toBe('active');
+    database.close();
+  });
+});

package/__tests__/database.workflow-workers.test.ts

@@ -0,0 +1,60 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { DevFlowDatabase } from '../src/database.js';
+
+const roots: string[] = [];
+
+function open(): { db: DevFlowDatabase; root: string } {
+  const root = mkdtempSync(join(tmpdir(), 'devflow-workers-'));
+  roots.push(root);
+  return { db: new DevFlowDatabase(root), root };
+}
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe('workflow worker persistence', () => {
+  it('persists legal transitions and refuses terminal mutation', () => {
+    const { db, root } = open();
+    const worker = db.createWorkflowWorker({
+      runId: 'run-1', stepId: 'step-1', projectRoot: root,
+      branch: 'devflow/run-1/step-1', worktreePath: join(root, '.worker'),
+      host: 'codex', contextReceipt: 'receipt-1', baseRevision: 'a'.repeat(40),
+    });
+    db.leaseWorkflowWorker(root, worker.workerId, 'owner', 1_000, 100);
+    db.transitionWorkflowWorker({ projectRoot: root, workerId: worker.workerId, target: 'starting', leaseOwner: 'owner', now: 110 });
+    db.transitionWorkflowWorker({ projectRoot: root, workerId: worker.workerId, target: 'running', leaseOwner: 'owner', now: 120 });
+    db.transitionWorkflowWorker({ projectRoot: root, workerId: worker.workerId, target: 'failed', leaseOwner: 'owner', reason: 'test', now: 130 });
+    expect(() => db.transitionWorkflowWorker({ projectRoot: root, workerId: worker.workerId, target: 'hold' }))
+      .toThrow(/TERMINAL_CONFLICT/);
+    expect(db.listWorkflowWorkerEvents(root, worker.workerId)).toHaveLength(5);
+    db.close();
+  });
+
+  it('recovers expired leases to hold without retrying the worktree', () => {
+    const { db, root } = open();
+    const worker = db.createWorkflowWorker({
+      runId: 'run-2', stepId: 'step-2', projectRoot: root,
+      branch: 'devflow/run-2/step-2', worktreePath: join(root, '.worker-2'),
+      host: 'claude-code', contextReceipt: 'receipt-2', baseRevision: 'b'.repeat(40),
+    });
+    db.leaseWorkflowWorker(root, worker.workerId, 'owner', 10, 100);
+    expect(db.recoverExpiredWorkflowWorkers(root, 111)[0]?.state).toBe('hold');
+    db.close();
+  });
+
+  it('keeps merge queue insertion idempotent', () => {
+    const { db, root } = open();
+    const input = {
+      workerId: 'worker-3', projectRoot: root, baseRevision: 'a', parentRevision: 'b',
+      candidateRevision: 'c', graderReceipts: ['grader:1'], simulationHash: 'sha256:1',
+    };
+    const first = db.enqueueWorkflowMerge(input);
+    expect(db.enqueueWorkflowMerge(input).mergeId).toBe(first.mergeId);
+    expect(db.transitionWorkflowMerge(root, first.mergeId, 'ready').state).toBe('ready');
+    db.close();
+  });
+});

package/dist/database.d.ts

@@ -2,6 +2,8 @@ import type { EnqueueWorkInput, LeaseWorkInput, RequestSessionClosureInput, Sess
 import { type SessionObligationRecord, type SessionObligationState } from './obligation-ledger';
 import { type FailHostActionInput, type HostActionRecord, type ReportHostActionInput, type RequestHostActionInput, type StartHostActionInput, type VerifyHostActionInput } from './host-actions';
 import { type AppendRetrievalCycleInput, type CreateRetrievalSessionInput, type RetrievalCycleRecord, type RetrievalSessionRecord, type RetrievalSessionState } from './retrieval-sessions';
+import { type AddLearningCandidateEvidenceInput, type LearningCandidateEvidenceRecord, type LearningCandidateRecord, type LearningCandidateState, type LearningCandidateVersionRecord, type TransitionLearningCandidateInput, type UpsertLearningCandidateInput } from './learning-candidates';
+import { type CreateWorkflowWorkerInput, type EnqueueWorkflowMergeInput, type TransitionWorkflowWorkerInput, type WorkflowMergeRecord, type WorkflowMergeState, type WorkflowWorkerEventRecord, type WorkflowWorkerRecord } from './workflow-workers';
 export interface BenchmarkReportRecord {
     runId: string;
     suiteId: string;
@@ -325,6 +327,22 @@ export declare class DevFlowDatabase {
         items: GovernanceAuditRecord[];
         total: number;
     };
+    upsertLearningCandidate(input: UpsertLearningCandidateInput): LearningCandidateRecord;
+    getLearningCandidate(id: string): LearningCandidateRecord | null;
+    listLearningCandidates(options?: {
+        projectRoot?: string;
+        states?: LearningCandidateState[];
+        limit?: number;
+    }): LearningCandidateRecord[];
+    addLearningCandidateEvidence(input: AddLearningCandidateEvidenceInput): LearningCandidateRecord;
+    listLearningCandidateEvidence(candidateId: string): LearningCandidateEvidenceRecord[];
+    resolveLearningContradiction(candidateId: string, evidenceId: string, resolvedAt?: number): LearningCandidateRecord;
+    transitionLearningCandidate(candidateId: string, input: TransitionLearningCandidateInput): LearningCandidateRecord;
+    listLearningCandidateVersions(candidateId: string): LearningCandidateVersionRecord[];
+    private assertLearningTransition;
+    private getLearningEvidenceAggregates;
+    private insertLearningCandidateVersion;
+    private insertLearningActivation;
     enqueueWork(input: EnqueueWorkInput): WorkItemRecord;
     getWorkByIdempotencyKey(idempotencyKey: string): WorkItemRecord | null;
     requestSessionClosure(input: RequestSessionClosureInput): SessionClosureRecord;
@@ -333,6 +351,7 @@ export declare class DevFlowDatabase {
     listSessionClosures(projectRoot: string, limit?: number): SessionClosureRecord[];
     leaseWork(input: LeaseWorkInput): WorkItemRecord[];
     completeWork(id: string, owner: string, now?: number): boolean;
+    heartbeatWork(id: string, owner: string, leaseMs: number, now?: number): boolean;
     retryWork(id: string, owner: string, error: WorkError, nextAttemptAt: number): boolean;
     deferWork(id: string, owner: string, error: WorkError, nextAttemptAt: number): boolean;
     deadLetterWork(id: string, owner: string, error: WorkError): boolean;
@@ -431,6 +450,29 @@ export declare class DevFlowDatabase {
     private withImmediateTransaction;
     private isTerminalHostActionState;
     private isLegalHostActionTransition;
+    createWorkflowWorker(input: CreateWorkflowWorkerInput): WorkflowWorkerRecord;
+    getWorkflowWorker(projectRoot: string, workerId: string): WorkflowWorkerRecord | null;
+    listWorkflowWorkers(projectRoot: string, options?: {
+        states?: WorkflowWorkerRecord['state'][];
+        runId?: string;
+        limit?: number;
+    }): WorkflowWorkerRecord[];
+    listWorkflowWorkerEvents(projectRoot: string, workerId: string): WorkflowWorkerEventRecord[];
+    leaseWorkflowWorker(projectRoot: string, workerId: string, owner: string, leaseMs: number, now?: number): WorkflowWorkerRecord;
+    heartbeatWorkflowWorker(projectRoot: string, workerId: string, owner: string, leaseMs: number, now?: number): WorkflowWorkerRecord;
+    transitionWorkflowWorker(input: TransitionWorkflowWorkerInput): WorkflowWorkerRecord;
+    recoverExpiredWorkflowWorkers(projectRoot: string, now?: number): WorkflowWorkerRecord[];
+    enqueueWorkflowMerge(input: EnqueueWorkflowMergeInput): WorkflowMergeRecord;
+    getWorkflowMerge(projectRoot: string, mergeId: string): WorkflowMergeRecord | null;
+    getWorkflowMergeByWorker(projectRoot: string, workerId: string): WorkflowMergeRecord | null;
+    listWorkflowMerges(projectRoot: string, limit?: number): WorkflowMergeRecord[];
+    transitionWorkflowMerge(projectRoot: string, mergeId: string, target: WorkflowMergeState, update?: {
+        parentRevision?: string;
+        simulationHash?: string;
+        mergeCommit?: string;
+        reason?: string;
+    }, now?: number): WorkflowMergeRecord;
+    private appendWorkflowWorkerEvent;
     all(sql: string, ...params: unknown[]): unknown[];
     get(sql: string, ...params: unknown[]): unknown;
     close(): void;