cognitive-core 0.2.4 → 0.3.1

package/dist/learning/maintenance-scheduler.js

@@ -12,9 +12,10 @@
  * contention. A duty-factor model ensures maintenance doesn't starve
  * the primary learning pipeline.
  */
+import { systemClock } from '../utils/clock.js';
 const DEFAULT_CONFIG = {
     mode: 'afterNBatches',
-    batchInterval: 5,
+    batchInterval: 1,
     intervalMs: 3_600_000,
     deferDuringBatch: true,
     maxQueueSize: 10,
@@ -29,8 +30,10 @@ export class MaintenanceScheduler {
     lastMaintenanceTime = 0;
     isBatchRunning = false;
     cycleHistory = [];
-    constructor(config) {
+    clock;
+    constructor(config, clock = systemClock) {
         this.config = { ...DEFAULT_CONFIG, ...config };
+        this.clock = clock;
     }
     /**
      * Register a maintenance task.
@@ -38,7 +41,7 @@ export class MaintenanceScheduler {
      */
     registerTask(task) {
         // Replace existing task with same name
-        this.registeredTasks = this.registeredTasks.filter(t => t.name !== task.name);
+        this.registeredTasks = this.registeredTasks.filter((t) => t.name !== task.name);
         this.registeredTasks.push(task);
         this.registeredTasks.sort((a, b) => b.priority - a.priority);
     }
@@ -46,7 +49,7 @@ export class MaintenanceScheduler {
      * Unregister a maintenance task by name.
      */
     unregisterTask(name) {
-        this.registeredTasks = this.registeredTasks.filter(t => t.name !== name);
+        this.registeredTasks = this.registeredTasks.filter((t) => t.name !== name);
     }
     /**
      * Signal that a batch cycle has completed.
@@ -81,8 +84,8 @@ export class MaintenanceScheduler {
             return this.batchesSinceLastMaintenance >= this.config.batchInterval;
         }
         if (this.config.mode === 'periodic') {
-            const now = Date.now();
-            return (now - this.lastMaintenanceTime) >= this.config.intervalMs;
+            const now = this.clock.nowMs();
+            return now - this.lastMaintenanceTime >= this.config.intervalMs;
         }
         return false;
     }
@@ -93,7 +96,7 @@ export class MaintenanceScheduler {
      * Can be called manually regardless of mode — bypasses trigger checks.
      */
     async runMaintenance(options) {
-        const start = Date.now();
+        const start = this.clock.nowMs();
         // Check if we should run (unless forced)
         if (!options?.force) {
             if (this.config.deferDuringBatch && this.isBatchRunning) {
@@ -106,7 +109,7 @@ export class MaintenanceScheduler {
         // Execute tasks in priority order
         const taskResults = [];
         for (const task of this.registeredTasks) {
-            const taskStart = Date.now();
+            const taskStart = this.clock.nowMs();
             try {
                 const result = await task.execute();
                 taskResults.push(result);
@@ -115,7 +118,7 @@ export class MaintenanceScheduler {
                 taskResults.push({
                     taskName: task.name,
                     success: false,
-                    durationMs: Date.now() - taskStart,
+                    durationMs: this.clock.nowMs() - taskStart,
                     details: {
                         error: error instanceof Error ? error.message : String(error),
                     },
@@ -124,12 +127,12 @@ export class MaintenanceScheduler {
         }
         // Reset counters
         this.batchesSinceLastMaintenance = 0;
-        this.lastMaintenanceTime = Date.now();
+        this.lastMaintenanceTime = this.clock.nowMs();
         const result = {
             ran: true,
             taskResults,
-            totalDurationMs: Date.now() - start,
-            timestamp: new Date(),
+            totalDurationMs: this.clock.nowMs() - start,
+            timestamp: this.clock.now(),
         };
         this.cycleHistory.push(result);
         if (this.cycleHistory.length > this.config.maxQueueSize) {
@@ -172,15 +175,15 @@ export class MaintenanceScheduler {
             ran: false,
             skipReason: reason,
             taskResults: [],
-            totalDurationMs: Date.now() - start,
-            timestamp: new Date(),
+            totalDurationMs: this.clock.nowMs() - start,
+            timestamp: this.clock.now(),
         };
     }
 }
 /**
  * Create a MaintenanceScheduler.
  */
-export function createMaintenanceScheduler(config) {
-    return new MaintenanceScheduler(config);
+export function createMaintenanceScheduler(config, clock) {
+    return new MaintenanceScheduler(config, clock);
 }
 //# sourceMappingURL=maintenance-scheduler.js.map

package/dist/learning/maintenance-scheduler.js.map

@@ -1 +1 @@
-{"version":3,"file":"maintenance-scheduler.js","sourceRoot":"","sources":["../../src/learning/maintenance-scheduler.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"maintenance-scheduler.js","sourceRoot":"","sources":["../../src/learning/maintenance-scheduler.ts"],"names":[],"mappings":"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"}

package/dist/learning/mechanism-trace.d.ts

@@ -0,0 +1,196 @@
+import type { ValidationRetrievalChannel, ValidationWriteChannel } from '../types/config.js';
+export declare const MECHANISM_TRACE_VERSION: 1;
+export type MechanismTraceVersion = typeof MECHANISM_TRACE_VERSION;
+export type MechanismTraceFamily = 'retrieval' | 'serve' | 'outcome' | 'attribution' | 'instant' | 'dream' | 'artifact' | 'mutation';
+export type MechanismArtifactType = 'experience' | 'knowledge' | 'playbook' | 'metaPlaybook' | 'shortTerm' | 'frontier' | 'diagnostic';
+export interface MechanismTraceBase {
+    version: MechanismTraceVersion;
+    family: MechanismTraceFamily;
+    timestamp: string;
+    /** Stable id for this mechanism event, when the emitter has one. */
+    eventId?: string;
+    /** Eval/session/run grouping key. */
+    runId?: string;
+    benchmark?: string;
+    arm?: string;
+    taskId?: string;
+    trajectoryId?: string;
+    /** Component that emitted the event, e.g. Atlas.solve or UnifiedLearningPipeline.dream. */
+    source?: string;
+}
+export interface MechanismRetrievalCandidate {
+    id: string;
+    type: MechanismArtifactType;
+    score?: number;
+    rank?: number;
+    retrievalMethod?: string;
+    decision?: 'use' | 'refine' | 'abstain' | 'filter';
+    reason?: string;
+    domainFallbackUsed?: boolean;
+    scoreFloorPassed?: boolean;
+    gateEnforced?: boolean;
+    injected?: boolean;
+    /** Lossless source diagnostic row, when this candidate came from candidateDecisions. */
+    rawCandidateDecision?: Record<string, unknown>;
+}
+export interface RetrievalMechanismTraceEvent extends MechanismTraceBase {
+    family: 'retrieval';
+    query: string;
+    domains?: string[];
+    channels?: ValidationRetrievalChannel[];
+    candidates: MechanismRetrievalCandidate[];
+    filters?: Record<string, unknown>;
+    fallback?: {
+        used: boolean;
+        reason?: string;
+    };
+}
+export interface ServedArtifact {
+    id: string;
+    type: MechanismArtifactType;
+    score?: number;
+    tokenCount?: number;
+    incorporationMode?: string;
+}
+export interface ServeMechanismTraceEvent extends MechanismTraceBase {
+    family: 'serve';
+    channels?: ValidationRetrievalChannel[];
+    injected: ServedArtifact[];
+    tokenFootprint?: number;
+    applicability?: {
+        gateEnabled?: boolean;
+        conditionsSurfaced?: boolean;
+    };
+}
+export interface OutcomeMechanismTraceEvent extends MechanismTraceBase {
+    family: 'outcome';
+    success: boolean;
+    status?: string;
+    partialScore?: number;
+    verifier?: string;
+    judgeScore?: number;
+    costUsd?: number;
+    latencyMs?: number;
+    model?: string;
+}
+export interface AttributionMechanismTraceEvent extends MechanismTraceBase {
+    family: 'attribution';
+    appliedPlaybookIds?: string[];
+    surfacedExperienceIds?: string[];
+    surfacedKnowledgeNoteIds?: string[];
+    injectedArtifactIds?: string[];
+    inference?: 'usage' | 'presence' | 'judge' | 'heuristic';
+    credit?: Array<{
+        id: string;
+        weight: number;
+        reason?: string;
+    }>;
+}
+export interface InstantMechanismTraceEvent extends MechanismTraceBase {
+    family: 'instant';
+    experienceStored?: {
+        id: string;
+        success?: boolean;
+        domain?: string;
+    };
+    matchedPlaybookIds?: string[];
+    confidenceDeltas?: Array<{
+        id: string;
+        delta: number;
+    }>;
+    frontierWrites?: number;
+    lightweightCounts?: {
+        knowledge?: number;
+        reflexion?: number;
+        causal?: number;
+    };
+    writeChannels?: ValidationWriteChannel[];
+}
+export interface DreamMechanismTraceEvent extends MechanismTraceBase {
+    family: 'dream';
+    rowsClaimed: number;
+    rowsCompleted: number;
+    rowsFailed: number;
+    analyses?: number;
+    playbooksCreated?: number;
+    playbooksRefined?: number;
+    semanticNotesExtracted?: number;
+    compression?: {
+        promoted?: number;
+        demoted?: number;
+        evicted?: number;
+    };
+    maintenance?: Record<string, unknown>;
+}
+export interface ArtifactMechanismTraceEvent extends MechanismTraceBase {
+    family: 'artifact';
+    artifactType: MechanismArtifactType;
+    artifactId: string;
+    action: 'created' | 'refined' | 'deleted' | 'candidate-created' | 'promoted' | 'rejected';
+    path?: string;
+    candidateId?: string;
+    validationStatus?: 'pending' | 'passed' | 'failed' | 'skipped';
+    evidence?: Record<string, unknown>;
+}
+/**
+ * Per-mutation-decision trace: emitted for EVERY playbook mutation proposal
+ * the maintenance loop considers (accepted, rejected/regression, and the
+ * sparse/empty-minibatch auto-accepts), so a fired — or suppressed — mutation
+ * is recoverable after the fact instead of being silently dropped. Carries the
+ * gate's decision breakdown (reason + parent/child sums + score delta), a
+ * compact before/after guidance diff, and the proposer's rationale.
+ */
+export interface MutationMechanismTraceEvent extends MechanismTraceBase {
+    family: 'mutation';
+    /** single-parent reflective mutation vs two-parent Pareto merge. */
+    mutationType: 'reflective' | 'merge';
+    /** Task signature the proposal was gated on, when scoped. */
+    taskSignature?: string;
+    /** Parent playbook the candidate was mutated from. */
+    parentId: string;
+    /** Second parent id (merge proposals only). */
+    secondaryParentId?: string;
+    /** Candidate (child) playbook id. */
+    candidateId?: string;
+    /** Candidate (child) playbook name. */
+    candidateName?: string;
+    /**
+     * Gate decision reason (`GateReason`): 'improved' | 'regression' |
+     * 'sparse-minibatch' | 'empty-minibatch' | 'no-mutation' | 'parent-missing'.
+     * Kept as a string here so this module stays free of a `mutation-gate` import.
+     */
+    reason: string;
+    accepted: boolean;
+    /** Sum of the parent's minibatch scores (merge: primary parent). */
+    parentSum: number;
+    /** Sum of the candidate's minibatch scores. */
+    childSum: number;
+    /** `childSum - parentSum` — positive when the candidate scored higher. */
+    scoreDelta: number;
+    /** Fresh judge calls the gate made (excludes cache hits). */
+    judgeCalls?: number;
+    /** Compact parent guidance text (truncated). */
+    guidanceBefore?: string;
+    /** Compact candidate guidance text (truncated). */
+    guidanceAfter?: string;
+    /** Proposer free-text rationale for the edit (truncated). */
+    rationale?: string;
+}
+export type MechanismTraceEvent = RetrievalMechanismTraceEvent | ServeMechanismTraceEvent | OutcomeMechanismTraceEvent | AttributionMechanismTraceEvent | InstantMechanismTraceEvent | DreamMechanismTraceEvent | ArtifactMechanismTraceEvent | MutationMechanismTraceEvent;
+export type MechanismTraceCollector = (event: MechanismTraceEvent) => void;
+export interface MechanismTraceSink {
+    emit(event: MechanismTraceEvent): void;
+    close?(): void | Promise<void>;
+}
+export declare const noopMechanismTraceCollector: MechanismTraceCollector;
+export declare function collectToSink(sink: MechanismTraceSink | null | undefined): MechanismTraceCollector;
+export declare function createCompositeMechanismTraceCollector(collectors: Array<MechanismTraceCollector | null | undefined>): MechanismTraceCollector;
+export declare function createMechanismTraceEvent<T extends MechanismTraceEvent>(event: Omit<T, 'version' | 'timestamp'> & {
+    version?: MechanismTraceVersion;
+    timestamp?: string;
+}): T;
+export declare function isMechanismTraceEvent(value: unknown): value is MechanismTraceEvent;
+export declare function createJsonlMechanismTraceSink(filePath: string | undefined): MechanismTraceSink;
+export declare function createTaskMechanismTraceSink(dir: string | undefined, taskId: string): MechanismTraceSink;
+export declare function emitMechanismTraceAsLiveTraceEntry(writeTrace: (entry: Record<string, unknown>) => void): MechanismTraceCollector;
+//# sourceMappingURL=mechanism-trace.d.ts.map

package/dist/learning/mechanism-trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mechanism-trace.d.ts","sourceRoot":"","sources":["../../src/learning/mechanism-trace.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,0BAA0B,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAE7F,eAAO,MAAM,uBAAuB,EAAG,CAAU,CAAC;AAElD,MAAM,MAAM,qBAAqB,GAAG,OAAO,uBAAuB,CAAC;AAEnE,MAAM,MAAM,oBAAoB,GAC9B,WAAW,GAAG,OAAO,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,CAAC;AAEpG,MAAM,MAAM,qBAAqB,GAC7B,YAAY,GACZ,WAAW,GACX,UAAU,GACV,cAAc,GACd,WAAW,GACX,UAAU,GACV,YAAY,CAAC;AAEjB,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,qBAAqB,CAAC;IAC/B,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,2BAA2B;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,qBAAqB,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wFAAwF;IACxF,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,4BAA6B,SAAQ,kBAAkB;IACtE,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,0BAA0B,EAAE,CAAC;IACxC,UAAU,EAAE,2BAA2B,EAAE,CAAC;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,QAAQ,CAAC,EAAE;QACT,IAAI,EAAE,OAAO,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,qBAAqB,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,wBAAyB,SAAQ,kBAAkB;IAClE,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,0BAA0B,EAAE,CAAC;IACxC,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE;QACd,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,kBAAkB,CAAC,EAAE,OAAO,CAAC;KAC9B,CAAC;CACH;AAED,MAAM,WAAW,0BAA2B,SAAQ,kBAAkB;IACpE,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,8BAA+B,SAAQ,kBAAkB;IACxE,MAAM,EAAE,aAAa,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,wBAAwB,CAAC,EAAE,MAAM,EAAE,CAAC;IACpC,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,SAAS,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,WAAW,CAAC;IACzD,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjE;AAED,MAAM,WAAW,0BAA2B,SAAQ,kBAAkB;IACpE,MAAM,EAAE,SAAS,CAAC;IAClB,gBAAgB,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,gBAAgB,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,aAAa,CAAC,EAAE,sBAAsB,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,wBAAyB,SAAQ,kBAAkB;IAClE,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,WAAW,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,2BAA4B,SAAQ,kBAAkB;IACrE,MAAM,EAAE,UAAU,CAAC;IACnB,YAAY,EAAE,qBAAqB,CAAC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,mBAAmB,GAAG,UAAU,GAAG,UAAU,CAAC;IAC1F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,2BAA4B,SAAQ,kBAAkB;IACrE,MAAM,EAAE,UAAU,CAAC;IACnB,oEAAoE;IACpE,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC;IACrC,6DAA6D;IAC7D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,mBAAmB,GAC3B,4BAA4B,GAC5B,wBAAwB,GACxB,0BAA0B,GAC1B,8BAA8B,GAC9B,0BAA0B,GAC1B,wBAAwB,GACxB,2BAA2B,GAC3B,2BAA2B,CAAC;AAEhC,MAAM,MAAM,uBAAuB,GAAG,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;AAE3E,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACvC,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC;AAED,eAAO,MAAM,2BAA2B,EAAE,uBAEzC,CAAC;AAEF,wBAAgB,aAAa,CAC3B,IAAI,EAAE,kBAAkB,GAAG,IAAI,GAAG,SAAS,GAC1C,uBAAuB,CAGzB;AAED,wBAAgB,sCAAsC,CACpD,UAAU,EAAE,KAAK,CAAC,uBAAuB,GAAG,IAAI,GAAG,SAAS,CAAC,GAC5D,uBAAuB,CAWzB;AAED,wBAAgB,yBAAyB,CAAC,CAAC,SAAS,mBAAmB,EACrE,KAAK,EAAE,IAAI,CAAC,CAAC,EAAE,SAAS,GAAG,WAAW,CAAC,GAAG;IACxC,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GACA,CAAC,CAMH;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAkBlF;AAED,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,kBAAkB,CAoB9F;AAED,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,MAAM,EAAE,MAAM,GACb,kBAAkB,CAIpB;AAED,wBAAgB,kCAAkC,CAChD,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GACnD,uBAAuB,CAIzB"}

package/dist/learning/mechanism-trace.js

@@ -0,0 +1,81 @@
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+export const MECHANISM_TRACE_VERSION = 1;
+export const noopMechanismTraceCollector = () => {
+    // no-op
+};
+export function collectToSink(sink) {
+    if (!sink)
+        return noopMechanismTraceCollector;
+    return (event) => sink.emit(event);
+}
+export function createCompositeMechanismTraceCollector(collectors) {
+    const active = collectors.filter((collector) => typeof collector === 'function');
+    if (active.length === 0)
+        return noopMechanismTraceCollector;
+    if (active.length === 1)
+        return active[0];
+    return (event) => {
+        for (const collector of active) {
+            collector(event);
+        }
+    };
+}
+export function createMechanismTraceEvent(event) {
+    return {
+        version: MECHANISM_TRACE_VERSION,
+        timestamp: new Date().toISOString(),
+        ...event,
+    };
+}
+export function isMechanismTraceEvent(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const record = value;
+    return (record.version === MECHANISM_TRACE_VERSION &&
+        typeof record.timestamp === 'string' &&
+        typeof record.family === 'string' &&
+        [
+            'retrieval',
+            'serve',
+            'outcome',
+            'attribution',
+            'instant',
+            'dream',
+            'artifact',
+            'mutation',
+        ].includes(record.family));
+}
+export function createJsonlMechanismTraceSink(filePath) {
+    if (!filePath) {
+        return { emit: noopMechanismTraceCollector };
+    }
+    try {
+        mkdirSync(dirname(filePath), { recursive: true });
+    }
+    catch {
+        // best-effort
+    }
+    return {
+        emit(event) {
+            try {
+                appendFileSync(filePath, JSON.stringify(event) + '\n');
+            }
+            catch {
+                // best-effort trace writing must not affect learning/eval behavior
+            }
+        },
+    };
+}
+export function createTaskMechanismTraceSink(dir, taskId) {
+    if (!dir)
+        return { emit: noopMechanismTraceCollector };
+    const sanitized = taskId.replace(/[^a-z0-9-]/g, '-');
+    return createJsonlMechanismTraceSink(join(dir, `${sanitized}.mechanisms.jsonl`));
+}
+export function emitMechanismTraceAsLiveTraceEntry(writeTrace) {
+    return (event) => {
+        writeTrace({ type: 'mechanism-trace', mechanism: event });
+    };
+}
+//# sourceMappingURL=mechanism-trace.js.map

package/dist/learning/mechanism-trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mechanism-trace.js","sourceRoot":"","sources":["../../src/learning/mechanism-trace.ts"],"names":[],"mappings":"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"}

package/dist/learning/merge-proposer.d.ts

@@ -0,0 +1,102 @@
+/**
+ * MergeProposer — recombine two Pareto-frontier playbooks with a common
+ * ancestor.
+ *
+ * Direct port of GEPA's `merge.py:69-207` (system-aware merge) adapted
+ * to cognitive-core's playbook shape. The premise: when two descendants
+ * of a common ancestor each won on disjoint subsets of work (one fixed
+ * what the other left broken), their improvements are *combinable*.
+ * Merge takes the union of disjoint changes — fields where exactly one
+ * descendant diverged from the ancestor adopt that descendant's value.
+ * Fields where both diverged take from the higher-scoring descendant on
+ * the relevant signature.
+ *
+ * Per-field whole-list comparison (scenario 9 decision):
+ *   - String fields (strategy, rollbackStrategy, codeExample): direct ==
+ *   - List fields: set equality (order-insensitive)
+ *   - Ordered lists (guidance.tactics, guidance.steps): treated as set
+ *     for comparison but reconstructed preserving the winner's order
+ *
+ * Output is a Playbook proposal — NOT persisted. Caller should pass it
+ * through `MutationGate.propose` for replay-based acceptance.
+ */
+import type { Playbook } from '../types/playbook.js';
+import type { PlaybookLibrary, FrontierMember } from '../memory/playbook.js';
+import type { SqlitePersistence } from '../persistence/index.js';
+/**
+ * A merge proposal: two parent playbooks, their common ancestor, and the
+ * merged child to be gated and persisted.
+ */
+export interface MergeProposal {
+    /** The higher-scoring of the two parents (becomes child.parentPlaybookId). */
+    primaryParentId: string;
+    /** The lower-scoring of the two parents. */
+    secondaryParentId: string;
+    /** Common ancestor used to compute field-level diffs. */
+    commonAncestorId: string;
+    /** Total win count of primaryParent on the signature. */
+    primaryWins: number;
+    /** Total win count of secondaryParent on the signature. */
+    secondaryWins: number;
+    /** The merged playbook (not yet persisted). */
+    merged: Playbook;
+}
+export interface MergeProposerConfig {
+    /** Max number of pairs to consider per call. Default 5. */
+    maxPairs?: number;
+    /**
+     * Skip pairs that have a recorded merge attempt newer than this many
+     * milliseconds. Prevents re-judging the same (A, B, ancestor) triplet
+     * every maintenance cycle. Default 24h.
+     *
+     * **Sizing guidance:** this window only fires when it's larger than
+     * the maintenance loop's cadence — if maintenance runs every 36h but
+     * the window is 24h, dedup expires before the next cycle and never
+     * blocks anything. Set this to roughly **5–6× the typical maintenance
+     * cadence** so a few cycles must pass before a rejected triplet gets
+     * re-judged. The default 24h assumes a sub-daily cadence (4–6h
+     * between maintenance runs); operators with circadian-only schedules
+     * should bump this to 5–7 days.
+     *
+     * Note: dedup is additive safety, not load-bearing correctness. The
+     * acceptance gate would catch any actually-bad merge regardless;
+     * dedup just saves a judge call. Getting the window exactly right is
+     * an optimization, not a bug.
+     */
+    dedupWindowMs?: number;
+}
+/**
+ * MergeProposer — finds Pareto-dominator pairs with a common ancestor
+ * and produces merged children.
+ */
+export declare class MergeProposer {
+    private readonly library;
+    private readonly persistence;
+    private config;
+    constructor(library: PlaybookLibrary, persistence: SqlitePersistence, config?: MergeProposerConfig);
+    /**
+     * Find candidate merge pairs on the Pareto frontier for `taskSignature`
+     * and produce merged playbook proposals for each.
+     */
+    proposePairsForSignature(taskSignature: string, opts?: {
+        domain?: string;
+    }): Promise<MergeProposal[]>;
+    /**
+     * Count how many (signature, experience) frontier pairs this playbook
+     * is tied-or-best on, restricted to a single signature. Used by the
+     * ancestor-score filter — if the ancestor matches the descendants on
+     * this many examples, there's no genuine divergence to merge.
+     */
+    private countFrontierWinsAt;
+}
+export declare function createMergeProposer(library: PlaybookLibrary, persistence: SqlitePersistence, config?: MergeProposerConfig): MergeProposer;
+/**
+ * Find the deepest (most-recent) common ancestor of two ancestry chains.
+ * Chains are ordered from descendant -> root. Returns null if no overlap.
+ */
+export declare function findCommonAncestor(chainA: string[], chainB: string[]): string | null;
+/**
+ * Per-field whole-list merge over (ancestor, a, b).
+ */
+export declare function mergePlaybooks(ancestor: Playbook, primary: FrontierMember, secondary: FrontierMember): Playbook;
+//# sourceMappingURL=merge-proposer.d.ts.map

package/dist/learning/merge-proposer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-proposer.d.ts","sourceRoot":"","sources":["../../src/learning/merge-proposer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,8EAA8E;IAC9E,eAAe,EAAE,MAAM,CAAC;IACxB,4CAA4C;IAC5C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,gBAAgB,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,aAAa,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,MAAM,EAAE,QAAQ,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAOD;;;GAGG;AACH,qBAAa,aAAa;IAItB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAJ9B,OAAO,CAAC,MAAM,CAAgC;gBAG3B,OAAO,EAAE,eAAe,EACxB,WAAW,EAAE,iBAAiB,EAC/C,MAAM,GAAE,mBAAwB;IAKlC;;;OAGG;IACG,wBAAwB,CAC5B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GACzB,OAAO,CAAC,aAAa,EAAE,CAAC;IAuE3B;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;CAiB5B;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,eAAe,EACxB,WAAW,EAAE,iBAAiB,EAC9B,MAAM,CAAC,EAAE,mBAAmB,GAC3B,aAAa,CAEf;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAMpF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,cAAc,GACxB,QAAQ,CA4EV"}