@devflow-tools/database 0.17.8 → 0.18.0

package/src/host-actions.ts

@@ -1,211 +0,0 @@
-export type HostActionState =
-  | 'waiting'
-  | 'running'
-  | 'reported'
-  | 'verified'
-  | 'failed'
-  | 'cancelled'
-  | 'degraded';
-
-export interface HostActionRecord {
-  actionId: string;
-  runId: string;
-  engineRunId: string;
-  stepId: string;
-  projectRoot: string;
-  sessionId?: string;
-  executionId?: string;
-  contextReceipt?: string;
-  state: HostActionState;
-  report: Record<string, unknown>;
-  evidenceHash?: string;
-  createdAt: number;
-  updatedAt: number;
-  finishedAt?: number;
-}
-
-export interface RequestHostActionInput {
-  actionId?: string;
-  runId: string;
-  engineRunId: string;
-  stepId: string;
-  projectRoot: string;
-  sessionId?: string;
-  executionId?: string;
-  contextReceipt?: string;
-}
-
-export interface StartHostActionInput {
-  actionId: string;
-  projectRoot: string;
-}
-
-export interface ReportHostActionInput {
-  actionId: string;
-  projectRoot: string;
-  report: Record<string, unknown>;
-  evidenceHash?: string;
-}
-
-export interface VerifyHostActionInput extends ReportHostActionInput {
-  evidenceHash: string;
-}
-
-export interface FailHostActionInput extends ReportHostActionInput {
-  outcome?: 'failed' | 'cancelled' | 'degraded';
-}
-
-const HOST_ACTION_STATES = new Set<HostActionState>([
-  'waiting',
-  'running',
-  'reported',
-  'verified',
-  'failed',
-  'cancelled',
-  'degraded',
-]);
-
-export function isHostActionState(value: unknown): value is HostActionState {
-  return typeof value === 'string' && HOST_ACTION_STATES.has(value as HostActionState);
-}
-
-export function mapHostActionRow(row: Record<string, unknown>): HostActionRecord {
-  if (!isHostActionState(row.state)) {
-    throw new Error(`Invalid persisted host action state: ${String(row.state)}`);
-  }
-
-  return {
-    actionId: asRequiredString(row.action_id, 'action_id'),
-    runId: asRequiredString(row.run_id, 'run_id'),
-    engineRunId: asRequiredString(row.engine_run_id, 'engine_run_id'),
-    stepId: asRequiredString(row.step_id, 'step_id'),
-    projectRoot: asRequiredString(row.project_root, 'project_root'),
-    sessionId: asOptionalString(row.session_id),
-    executionId: asOptionalString(row.execution_id),
-    contextReceipt: asOptionalString(row.context_receipt),
-    state: row.state,
-    report: parseReport(row.report_json),
-    evidenceHash: asOptionalString(row.evidence_hash),
-    createdAt: asFiniteNumber(row.created_at, 'created_at'),
-    updatedAt: asFiniteNumber(row.updated_at, 'updated_at'),
-    finishedAt: asOptionalFiniteNumber(row.finished_at),
-  };
-}
-
-export function serializeHostActionReport(report: Record<string, unknown>): string {
-  if (!isPlainObject(report)) throw new Error('Host action report must be a plain object');
-  return JSON.stringify(canonicalizeJson(report, '$', new WeakSet<object>()));
-}
-
-export function hostActionReportsEqual(
-  left: Record<string, unknown>,
-  right: Record<string, unknown>,
-): boolean {
-  return serializeHostActionReport(left) === serializeHostActionReport(right);
-}
-
-function parseReport(value: unknown): Record<string, unknown> {
-  if (typeof value !== 'string') {
-    throw new Error('Invalid persisted host action report_json: expected JSON text');
-  }
-  try {
-    const parsed: unknown = JSON.parse(value);
-    if (!isPlainObject(parsed)) {
-      throw new Error('expected a JSON object');
-    }
-    serializeHostActionReport(parsed);
-    return parsed;
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
-    throw new Error(`Invalid persisted host action report_json: ${detail}`);
-  }
-}
-
-function canonicalizeJson(value: unknown, path: string, ancestors: WeakSet<object>): 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 nonJsonValueError(path);
-    }
-    return value;
-  }
-  if (typeof value !== 'object') throw nonJsonValueError(path);
-  if (ancestors.has(value)) throw new Error(`Host action report contains a cycle at ${path}`);
-
-  ancestors.add(value);
-  try {
-    if (Array.isArray(value)) return canonicalizeArray(value, path, ancestors);
-    if (!isPlainObject(value)) throw nonJsonValueError(path);
-
-    const result: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
-    const keys = Reflect.ownKeys(value);
-    for (const key of keys) {
-      if (typeof key !== 'string') throw nonJsonValueError(`${path}[symbol]`);
-      const descriptor = Object.getOwnPropertyDescriptor(value, key);
-      if (!descriptor?.enumerable || !('value' in descriptor)) {
-        throw nonJsonValueError(`${path}.${key}`);
-      }
-    }
-    for (const key of (keys as string[]).slice().sort(comparePropertyKeys)) {
-      const descriptor = Object.getOwnPropertyDescriptor(value, key)!;
-      result[key] = canonicalizeJson(descriptor.value, `${path}.${key}`, ancestors);
-    }
-    return result;
-  } finally {
-    ancestors.delete(value);
-  }
-}
-
-function canonicalizeArray(value: unknown[], path: string, ancestors: WeakSet<object>): unknown[] {
-  if (Object.getPrototypeOf(value) !== Array.prototype) throw nonJsonValueError(path);
-  const keys = Reflect.ownKeys(value);
-  const expectedKeys = new Set(['length', ...Array.from({ length: value.length }, (_, index) => String(index))]);
-  if (keys.some(key => typeof key !== 'string' || !expectedKeys.has(key))) {
-    throw nonJsonValueError(path);
-  }
-
-  return Array.from({ length: value.length }, (_, index) => {
-    const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
-    if (!descriptor?.enumerable || !('value' in descriptor)) {
-      throw nonJsonValueError(`${path}[${index}]`);
-    }
-    return canonicalizeJson(descriptor.value, `${path}[${index}]`, ancestors);
-  });
-}
-
-function comparePropertyKeys(left: string, right: string): number {
-  return left < right ? -1 : left > right ? 1 : 0;
-}
-
-function nonJsonValueError(path: string): Error {
-  return new Error(`Host action report contains a non-JSON value at ${path}`);
-}
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
-  const prototype = Object.getPrototypeOf(value);
-  return prototype === Object.prototype || prototype === null;
-}
-
-function asRequiredString(value: unknown, column: string): string {
-  if (typeof value !== 'string' || value.length === 0) {
-    throw new Error(`Invalid persisted host action ${column}`);
-  }
-  return value;
-}
-
-function asOptionalString(value: unknown): string | undefined {
-  return typeof value === 'string' ? value : undefined;
-}
-
-function asFiniteNumber(value: unknown, column: string): number {
-  const number = Number(value);
-  if (!Number.isFinite(number)) throw new Error(`Invalid persisted host action ${column}`);
-  return number;
-}
-
-function asOptionalFiniteNumber(value: unknown): number | undefined {
-  if (value === null || value === undefined) return undefined;
-  const number = Number(value);
-  return Number.isFinite(number) ? number : undefined;
-}

