principles-disciple 1.201.0 → 1.202.0

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

@@ -0,0 +1,247 @@
+/**
+ * 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;
+    stopReason?: string | null;
+    thinkingBlocksCount?: number | null;
+    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;
+    resultPreview?: string | null;
+    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;
+    stopReason: string | null;
+    thinkingBlocksCount: number | 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;
+}
+/**
+ * Raw row from tool_calls for RuleContext v2 history assembly.
+ * Fields are raw strings from SQLite — the assembler validates them as unknown.
+ */
+export interface RuleHostContextRow {
+    readonly id: number;
+    readonly toolName: string;
+    readonly outcome: string;
+    readonly paramsJson: string;
+}
+/** A single tool call selected by an Owner as labelled RuleHost evidence. */
+export interface RuleHostEvidenceRow extends RuleHostContextRow {
+    readonly sessionId: string;
+}
+/**
+ * Result of getRuleHostContextRows: FIFO-ordered rows + truncated flag.
+ * truncated=true when more than `limit` rows existed (limit+1 read trick).
+ */
+export interface RuleHostContextResult {
+    readonly rows: readonly RuleHostContextRow[];
+    readonly truncated: boolean;
+}
+export type { DailyMetricRow };

package/dist/core/trajectory.d.ts

@@ -0,0 +1,279 @@
+import type { CorrectionSampleReviewStatus, CorrectionExportMode, TrajectoryDataStats, TrajectoryAssistantTurnInput, TrajectoryUserTurnInput, TrajectoryToolCallInput, TrajectoryPainEventInput, TrajectoryGateBlockInput, TrajectoryTrustChangeInput, TrajectoryPrincipleEventInput, TrajectoryTaskOutcomeInput, TrajectorySessionInput, EvolutionTaskInput, EvolutionEventInput, EvolutionTaskRecord, EvolutionEventRecord, EvolutionTaskFilters, AssistantTurnRecord, CorrectionSampleRecord, TrajectoryExportResult, TrajectoryDatabaseOptions, RuleHostContextResult, RuleHostEvidenceRow } 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, RuleHostContextRow, RuleHostContextResult, RuleHostEvidenceRow, } from './trajectory-types.js';
+/**
+ * Initialize trajectory.db schema at the given workspace directory.
+ *
+ * Opens trajectory.db in write mode, applies the full schema (tables + indexes + views +
+ * migrations), then closes the DB. Does NOT run importLegacyArtifacts() or
+ * pruneUnreferencedBlobs() — those are runtime side-effects of TrajectoryDatabase
+ * construction and are not needed for pure initialization.
+ *
+ * Idempotent: safe to call on an existing DB; all CREATE statements use IF NOT EXISTS.
+ *
+ * @returns list of created/verified table names and any warnings
+ */
+export declare function initTrajectorySchema(workspaceDir: string): {
+    tables: string[];
+    warnings: string[];
+};
+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;
+    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;
+        resultPreview: string | null;
+        createdAt: string;
+    }[];
+    /**
+     * PRI-482 Phase 3: Query tool_calls for RuleContext v2 history assembly.
+     *
+     * Reads limit+1 rows (DESC by id) to compute truncated, then reverses to FIFO.
+     * Returns raw rows — the assembler (rule-context-assembler.ts) validates them.
+     *
+     * Spec: §5.1, §5.2. ERR-026: reuses production schema (no hand-written DDL).
+     */
+    getRuleHostContextRows(sessionId: string, limit?: number): RuleHostContextResult;
+    /** Resolve one Owner-selected tool call without inferring its desired label. */
+    getRuleHostEvidenceRow(id: number): RuleHostEvidenceRow | null;
+    /** Return FIFO history strictly before an Owner-selected tool call. */
+    getRuleHostContextRowsBefore(sessionId: string, beforeId: number, limit?: number): RuleHostContextResult;
+    /**
+     * 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;
+    }[];
+    /**
+     * PRI-484 Phase 5 — Look up a single pain event by canonical_pain_id.
+     *
+     * Used by BehaviorExamplePackAssembler to anchor a pain lineage without
+     * already knowing the session_id. Returns null when not found.
+     *
+     * ERR-001 (rc-1, rc-2): row fields validated as unknown — no `as` bypass.
+     * Uses a type-guard predicate to narrow the DB row structurally.
+     */
+    getPainEventByCanonicalId(canonicalPainId: string): {
+        id: number;
+        sessionId: string;
+        source: string;
+        score: number;
+        reason: string | null;
+        severity: string | null;
+        origin: string | null;
+        confidence: number | null;
+        text: string | null;
+        canonicalPainId: string;
+        runtimeTaskId: string | null;
+        createdAt: string;
+    } | null;
+    /**
+     * 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;
+}

package/dist/core/workflow-funnel-loader.d.ts

@@ -0,0 +1,72 @@
+/**
+ * WorkflowFunnelLoader — Loads and watches workflows.yaml as the SSOT
+ * for WORKFLOW_FUNNELS definition table.
+ *
+ * D-01: workflows.yaml is the single source of truth (SSOT).
+ * D-02: workflows.yaml lives in .state/ directory per workspace.
+ * D-03: Developers manually maintain workflows.yaml (no auto-registration).
+ * D-04: Code only reads YAML, never writes it.
+ */
+/**
+ * A single stage in a workflow funnel.
+ * Policy fields are optional — existing stages without policy fields remain valid.
+ */
+export interface WorkflowStage {
+    name: string;
+    eventType: string;
+    eventCategory: string;
+    statsField: string;
+    timeoutMs?: number;
+    successCriteria?: string;
+    legacyDisabled?: boolean;
+    observability?: {
+        enabled?: boolean;
+        emitEvents?: string[];
+    };
+}
+/**
+ * Funnel-level policy that applies to all stages unless overridden per-stage.
+ */
+export interface FunnelPolicy {
+    timeoutMs?: number;
+    stageOrder?: 'strict' | 'relaxed';
+    legacyDisabled?: boolean;
+    observability?: {
+        enabled?: boolean;
+        emitEvents?: string[];
+        logLevel?: 'debug' | 'info' | 'warn' | 'error';
+    };
+}
+/**
+ * A workflow funnel definition.
+ */
+export interface WorkflowFunnel {
+    workflowId: string;
+    stages: WorkflowStage[];
+    policy?: FunnelPolicy;
+}
+/**
+ * Root of workflows.yaml schema.
+ */
+export interface WorkflowFunnelConfig {
+    version: string;
+    funnels: WorkflowFunnel[];
+}
+export declare class WorkflowFunnelLoader {
+    private readonly funnels;
+    private readonly fullFunnels;
+    private readonly configPath;
+    private watchHandle?;
+    private readonly warnings;
+    constructor(stateDir: string);
+    load(): void;
+    watch(): void;
+    dispose(): void;
+    getStages(workflowId: string): WorkflowStage[];
+    getFunnel(workflowId: string): WorkflowFunnel | undefined;
+    getAllFunnels(): Map<string, WorkflowStage[]>;
+    getAllFunnelsWithPolicy(): Map<string, WorkflowFunnel>;
+    getWarnings(): string[];
+    getConfigPath(): string;
+    private cloneFunnel;
+}