@devflow-tools/database 0.17.8 → 0.18.1

package/src/retrieval-sessions.ts

@@ -1,196 +0,0 @@
-export const RETRIEVAL_MAX_CYCLES = 3 as const;
-
-export type RetrievalSessionState = 'open' | 'satisfied' | 'exhausted' | 'expired';
-
-export type RetrievalGapKind =
-  | 'target'
-  | 'caller'
-  | 'route'
-  | 'resource'
-  | 'test'
-  | 'configuration'
-  | 'symbol_ambiguity'
-  | 'memory_applicability'
-  | 'knowledge_version'
-  | 'runtime_evidence'
-  | 'unavailable_channel';
-
-export interface RetrievalGapRecord {
-  kind: RetrievalGapKind;
-  target?: string;
-  reason: string;
-  evidence: string[];
-  resolver: 'codegraph' | 'memory' | 'knowledge' | 'analyzer' | 'none';
-  priority: number;
-}
-
-export interface RetrievalCycleRecord {
-  retrievalSessionId: string;
-  cycle: number;
-  gaps: RetrievalGapRecord[];
-  selectedIds: string[];
-  rejectedIds: string[];
-  tokenCost: number;
-  remainingTokenBudget: number;
-  quality: Record<string, unknown>;
-  receipt: string;
-  evidenceHash: string;
-  createdAt: number;
-}
-
-export interface RetrievalSessionRecord {
-  id: string;
-  requestId: string;
-  projectRoot: string;
-  sessionId: string;
-  executionId?: string;
-  query: string;
-  intent: string;
-  state: RetrievalSessionState;
-  cycle: number;
-  maxCycles: typeof RETRIEVAL_MAX_CYCLES;
-  initialTokenBudget: number;
-  remainingTokenBudget: number;
-  baselineReceipt: string;
-  finalReceipt?: string;
-  createdAt: number;
-  updatedAt: number;
-  expiresAt: number;
-}
-
-export interface CreateRetrievalSessionInput {
-  id?: string;
-  requestId: string;
-  projectRoot: string;
-  sessionId: string;
-  executionId?: string;
-  query: string;
-  intent: string;
-  tokenBudget: number;
-  baselineReceipt: string;
-  expiresAt: number;
-}
-
-export interface AppendRetrievalCycleInput {
-  retrievalSessionId: string;
-  projectRoot: string;
-  sessionId: string;
-  baselineReceipt: string;
-  cycle: number;
-  gaps: RetrievalGapRecord[];
-  selectedIds: string[];
-  rejectedIds: string[];
-  tokenCost: number;
-  remainingTokenBudget: number;
-  quality: Record<string, unknown>;
-  receipt: string;
-  evidenceHash: string;
-}
-
-export function mapRetrievalSessionRow(row: Record<string, unknown>): RetrievalSessionRecord {
-  const state = requiredString(row.state, 'state');
-  if (!isRetrievalSessionState(state)) {
-    throw new Error(`Invalid persisted retrieval session state: ${state}`);
-  }
-  const maxCycles = finiteInteger(row.max_cycles, 'max_cycles');
-  if (maxCycles !== RETRIEVAL_MAX_CYCLES) {
-    throw new Error(`Invalid persisted retrieval max_cycles: ${maxCycles}`);
-  }
-  return {
-    id: requiredString(row.id, 'id'),
-    requestId: requiredString(row.request_id, 'request_id'),
-    projectRoot: requiredString(row.project_root, 'project_root'),
-    sessionId: requiredString(row.session_id, 'session_id'),
-    executionId: optionalString(row.execution_id),
-    query: requiredString(row.query, 'query'),
-    intent: requiredString(row.intent, 'intent'),
-    state,
-    cycle: finiteInteger(row.cycle, 'cycle'),
-    maxCycles: RETRIEVAL_MAX_CYCLES,
-    initialTokenBudget: finiteInteger(row.initial_token_budget, 'initial_token_budget'),
-    remainingTokenBudget: finiteInteger(row.remaining_token_budget, 'remaining_token_budget'),
-    baselineReceipt: requiredString(row.baseline_receipt, 'baseline_receipt'),
-    finalReceipt: optionalString(row.final_receipt),
-    createdAt: finiteInteger(row.created_at, 'created_at'),
-    updatedAt: finiteInteger(row.updated_at, 'updated_at'),
-    expiresAt: finiteInteger(row.expires_at, 'expires_at'),
-  };
-}
-
-export function mapRetrievalCycleRow(row: Record<string, unknown>): RetrievalCycleRecord {
-  return {
-    retrievalSessionId: requiredString(row.retrieval_session_id, 'retrieval_session_id'),
-    cycle: finiteInteger(row.cycle, 'cycle'),
-    gaps: parseJsonArray(row.gaps_json, 'gaps_json') as RetrievalGapRecord[],
-    selectedIds: parseStringArray(row.selected_ids, 'selected_ids'),
-    rejectedIds: parseStringArray(row.rejected_ids, 'rejected_ids'),
-    tokenCost: finiteInteger(row.token_cost, 'token_cost'),
-    remainingTokenBudget: finiteInteger(row.remaining_token_budget, 'remaining_token_budget'),
-    quality: parseJsonObject(row.quality_json, 'quality_json'),
-    receipt: requiredString(row.receipt, 'receipt'),
-    evidenceHash: requiredString(row.evidence_hash, 'evidence_hash'),
-    createdAt: finiteInteger(row.created_at, 'created_at'),
-  };
-}
-
-export function serializeRetrievalJson(value: unknown): string {
-  return JSON.stringify(canonicalize(value));
-}
-
-export function isRetrievalSessionState(value: unknown): value is RetrievalSessionState {
-  return value === 'open' || value === 'satisfied' || value === 'exhausted' || value === 'expired';
-}
-
-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('Retrieval 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('Retrieval 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 parseJsonArray(value: unknown, field: string): unknown[] {
-  const parsed = parseJson(value, field);
-  if (!Array.isArray(parsed)) throw new Error(`Invalid persisted ${field}: expected array`);
-  return parsed;
-}
-
-function parseStringArray(value: unknown, field: string): string[] {
-  const parsed = parseJsonArray(value, field);
-  if (parsed.some(item => typeof item !== 'string')) throw new Error(`Invalid persisted ${field}: expected strings`);
-  return parsed as string[];
-}
-
-function parseJsonObject(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 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 finiteInteger(value: unknown, field: string): number {
-  const result = Number(value);
-  if (!Number.isSafeInteger(result) || result < 0) throw new Error(`Invalid persisted ${field}`);
-  return result;
-}

package/src/semantic-resolution.ts

@@ -1,181 +0,0 @@
-export type PersistedSemanticResolutionState = 'provisional' | 'resolved' | 'abstained' | 'unavailable';
-export type PersistedSemanticGeneratedBy = 'deterministic' | 'embedding_router' | 'host_semantic' | 'hybrid';
-
-export interface SemanticResolutionRecord {
-  frameHash: string;
-  projectRoot: string;
-  projectId: string;
-  hostId: string;
-  sessionId: string;
-  turnId: string;
-  requestId: string;
-  sourceHash: string;
-  artifactHash: string;
-  artifactRevision: number;
-  supersedesFrameHash?: string;
-  state: PersistedSemanticResolutionState;
-  generatedBy: PersistedSemanticGeneratedBy;
-  modelId?: string;
-  modelRevision?: string;
-  routeCatalogVersion: string;
-  thresholdVersion: string;
-  route: Record<string, unknown>;
-  sampling: Record<string, unknown>;
-  conflicts: Array<Record<string, unknown>>;
-  frame: Record<string, unknown>;
-  durationMs: number;
-  createdAt: number;
-}
-
-const STATES = new Set<PersistedSemanticResolutionState>([
-  'provisional', 'resolved', 'abstained', 'unavailable',
-]);
-const GENERATORS = new Set<PersistedSemanticGeneratedBy>([
-  'deterministic', 'embedding_router', 'host_semantic', 'hybrid',
-]);
-
-export function assertSemanticResolutionRecord(record: SemanticResolutionRecord): void {
-  for (const [field, value] of Object.entries({
-    frameHash: record.frameHash,
-    projectRoot: record.projectRoot,
-    projectId: record.projectId,
-    hostId: record.hostId,
-    sessionId: record.sessionId,
-    turnId: record.turnId,
-    requestId: record.requestId,
-    sourceHash: record.sourceHash,
-    artifactHash: record.artifactHash,
-    routeCatalogVersion: record.routeCatalogVersion,
-    thresholdVersion: record.thresholdVersion,
-  })) {
-    if (typeof value !== 'string' || value.length === 0) {
-      throw new Error(`SEMANTIC_RESOLUTION_INVALID:${field}`);
-    }
-  }
-  if (!Number.isSafeInteger(record.artifactRevision) || record.artifactRevision < 1) {
-    throw new Error('SEMANTIC_RESOLUTION_INVALID:artifactRevision');
-  }
-  if (!Number.isSafeInteger(record.durationMs) || record.durationMs < 0
-    || !Number.isSafeInteger(record.createdAt) || record.createdAt < 0) {
-    throw new Error('SEMANTIC_RESOLUTION_INVALID:timing');
-  }
-  if (!STATES.has(record.state) || !GENERATORS.has(record.generatedBy)) {
-    throw new Error('SEMANTIC_RESOLUTION_INVALID:enum');
-  }
-  if (record.frame.frameHash !== record.frameHash) {
-    throw new Error('SEMANTIC_RESOLUTION_FRAME_HASH_MISMATCH');
-  }
-  stableSemanticResolutionJson(record.route);
-  stableSemanticResolutionJson(record.sampling);
-  stableSemanticResolutionJson(record.conflicts);
-  stableSemanticResolutionJson(record.frame);
-}
-
-export function stableSemanticResolutionJson(value: unknown): string {
-  return JSON.stringify(canonicalize(value));
-}
-
-export function mapSemanticResolutionRow(row: Record<string, unknown>): SemanticResolutionRecord {
-  const state = requiredString(row.state, 'state') as PersistedSemanticResolutionState;
-  const generatedBy = requiredString(row.generated_by, 'generated_by') as PersistedSemanticGeneratedBy;
-  if (!STATES.has(state) || !GENERATORS.has(generatedBy)) {
-    throw new Error('SEMANTIC_RESOLUTION_ROW_INVALID:enum');
-  }
-  const result: SemanticResolutionRecord = {
-    frameHash: requiredString(row.frame_hash, 'frame_hash'),
-    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'),
-    sourceHash: requiredString(row.source_hash, 'source_hash'),
-    artifactHash: requiredString(row.artifact_hash, 'artifact_hash'),
-    artifactRevision: requiredPositiveInteger(row.artifact_revision, 'artifact_revision'),
-    ...(optionalString(row.supersedes_frame_hash)
-      ? { supersedesFrameHash: optionalString(row.supersedes_frame_hash) }
-      : {}),
-    state,
-    generatedBy,
-    ...(optionalString(row.model_id) ? { modelId: optionalString(row.model_id) } : {}),
-    ...(optionalString(row.model_revision) ? { modelRevision: optionalString(row.model_revision) } : {}),
-    routeCatalogVersion: requiredString(row.route_catalog_version, 'route_catalog_version'),
-    thresholdVersion: requiredString(row.threshold_version, 'threshold_version'),
-    route: parseObject(row.route_json, 'route_json'),
-    sampling: parseObject(row.sampling_json, 'sampling_json'),
-    conflicts: parseObjectArray(row.conflicts_json, 'conflicts_json'),
-    frame: parseObject(row.frame_json, 'frame_json'),
-    durationMs: requiredNonNegativeInteger(row.duration_ms, 'duration_ms'),
-    createdAt: requiredNonNegativeInteger(row.created_at, 'created_at'),
-  };
-  assertSemanticResolutionRecord(result);
-  return result;
-}
-
-function canonicalize(value: unknown): unknown {
-  if (value === undefined) return undefined;
-  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_RESOLUTION_JSON_INVALID');
-    return value;
-  }
-  if (Array.isArray(value)) return value.map(item => {
-    if (item === undefined) throw new Error('SEMANTIC_RESOLUTION_JSON_INVALID');
-    return canonicalize(item);
-  });
-  if (!value || typeof value !== 'object' || Object.getPrototypeOf(value) !== Object.prototype) {
-    throw new Error('SEMANTIC_RESOLUTION_JSON_INVALID');
-  }
-  const record = value as Record<string, unknown>;
-  return Object.fromEntries(Object.keys(record).sort()
-    .filter(key => record[key] !== undefined)
-    .map(key => [key, canonicalize(record[key])]));
-}
-
-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(`SEMANTIC_RESOLUTION_ROW_INVALID:${field}`);
-  }
-  return parsed as Record<string, unknown>;
-}
-
-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(`SEMANTIC_RESOLUTION_ROW_INVALID:${field}`);
-  }
-  return parsed as Array<Record<string, unknown>>;
-}
-
-function parseJson(value: unknown, field: string): unknown {
-  if (typeof value !== 'string') throw new Error(`SEMANTIC_RESOLUTION_ROW_INVALID:${field}`);
-  try { return JSON.parse(value) as unknown; } catch {
-    throw new Error(`SEMANTIC_RESOLUTION_ROW_INVALID:${field}`);
-  }
-}
-
-function requiredString(value: unknown, field: string): string {
-  if (typeof value !== 'string' || value.length === 0) {
-    throw new Error(`SEMANTIC_RESOLUTION_ROW_INVALID:${field}`);
-  }
-  return value;
-}
-
-function optionalString(value: unknown): string | undefined {
-  return typeof value === 'string' && value.length > 0 ? value : undefined;
-}
-
-function requiredPositiveInteger(value: unknown, field: string): number {
-  const result = requiredNonNegativeInteger(value, field);
-  if (result < 1) throw new Error(`SEMANTIC_RESOLUTION_ROW_INVALID:${field}`);
-  return result;
-}
-
-function requiredNonNegativeInteger(value: unknown, field: string): number {
-  const result = Number(value);
-  if (!Number.isSafeInteger(result) || result < 0) {
-    throw new Error(`SEMANTIC_RESOLUTION_ROW_INVALID:${field}`);
-  }
-  return result;
-}