package/src/index.ts

@@ -1,153 +0,0 @@
-export {
-  DevFlowDatabase,
-  getGlobalDevFlowDbPath,
-  openGlobalDevFlowDatabase,
-  openGlobalDevFlowReadOnlyDatabase,
-} from './database';
-export type {
-  BenchmarkReportMetaRecord,
-  BenchmarkReportRecord,
-  FeedbackRecord,
-  GovernanceAuditRecord,
-  GovernanceRuleRecord,
-  HookFallbackRecord,
-  HookReceiptRecord,
-  ContextReceiptRecord,
-  ContextSelectionEventRecord,
-  PolicyVerificationBaselineRecord,
-  MemoryDistillCheckpointRecord,
-  MemoryTurnRecord,
-  MemoryTurnStatus,
-  TelemetryFailureRecord,
-} from './database';
-export type {
-  EnqueueWorkInput,
-  LeaseWorkInput,
-  RequestSessionClosureInput,
-  SessionClosureRecord,
-  SessionClosureState,
-  WorkError,
-  WorkItemRecord,
-  WorkKind,
-  WorkQueueHealth,
-  WorkState,
-  ProjectMutationLeaseRecord,
-} from './work-queue';
-export type {
-  RetrievalLedgerEventRecord,
-  RetrievalLedgerSourceType,
-  RetrievalLedgerStage,
-} from './retrieval-ledger';
-export {
-  hostActionReportsEqual,
-  isHostActionState,
-  mapHostActionRow,
-  serializeHostActionReport,
-} from './host-actions';
-export { RETRIEVAL_MAX_CYCLES, isRetrievalSessionState } from './retrieval-sessions';
-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 {
-  mapTaskRuntimeEventRow,
-  mapTaskRuntimeSnapshotRow,
-  stableTaskRuntimeHash,
-  stableTaskRuntimeJson,
-} from './task-runtime';
-export type {
-  TaskRuntimeChannelRecord,
-  TaskRuntimeChannelRequirement,
-  TaskRuntimeChannelStatus,
-  TaskRuntimeEventRecord,
-  TaskRuntimeIdentityRecord,
-  TaskRuntimeObligationRecord,
-  TaskRuntimeObligationState,
-  TaskRuntimeSnapshotRecord,
-} from './task-runtime';
-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';
-export type {
-  AddLearningCandidateEvidenceInput,
-  LearningCandidateEvidenceRecord,
-  LearningCandidateKind,
-  LearningCandidateRecord,
-  LearningCandidateState,
-  LearningCandidateVersionRecord,
-  LearningEvidencePolarity,
-  LearningOutcomeState,
-  TransitionLearningCandidateInput,
-  UpsertLearningCandidateInput,
-} from './learning-candidates';
-export type {
-  SessionObligationKind,
-  SessionObligationRecord,
-  SessionObligationState,
-} from './obligation-ledger';
-export {
-  assertSemanticResolutionRecord,
-  mapSemanticResolutionRow,
-  stableSemanticResolutionJson,
-} from './semantic-resolution';
-export type {
-  PersistedSemanticGeneratedBy,
-  PersistedSemanticResolutionState,
-  SemanticResolutionRecord,
-} from './semantic-resolution';

