@devflow-tools/database 0.17.0 → 0.17.1

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [0.17.1](https://github.com/shilongfeicool/dev-flow/compare/v0.16.28...v0.17.1) (2026-07-31)
+
+
+### Features
+
+* **context:** preserve immutable task intent ([249023d](https://github.com/shilongfeicool/dev-flow/commit/249023d091970bdb6a2744ac467cdf594c353d00))
+* **control:** add task semantic identity contracts ([480d213](https://github.com/shilongfeicool/dev-flow/commit/480d2138e8408f25b888228d5e20050a938c50ec))
+* **hooks:** close turns with canonical receipts ([69a577a](https://github.com/shilongfeicool/dev-flow/commit/69a577ada60abaf6c729f9722715bfe6f310bb2f))
+* **retrieval:** enforce actions and track verified outcomes ([5e2756a](https://github.com/shilongfeicool/dev-flow/commit/5e2756ababaa246cd78ea7bc6877f59e5972e5db))
+
+
+
+
+
 # [0.17.0](https://github.com/shilongfeicool/dev-flow/compare/v0.16.28...v0.17.0) (2026-07-30)
 
 

package/dist/database.d.ts

@@ -5,6 +5,7 @@ import { type AppendRetrievalCycleInput, type CreateRetrievalSessionInput, type
 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';
 import type { RetrievalLedgerEventRecord } from './retrieval-ledger';
+import { type ChannelQueryPlanRecord, type TaskIntentArtifactRecord, type TerminalTransitionRecord, type ToolNameResolutionRecord, type TranscriptCheckpointRecord } from './task-semantic-control';
 export interface BenchmarkReportRecord {
     runId: string;
     suiteId: string;
@@ -420,6 +421,44 @@ export declare class DevFlowDatabase {
     getActiveContextReceipt(projectRoot: string, sessionId: string, executionId?: string, now?: number): ContextReceiptRecord | null;
     recordContextSelectionEvent(event: ContextSelectionEventRecord): boolean;
     appendRetrievalLedgerEvent(event: RetrievalLedgerEventRecord): boolean;
+    appendTaskIntentArtifact(record: TaskIntentArtifactRecord): TaskIntentArtifactRecord;
+    getTaskIntentArtifact(artifactHash: string): TaskIntentArtifactRecord | null;
+    getLatestTaskIntentArtifact(input: {
+        projectRoot: string;
+        sessionId: string;
+        turnId?: string;
+        requestId?: string;
+    }): TaskIntentArtifactRecord | null;
+    getTaskIntentArtifactBySource(input: {
+        projectRoot: string;
+        sessionId: string;
+        sourceHash: string;
+    }): TaskIntentArtifactRecord | null;
+    listLatestTaskIntentArtifacts(projectRoot: string, sessionId: string): TaskIntentArtifactRecord[];
+    appendChannelQueryPlan(record: ChannelQueryPlanRecord): ChannelQueryPlanRecord;
+    getChannelQueryPlan(planHash: string): ChannelQueryPlanRecord | null;
+    getChannelQueryPlanForIntent(input: {
+        projectRoot: string;
+        sessionId: string;
+        turnId: string;
+        sourceIntentHash: string;
+    }): ChannelQueryPlanRecord | null;
+    appendToolNameResolution(record: ToolNameResolutionRecord): boolean;
+    listToolNameResolutions(input: {
+        projectRoot: string;
+        sessionId: string;
+        requestId?: string;
+    }): ToolNameResolutionRecord[];
+    appendTerminalTransition(record: TerminalTransitionRecord): TerminalTransitionRecord;
+    getTerminalTransition(receiptId: string): TerminalTransitionRecord | null;
+    getLatestTerminalTransition(projectRoot: string, sessionId: string, turnId: string): TerminalTransitionRecord | null;
+    appendTranscriptCheckpoint(record: TranscriptCheckpointRecord): boolean;
+    getLatestTranscriptCheckpoint(input: {
+        projectRoot: string;
+        hostId: string;
+        sessionId: string;
+        sourcePath: string;
+    }): TranscriptCheckpointRecord | null;
     listRetrievalLedgerEvents(options: {
         projectRoot: string;
         sessionId?: string;

package/dist/database.js

@@ -13,6 +13,7 @@ const host_actions_1 = require("./host-actions");
 const retrieval_sessions_1 = require("./retrieval-sessions");
 const learning_candidates_1 = require("./learning-candidates");
 const workflow_workers_1 = require("./workflow-workers");
+const task_semantic_control_1 = require("./task-semantic-control");
 const CONTEXT_REQUIRED_SKILLS = new Set([
     'react', 'vue', 'nest', 'nextjs', 'graphql', 'typescript',
 ]);
@@ -329,6 +330,119 @@ class DevFlowDatabase {
         project_root, session_id, execution_id, request_id, context_receipt, source_type, source_id, created_at
       );
 
+      CREATE TABLE IF NOT EXISTS devflow_task_intent_artifacts (
+        artifact_hash TEXT PRIMARY KEY,
+        project_root TEXT NOT NULL,
+        project_id TEXT NOT NULL,
+        host_id TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        turn_id TEXT NOT NULL,
+        request_id TEXT NOT NULL,
+        execution_id TEXT,
+        version INTEGER NOT NULL CHECK(version > 0),
+        supersedes_hash TEXT,
+        raw_prompt TEXT NOT NULL,
+        normalized_prompt TEXT NOT NULL,
+        command TEXT,
+        slash_args_json TEXT NOT NULL DEFAULT '[]',
+        active_skill TEXT,
+        intent TEXT NOT NULL,
+        action TEXT NOT NULL,
+        entities_json TEXT NOT NULL DEFAULT '[]',
+        target_anchors_json TEXT NOT NULL DEFAULT '[]',
+        policy_constraints_json TEXT NOT NULL DEFAULT '[]',
+        classification_evidence_json TEXT NOT NULL DEFAULT '[]',
+        source_event_ids_json TEXT NOT NULL DEFAULT '[]',
+        source_hash TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        UNIQUE(project_root, session_id, turn_id, version),
+        UNIQUE(project_root, session_id, request_id, version)
+      );
+      CREATE INDEX IF NOT EXISTS idx_task_intent_active
+        ON devflow_task_intent_artifacts(project_root, session_id, turn_id, version DESC);
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_task_intent_source
+        ON devflow_task_intent_artifacts(project_root, session_id, source_hash, version);
+
+      CREATE TABLE IF NOT EXISTS devflow_channel_query_plans (
+        plan_hash TEXT PRIMARY KEY,
+        source_intent_hash TEXT NOT NULL,
+        project_root TEXT NOT NULL,
+        project_id TEXT NOT NULL,
+        host_id TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        turn_id TEXT NOT NULL,
+        request_id TEXT NOT NULL,
+        execution_id TEXT,
+        code_queries_json TEXT NOT NULL DEFAULT '[]',
+        memory_queries_json TEXT NOT NULL DEFAULT '[]',
+        knowledge_queries_json TEXT NOT NULL DEFAULT '[]',
+        generated_by TEXT NOT NULL
+          CHECK(generated_by IN ('deterministic', 'host_semantic', 'hybrid')),
+        degradation_json TEXT,
+        created_at INTEGER NOT NULL,
+        UNIQUE(project_root, session_id, turn_id, source_intent_hash)
+      );
+      CREATE INDEX IF NOT EXISTS idx_channel_query_plan_request
+        ON devflow_channel_query_plans(project_root, session_id, request_id, created_at DESC);
+
+      CREATE TABLE IF NOT EXISTS devflow_tool_name_resolutions (
+        id TEXT PRIMARY KEY,
+        source_hash TEXT NOT NULL UNIQUE,
+        project_root TEXT NOT NULL,
+        project_id TEXT NOT NULL,
+        host_id TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        turn_id TEXT NOT NULL,
+        request_id TEXT NOT NULL,
+        execution_id TEXT,
+        requested_name TEXT NOT NULL,
+        canonical_name TEXT,
+        projected_name TEXT,
+        status TEXT NOT NULL CHECK(status IN ('canonical', 'alias', 'unsupported')),
+        attempt INTEGER NOT NULL CHECK(attempt >= 0),
+        capability_mechanism TEXT,
+        reason TEXT,
+        created_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_tool_resolution_request
+        ON devflow_tool_name_resolutions(project_root, session_id, request_id, created_at);
+
+      CREATE TABLE IF NOT EXISTS devflow_terminal_transitions (
+        receipt_id TEXT PRIMARY KEY,
+        project_root TEXT NOT NULL,
+        project_id TEXT NOT NULL,
+        host_id TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        turn_id TEXT NOT NULL,
+        request_id TEXT NOT NULL,
+        execution_id TEXT,
+        sequence INTEGER NOT NULL CHECK(sequence > 0),
+        from_state TEXT,
+        to_state TEXT NOT NULL,
+        source_receipt_id TEXT,
+        reason TEXT NOT NULL,
+        payload_json TEXT NOT NULL DEFAULT '{}',
+        created_at INTEGER NOT NULL,
+        UNIQUE(project_root, session_id, turn_id, sequence)
+      );
+      CREATE INDEX IF NOT EXISTS idx_terminal_transition_turn
+        ON devflow_terminal_transitions(project_root, session_id, turn_id, sequence);
+
+      CREATE TABLE IF NOT EXISTS devflow_transcript_checkpoints (
+        id TEXT PRIMARY KEY,
+        project_root TEXT NOT NULL,
+        host_id TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        source_path TEXT NOT NULL,
+        source_hash TEXT NOT NULL,
+        byte_offset INTEGER NOT NULL CHECK(byte_offset >= 0),
+        event_count INTEGER NOT NULL CHECK(event_count >= 0),
+        created_at INTEGER NOT NULL,
+        UNIQUE(project_root, host_id, session_id, source_path, source_hash)
+      );
+      CREATE INDEX IF NOT EXISTS idx_transcript_checkpoint_latest
+        ON devflow_transcript_checkpoints(project_root, host_id, session_id, source_path, created_at DESC);
+
       CREATE TABLE IF NOT EXISTS devflow_policy_verification_baselines (
         project_root TEXT NOT NULL,
         kind TEXT NOT NULL,
@@ -2950,6 +3064,232 @@ class DevFlowDatabase {
       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `).run(event.id, event.projectRoot, event.sessionId, event.executionId ?? null, event.turnId ?? null, event.requestId, event.contextReceipt, event.sourceType, event.sourceId, event.stage, event.rank ?? null, event.rawScore ?? null, event.normalizedScore ?? null, event.finalScore ?? null, JSON.stringify(event.applicability), event.reason ?? null, JSON.stringify(event.toolEvidence), event.verificationReceipt ?? null, JSON.stringify(event.payload), event.createdAt).changes > 0;
     }
+    appendTaskIntentArtifact(record) {
+        (0, task_semantic_control_1.assertTaskIdentity)(record);
+        if (!Number.isSafeInteger(record.version) || record.version <= 0) {
+            throw new Error('TASK_INTENT_INVALID_VERSION');
+        }
+        const existingByHash = this.getTaskIntentArtifact(record.artifactHash);
+        if (existingByHash) {
+            if ((0, task_semantic_control_1.stableSemanticJson)(existingByHash) !== (0, task_semantic_control_1.stableSemanticJson)(record)) {
+                throw new Error(`TASK_INTENT_HASH_CONFLICT:${record.artifactHash}`);
+            }
+            return existingByHash;
+        }
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const conflicting = this.db.prepare(`
+        SELECT * FROM devflow_task_intent_artifacts
+        WHERE project_root = ? AND session_id = ? AND turn_id = ? AND version = ?
+      `).get(record.projectRoot, record.sessionId, record.turnId, record.version);
+            if (conflicting)
+                throw new Error(`TASK_INTENT_VERSION_CONFLICT:${record.turnId}:${record.version}`);
+            if (record.supersedesHash && !this.getTaskIntentArtifact(record.supersedesHash)) {
+                throw new Error(`TASK_INTENT_SUPERSEDED_NOT_FOUND:${record.supersedesHash}`);
+            }
+            this.db.prepare(`
+        INSERT INTO devflow_task_intent_artifacts (
+          artifact_hash, project_root, project_id, host_id, session_id, turn_id, request_id,
+          execution_id, version, supersedes_hash, raw_prompt, normalized_prompt, command,
+          slash_args_json, active_skill, intent, action, entities_json, target_anchors_json,
+          policy_constraints_json, classification_evidence_json, source_event_ids_json,
+          source_hash, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(record.artifactHash, record.projectRoot, record.projectId, record.hostId, record.sessionId, record.turnId, record.requestId, record.executionId ?? null, record.version, record.supersedesHash ?? null, record.rawPrompt, record.normalizedPrompt, record.command ?? null, (0, task_semantic_control_1.stableSemanticJson)(record.slashArgs), record.activeSkill ?? null, record.intent, record.action, (0, task_semantic_control_1.stableSemanticJson)(record.entities), (0, task_semantic_control_1.stableSemanticJson)(record.targetAnchors), (0, task_semantic_control_1.stableSemanticJson)(record.policyConstraints), (0, task_semantic_control_1.stableSemanticJson)(record.classificationEvidence), (0, task_semantic_control_1.stableSemanticJson)(record.sourceEventIds), record.sourceHash, record.createdAt);
+            const created = this.getTaskIntentArtifact(record.artifactHash);
+            this.db.exec('COMMIT');
+            return created;
+        }
+        catch (error) {
+            try {
+                this.db.exec('ROLLBACK');
+            }
+            catch { }
+            throw error;
+        }
+    }
+    getTaskIntentArtifact(artifactHash) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_task_intent_artifacts WHERE artifact_hash = ?
+    `).get(artifactHash);
+        return row ? (0, task_semantic_control_1.mapTaskIntentArtifactRow)(row) : null;
+    }
+    getLatestTaskIntentArtifact(input) {
+        if (!input.turnId && !input.requestId)
+            throw new Error('TASK_INTENT_LOOKUP_IDENTITY_REQUIRED');
+        const predicates = ['project_root = ?', 'session_id = ?'];
+        const params = [input.projectRoot, input.sessionId];
+        if (input.turnId) {
+            predicates.push('turn_id = ?');
+            params.push(input.turnId);
+        }
+        if (input.requestId) {
+            predicates.push('request_id = ?');
+            params.push(input.requestId);
+        }
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_task_intent_artifacts
+      WHERE ${predicates.join(' AND ')} ORDER BY version DESC, created_at DESC LIMIT 1
+    `).get(...params);
+        return row ? (0, task_semantic_control_1.mapTaskIntentArtifactRow)(row) : null;
+    }
+    getTaskIntentArtifactBySource(input) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_task_intent_artifacts
+      WHERE project_root = ? AND session_id = ? AND source_hash = ?
+      ORDER BY version DESC, created_at DESC LIMIT 1
+    `).get(input.projectRoot, input.sessionId, input.sourceHash);
+        return row ? (0, task_semantic_control_1.mapTaskIntentArtifactRow)(row) : null;
+    }
+    listLatestTaskIntentArtifacts(projectRoot, sessionId) {
+        return this.db.prepare(`
+      SELECT artifact.* FROM devflow_task_intent_artifacts artifact
+      JOIN (
+        SELECT turn_id, MAX(version) AS version
+        FROM devflow_task_intent_artifacts
+        WHERE project_root = ? AND session_id = ? GROUP BY turn_id
+      ) latest ON latest.turn_id = artifact.turn_id AND latest.version = artifact.version
+      WHERE artifact.project_root = ? AND artifact.session_id = ?
+      ORDER BY artifact.created_at ASC, artifact.turn_id ASC
+    `).all(projectRoot, sessionId, projectRoot, sessionId)
+            .map(task_semantic_control_1.mapTaskIntentArtifactRow);
+    }
+    appendChannelQueryPlan(record) {
+        (0, task_semantic_control_1.assertTaskIdentity)(record);
+        const source = this.getTaskIntentArtifact(record.sourceIntentHash);
+        if (!source)
+            throw new Error(`QUERY_PLAN_INTENT_NOT_FOUND:${record.sourceIntentHash}`);
+        if (!sameTaskIdentity(source, record))
+            throw new Error('QUERY_PLAN_IDENTITY_MISMATCH');
+        const existing = this.getChannelQueryPlan(record.planHash);
+        if (existing) {
+            if ((0, task_semantic_control_1.stableSemanticJson)(existing) !== (0, task_semantic_control_1.stableSemanticJson)(record)) {
+                throw new Error(`QUERY_PLAN_HASH_CONFLICT:${record.planHash}`);
+            }
+            return existing;
+        }
+        try {
+            this.db.prepare(`
+        INSERT INTO devflow_channel_query_plans (
+          plan_hash, source_intent_hash, project_root, project_id, host_id, session_id,
+          turn_id, request_id, execution_id, code_queries_json, memory_queries_json,
+          knowledge_queries_json, generated_by, degradation_json, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(record.planHash, record.sourceIntentHash, record.projectRoot, record.projectId, record.hostId, record.sessionId, record.turnId, record.requestId, record.executionId ?? null, (0, task_semantic_control_1.stableSemanticJson)(record.code), (0, task_semantic_control_1.stableSemanticJson)(record.memory), (0, task_semantic_control_1.stableSemanticJson)(record.knowledge), record.generatedBy, record.degradation ? (0, task_semantic_control_1.stableSemanticJson)(record.degradation) : null, record.createdAt);
+        }
+        catch (error) {
+            if (String(error).includes('UNIQUE constraint failed')) {
+                throw new Error(`QUERY_PLAN_SOURCE_CONFLICT:${record.sourceIntentHash}`);
+            }
+            throw error;
+        }
+        return this.getChannelQueryPlan(record.planHash);
+    }
+    getChannelQueryPlan(planHash) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_channel_query_plans WHERE plan_hash = ?
+    `).get(planHash);
+        return row ? (0, task_semantic_control_1.mapChannelQueryPlanRow)(row) : null;
+    }
+    getChannelQueryPlanForIntent(input) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_channel_query_plans
+      WHERE project_root = ? AND session_id = ? AND turn_id = ? AND source_intent_hash = ?
+      ORDER BY created_at DESC LIMIT 1
+    `).get(input.projectRoot, input.sessionId, input.turnId, input.sourceIntentHash);
+        return row ? (0, task_semantic_control_1.mapChannelQueryPlanRow)(row) : null;
+    }
+    appendToolNameResolution(record) {
+        (0, task_semantic_control_1.assertTaskIdentity)(record);
+        if (!Number.isSafeInteger(record.attempt) || record.attempt < 0) {
+            throw new Error('TOOL_RESOLUTION_INVALID_ATTEMPT');
+        }
+        return this.db.prepare(`
+      INSERT OR IGNORE INTO devflow_tool_name_resolutions (
+        id, source_hash, project_root, project_id, host_id, session_id, turn_id,
+        request_id, execution_id, requested_name, canonical_name, projected_name,
+        status, attempt, capability_mechanism, reason, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(record.id, record.sourceHash, record.projectRoot, record.projectId, record.hostId, record.sessionId, record.turnId, record.requestId, record.executionId ?? null, record.requestedName, record.canonicalName ?? null, record.projectedName ?? null, record.status, record.attempt, record.capabilityMechanism ?? null, record.reason ?? null, record.createdAt).changes > 0;
+    }
+    listToolNameResolutions(input) {
+        const predicates = ['project_root = ?', 'session_id = ?'];
+        const params = [input.projectRoot, input.sessionId];
+        if (input.requestId) {
+            predicates.push('request_id = ?');
+            params.push(input.requestId);
+        }
+        return this.db.prepare(`
+      SELECT * FROM devflow_tool_name_resolutions WHERE ${predicates.join(' AND ')}
+      ORDER BY created_at ASC, attempt ASC, id ASC
+    `).all(...params).map(task_semantic_control_1.mapToolNameResolutionRow);
+    }
+    appendTerminalTransition(record) {
+        (0, task_semantic_control_1.assertTaskIdentity)(record);
+        if (!Number.isSafeInteger(record.sequence) || record.sequence <= 0) {
+            throw new Error('TERMINAL_TRANSITION_INVALID_SEQUENCE');
+        }
+        const existing = this.getTerminalTransition(record.receiptId);
+        if (existing) {
+            if ((0, task_semantic_control_1.stableSemanticJson)(existing) !== (0, task_semantic_control_1.stableSemanticJson)(record)) {
+                throw new Error(`TERMINAL_RECEIPT_CONFLICT:${record.receiptId}`);
+            }
+            return existing;
+        }
+        const latest = this.getLatestTerminalTransition(record.projectRoot, record.sessionId, record.turnId);
+        if (record.sequence !== (latest?.sequence ?? 0) + 1) {
+            throw new Error(`TERMINAL_TRANSITION_SEQUENCE:${latest?.sequence ?? 0}->${record.sequence}`);
+        }
+        if ((latest?.toState ?? undefined) !== record.fromState) {
+            throw new Error(`TERMINAL_TRANSITION_FROM_MISMATCH:${record.fromState ?? 'none'}`);
+        }
+        this.db.prepare(`
+      INSERT INTO devflow_terminal_transitions (
+        receipt_id, project_root, project_id, host_id, session_id, turn_id, request_id,
+        execution_id, sequence, from_state, to_state, source_receipt_id, reason,
+        payload_json, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(record.receiptId, record.projectRoot, record.projectId, record.hostId, record.sessionId, record.turnId, record.requestId, record.executionId ?? null, record.sequence, record.fromState ?? null, record.toState, record.sourceReceiptId ?? null, record.reason, (0, task_semantic_control_1.stableSemanticJson)(record.payload), record.createdAt);
+        return this.getTerminalTransition(record.receiptId);
+    }
+    getTerminalTransition(receiptId) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_terminal_transitions WHERE receipt_id = ?
+    `).get(receiptId);
+        return row ? (0, task_semantic_control_1.mapTerminalTransitionRow)(row) : null;
+    }
+    getLatestTerminalTransition(projectRoot, sessionId, turnId) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_terminal_transitions
+      WHERE project_root = ? AND session_id = ? AND turn_id = ?
+      ORDER BY sequence DESC LIMIT 1
+    `).get(projectRoot, sessionId, turnId);
+        return row ? (0, task_semantic_control_1.mapTerminalTransitionRow)(row) : null;
+    }
+    appendTranscriptCheckpoint(record) {
+        if (!record.id || !record.projectRoot || !record.hostId || !record.sessionId
+            || !record.sourcePath || !record.sourceHash) {
+            throw new Error('TRANSCRIPT_CHECKPOINT_INVALID_IDENTITY');
+        }
+        if (!Number.isSafeInteger(record.byteOffset) || record.byteOffset < 0
+            || !Number.isSafeInteger(record.eventCount) || record.eventCount < 0) {
+            throw new Error('TRANSCRIPT_CHECKPOINT_INVALID_POSITION');
+        }
+        return this.db.prepare(`
+      INSERT OR IGNORE INTO devflow_transcript_checkpoints (
+        id, project_root, host_id, session_id, source_path, source_hash,
+        byte_offset, event_count, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(record.id, record.projectRoot, record.hostId, record.sessionId, record.sourcePath, record.sourceHash, record.byteOffset, record.eventCount, record.createdAt).changes > 0;
+    }
+    getLatestTranscriptCheckpoint(input) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_transcript_checkpoints
+      WHERE project_root = ? AND host_id = ? AND session_id = ? AND source_path = ?
+      ORDER BY created_at DESC, byte_offset DESC LIMIT 1
+    `).get(input.projectRoot, input.hostId, input.sessionId, input.sourcePath);
+        return row ? (0, task_semantic_control_1.mapTranscriptCheckpointRow)(row) : null;
+    }
     listRetrievalLedgerEvents(options) {
         const predicates = ['project_root = ?'];
         const params = [options.projectRoot];
@@ -3922,3 +4262,12 @@ function canonicalWorkflowProjectRoot(projectRoot) {
         return resolved;
     }
 }
+function sameTaskIdentity(left, right) {
+    return left.projectRoot === right.projectRoot
+        && left.projectId === right.projectId
+        && left.hostId === right.hostId
+        && left.sessionId === right.sessionId
+        && left.turnId === right.turnId
+        && left.requestId === right.requestId
+        && left.executionId === right.executionId;
+}

package/dist/index.d.ts

@@ -7,6 +7,8 @@ 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 { assertTaskIdentity, mapChannelQueryPlanRow, mapTaskIntentArtifactRow, mapTerminalTransitionRow, mapToolNameResolutionRow, mapTranscriptCheckpointRow, stableSemanticJson, } from './task-semantic-control';
+export type { ChannelQueryPlanRecord, TaskIdentityRecord, TaskIntentArtifactRecord, TerminalTransitionRecord, ToolNameResolutionRecord, ToolNameResolutionStatus, TranscriptCheckpointRecord, } from './task-semantic-control';
 export { LEGAL_WORKFLOW_WORKER_TRANSITIONS, TERMINAL_WORKFLOW_WORKER_STATES, mapWorkflowMergeRow, mapWorkflowWorkerEventRow, mapWorkflowWorkerRow, } from './workflow-workers';
 export type { CreateWorkflowWorkerInput, EnqueueWorkflowMergeInput, TransitionWorkflowWorkerInput, WorkflowMergeRecord, WorkflowMergeState, WorkflowWorkerEventRecord, WorkflowWorkerRecord, WorkflowWorkerState, } from './workflow-workers';
 export { mapLearningCandidateRow, mapLearningEvidenceRow, mapLearningVersionRow, stableLearningJson, } from './learning-candidates';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stableLearningJson = exports.mapLearningVersionRow = exports.mapLearningEvidenceRow = exports.mapLearningCandidateRow = exports.mapWorkflowWorkerRow = exports.mapWorkflowWorkerEventRow = exports.mapWorkflowMergeRow = exports.TERMINAL_WORKFLOW_WORKER_STATES = exports.LEGAL_WORKFLOW_WORKER_TRANSITIONS = 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.mapWorkflowWorkerRow = exports.mapWorkflowWorkerEventRow = exports.mapWorkflowMergeRow = exports.TERMINAL_WORKFLOW_WORKER_STATES = exports.LEGAL_WORKFLOW_WORKER_TRANSITIONS = exports.stableSemanticJson = exports.mapTranscriptCheckpointRow = exports.mapToolNameResolutionRow = exports.mapTerminalTransitionRow = exports.mapTaskIntentArtifactRow = exports.mapChannelQueryPlanRow = exports.assertTaskIdentity = 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,6 +16,14 @@ 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 task_semantic_control_1 = require("./task-semantic-control");
+Object.defineProperty(exports, "assertTaskIdentity", { enumerable: true, get: function () { return task_semantic_control_1.assertTaskIdentity; } });
+Object.defineProperty(exports, "mapChannelQueryPlanRow", { enumerable: true, get: function () { return task_semantic_control_1.mapChannelQueryPlanRow; } });
+Object.defineProperty(exports, "mapTaskIntentArtifactRow", { enumerable: true, get: function () { return task_semantic_control_1.mapTaskIntentArtifactRow; } });
+Object.defineProperty(exports, "mapTerminalTransitionRow", { enumerable: true, get: function () { return task_semantic_control_1.mapTerminalTransitionRow; } });
+Object.defineProperty(exports, "mapToolNameResolutionRow", { enumerable: true, get: function () { return task_semantic_control_1.mapToolNameResolutionRow; } });
+Object.defineProperty(exports, "mapTranscriptCheckpointRow", { enumerable: true, get: function () { return task_semantic_control_1.mapTranscriptCheckpointRow; } });
+Object.defineProperty(exports, "stableSemanticJson", { enumerable: true, get: function () { return task_semantic_control_1.stableSemanticJson; } });
 var workflow_workers_1 = require("./workflow-workers");
 Object.defineProperty(exports, "LEGAL_WORKFLOW_WORKER_TRANSITIONS", { enumerable: true, get: function () { return workflow_workers_1.LEGAL_WORKFLOW_WORKER_TRANSITIONS; } });
 Object.defineProperty(exports, "TERMINAL_WORKFLOW_WORKER_STATES", { enumerable: true, get: function () { return workflow_workers_1.TERMINAL_WORKFLOW_WORKER_STATES; } });

package/dist/task-semantic-control.d.ts

@@ -0,0 +1,79 @@
+export interface TaskIdentityRecord {
+    projectRoot: string;
+    projectId: string;
+    hostId: string;
+    sessionId: string;
+    turnId: string;
+    requestId: string;
+    executionId?: string;
+}
+export interface TaskIntentArtifactRecord extends TaskIdentityRecord {
+    version: number;
+    supersedesHash?: string;
+    rawPrompt: string;
+    normalizedPrompt: string;
+    command?: string;
+    slashArgs: string[];
+    activeSkill?: string;
+    intent: string;
+    action: string;
+    entities: string[];
+    targetAnchors: string[];
+    policyConstraints: string[];
+    classificationEvidence: Array<Record<string, unknown>>;
+    sourceEventIds: string[];
+    sourceHash: string;
+    artifactHash: string;
+    createdAt: number;
+}
+export interface ChannelQueryPlanRecord extends TaskIdentityRecord {
+    sourceIntentHash: string;
+    planHash: string;
+    code: Array<Record<string, unknown>>;
+    memory: Array<Record<string, unknown>>;
+    knowledge: Array<Record<string, unknown>>;
+    generatedBy: 'deterministic' | 'host_semantic' | 'hybrid';
+    degradation?: Record<string, unknown>;
+    createdAt: number;
+}
+export type ToolNameResolutionStatus = 'canonical' | 'alias' | 'unsupported';
+export interface ToolNameResolutionRecord extends TaskIdentityRecord {
+    id: string;
+    sourceHash: string;
+    requestedName: string;
+    canonicalName?: string;
+    projectedName?: string;
+    status: ToolNameResolutionStatus;
+    attempt: number;
+    capabilityMechanism?: string;
+    reason?: string;
+    createdAt: number;
+}
+export interface TerminalTransitionRecord extends TaskIdentityRecord {
+    sequence: number;
+    fromState?: string;
+    toState: string;
+    receiptId: string;
+    sourceReceiptId?: string;
+    reason: string;
+    payload: Record<string, unknown>;
+    createdAt: number;
+}
+export interface TranscriptCheckpointRecord {
+    id: string;
+    projectRoot: string;
+    hostId: string;
+    sessionId: string;
+    sourcePath: string;
+    sourceHash: string;
+    byteOffset: number;
+    eventCount: number;
+    createdAt: number;
+}
+export declare function stableSemanticJson(value: unknown): string;
+export declare function mapTaskIntentArtifactRow(row: Record<string, unknown>): TaskIntentArtifactRecord;
+export declare function mapChannelQueryPlanRow(row: Record<string, unknown>): ChannelQueryPlanRecord;
+export declare function mapToolNameResolutionRow(row: Record<string, unknown>): ToolNameResolutionRecord;
+export declare function mapTerminalTransitionRow(row: Record<string, unknown>): TerminalTransitionRecord;
+export declare function mapTranscriptCheckpointRow(row: Record<string, unknown>): TranscriptCheckpointRecord;
+export declare function assertTaskIdentity(record: TaskIdentityRecord): void;