package/src/task-runtime.ts

@@ -1,169 +0,0 @@
-import { createHash } from 'node:crypto';
-
-export interface TaskRuntimeIdentityRecord {
-  projectRoot: string;
-  projectId: string;
-  hostId: string;
-  sessionId: string;
-  turnId: string;
-  requestId: string;
-  executionId?: string;
-}
-
-export interface TaskRuntimeEventRecord {
-  schemaVersion: 'task-runtime-event.v1';
-  producer: string;
-  producerVersion: string;
-  eventId: string;
-  sequence: number;
-  identity: TaskRuntimeIdentityRecord;
-  taskSpecHash: string;
-  kind: string;
-  payload: Record<string, unknown>;
-  createdAt: number;
-}
-
-export type TaskRuntimeChannelRequirement = 'required' | 'optional' | 'not_required';
-export type TaskRuntimeChannelStatus =
-  | 'satisfied' | 'intentional_abstention' | 'empty_valid' | 'degraded' | 'failed';
-export type TaskRuntimeObligationState = 'pending' | 'satisfied' | 'degraded' | 'failed';
-
-export interface TaskRuntimeChannelRecord {
-  requirement: TaskRuntimeChannelRequirement;
-  status: TaskRuntimeChannelStatus;
-  reasonCode: string;
-  evidenceIds: string[];
-  material: boolean;
-}
-
-export interface TaskRuntimeObligationRecord {
-  requirement: TaskRuntimeChannelRequirement;
-  state: TaskRuntimeObligationState;
-  receiptId?: string;
-  reasonCode?: string;
-}
-
-export interface TaskRuntimeSnapshotRecord {
-  schemaVersion: 'task-runtime-snapshot.v1';
-  producer: string;
-  producerVersion: string;
-  identity: TaskRuntimeIdentityRecord;
-  taskSpecHash: string;
-  lastEventSequence: number;
-  artifacts: {
-    requiredIdentityIds: string[];
-    resolvedIdentityIds: string[];
-    ambiguousIdentityIds: string[];
-  };
-  channels: Partial<Record<'code' | 'memory' | 'knowledge', TaskRuntimeChannelRecord>>;
-  contextReceiptId?: string;
-  action: TaskRuntimeObligationRecord;
-  verification: TaskRuntimeObligationRecord;
-  memory: TaskRuntimeObligationRecord;
-  durableWorkIds: string[];
-  terminal: 'running' | 'retry_pending' | 'completed' | 'completed_with_degradation' | 'failed';
-  runtimeHealth: 'healthy' | 'degraded' | 'unavailable';
-  snapshotHash: string;
-  updatedAt: number;
-}
-
-export function stableTaskRuntimeJson(value: unknown): string {
-  return JSON.stringify(canonicalize(value));
-}
-
-export function stableTaskRuntimeHash(value: unknown): string {
-  return createHash('sha256').update(stableTaskRuntimeJson(value)).digest('hex');
-}
-
-export function mapTaskRuntimeEventRow(row: Record<string, unknown>): TaskRuntimeEventRecord {
-  return {
-    schemaVersion: requiredLiteral(row.schema_version, 'task-runtime-event.v1'),
-    producer: requiredString(row.producer, 'producer'),
-    producerVersion: requiredString(row.producer_version, 'producer_version'),
-    eventId: requiredString(row.event_id, 'event_id'),
-    sequence: requiredPositiveInteger(row.sequence, 'sequence'),
-    identity: mapIdentity(row),
-    taskSpecHash: requiredString(row.task_spec_hash, 'task_spec_hash'),
-    kind: requiredString(row.kind, 'kind'),
-    payload: parseObject(row.payload_json, 'payload_json'),
-    createdAt: requiredNonNegativeInteger(row.created_at, 'created_at'),
-  };
-}
-
-export function mapTaskRuntimeSnapshotRow(row: Record<string, unknown>): TaskRuntimeSnapshotRecord {
-  const snapshot = parseObject(row.snapshot_json, 'snapshot_json') as unknown as TaskRuntimeSnapshotRecord;
-  if (snapshot.schemaVersion !== 'task-runtime-snapshot.v1') {
-    throw new Error(`TASK_RUNTIME_SCHEMA_UNSUPPORTED:${String(snapshot.schemaVersion)}`);
-  }
-  if (snapshot.snapshotHash !== requiredString(row.snapshot_hash, 'snapshot_hash')) {
-    throw new Error('TASK_RUNTIME_SNAPSHOT_HASH_MISMATCH');
-  }
-  const { snapshotHash: _snapshotHash, ...body } = snapshot;
-  if (stableTaskRuntimeHash(body) !== snapshot.snapshotHash) {
-    throw new Error('TASK_RUNTIME_SNAPSHOT_HASH_MISMATCH');
-  }
-  return snapshot;
-}
-
-function mapIdentity(row: Record<string, unknown>): TaskRuntimeIdentityRecord {
-  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'),
-    ...(optionalString(row.execution_id) ? { executionId: optionalString(row.execution_id) } : {}),
-  };
-}
-
-function requiredLiteral<T extends string>(value: unknown, literal: T): T {
-  if (value !== literal) throw new Error(`TASK_RUNTIME_SCHEMA_UNSUPPORTED:${String(value)}`);
-  return literal;
-}
-
-function requiredString(value: unknown, field: string): string {
-  if (typeof value !== 'string' || !value.trim()) throw new Error(`TASK_RUNTIME_ROW_INVALID:${field}`);
-  return value;
-}
-
-function optionalString(value: unknown): string | undefined {
-  return typeof value === 'string' && value.length > 0 ? value : undefined;
-}
-
-function requiredPositiveInteger(value: unknown, field: string): number {
-  const result = Number(value);
-  if (!Number.isSafeInteger(result) || result < 1) throw new Error(`TASK_RUNTIME_ROW_INVALID:${field}`);
-  return result;
-}
-
-function requiredNonNegativeInteger(value: unknown, field: string): number {
-  const result = Number(value);
-  if (!Number.isSafeInteger(result) || result < 0) throw new Error(`TASK_RUNTIME_ROW_INVALID:${field}`);
-  return result;
-}
-
-function parseObject(value: unknown, field: string): Record<string, unknown> {
-  if (typeof value !== 'string') throw new Error(`TASK_RUNTIME_ROW_INVALID:${field}`);
-  try {
-    const parsed = JSON.parse(value) as unknown;
-    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('not object');
-    return parsed as Record<string, unknown>;
-  } catch {
-    throw new Error(`TASK_RUNTIME_ROW_INVALID:${field}`);
-  }
-}
-
-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('TASK_RUNTIME_JSON_INVALID');
-    return value;
-  }
-  if (Array.isArray(value)) return value.map(canonicalize);
-  if (!value || typeof value !== 'object' || Object.getPrototypeOf(value) !== Object.prototype) {
-    throw new Error('TASK_RUNTIME_JSON_INVALID');
-  }
-  return Object.fromEntries(Object.keys(value as Record<string, unknown>).sort()
-    .map(key => [key, canonicalize((value as Record<string, unknown>)[key])]));
-}