package/src/learning-candidates.ts

@@ -1,181 +0,0 @@
-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 function mapLearningCandidateRow(row: Record<string, unknown>): LearningCandidateRecord {
-  return {
-    id: String(row.id),
-    projectRoot: String(row.project_root),
-    scope: row.scope === 'global' ? 'global' : 'project',
-    state: row.state as LearningCandidateState,
-    kind: row.kind as LearningCandidateKind,
-    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),
-  };
-}
-
-export function mapLearningEvidenceRow(row: Record<string, unknown>): LearningCandidateEvidenceRecord {
-  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 as LearningCandidateEvidenceRecord['sourceType'],
-    polarity: row.polarity as LearningEvidencePolarity,
-    outcome: row.outcome as LearningOutcomeState,
-    evidenceHash: String(row.evidence_hash),
-    receipt: optionalString(row.receipt),
-    payload: parseRecord(row.payload_json),
-    createdAt: Number(row.created_at),
-    resolvedAt: optionalNumber(row.resolved_at),
-  };
-}
-
-export function mapLearningVersionRow(row: Record<string, unknown>): LearningCandidateVersionRecord {
-  return {
-    candidateId: String(row.candidate_id),
-    version: Number(row.version),
-    trigger: parseRecord(row.trigger_json),
-    instruction: String(row.instruction),
-    createdAt: Number(row.created_at),
-  };
-}
-
-export function stableLearningJson(value: unknown): string {
-  if (Array.isArray(value)) return `[${value.map(stableLearningJson).join(',')}]`;
-  if (!value || typeof value !== 'object') return JSON.stringify(value) ?? 'null';
-  const record = value as Record<string, unknown>;
-  return `{${Object.keys(record).sort().map(key => `${JSON.stringify(key)}:${stableLearningJson(record[key])}`).join(',')}}`;
-}
-
-function parseRecord(value: unknown): Record<string, unknown> {
-  try {
-    const parsed = typeof value === 'string' ? JSON.parse(value) as unknown : value;
-    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
-      ? parsed as Record<string, unknown>
-      : {};
-  } catch {
-    return {};
-  }
-}
-
-function optionalString(value: unknown): string | undefined {
-  return typeof value === 'string' && value.length > 0 ? value : undefined;
-}
-
-function optionalNumber(value: unknown): number | undefined {
-  return value === null || value === undefined ? undefined : Number(value);
-}

package/src/node-sqlite.ts

