@devflow-tools/database 0.16.18 → 0.16.20

package/src/host-actions.ts

@@ -0,0 +1,211 @@
+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

@@ -30,6 +30,31 @@ export type {
   WorkQueueHealth,
   WorkState,
 } from './work-queue';
+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,

package/src/retrieval-sessions.ts

@@ -0,0 +1,196 @@
+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;
+}