@devflow-tools/database 0.16.34 → 0.17.1

package/dist/task-semantic-control.js

@@ -0,0 +1,196 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stableSemanticJson = stableSemanticJson;
+exports.mapTaskIntentArtifactRow = mapTaskIntentArtifactRow;
+exports.mapChannelQueryPlanRow = mapChannelQueryPlanRow;
+exports.mapToolNameResolutionRow = mapToolNameResolutionRow;
+exports.mapTerminalTransitionRow = mapTerminalTransitionRow;
+exports.mapTranscriptCheckpointRow = mapTranscriptCheckpointRow;
+exports.assertTaskIdentity = assertTaskIdentity;
+function stableSemanticJson(value) {
+    return JSON.stringify(canonicalize(value));
+}
+function mapTaskIntentArtifactRow(row) {
+    return {
+        ...mapTaskIdentityRow(row),
+        version: requiredPositiveInteger(row.version, 'version'),
+        supersedesHash: optionalString(row.supersedes_hash),
+        rawPrompt: requiredString(row.raw_prompt, 'raw_prompt'),
+        normalizedPrompt: requiredString(row.normalized_prompt, 'normalized_prompt'),
+        command: optionalString(row.command),
+        slashArgs: parseStringArray(row.slash_args_json, 'slash_args_json'),
+        activeSkill: optionalString(row.active_skill),
+        intent: requiredString(row.intent, 'intent'),
+        action: requiredString(row.action, 'action'),
+        entities: parseStringArray(row.entities_json, 'entities_json'),
+        targetAnchors: parseStringArray(row.target_anchors_json, 'target_anchors_json'),
+        policyConstraints: parseStringArray(row.policy_constraints_json, 'policy_constraints_json'),
+        classificationEvidence: parseObjectArray(row.classification_evidence_json, 'classification_evidence_json'),
+        sourceEventIds: parseStringArray(row.source_event_ids_json, 'source_event_ids_json'),
+        sourceHash: requiredString(row.source_hash, 'source_hash'),
+        artifactHash: requiredString(row.artifact_hash, 'artifact_hash'),
+        createdAt: requiredNonNegativeInteger(row.created_at, 'created_at'),
+    };
+}
+function mapChannelQueryPlanRow(row) {
+    const generatedBy = requiredString(row.generated_by, 'generated_by');
+    if (generatedBy !== 'deterministic' && generatedBy !== 'host_semantic' && generatedBy !== 'hybrid') {
+        throw new Error(`Invalid persisted generated_by: ${generatedBy}`);
+    }
+    return {
+        ...mapTaskIdentityRow(row),
+        sourceIntentHash: requiredString(row.source_intent_hash, 'source_intent_hash'),
+        planHash: requiredString(row.plan_hash, 'plan_hash'),
+        code: parseObjectArray(row.code_queries_json, 'code_queries_json'),
+        memory: parseObjectArray(row.memory_queries_json, 'memory_queries_json'),
+        knowledge: parseObjectArray(row.knowledge_queries_json, 'knowledge_queries_json'),
+        generatedBy,
+        degradation: parseOptionalObject(row.degradation_json, 'degradation_json'),
+        createdAt: requiredNonNegativeInteger(row.created_at, 'created_at'),
+    };
+}
+function mapToolNameResolutionRow(row) {
+    const status = requiredString(row.status, 'status');
+    if (status !== 'canonical' && status !== 'alias' && status !== 'unsupported') {
+        throw new Error(`Invalid persisted tool resolution status: ${status}`);
+    }
+    return {
+        ...mapTaskIdentityRow(row),
+        id: requiredString(row.id, 'id'),
+        sourceHash: requiredString(row.source_hash, 'source_hash'),
+        requestedName: requiredString(row.requested_name, 'requested_name'),
+        canonicalName: optionalString(row.canonical_name),
+        projectedName: optionalString(row.projected_name),
+        status,
+        attempt: requiredNonNegativeInteger(row.attempt, 'attempt'),
+        capabilityMechanism: optionalString(row.capability_mechanism),
+        reason: optionalString(row.reason),
+        createdAt: requiredNonNegativeInteger(row.created_at, 'created_at'),
+    };
+}
+function mapTerminalTransitionRow(row) {
+    return {
+        ...mapTaskIdentityRow(row),
+        sequence: requiredPositiveInteger(row.sequence, 'sequence'),
+        fromState: optionalString(row.from_state),
+        toState: requiredString(row.to_state, 'to_state'),
+        receiptId: requiredString(row.receipt_id, 'receipt_id'),
+        sourceReceiptId: optionalString(row.source_receipt_id),
+        reason: requiredString(row.reason, 'reason'),
+        payload: parseObject(row.payload_json, 'payload_json'),
+        createdAt: requiredNonNegativeInteger(row.created_at, 'created_at'),
+    };
+}
+function mapTranscriptCheckpointRow(row) {
+    return {
+        id: requiredString(row.id, 'id'),
+        projectRoot: requiredString(row.project_root, 'project_root'),
+        hostId: requiredString(row.host_id, 'host_id'),
+        sessionId: requiredString(row.session_id, 'session_id'),
+        sourcePath: requiredString(row.source_path, 'source_path'),
+        sourceHash: requiredString(row.source_hash, 'source_hash'),
+        byteOffset: requiredNonNegativeInteger(row.byte_offset, 'byte_offset'),
+        eventCount: requiredNonNegativeInteger(row.event_count, 'event_count'),
+        createdAt: requiredNonNegativeInteger(row.created_at, 'created_at'),
+    };
+}
+function assertTaskIdentity(record) {
+    for (const [field, value] of Object.entries({
+        projectRoot: record.projectRoot,
+        projectId: record.projectId,
+        hostId: record.hostId,
+        sessionId: record.sessionId,
+        turnId: record.turnId,
+        requestId: record.requestId,
+    })) {
+        if (typeof value !== 'string' || value.trim().length === 0) {
+            throw new Error(`TASK_IDENTITY_INVALID:${field}`);
+        }
+    }
+    if (record.executionId !== undefined && record.executionId.trim().length === 0) {
+        throw new Error('TASK_IDENTITY_INVALID:executionId');
+    }
+}
+function mapTaskIdentityRow(row) {
+    return {
+        projectRoot: requiredString(row.project_root, 'project_root'),
+        projectId: requiredString(row.project_id, 'project_id'),
+        hostId: requiredString(row.host_id, 'host_id'),
+        sessionId: requiredString(row.session_id, 'session_id'),
+        turnId: requiredString(row.turn_id, 'turn_id'),
+        requestId: requiredString(row.request_id, 'request_id'),
+        executionId: optionalString(row.execution_id),
+    };
+}
+function canonicalize(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value) || Object.is(value, -0))
+            throw new Error('Semantic control evidence must be lossless JSON');
+        return value;
+    }
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (!value || typeof value !== 'object' || Object.getPrototypeOf(value) !== Object.prototype) {
+        throw new Error('Semantic control evidence must be plain JSON');
+    }
+    const record = value;
+    return Object.fromEntries(Object.keys(record).sort().map(key => [key, canonicalize(record[key])]));
+}
+function parseJson(value, field) {
+    if (typeof value !== 'string')
+        throw new Error(`Invalid persisted ${field}: expected JSON text`);
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw new Error(`Invalid persisted ${field}: malformed JSON`);
+    }
+}
+function parseStringArray(value, field) {
+    const parsed = parseJson(value, field);
+    if (!Array.isArray(parsed) || parsed.some(item => typeof item !== 'string')) {
+        throw new Error(`Invalid persisted ${field}: expected string array`);
+    }
+    return parsed;
+}
+function parseObjectArray(value, field) {
+    const parsed = parseJson(value, field);
+    if (!Array.isArray(parsed) || parsed.some(item => !item || typeof item !== 'object' || Array.isArray(item))) {
+        throw new Error(`Invalid persisted ${field}: expected object array`);
+    }
+    return parsed;
+}
+function parseObject(value, field) {
+    const parsed = parseJson(value, field);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`Invalid persisted ${field}: expected object`);
+    }
+    return parsed;
+}
+function parseOptionalObject(value, field) {
+    if (value === null || value === undefined)
+        return undefined;
+    return parseObject(value, field);
+}
+function requiredString(value, field) {
+    if (typeof value !== 'string' || value.length === 0)
+        throw new Error(`Invalid persisted ${field}`);
+    return value;
+}
+function optionalString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function requiredNonNegativeInteger(value, field) {
+    const result = Number(value);
+    if (!Number.isSafeInteger(result) || result < 0)
+        throw new Error(`Invalid persisted ${field}`);
+    return result;
+}
+function requiredPositiveInteger(value, field) {
+    const result = requiredNonNegativeInteger(value, field);
+    if (result === 0)
+        throw new Error(`Invalid persisted ${field}`);
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devflow-tools/database",
-  "version": "0.16.34",
+  "version": "0.17.1",
   "description": "DevFlow SQLite database package",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/database.ts

@@ -70,6 +70,20 @@ import {
   type WorkflowWorkerRecord,
 } from './workflow-workers';
 import type { RetrievalLedgerEventRecord } from './retrieval-ledger';
+import {
+  assertTaskIdentity,
+  mapChannelQueryPlanRow,
+  mapTaskIntentArtifactRow,
+  mapTerminalTransitionRow,
+  mapToolNameResolutionRow,
+  mapTranscriptCheckpointRow,
+  stableSemanticJson,
+  type ChannelQueryPlanRecord,
+  type TaskIntentArtifactRecord,
+  type TerminalTransitionRecord,
+  type ToolNameResolutionRecord,
+  type TranscriptCheckpointRecord,
+} from './task-semantic-control';
 
 export interface BenchmarkReportRecord {
   runId: string;
@@ -567,6 +581,119 @@ export 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,
@@ -3685,6 +3812,293 @@ export class DevFlowDatabase {
     ).changes > 0;
   }
 
+  appendTaskIntentArtifact(record: TaskIntentArtifactRecord): TaskIntentArtifactRecord {
+    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 (stableSemanticJson(existingByHash) !== 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) as Record<string, unknown> | undefined;
+      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, stableSemanticJson(record.slashArgs), record.activeSkill ?? null,
+        record.intent, record.action, stableSemanticJson(record.entities),
+        stableSemanticJson(record.targetAnchors), stableSemanticJson(record.policyConstraints),
+        stableSemanticJson(record.classificationEvidence), 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: string): TaskIntentArtifactRecord | null {
+    const row = this.db.prepare(`
+      SELECT * FROM devflow_task_intent_artifacts WHERE artifact_hash = ?
+    `).get(artifactHash) as Record<string, unknown> | undefined;
+    return row ? mapTaskIntentArtifactRow(row) : null;
+  }
+
+  getLatestTaskIntentArtifact(input: {
+    projectRoot: string;
+    sessionId: string;
+    turnId?: string;
+    requestId?: string;
+  }): TaskIntentArtifactRecord | null {
+    if (!input.turnId && !input.requestId) throw new Error('TASK_INTENT_LOOKUP_IDENTITY_REQUIRED');
+    const predicates = ['project_root = ?', 'session_id = ?'];
+    const params: unknown[] = [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) as Record<string, unknown> | undefined;
+    return row ? mapTaskIntentArtifactRow(row) : null;
+  }
+
+  getTaskIntentArtifactBySource(input: {
+    projectRoot: string;
+    sessionId: string;
+    sourceHash: string;
+  }): TaskIntentArtifactRecord | null {
+    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) as Record<string, unknown> | undefined;
+    return row ? mapTaskIntentArtifactRow(row) : null;
+  }
+
+  listLatestTaskIntentArtifacts(projectRoot: string, sessionId: string): TaskIntentArtifactRecord[] {
+    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) as Array<Record<string, unknown>>)
+      .map(mapTaskIntentArtifactRow);
+  }
+
+  appendChannelQueryPlan(record: ChannelQueryPlanRecord): ChannelQueryPlanRecord {
+    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 (stableSemanticJson(existing) !== 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, stableSemanticJson(record.code),
+        stableSemanticJson(record.memory), stableSemanticJson(record.knowledge),
+        record.generatedBy, record.degradation ? 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: string): ChannelQueryPlanRecord | null {
+    const row = this.db.prepare(`
+      SELECT * FROM devflow_channel_query_plans WHERE plan_hash = ?
+    `).get(planHash) as Record<string, unknown> | undefined;
+    return row ? mapChannelQueryPlanRow(row) : null;
+  }
+
+  getChannelQueryPlanForIntent(input: {
+    projectRoot: string;
+    sessionId: string;
+    turnId: string;
+    sourceIntentHash: string;
+  }): ChannelQueryPlanRecord | null {
+    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,
+    ) as Record<string, unknown> | undefined;
+    return row ? mapChannelQueryPlanRow(row) : null;
+  }
+
+  appendToolNameResolution(record: ToolNameResolutionRecord): boolean {
+    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: {
+    projectRoot: string;
+    sessionId: string;
+    requestId?: string;
+  }): ToolNameResolutionRecord[] {
+    const predicates = ['project_root = ?', 'session_id = ?'];
+    const params: unknown[] = [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) as Array<Record<string, unknown>>).map(mapToolNameResolutionRow);
+  }
+
+  appendTerminalTransition(record: TerminalTransitionRecord): TerminalTransitionRecord {
+    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 (stableSemanticJson(existing) !== 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, stableSemanticJson(record.payload),
+      record.createdAt,
+    );
+    return this.getTerminalTransition(record.receiptId)!;
+  }
+
+  getTerminalTransition(receiptId: string): TerminalTransitionRecord | null {
+    const row = this.db.prepare(`
+      SELECT * FROM devflow_terminal_transitions WHERE receipt_id = ?
+    `).get(receiptId) as Record<string, unknown> | undefined;
+    return row ? mapTerminalTransitionRow(row) : null;
+  }
+
+  getLatestTerminalTransition(
+    projectRoot: string,
+    sessionId: string,
+    turnId: string,
+  ): TerminalTransitionRecord | null {
+    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) as Record<string, unknown> | undefined;
+    return row ? mapTerminalTransitionRow(row) : null;
+  }
+
+  appendTranscriptCheckpoint(record: TranscriptCheckpointRecord): boolean {
+    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: {
+    projectRoot: string;
+    hostId: string;
+    sessionId: string;
+    sourcePath: string;
+  }): TranscriptCheckpointRecord | null {
+    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) as Record<string, unknown> | undefined;
+    return row ? mapTranscriptCheckpointRow(row) : null;
+  }
+
   listRetrievalLedgerEvents(options: {
     projectRoot: string; sessionId?: string; executionId?: string; requestId?: string;
   }): RetrievalLedgerEventRecord[] {
@@ -4924,3 +5338,22 @@ function canonicalWorkflowProjectRoot(projectRoot: string): string {
   const resolved = resolve(projectRoot);
   try { return realpathSync(resolved); } catch { return resolved; }
 }
+
+function sameTaskIdentity(
+  left: {
+    projectRoot: string; projectId: string; hostId: string; sessionId: string;
+    turnId: string; requestId: string; executionId?: string;
+  },
+  right: {
+    projectRoot: string; projectId: string; hostId: string; sessionId: string;
+    turnId: string; requestId: string; executionId?: string;
+  },
+): boolean {
+  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/src/index.ts

@@ -65,6 +65,24 @@ 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,