@devflow-tools/database 0.17.0 → 0.17.2

package/src/index.ts

@@ -2,6 +2,7 @@ export {
   DevFlowDatabase,
   getGlobalDevFlowDbPath,
   openGlobalDevFlowDatabase,
+  openGlobalDevFlowReadOnlyDatabase,
 } from './database';
 export type {
   BenchmarkReportMetaRecord,
@@ -65,6 +66,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,

package/src/node-sqlite.ts

@@ -4,11 +4,15 @@ import type { Database, Statement, RunResult } from './types';
 export class NodeSqliteDatabase implements Database {
   private db: DatabaseSync;
 
-  constructor(path: string, busyTimeoutMs = 10000) {
-    this.db = new DatabaseSync(path);
+  constructor(path: string, busyTimeoutMs = 10000, readOnly = false) {
+    this.db = readOnly
+      ? new DatabaseSync(path, { readOnly: true })
+      : new DatabaseSync(path);
     this.db.exec(`PRAGMA busy_timeout = ${Math.max(0, Math.floor(busyTimeoutMs))}`);
-    this.db.exec('PRAGMA journal_mode = WAL');
-    this.db.exec('PRAGMA synchronous = NORMAL');
+    if (!readOnly) {
+      this.db.exec('PRAGMA journal_mode = WAL');
+      this.db.exec('PRAGMA synchronous = NORMAL');
+    }
   }
 
   exec(sql: string): void {

package/src/task-semantic-control.ts

@@ -0,0 +1,270 @@
+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 function stableSemanticJson(value: unknown): string {
+  return JSON.stringify(canonicalize(value));
+}
+
+export function mapTaskIntentArtifactRow(row: Record<string, unknown>): TaskIntentArtifactRecord {
+  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'),
+  };
+}
+
+export function mapChannelQueryPlanRow(row: Record<string, unknown>): ChannelQueryPlanRecord {
+  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'),
+  };
+}
+
+export function mapToolNameResolutionRow(row: Record<string, unknown>): ToolNameResolutionRecord {
+  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'),
+  };
+}
+
+export function mapTerminalTransitionRow(row: Record<string, unknown>): TerminalTransitionRecord {
+  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'),
+  };
+}
+
+export function mapTranscriptCheckpointRow(row: Record<string, unknown>): TranscriptCheckpointRecord {
+  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'),
+  };
+}
+
+export function assertTaskIdentity(record: TaskIdentityRecord): void {
+  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: Record<string, unknown>): TaskIdentityRecord {
+  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: unknown): unknown {
+  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 as Record<string, unknown>;
+  return Object.fromEntries(Object.keys(record).sort().map(key => [key, canonicalize(record[key])]));
+}
+
+function parseJson(value: unknown, field: string): unknown {
+  if (typeof value !== 'string') throw new Error(`Invalid persisted ${field}: expected JSON text`);
+  try { return JSON.parse(value) as unknown; } catch { throw new Error(`Invalid persisted ${field}: malformed JSON`); }
+}
+
+function parseStringArray(value: unknown, field: string): string[] {
+  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 as string[];
+}
+
+function parseObjectArray(value: unknown, field: string): Array<Record<string, unknown>> {
+  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 as Array<Record<string, unknown>>;
+}
+
+function parseObject(value: unknown, field: string): Record<string, unknown> {
+  const parsed = parseJson(value, field);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`Invalid persisted ${field}: expected object`);
+  }
+  return parsed as Record<string, unknown>;
+}
+
+function parseOptionalObject(value: unknown, field: string): Record<string, unknown> | undefined {
+  if (value === null || value === undefined) return undefined;
+  return parseObject(value, field);
+}
+
+function requiredString(value: unknown, field: string): string {
+  if (typeof value !== 'string' || value.length === 0) throw new Error(`Invalid persisted ${field}`);
+  return value;
+}
+
+function optionalString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function requiredNonNegativeInteger(value: unknown, field: string): number {
+  const result = Number(value);
+  if (!Number.isSafeInteger(result) || result < 0) throw new Error(`Invalid persisted ${field}`);
+  return result;
+}
+
+function requiredPositiveInteger(value: unknown, field: string): number {
+  const result = requiredNonNegativeInteger(value, field);
+  if (result === 0) throw new Error(`Invalid persisted ${field}`);
+  return result;
+}

package/src/work-queue.ts

@@ -59,6 +59,7 @@ export interface LeaseWorkInput {
   projectRoot: string;
   owner: string;
   kinds?: WorkKind[];
+  workItemIds?: string[];
   limit: number;
   leaseMs: number;
   now?: number;