@devflow-tools/database 0.16.21 → 0.16.22

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [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/dist/database.d.ts

@@ -2,6 +2,7 @@ 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';
 export interface BenchmarkReportRecord {
     runId: string;
     suiteId: string;
@@ -325,6 +326,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;

package/dist/database.js

@@ -11,6 +11,7 @@ const crypto_1 = require("crypto");
 const obligation_ledger_1 = require("./obligation-ledger");
 const host_actions_1 = require("./host-actions");
 const retrieval_sessions_1 = require("./retrieval-sessions");
+const learning_candidates_1 = require("./learning-candidates");
 const CONTEXT_REQUIRED_SKILLS = new Set([
     'react', 'vue', 'nest', 'nextjs', 'graphql', 'typescript',
 ]);
@@ -477,6 +478,74 @@ class DevFlowDatabase {
       CREATE INDEX IF NOT EXISTS idx_session_closures_state
         ON devflow_session_closures(project_root, state, updated_at DESC);
 
+      CREATE TABLE IF NOT EXISTS devflow_learning_candidates (
+        id TEXT PRIMARY KEY,
+        project_root TEXT NOT NULL,
+        scope TEXT NOT NULL CHECK(scope IN ('project', 'global')),
+        state TEXT NOT NULL DEFAULT 'observed'
+          CHECK(state IN ('observed', 'candidate', 'shadow', 'evaluated', 'active', 'rejected', 'retired')),
+        kind TEXT NOT NULL CHECK(kind IN ('convention', 'workflow', 'tool_preference', 'correction')),
+        trigger_json TEXT NOT NULL,
+        instruction TEXT NOT NULL,
+        confidence REAL NOT NULL CHECK(confidence BETWEEN 0 AND 1),
+        overlay_version INTEGER NOT NULL DEFAULT 1 CHECK(overlay_version > 0),
+        supporting_sessions INTEGER NOT NULL DEFAULT 0 CHECK(supporting_sessions >= 0),
+        successful_outcomes INTEGER NOT NULL DEFAULT 0 CHECK(successful_outcomes >= 0),
+        contradictions INTEGER NOT NULL DEFAULT 0 CHECK(contradictions >= 0),
+        manual_only INTEGER NOT NULL DEFAULT 0 CHECK(manual_only IN (0, 1)),
+        risk TEXT NOT NULL DEFAULT 'low' CHECK(risk IN ('low', 'medium', 'high')),
+        grader_receipt TEXT,
+        expires_at INTEGER,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_learning_candidates_project
+        ON devflow_learning_candidates(project_root, state, kind, updated_at DESC);
+
+      CREATE TABLE IF NOT EXISTS devflow_learning_candidate_versions (
+        candidate_id TEXT NOT NULL,
+        version INTEGER NOT NULL CHECK(version > 0),
+        trigger_json TEXT NOT NULL,
+        instruction TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        PRIMARY KEY(candidate_id, version)
+      );
+
+      CREATE TABLE IF NOT EXISTS devflow_learning_candidate_evidence (
+        id TEXT PRIMARY KEY,
+        candidate_id TEXT NOT NULL,
+        project_root TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        execution_id TEXT,
+        memory_observation_id TEXT,
+        outcome_id TEXT,
+        source_type TEXT NOT NULL
+          CHECK(source_type IN ('memory', 'correction', 'workflow_outcome', 'tool_preference', 'convention', 'grader', 'manual')),
+        polarity TEXT NOT NULL CHECK(polarity IN ('supporting', 'contradicting')),
+        outcome TEXT NOT NULL DEFAULT 'unknown' CHECK(outcome IN ('positive', 'negative', 'unknown')),
+        evidence_hash TEXT NOT NULL,
+        receipt TEXT,
+        payload_json TEXT NOT NULL DEFAULT '{}',
+        created_at INTEGER NOT NULL,
+        resolved_at INTEGER,
+        UNIQUE(candidate_id, evidence_hash)
+      );
+      CREATE INDEX IF NOT EXISTS idx_learning_evidence_candidate
+        ON devflow_learning_candidate_evidence(candidate_id, polarity, resolved_at, created_at);
+
+      CREATE TABLE IF NOT EXISTS devflow_learning_activation_history (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        candidate_id TEXT NOT NULL,
+        from_state TEXT NOT NULL,
+        to_state TEXT NOT NULL,
+        reason TEXT NOT NULL,
+        grader_receipt TEXT,
+        manual_approval INTEGER NOT NULL DEFAULT 0 CHECK(manual_approval IN (0, 1)),
+        changed_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_learning_activation_candidate
+        ON devflow_learning_activation_history(candidate_id, changed_at DESC);
+
       CREATE TABLE IF NOT EXISTS devflow_host_actions (
         action_id TEXT PRIMARY KEY,
         run_id TEXT NOT NULL,
@@ -1815,6 +1884,245 @@ class DevFlowDatabase {
             total: Number(count?.total ?? 0),
         };
     }
+    // ---- Governed Learning ----
+    upsertLearningCandidate(input) {
+        if (!input.id.trim())
+            throw new Error('Learning candidate requires an ID');
+        if (!input.projectRoot.trim())
+            throw new Error('Learning candidate requires a project root');
+        if (!input.instruction.trim())
+            throw new Error('Learning candidate requires an instruction');
+        if (!Number.isFinite(input.confidence) || input.confidence < 0 || input.confidence > 1) {
+            throw new Error('Learning candidate confidence must be between 0 and 1');
+        }
+        return this.db.transaction(() => {
+            const now = Date.now();
+            const existing = this.getLearningCandidate(input.id);
+            const triggerJson = (0, learning_candidates_1.stableLearningJson)(input.trigger);
+            const instruction = input.instruction.trim().slice(0, 2000);
+            if (!existing) {
+                this.db.prepare(`
+          INSERT INTO devflow_learning_candidates (
+            id, project_root, scope, state, kind, trigger_json, instruction,
+            confidence, overlay_version, supporting_sessions, successful_outcomes,
+            contradictions, manual_only, risk, expires_at, created_at, updated_at
+          ) VALUES (?, ?, ?, 'observed', ?, ?, ?, ?, 1, 0, 0, 0, ?, ?, ?, ?, ?)
+        `).run(input.id, input.projectRoot, input.scope, input.kind, triggerJson, instruction, input.confidence, input.manualOnly ? 1 : 0, input.risk ?? 'low', input.expiresAt ?? null, now, now);
+                this.insertLearningCandidateVersion(input.id, 1, triggerJson, instruction, now);
+                return this.getLearningCandidate(input.id);
+            }
+            if (existing.projectRoot !== input.projectRoot || existing.scope !== input.scope || existing.kind !== input.kind) {
+                throw new Error(`Learning candidate identity mismatch for ${input.id}`);
+            }
+            const contentChanged = (0, learning_candidates_1.stableLearningJson)(existing.trigger) !== triggerJson
+                || existing.instruction !== instruction;
+            const nextVersion = contentChanged ? existing.overlayVersion + 1 : existing.overlayVersion;
+            const nextState = contentChanged && (existing.state === 'active' || existing.state === 'evaluated')
+                ? 'shadow'
+                : existing.state;
+            this.db.prepare(`
+        UPDATE devflow_learning_candidates
+        SET trigger_json = ?, instruction = ?, confidence = ?, overlay_version = ?,
+            state = ?, manual_only = MAX(manual_only, ?),
+            risk = CASE
+              WHEN risk = 'high' OR ? = 'high' THEN 'high'
+              WHEN risk = 'medium' OR ? = 'medium' THEN 'medium'
+              ELSE 'low'
+            END,
+            expires_at = ?, updated_at = ?
+        WHERE id = ?
+      `).run(triggerJson, instruction, Math.max(existing.confidence, input.confidence), nextVersion, nextState, input.manualOnly ? 1 : 0, input.risk ?? 'low', input.risk ?? 'low', input.expiresAt ?? existing.expiresAt ?? null, now, input.id);
+            if (contentChanged) {
+                this.insertLearningCandidateVersion(input.id, nextVersion, triggerJson, instruction, now);
+                if (nextState !== existing.state) {
+                    this.insertLearningActivation(input.id, existing.state, nextState, 'candidate_content_changed', undefined, false, now);
+                }
+            }
+            return this.getLearningCandidate(input.id);
+        });
+    }
+    getLearningCandidate(id) {
+        const row = this.db.prepare('SELECT * FROM devflow_learning_candidates WHERE id = ?')
+            .get(id);
+        return row ? (0, learning_candidates_1.mapLearningCandidateRow)(row) : null;
+    }
+    listLearningCandidates(options = {}) {
+        const predicates = [];
+        const params = [];
+        if (options.projectRoot) {
+            predicates.push('(project_root = ? OR scope = \'global\')');
+            params.push(options.projectRoot);
+        }
+        const states = [...new Set(options.states ?? [])];
+        if (states.length > 0) {
+            predicates.push(`state IN (${states.map(() => '?').join(',')})`);
+            params.push(...states);
+        }
+        const rows = this.db.prepare(`
+      SELECT * FROM devflow_learning_candidates
+      ${predicates.length > 0 ? `WHERE ${predicates.join(' AND ')}` : ''}
+      ORDER BY updated_at DESC, id ASC
+      LIMIT ?
+    `).all(...params, Math.max(1, Math.min(options.limit ?? 200, 2000)));
+        return rows.map(learning_candidates_1.mapLearningCandidateRow);
+    }
+    addLearningCandidateEvidence(input) {
+        if (!input.evidenceHash.trim())
+            throw new Error('Learning evidence requires a hash');
+        if (!input.sessionId.trim())
+            throw new Error('Learning evidence requires a session ID');
+        return this.db.transaction(() => {
+            const candidate = this.getLearningCandidate(input.candidateId);
+            if (!candidate)
+                throw new Error(`Learning candidate ${input.candidateId} does not exist`);
+            if (candidate.projectRoot !== input.projectRoot && candidate.scope !== 'global') {
+                throw new Error(`Learning evidence project mismatch for ${input.candidateId}`);
+            }
+            const createdAt = input.createdAt ?? Date.now();
+            const inserted = this.db.prepare(`
+        INSERT OR IGNORE INTO devflow_learning_candidate_evidence (
+          id, candidate_id, project_root, session_id, execution_id,
+          memory_observation_id, outcome_id, source_type, polarity, outcome,
+          evidence_hash, receipt, payload_json, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(input.id, input.candidateId, input.projectRoot, input.sessionId, input.executionId ?? null, input.memoryObservationId ?? null, input.outcomeId ?? null, input.sourceType, input.polarity, input.outcome ?? 'unknown', input.evidenceHash, input.receipt ?? null, (0, learning_candidates_1.stableLearningJson)(input.payload ?? {}), createdAt).changes === 1;
+            if (!inserted)
+                return candidate;
+            const previousState = candidate.state;
+            const aggregates = this.getLearningEvidenceAggregates(input.candidateId);
+            let state = previousState;
+            if (state === 'observed' && aggregates.supportingSessions > 0)
+                state = 'candidate';
+            if (aggregates.contradictions > 0 && (state === 'active' || state === 'evaluated'))
+                state = 'shadow';
+            this.db.prepare(`
+        UPDATE devflow_learning_candidates
+        SET state = ?, supporting_sessions = ?, successful_outcomes = ?,
+            contradictions = ?, updated_at = ?
+        WHERE id = ?
+      `).run(state, aggregates.supportingSessions, aggregates.successfulOutcomes, aggregates.contradictions, createdAt, input.candidateId);
+            if (state !== previousState) {
+                this.insertLearningActivation(input.candidateId, previousState, state, aggregates.contradictions > 0 ? 'unresolved_contradiction' : 'first_supporting_evidence', undefined, false, createdAt);
+            }
+            return this.getLearningCandidate(input.candidateId);
+        });
+    }
+    listLearningCandidateEvidence(candidateId) {
+        const rows = this.db.prepare(`
+      SELECT * FROM devflow_learning_candidate_evidence
+      WHERE candidate_id = ? ORDER BY created_at ASC, id ASC
+    `).all(candidateId);
+        return rows.map(learning_candidates_1.mapLearningEvidenceRow);
+    }
+    resolveLearningContradiction(candidateId, evidenceId, resolvedAt = Date.now()) {
+        return this.db.transaction(() => {
+            this.db.prepare(`
+        UPDATE devflow_learning_candidate_evidence
+        SET resolved_at = ?
+        WHERE id = ? AND candidate_id = ? AND polarity = 'contradicting' AND resolved_at IS NULL
+      `).run(resolvedAt, evidenceId, candidateId);
+            const aggregates = this.getLearningEvidenceAggregates(candidateId);
+            this.db.prepare(`
+        UPDATE devflow_learning_candidates
+        SET supporting_sessions = ?, successful_outcomes = ?, contradictions = ?, updated_at = ?
+        WHERE id = ?
+      `).run(aggregates.supportingSessions, aggregates.successfulOutcomes, aggregates.contradictions, resolvedAt, candidateId);
+            const candidate = this.getLearningCandidate(candidateId);
+            if (!candidate)
+                throw new Error(`Learning candidate ${candidateId} does not exist`);
+            return candidate;
+        });
+    }
+    transitionLearningCandidate(candidateId, input) {
+        return this.db.transaction(() => {
+            const candidate = this.getLearningCandidate(candidateId);
+            if (!candidate)
+                throw new Error(`Learning candidate ${candidateId} does not exist`);
+            if (candidate.state === input.target)
+                return candidate;
+            this.assertLearningTransition(candidate, input);
+            const changedAt = input.changedAt ?? Date.now();
+            const graderReceipt = input.graderReceipt ?? candidate.graderReceipt;
+            this.db.prepare(`
+        UPDATE devflow_learning_candidates
+        SET state = ?, grader_receipt = COALESCE(?, grader_receipt), updated_at = ?
+        WHERE id = ?
+      `).run(input.target, graderReceipt ?? null, changedAt, candidateId);
+            this.insertLearningActivation(candidateId, candidate.state, input.target, input.reason, graderReceipt, input.manualApproval === true, changedAt);
+            return this.getLearningCandidate(candidateId);
+        });
+    }
+    listLearningCandidateVersions(candidateId) {
+        const rows = this.db.prepare(`
+      SELECT * FROM devflow_learning_candidate_versions
+      WHERE candidate_id = ? ORDER BY version ASC
+    `).all(candidateId);
+        return rows.map(learning_candidates_1.mapLearningVersionRow);
+    }
+    assertLearningTransition(candidate, input) {
+        const terminal = input.target === 'rejected' || input.target === 'retired';
+        const rollback = input.target === 'shadow'
+            && (candidate.state === 'active' || candidate.state === 'evaluated');
+        const legal = {
+            observed: ['candidate', 'rejected', 'retired'],
+            candidate: ['shadow', 'rejected', 'retired'],
+            shadow: ['evaluated', 'rejected', 'retired'],
+            evaluated: ['active', 'shadow', 'rejected', 'retired'],
+            active: ['shadow', 'retired'],
+            rejected: ['retired'],
+            retired: [],
+        };
+        if (!terminal && !rollback && !legal[candidate.state].includes(input.target)) {
+            throw new Error(`Illegal learning transition ${candidate.state} -> ${input.target}`);
+        }
+        if (input.target === 'shadow') {
+            if (candidate.supportingSessions < 3 || candidate.successfulOutcomes < 2) {
+                throw new Error('Learning candidate requires three sessions and two verified outcomes before shadow');
+            }
+        }
+        if (input.target === 'evaluated' && candidate.contradictions > 0) {
+            throw new Error('Learning candidate has unresolved contradictions');
+        }
+        if (input.target === 'active') {
+            const receipt = input.graderReceipt ?? candidate.graderReceipt;
+            if (!receipt)
+                throw new Error('Learning candidate activation requires a grader receipt');
+            if (candidate.contradictions > 0)
+                throw new Error('Learning candidate has unresolved contradictions');
+            const manualRequired = candidate.scope === 'global' || candidate.manualOnly || candidate.risk === 'high';
+            if (manualRequired && input.manualApproval !== true) {
+                throw new Error('Learning candidate requires manual approval');
+            }
+        }
+    }
+    getLearningEvidenceAggregates(candidateId) {
+        const row = this.db.prepare(`
+      SELECT
+        COUNT(DISTINCT CASE WHEN polarity = 'supporting' THEN session_id END) AS supporting_sessions,
+        COUNT(DISTINCT CASE WHEN polarity = 'supporting' AND outcome = 'positive' THEN session_id END) AS successful_outcomes,
+        SUM(CASE WHEN polarity = 'contradicting' AND resolved_at IS NULL THEN 1 ELSE 0 END) AS contradictions
+      FROM devflow_learning_candidate_evidence WHERE candidate_id = ?
+    `).get(candidateId);
+        return {
+            supportingSessions: Number(row?.supporting_sessions ?? 0),
+            successfulOutcomes: Number(row?.successful_outcomes ?? 0),
+            contradictions: Number(row?.contradictions ?? 0),
+        };
+    }
+    insertLearningCandidateVersion(candidateId, version, triggerJson, instruction, createdAt) {
+        this.db.prepare(`
+      INSERT OR IGNORE INTO devflow_learning_candidate_versions
+        (candidate_id, version, trigger_json, instruction, created_at)
+      VALUES (?, ?, ?, ?, ?)
+    `).run(candidateId, version, triggerJson, instruction, createdAt);
+    }
+    insertLearningActivation(candidateId, fromState, toState, reason, graderReceipt, manualApproval, changedAt) {
+        this.db.prepare(`
+      INSERT INTO devflow_learning_activation_history
+        (candidate_id, from_state, to_state, reason, grader_receipt, manual_approval, changed_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(candidateId, fromState, toState, reason.trim().slice(0, 500), graderReceipt ?? null, manualApproval ? 1 : 0, changedAt);
+    }
     // ---- Durable Work Queue ----
     enqueueWork(input) {
         if (!input.idempotencyKey.trim())

package/dist/index.d.ts

@@ -6,4 +6,6 @@ export { RETRIEVAL_MAX_CYCLES, isRetrievalSessionState } from './retrieval-sessi
 export type { AppendRetrievalCycleInput, CreateRetrievalSessionInput, RetrievalCycleRecord, RetrievalGapKind, RetrievalGapRecord, RetrievalSessionRecord, RetrievalSessionState, } from './retrieval-sessions';
 export type { FailHostActionInput, HostActionRecord, HostActionState, ReportHostActionInput, RequestHostActionInput, StartHostActionInput, VerifyHostActionInput, } from './host-actions';
 export { mapSessionObligationRow, normalizeTurnId, } from './obligation-ledger';
+export { mapLearningCandidateRow, mapLearningEvidenceRow, mapLearningVersionRow, stableLearningJson, } from './learning-candidates';
+export type { AddLearningCandidateEvidenceInput, LearningCandidateEvidenceRecord, LearningCandidateKind, LearningCandidateRecord, LearningCandidateState, LearningCandidateVersionRecord, LearningEvidencePolarity, LearningOutcomeState, TransitionLearningCandidateInput, UpsertLearningCandidateInput, } from './learning-candidates';
 export type { SessionObligationKind, SessionObligationRecord, SessionObligationState, } from './obligation-ledger';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeTurnId = exports.mapSessionObligationRow = exports.isRetrievalSessionState = exports.RETRIEVAL_MAX_CYCLES = exports.serializeHostActionReport = exports.mapHostActionRow = exports.isHostActionState = exports.hostActionReportsEqual = exports.openGlobalDevFlowDatabase = exports.getGlobalDevFlowDbPath = exports.DevFlowDatabase = void 0;
+exports.stableLearningJson = exports.mapLearningVersionRow = exports.mapLearningEvidenceRow = exports.mapLearningCandidateRow = exports.normalizeTurnId = exports.mapSessionObligationRow = exports.isRetrievalSessionState = exports.RETRIEVAL_MAX_CYCLES = exports.serializeHostActionReport = exports.mapHostActionRow = exports.isHostActionState = exports.hostActionReportsEqual = exports.openGlobalDevFlowDatabase = exports.getGlobalDevFlowDbPath = exports.DevFlowDatabase = void 0;
 var database_1 = require("./database");
 Object.defineProperty(exports, "DevFlowDatabase", { enumerable: true, get: function () { return database_1.DevFlowDatabase; } });
 Object.defineProperty(exports, "getGlobalDevFlowDbPath", { enumerable: true, get: function () { return database_1.getGlobalDevFlowDbPath; } });
@@ -16,3 +16,8 @@ Object.defineProperty(exports, "isRetrievalSessionState", { enumerable: true, ge
 var obligation_ledger_1 = require("./obligation-ledger");
 Object.defineProperty(exports, "mapSessionObligationRow", { enumerable: true, get: function () { return obligation_ledger_1.mapSessionObligationRow; } });
 Object.defineProperty(exports, "normalizeTurnId", { enumerable: true, get: function () { return obligation_ledger_1.normalizeTurnId; } });
+var learning_candidates_1 = require("./learning-candidates");
+Object.defineProperty(exports, "mapLearningCandidateRow", { enumerable: true, get: function () { return learning_candidates_1.mapLearningCandidateRow; } });
+Object.defineProperty(exports, "mapLearningEvidenceRow", { enumerable: true, get: function () { return learning_candidates_1.mapLearningEvidenceRow; } });
+Object.defineProperty(exports, "mapLearningVersionRow", { enumerable: true, get: function () { return learning_candidates_1.mapLearningVersionRow; } });
+Object.defineProperty(exports, "stableLearningJson", { enumerable: true, get: function () { return learning_candidates_1.stableLearningJson; } });

package/dist/learning-candidates.d.ts

@@ -0,0 +1,87 @@
+export type LearningCandidateState = 'observed' | 'candidate' | 'shadow' | 'evaluated' | 'active' | 'rejected' | 'retired';
+export type LearningCandidateKind = 'convention' | 'workflow' | 'tool_preference' | 'correction';
+export type LearningEvidencePolarity = 'supporting' | 'contradicting';
+export type LearningOutcomeState = 'positive' | 'negative' | 'unknown';
+export interface LearningCandidateRecord {
+    id: string;
+    projectRoot: string;
+    scope: 'project' | 'global';
+    state: LearningCandidateState;
+    kind: LearningCandidateKind;
+    trigger: Record<string, unknown>;
+    instruction: string;
+    confidence: number;
+    overlayVersion: number;
+    supportingSessions: number;
+    successfulOutcomes: number;
+    contradictions: number;
+    manualOnly: boolean;
+    risk: 'low' | 'medium' | 'high';
+    graderReceipt?: string;
+    expiresAt?: number;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface LearningCandidateVersionRecord {
+    candidateId: string;
+    version: number;
+    trigger: Record<string, unknown>;
+    instruction: string;
+    createdAt: number;
+}
+export interface LearningCandidateEvidenceRecord {
+    id: string;
+    candidateId: string;
+    projectRoot: string;
+    sessionId: string;
+    executionId?: string;
+    memoryObservationId?: string;
+    outcomeId?: string;
+    sourceType: 'memory' | 'correction' | 'workflow_outcome' | 'tool_preference' | 'convention' | 'grader' | 'manual';
+    polarity: LearningEvidencePolarity;
+    outcome: LearningOutcomeState;
+    evidenceHash: string;
+    receipt?: string;
+    payload: Record<string, unknown>;
+    createdAt: number;
+    resolvedAt?: number;
+}
+export interface UpsertLearningCandidateInput {
+    id: string;
+    projectRoot: string;
+    scope: 'project' | 'global';
+    kind: LearningCandidateKind;
+    trigger: Record<string, unknown>;
+    instruction: string;
+    confidence: number;
+    manualOnly?: boolean;
+    risk?: 'low' | 'medium' | 'high';
+    expiresAt?: number;
+}
+export interface AddLearningCandidateEvidenceInput {
+    id: string;
+    candidateId: string;
+    projectRoot: string;
+    sessionId: string;
+    executionId?: string;
+    memoryObservationId?: string;
+    outcomeId?: string;
+    sourceType: LearningCandidateEvidenceRecord['sourceType'];
+    polarity: LearningEvidencePolarity;
+    outcome?: LearningOutcomeState;
+    evidenceHash: string;
+    receipt?: string;
+    payload?: Record<string, unknown>;
+    createdAt?: number;
+}
+export interface TransitionLearningCandidateInput {
+    target: LearningCandidateState;
+    reason: string;
+    graderReceipt?: string;
+    manualApproval?: boolean;
+    changedAt?: number;
+}
+export declare function mapLearningCandidateRow(row: Record<string, unknown>): LearningCandidateRecord;
+export declare function mapLearningEvidenceRow(row: Record<string, unknown>): LearningCandidateEvidenceRecord;
+export declare function mapLearningVersionRow(row: Record<string, unknown>): LearningCandidateVersionRecord;
+export declare function stableLearningJson(value: unknown): string;

package/dist/learning-candidates.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapLearningCandidateRow = mapLearningCandidateRow;
+exports.mapLearningEvidenceRow = mapLearningEvidenceRow;
+exports.mapLearningVersionRow = mapLearningVersionRow;
+exports.stableLearningJson = stableLearningJson;
+function mapLearningCandidateRow(row) {
+    return {
+        id: String(row.id),
+        projectRoot: String(row.project_root),
+        scope: row.scope === 'global' ? 'global' : 'project',
+        state: row.state,
+        kind: row.kind,
+        trigger: parseRecord(row.trigger_json),
+        instruction: String(row.instruction),
+        confidence: Number(row.confidence),
+        overlayVersion: Number(row.overlay_version),
+        supportingSessions: Number(row.supporting_sessions),
+        successfulOutcomes: Number(row.successful_outcomes),
+        contradictions: Number(row.contradictions),
+        manualOnly: Number(row.manual_only) === 1,
+        risk: row.risk === 'high' ? 'high' : row.risk === 'medium' ? 'medium' : 'low',
+        graderReceipt: optionalString(row.grader_receipt),
+        expiresAt: optionalNumber(row.expires_at),
+        createdAt: Number(row.created_at),
+        updatedAt: Number(row.updated_at),
+    };
+}
+function mapLearningEvidenceRow(row) {
+    return {
+        id: String(row.id),
+        candidateId: String(row.candidate_id),
+        projectRoot: String(row.project_root),
+        sessionId: String(row.session_id),
+        executionId: optionalString(row.execution_id),
+        memoryObservationId: optionalString(row.memory_observation_id),
+        outcomeId: optionalString(row.outcome_id),
+        sourceType: row.source_type,
+        polarity: row.polarity,
+        outcome: row.outcome,
+        evidenceHash: String(row.evidence_hash),
+        receipt: optionalString(row.receipt),
+        payload: parseRecord(row.payload_json),
+        createdAt: Number(row.created_at),
+        resolvedAt: optionalNumber(row.resolved_at),
+    };
+}
+function mapLearningVersionRow(row) {
+    return {
+        candidateId: String(row.candidate_id),
+        version: Number(row.version),
+        trigger: parseRecord(row.trigger_json),
+        instruction: String(row.instruction),
+        createdAt: Number(row.created_at),
+    };
+}
+function stableLearningJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableLearningJson).join(',')}]`;
+    if (!value || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    const record = value;
+    return `{${Object.keys(record).sort().map(key => `${JSON.stringify(key)}:${stableLearningJson(record[key])}`).join(',')}}`;
+}
+function parseRecord(value) {
+    try {
+        const parsed = typeof value === 'string' ? JSON.parse(value) : value;
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+function optionalString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function optionalNumber(value) {
+    return value === null || value === undefined ? undefined : Number(value);
+}