@@ -1,60 +0,0 @@
-import { DatabaseSync } from 'node:sqlite';
-import type { Database, Statement, RunResult } from './types';
-
-export class NodeSqliteDatabase implements Database {
-  private db: DatabaseSync;
-
-  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))}`);
-    if (!readOnly) {
-      this.db.exec('PRAGMA journal_mode = WAL');
-      this.db.exec('PRAGMA synchronous = NORMAL');
-    }
-  }
-
-  exec(sql: string): void {
-    this.db.exec(sql);
-  }
-
-  prepare(sql: string): Statement {
-    const stmt = this.db.prepare(sql);
-    return {
-      run: (...params: any[]): RunResult => {
-        const result = stmt.run(...normalizeParams(params));
-        return {
-          changes: Number(result.changes),
-          lastInsertRowid: result.lastInsertRowid,
-        };
-      },
-      get: (...params: any[]): any => {
-        return stmt.get(...normalizeParams(params));
-      },
-      all: (...params: any[]): any[] => {
-        return stmt.all(...normalizeParams(params));
-      },
-    };
-  }
-
-  transaction<T>(fn: () => T): T {
-    this.db.exec('BEGIN');
-    try {
-      const result = fn();
-      this.db.exec('COMMIT');
-      return result;
-    } catch (err) {
-      this.db.exec('ROLLBACK');
-      throw err;
-    }
-  }
-
-  close(): void {
-    this.db.close();
-  }
-}
-
-function normalizeParams(params: any[]): any[] {
-  return params.map(value => typeof value === 'boolean' ? Number(value) : value);
-}

package/src/obligation-ledger.ts

@@ -1,57 +0,0 @@
-export type SessionObligationKind =
-  | 'memory_decision'
-  | 'evidence_contract'
-  | 'session_finalize';
-
-export type SessionObligationState =
-  | 'open'
-  | 'satisfied'
-  | 'degraded'
-  | 'cancelled';
-
-export interface SessionObligationRecord {
-  obligationId: string;
-  projectRoot: string;
-  sessionId: string;
-  executionId?: string;
-  turnId?: string;
-  kind: SessionObligationKind;
-  state: SessionObligationState;
-  payload: Record<string, unknown>;
-  receiptId?: string;
-  reason?: string;
-  createdAt: number;
-  updatedAt: number;
-  resolvedAt?: number;
-}
-
-export function normalizeTurnId(value: string): string {
-  const trimmed = value.trim();
-  if (!trimmed) throw new Error('Memory turn ID is required');
-  return trimmed.startsWith('turn:') ? trimmed : `turn:${trimmed}`;
-}
-
-export function mapSessionObligationRow(row: Record<string, unknown>): SessionObligationRecord {
-  let payload: Record<string, unknown> = {};
-  try {
-    const parsed = JSON.parse(String(row.payload ?? '{}')) as unknown;
-    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-      payload = parsed as Record<string, unknown>;
-    }
-  } catch {}
-  return {
-    obligationId: String(row.obligation_id),
-    projectRoot: String(row.project_root),
-    sessionId: String(row.session_id),
-    executionId: typeof row.execution_id === 'string' ? row.execution_id : undefined,
-    turnId: typeof row.turn_id === 'string' ? row.turn_id : undefined,
-    kind: row.kind as SessionObligationKind,
-    state: row.state as SessionObligationState,
-    payload,
-    receiptId: typeof row.receipt_id === 'string' ? row.receipt_id : undefined,
-    reason: typeof row.reason === 'string' ? row.reason : undefined,
-    createdAt: Number(row.created_at),
-    updatedAt: Number(row.updated_at),
-    resolvedAt: typeof row.resolved_at === 'number' ? row.resolved_at : undefined,
-  };
-}

package/src/retrieval-ledger.ts

@@ -1,35 +0,0 @@
-export type RetrievalLedgerStage =
-  | 'eligible' | 'candidate' | 'selected' | 'exposed' | 'adopted' | 'consumed' | 'verified'
-  | 'positive_outcome' | 'negative_outcome' | 'unknown' | 'unknown_outcome' | 'rejected';
-
-export type RetrievalLedgerSourceType = 'code' | 'memory' | 'knowledge' | 'action';
-
-export interface RetrievalLedgerEventRecord {
-  schemaVersion?: 'retrieval-ledger-event.v1';
-  id: string;
-  projectRoot: string;
-  sessionId: string;
-  executionId?: string;
-  turnId?: string;
-  requestId: string;
-  contextReceipt: string;
-  sourceType: RetrievalLedgerSourceType;
-  sourceId: string;
-  taskSpecHash?: string;
-  actor?: string;
-  sourceVersion?: string;
-  sourceContentHash?: string;
-  evidenceIds?: string[];
-  reasonCode?: string;
-  stage: RetrievalLedgerStage;
-  rank?: number;
-  rawScore?: number;
-  normalizedScore?: number;
-  finalScore?: number;
-  applicability: string[];
-  reason?: string;
-  toolEvidence: string[];
-  verificationReceipt?: string;
-  payload: Record<string, unknown>;
-  createdAt: number;
-}