principles-disciple 1.126.0 → 1.128.0

package/dist/core/trajectory-types.d.ts

@@ -0,0 +1,220 @@
+/**
+ * Trajectory database type definitions.
+ *
+ * PURPOSE: Track task outcomes, trust changes, and evolution progress over time.
+ * USAGE: Insights, trends, and Phase 3 supporting evidence (where explicitly allowed).
+ * NOT FOR: Control decisions, Phase 3 eligibility, or real-time operations.
+ */
+export type CorrectionSampleReviewStatus = 'pending' | 'approved' | 'rejected';
+export type CorrectionExportMode = 'raw' | 'redacted';
+export interface TrajectoryDataStats {
+    dbPath: string;
+    dbSizeBytes: number;
+    assistantTurns: number;
+    userTurns: number;
+    toolCalls: number;
+    painEvents: number;
+    pendingSamples: number;
+    approvedSamples: number;
+    blobBytes: number;
+    lastIngestAt: string | null;
+}
+export interface TrajectoryAssistantTurnInput {
+    sessionId: string;
+    runId: string;
+    provider: string;
+    model: string;
+    rawText: string;
+    sanitizedText: string;
+    usageJson: unknown;
+    empathySignalJson: unknown;
+    createdAt?: string;
+}
+export interface TrajectoryUserTurnInput {
+    sessionId: string;
+    turnIndex: number;
+    rawText: string;
+    correctionDetected: boolean;
+    correctionCue?: string | null;
+    referencesAssistantTurnId?: number | null;
+    createdAt?: string;
+}
+export interface TrajectoryToolCallInput {
+    sessionId: string;
+    toolName: string;
+    outcome: 'success' | 'failure' | 'blocked';
+    durationMs?: number | null;
+    exitCode?: number | null;
+    errorType?: string | null;
+    errorMessage?: string | null;
+    gfiBefore?: number | null;
+    gfiAfter?: number | null;
+    paramsJson?: unknown;
+    createdAt?: string;
+}
+export interface TrajectoryPainEventInput {
+    sessionId: string;
+    source: string;
+    score: number;
+    reason?: string | null;
+    severity?: string | null;
+    origin?: string | null;
+    confidence?: number | null;
+    text?: string;
+    createdAt?: string;
+    /** PRI-406: Canonical pain identity (e.g. manual_<ts>_<hash> or pain_<ts>_<hash>). */
+    canonicalPainId?: string;
+    /** PRI-406: Runtime V2 diagnostician task ID linked to this pain event. */
+    runtimeTaskId?: string;
+}
+export interface TrajectoryGateBlockInput {
+    sessionId?: string | null;
+    toolName: string;
+    filePath?: string | null;
+    reason: string;
+    planStatus?: string | null;
+    createdAt?: string;
+}
+type DailyMetricRow = {
+    day: string;
+    tool_calls: number;
+    failures: number;
+    user_corrections: number;
+};
+export interface TrajectoryTrustChangeInput {
+    sessionId?: string | null;
+    previousScore: number;
+    newScore: number;
+    delta: number;
+    reason: string;
+    createdAt?: string;
+}
+export interface TrajectoryPrincipleEventInput {
+    principleId?: string | null;
+    eventType: string;
+    payload: unknown;
+    createdAt?: string;
+}
+export interface TrajectoryTaskOutcomeInput {
+    sessionId: string;
+    taskId?: string | null;
+    outcome: string;
+    summary?: string | null;
+    principleIdsJson?: unknown;
+    createdAt?: string;
+}
+export interface TrajectorySessionInput {
+    sessionId: string;
+    startedAt?: string;
+}
+export type TaskKind = 'pain_diagnosis' | 'sleep_reflection' | 'model_eval' | 'keyword_optimization';
+export type TaskPriority = 'high' | 'medium' | 'low';
+interface EvolutionTaskInputBase {
+    taskId: string;
+    traceId: string;
+    source: string;
+    reason?: string | null;
+    score?: number;
+    status?: string;
+    enqueuedAt?: string | null;
+    startedAt?: string | null;
+    completedAt?: string | null;
+    resolution?: string | null;
+    createdAt?: string;
+    updatedAt?: string;
+}
+export interface EvolutionTaskInputV2 extends EvolutionTaskInputBase {
+    taskKind?: TaskKind;
+    priority?: TaskPriority;
+    retryCount?: number;
+    maxRetries?: number;
+    lastError?: string | null;
+    resultRef?: string | null;
+}
+export type EvolutionTaskInput = EvolutionTaskInputV2;
+export interface EvolutionEventInput {
+    traceId: string;
+    taskId?: string | null;
+    stage: string;
+    level?: string;
+    message: string;
+    summary?: string | null;
+    metadata?: unknown;
+    createdAt?: string;
+}
+export interface EvolutionTaskRecord {
+    id: number;
+    taskId: string;
+    traceId: string;
+    source: string;
+    reason: string | null;
+    score: number;
+    status: string;
+    enqueuedAt: string | null;
+    startedAt: string | null;
+    completedAt: string | null;
+    resolution: string | null;
+    createdAt: string;
+    updatedAt: string;
+    taskKind: TaskKind | null;
+    priority: TaskPriority | null;
+    retryCount: number | null;
+    maxRetries: number | null;
+    lastError: string | null;
+    resultRef: string | null;
+}
+export interface EvolutionEventRecord {
+    id: number;
+    traceId: string;
+    taskId: string | null;
+    stage: string;
+    level: string;
+    message: string;
+    summary: string | null;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+}
+export interface EvolutionTaskFilters {
+    status?: string;
+    dateFrom?: string;
+    dateTo?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface AssistantTurnRecord {
+    id: number;
+    sessionId: string;
+    runId: string;
+    provider: string;
+    model: string;
+    rawText: string;
+    sanitizedText: string;
+    blobRef: string | null;
+    createdAt: string;
+}
+export interface CorrectionSampleRecord {
+    sampleId: string;
+    sessionId: string;
+    badAssistantTurnId: number;
+    userCorrectionTurnId: number;
+    recoveryToolSpanJson: string;
+    diffExcerpt: string;
+    principleIdsJson: string;
+    qualityScore: number;
+    reviewStatus: CorrectionSampleReviewStatus;
+    exportMode: CorrectionExportMode;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface TrajectoryExportResult {
+    filePath: string;
+    count: number;
+    mode?: CorrectionExportMode;
+}
+export interface TrajectoryDatabaseOptions {
+    workspaceDir: string;
+    blobInlineThresholdBytes?: number;
+    busyTimeoutMs?: number;
+    orphanBlobGraceDays?: number;
+}
+export type { DailyMetricRow };

package/dist/core/trajectory-types.js

@@ -0,0 +1,8 @@
+/**
+ * Trajectory database type definitions.
+ *
+ * PURPOSE: Track task outcomes, trust changes, and evolution progress over time.
+ * USAGE: Insights, trends, and Phase 3 supporting evidence (where explicitly allowed).
+ * NOT FOR: Control decisions, Phase 3 eligibility, or real-time operations.
+ */
+export {};

package/dist/core/trajectory.d.ts

@@ -0,0 +1,242 @@
+import type { CorrectionSampleReviewStatus, CorrectionExportMode, TrajectoryDataStats, TrajectoryAssistantTurnInput, TrajectoryUserTurnInput, TrajectoryToolCallInput, TrajectoryPainEventInput, TrajectoryGateBlockInput, TrajectoryTrustChangeInput, TrajectoryPrincipleEventInput, TrajectoryTaskOutcomeInput, TrajectorySessionInput, EvolutionTaskInput, EvolutionEventInput, EvolutionTaskRecord, EvolutionEventRecord, EvolutionTaskFilters, AssistantTurnRecord, CorrectionSampleRecord, TrajectoryExportResult, TrajectoryDatabaseOptions } from './trajectory-types.js';
+export type { CorrectionSampleReviewStatus, CorrectionExportMode, TrajectoryDataStats, TrajectoryAssistantTurnInput, TrajectoryUserTurnInput, TrajectoryToolCallInput, TrajectoryPainEventInput, TrajectoryGateBlockInput, DailyMetricRow, TrajectoryTrustChangeInput, TrajectoryPrincipleEventInput, TrajectoryTaskOutcomeInput, TrajectorySessionInput, TaskKind, TaskPriority, EvolutionTaskInput, EvolutionEventInput, EvolutionTaskRecord, EvolutionEventRecord, EvolutionTaskFilters, AssistantTurnRecord, CorrectionSampleRecord, TrajectoryExportResult, TrajectoryDatabaseOptions, } from './trajectory-types.js';
+export declare class TrajectoryDatabase {
+    private readonly workspaceDir;
+    private readonly stateDir;
+    private readonly dbPath;
+    private readonly blobDir;
+    private readonly exportDir;
+    private readonly blobInlineThresholdBytes;
+    private readonly orphanBlobGraceMs;
+    private readonly db;
+    constructor(opts: TrajectoryDatabaseOptions);
+    dispose(): void;
+    recordSession(input: TrajectorySessionInput): void;
+    recordAssistantTurn(input: TrajectoryAssistantTurnInput): number;
+    recordUserTurn(input: TrajectoryUserTurnInput): number;
+    recordToolCall(input: TrajectoryToolCallInput): number;
+    recordPainEvent(input: TrajectoryPainEventInput): number;
+    /**
+     * Search pain_events using FTS5 full-text search (MEM-04).
+     * Returns pain events matching the query, ordered by relevance.
+     */
+    searchPainEvents(query: string, limit?: number): {
+        id: number;
+        sessionId: string;
+        source: string;
+        score: number;
+        reason: string | null;
+        severity: string | null;
+        origin: string | null;
+        confidence: number | null;
+        text: string | null;
+        createdAt: string;
+    }[];
+    recordGateBlock(input: TrajectoryGateBlockInput): void;
+    recordTrustChange(input: TrajectoryTrustChangeInput): void;
+    recordPrincipleEvent(input: TrajectoryPrincipleEventInput): void;
+    recordTaskOutcome(input: TrajectoryTaskOutcomeInput): void;
+    recordEvolutionTask(input: EvolutionTaskInput): void;
+    updateEvolutionTask(taskId: string, updates: Partial<Omit<EvolutionTaskInput, 'taskId' | 'traceId' | 'source'>>): void;
+    recordEvolutionEvent(input: EvolutionEventInput): void;
+    /**
+     * List evolution tasks with optional filtering.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
+    listEvolutionTasks(filters?: EvolutionTaskFilters): EvolutionTaskRecord[];
+    /**
+     * List evolution events for a trace or globally.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
+    listEvolutionEvents(traceId?: string, filters?: {
+        limit?: number;
+        offset?: number;
+    }): EvolutionEventRecord[];
+    /**
+     * Get evolution task by trace ID.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
+    getEvolutionTaskByTraceId(traceId: string): EvolutionTaskRecord | null;
+    /**
+     * Get evolution task statistics.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
+    getEvolutionStats(): {
+        total: number;
+        pending: number;
+        inProgress: number;
+        completed: number;
+        failed: number;
+    };
+    /**
+     * List recent sessions from the trajectory database.
+     *
+     * Returns: Recent session records ordered by most recently updated.
+     *
+     * @param options.limit - Maximum number of sessions to return (default: 20)
+     * @param options.dateFrom - Only return sessions updated after this date
+     * @param options.dateTo - Only return sessions updated before this date
+     */
+    listRecentSessions(options?: {
+        limit?: number;
+        dateFrom?: string;
+        dateTo?: string;
+    }): {
+        sessionId: string;
+        startedAt: string;
+        updatedAt: string;
+    }[];
+    /**
+     * List assistant turns for a session.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
+    listAssistantTurns(sessionId: string): AssistantTurnRecord[];
+    /**
+     * List tool calls for a session.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
+    listToolCallsForSession(sessionId: string): {
+        id: number;
+        toolName: string;
+        outcome: string;
+        filePath: string | null;
+        durationMs: number | null;
+        exitCode: number | null;
+        errorType: string | null;
+        errorMessage: string | null;
+        gfiBefore: number | null;
+        gfiAfter: number | null;
+        createdAt: string;
+    }[];
+    /**
+     * List pain events for a session.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
+    listPainEventsForSession(sessionId: string): {
+        id: number;
+        source: string;
+        score: number;
+        reason: string | null;
+        severity: string | null;
+        origin: string | null;
+        confidence: number | null;
+        createdAt: string;
+    }[];
+    /**
+     * List user turns for a session.
+     * Returns sanitized/reduced fields for nocturnal use — NO raw text.
+     */
+    listUserTurnsForSession(sessionId: string): {
+        id: number;
+        turnIndex: number;
+        rawExcerpt: string;
+        correctionDetected: boolean;
+        correctionCue: string | null;
+        createdAt: string;
+    }[];
+    /**
+     * List correction samples with optional review status filter.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
+    listCorrectionSamples(status?: CorrectionSampleReviewStatus): CorrectionSampleRecord[];
+    /**
+     * List gate blocks for a session.
+     * Returns minimal fields for nocturnal use — no raw text.
+     */
+    listGateBlocksForSession(sessionId: string): {
+        id: number;
+        toolName: string;
+        filePath: string | null;
+        reason: string;
+        planStatus: string | null;
+        createdAt: string;
+    }[];
+    /**
+     * List correction samples for a specific session.
+     * Returns minimal fields for nocturnal use — correction cue only.
+     * #268: Wire correction_samples into nocturnal pipeline.
+     */
+    listCorrectionSamplesForSession(sessionId: string): {
+        correctionCue: string | null;
+    }[];
+    reviewCorrectionSample(sampleId: string, status: Exclude<CorrectionSampleReviewStatus, 'pending'>, note?: string): CorrectionSampleRecord;
+    /**
+     * When a correction sample is rejected, emit a pain event to the trajectory.
+     * This feeds rejected corrections into the nocturnal pipeline as a high-fidelity
+     * violation signal (human-verified, unlike heuristic pain detection).
+     */
+    private recordCorrectionRejectedPain;
+    /**
+     * Export correction samples to JSONL file.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
+    exportCorrections(opts: {
+        mode: CorrectionExportMode;
+        approvedOnly: boolean;
+    }): TrajectoryExportResult;
+    /**
+     * Export analytics data to JSON file.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
+    exportAnalytics(): TrajectoryExportResult;
+    /**
+     * Get trajectory database statistics.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
+    getDataStats(): TrajectoryDataStats;
+    cleanupBlobStorage(): {
+        removedFiles: number;
+        reclaimedBytes: number;
+    };
+    private initSchema;
+    private importLegacyArtifacts;
+    private migrateSchema;
+    /**
+     * Get daily metrics for analytics.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
+    private dailyMetrics;
+    private importLegacySessions;
+    private importLegacyEvents;
+    private importLegacyEvolution;
+    private markImported;
+    private isImported;
+    private maybeCreateCorrectionSample;
+    private recordExportAudit;
+    private storeRawText;
+    private restoreRawText;
+    private computeBlobBytes;
+    private pruneUnreferencedBlobs;
+    private withWrite;
+}
+export declare class TrajectoryRegistry {
+    private static readonly instances;
+    static get(workspaceDir: string, opts?: Omit<TrajectoryDatabaseOptions, 'workspaceDir'>): TrajectoryDatabase;
+    static dispose(workspaceDir: string): void;
+    static clear(): void;
+    static use<T>(workspaceDir: string, fn: (_db: TrajectoryDatabase) => T, opts?: Omit<TrajectoryDatabaseOptions, 'workspaceDir'>): T;
+}