@devflow-tools/database 0.16.20 → 0.16.22

package/src/learning-candidates.ts

@@ -0,0 +1,181 @@
+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/work-queue.ts

@@ -4,6 +4,8 @@ export type WorkKind =
   | 'memory.turn_capture'
   | 'memory.turn_distill'
   | 'memory.vector_backfill'
+  | 'context.prefetch'
+  | 'learning.analyze_session'
   | 'session.bootstrap'
   | 'session.finalize'
   | 'telemetry.reconcile';