cognitive-core 0.2.4 → 0.3.1

package/dist/learning/distiller.js

@@ -0,0 +1,353 @@
+/**
+ * TrajectoryDistiller — LLM-backed distillation of trajectories into
+ * transferable, condition-tagged Playbook items.
+ *
+ * Design (Phase 3 / PR-D1):
+ *   - One LLM call per trajectory, batched in the dream/batch phase (never the
+ *     <200ms InstantLoop hot path).
+ *   - Output mapped into the *existing* Playbook schema: no new core type.
+ *   - Failures distill to anti-pattern-only items (never positive exemplars).
+ *   - Results cached by sha256(canonical-trajectory-form + PROMPT_VERSION) so
+ *     re-runs are fully reproducible and LLM-free after the first distillation.
+ *   - Heuristic PlaybookExtractor remains the no-LLM fallback; this distiller
+ *     is the LLM-backed alternative (switched by patternExtractor==='llm').
+ *
+ * PR-D2 hook (curation / dedup):
+ *   - `distill()` returns a raw Playbook; callers decide whether to add or
+ *     merge. The comment "D2-hook" marks the call-site in unified-pipeline.ts
+ *     where near-dup checking will be inserted.
+ */
+import { createHash } from 'node:crypto';
+import { randomUUID } from 'node:crypto';
+import { createPlaybook } from '../types/playbook.js';
+// ============================================================================
+// Prompt versioning — bump this string whenever the prompt changes so old
+// cache entries are automatically bypassed.
+// ============================================================================
+// v2 (2026-07-02): oracle-signal awareness — verifierOutput (expected/diff) is
+// threaded through and the prompt now demands the output CONTRACT (shape, not
+// gold values). See docs/DESIGN-meta-learning-validation.md § "Train-time
+// oracle signal vs solve-time firewall".
+export const DISTILLER_PROMPT_VERSION = 'v2';
+const DEFAULT_CONFIG = {
+    model: 'claude-sonnet-4-5',
+    maxTokens: 1200,
+    initialConfidenceBase: 0.4,
+};
+// ============================================================================
+// TrajectoryDistiller
+// ============================================================================
+export class TrajectoryDistiller {
+    llm;
+    persistence;
+    config;
+    constructor(llm, persistence, config) {
+        this.llm = llm;
+        this.persistence = persistence;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Distill a single trajectory into a Playbook item.
+     *
+     * - Success trajectories → strategy + tactics + applicability + antiPatterns.
+     * - Failure trajectories → antiPattern-only item (guidance.strategy is the
+     *   lesson-as-negative; no tactics, no positive exemplar injected).
+     *
+     * Returns null when:
+     *   - The LLM returns malformed JSON / fails the self-check rubric.
+     *   - The LLM call itself throws.
+     *
+     * The caller (unified-pipeline) is responsible for storing/merging the result.
+     * PR-D2 curation (near-dup check) hooks here at the call-site.
+     */
+    async distill(trajectory, outcome, verifierOutput) {
+        // 1. Build cache key — includes the verifier oracle so a re-distill with
+        // the oracle now available doesn't return a stale oracle-free entry.
+        const cacheKey = this.buildCacheKey(trajectory, verifierOutput);
+        // 2. Cache hit — return without an LLM call
+        if (this.persistence) {
+            const cached = this.persistence.getDistillationCache(cacheKey);
+            if (cached) {
+                try {
+                    return JSON.parse(cached.playbook_json);
+                }
+                catch {
+                    // Corrupt cache entry — fall through to re-distill
+                }
+            }
+        }
+        // 3. Build prompt and call LLM
+        const prompt = buildDistillationPrompt(trajectory, outcome, verifierOutput);
+        let raw;
+        try {
+            raw = await this.llm.complete([{ role: 'user', content: prompt }], {
+                temperature: 0,
+                maxTokens: this.config.maxTokens,
+            });
+        }
+        catch {
+            return null;
+        }
+        // 4. Parse response
+        const parsed = parseDistillationResponse(raw);
+        if (!parsed)
+            return null;
+        // 5. Self-check: at least 2 of 3 rubric criteria must pass
+        const selfCheckScore = (parsed.selfCheck.nonObvious ? 1 : 0) +
+            (parsed.selfCheck.conditioned ? 1 : 0) +
+            (parsed.selfCheck.actionable ? 1 : 0);
+        if (selfCheckScore < 2)
+            return null;
+        // 6. Map to Playbook schema
+        // F3(a): derive initial confidence from self-check score.
+        // Formula: base + 0.1 * selfCheckScore (capped at 0.99).
+        // selfCheckScore ∈ {2,3} after the gate above:
+        //   score=2 → 0.6, score=3 → 0.7 (meets the router 0.7 gate on a max-score item).
+        const derivedConfidence = Math.min(0.99, this.config.initialConfidenceBase + 0.1 * selfCheckScore);
+        const isFailure = !outcome.success;
+        const playbook = buildPlaybook(parsed, trajectory, isFailure, derivedConfidence);
+        // 7. Store in cache
+        if (this.persistence) {
+            try {
+                this.persistence.setDistillationCache({
+                    cache_key: cacheKey,
+                    playbook_json: JSON.stringify(playbook),
+                    created_at: new Date().toISOString(),
+                });
+            }
+            catch {
+                // Non-fatal — distillation succeeded, caching is best-effort
+            }
+        }
+        return playbook;
+    }
+    /**
+     * Build the cache key for a trajectory.
+     * Exposed for testing (cache pre-seeding).
+     */
+    buildCacheKey(trajectory, verifierOutput) {
+        const canonical = buildCanonicalForm(trajectory);
+        const oracle = verifierOutput ? sha256(verifierOutput) : 'no-oracle';
+        return sha256(`${canonical}:${oracle}:${DISTILLER_PROMPT_VERSION}`);
+    }
+}
+// ============================================================================
+// Factory (repo convention)
+// ============================================================================
+export function createTrajectoryDistiller(llm, persistence, config) {
+    return new TrajectoryDistiller(llm, persistence, config);
+}
+// ============================================================================
+// Prompt construction
+// ============================================================================
+/**
+ * The distillation prompt.
+ *
+ * Rubric demanded inline: each item must be
+ *   (a) non-obvious to a frontier model — states something the base model
+ *       wouldn't know without observing this environment specifically,
+ *   (b) conditioned — explicitly says WHEN / under what circumstances it applies,
+ *   (c) actionable — provides concrete steps or avoid-rules, not platitudes.
+ *
+ * Self-check instruction forces the model to score its own output before emitting.
+ */
+function buildDistillationPrompt(trajectory, outcome, verifierOutput) {
+    const isSuccess = outcome.success;
+    const outcomeLabel = isSuccess
+        ? `SUCCESS (partial score: ${outcome.partialScore.toFixed(2)})`
+        : `FAILURE (partial score: ${outcome.partialScore.toFixed(2)}${outcome.errorInfo ? `, error: ${outcome.errorInfo}` : ''})`;
+    const steps = trajectory.steps
+        .slice(0, 20) // cap to avoid prompt bloat
+        .map((s, i) => {
+        const parts = [`Step ${i + 1}:`];
+        if (s.thought)
+            parts.push(`  Thought: ${s.thought.slice(0, 200)}`);
+        parts.push(`  Action: ${s.action.slice(0, 200)}`);
+        parts.push(`  Observation: ${s.observation.slice(0, 200)}`);
+        return parts.join('\n');
+    })
+        .join('\n');
+    const verifierSection = verifierOutput
+        ? `\n## Verifier oracle (reward signal for this COMPLETED task)\n${verifierOutput.slice(0, 1000)}\n\n` +
+            `This is the produced-vs-expected signal. Use it to capture the OUTPUT CONTRACT the verifier enforces (numeric int/float typing, which field-deltas count as "changed", deterministic sort keys, JSON/CSV schema shape, rounding, units). Distill the answer's SHAPE, strip the answer's CONTENT: KEEP the transferable contract, DROP the run-specific gold values (exact numbers/ids). A lesson that hard-codes this task's answer values is memorization and MUST be rejected.`
+        : '';
+    const modeInstruction = isSuccess
+        ? `Extract the generalizable strategy that made this succeed.${verifierOutput ? ' Prioritise the verifier-enforced output contract above process hygiene.' : ''}`
+        : `Extract the anti-patterns and guardrails from this failure. This item will be stored as a WARNING (what NOT to do), never as a positive exemplar.${verifierOutput ? ' If the verifier oracle shows the produced output violated a shape/typing/ordering/schema rule, encode that contract as the guardrail.' : ''}`;
+    return `You are a learning distiller. Your job is to extract a single, transferable strategy item from an agent trajectory.
+
+## Task
+Domain: ${trajectory.task.domain}
+Description: ${trajectory.task.description}
+
+## Outcome
+${outcomeLabel}
+
+## Trajectory steps
+${steps}${verifierSection}
+
+## Your job
+${modeInstruction}
+
+## Quality rubric — your output MUST satisfy ALL THREE criteria:
+(a) NON-OBVIOUS: The lesson must state something a frontier model would NOT already know from pretraining — it must be specific to this environment, codebase, API, tool behaviour, or task family. A generic best practice ("always test your code") FAILS this criterion.
+(b) CONDITIONED: The lesson must explicitly say WHEN it applies — what task shape, precondition, environment, or context triggers it. An unconditional rule ("never do X") FAILS unless it explains the specific context where X is dangerous.
+(c) ACTIONABLE: The lesson must provide concrete steps or avoid-rules — not vague advice. "Be careful" FAILS. "Run \`make check\` before committing because the pre-commit hook rejects npm test" PASSES.
+
+## Self-check
+Before emitting your JSON, score your own output: does it satisfy (a), (b), and (c)? Set the selfCheck fields accordingly. If your output fails 2 or more criteria, revise it until it passes or acknowledge it cannot be distilled.
+
+## Output format
+Respond with ONLY a JSON object (no markdown fences, no prose):
+{
+  "title": "<10-15 word kebab-case slug describing the lesson>",
+  "strategy": "<2-4 sentences: the generalizable lesson — WHY it worked or failed, what the environment-specific insight is>",
+  "applicability": {
+    "situations": ["<high-level task context, e.g. 'building inside a Docker container'>"],
+    "triggers": ["<concrete signal, e.g. 'build output shows ENOENT for /tmp/work'>"],
+    "domains": ["<domain slug, e.g. 'docker', 'typescript', 'alfworld'>"]
+  },
+  "tactics": [
+    "<concrete step 1 — for SUCCESS trajectories; empty array for FAILURE trajectories>"
+  ],
+  "antiPatterns": [
+    "<what NOT to do and why — especially important for FAILURE trajectories>"
+  ],
+  "confidenceRationale": "<1 sentence: how confident you are and why>",
+  "selfCheck": {
+    "nonObvious": <true|false>,
+    "conditioned": <true|false>,
+    "actionable": <true|false>
+  }
+}`;
+}
+// ============================================================================
+// Response parsing
+// ============================================================================
+function parseDistillationResponse(raw) {
+    // Strip markdown fences if the model added them despite instructions
+    const cleaned = raw
+        .replace(/^```(?:json)?\s*/m, '')
+        .replace(/\s*```$/m, '')
+        .trim();
+    try {
+        const obj = JSON.parse(cleaned);
+        // Validate required fields
+        if (typeof obj.title !== 'string' ||
+            typeof obj.strategy !== 'string' ||
+            !obj.applicability ||
+            typeof obj.applicability !== 'object' ||
+            !Array.isArray(obj.applicability.situations) ||
+            !Array.isArray(obj.applicability.triggers) ||
+            !Array.isArray(obj.applicability.domains) ||
+            !Array.isArray(obj.tactics) ||
+            !Array.isArray(obj.antiPatterns) ||
+            typeof obj.confidenceRationale !== 'string' ||
+            !obj.selfCheck ||
+            typeof obj.selfCheck !== 'object' ||
+            typeof obj.selfCheck.nonObvious !== 'boolean' ||
+            typeof obj.selfCheck.conditioned !== 'boolean' ||
+            typeof obj.selfCheck.actionable !== 'boolean') {
+            return null;
+        }
+        return {
+            title: String(obj.title),
+            strategy: String(obj.strategy),
+            applicability: {
+                situations: obj.applicability.situations.map(String),
+                triggers: obj.applicability.triggers.map(String),
+                domains: obj.applicability.domains.map(String),
+            },
+            tactics: obj.tactics.map(String),
+            antiPatterns: obj.antiPatterns.map(String),
+            confidenceRationale: String(obj.confidenceRationale),
+            selfCheck: {
+                nonObvious: obj.selfCheck.nonObvious,
+                conditioned: obj.selfCheck.conditioned,
+                actionable: obj.selfCheck.actionable,
+            },
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================================
+// Playbook mapping
+// ============================================================================
+function buildPlaybook(parsed, trajectory, isFailure, initialConfidence) {
+    const now = new Date();
+    // Failure trajectories: strategy is phrased as the negative lesson;
+    // tactics are empty (no positive steps from a failed run).
+    const strategy = isFailure ? `[Failure lesson] ${parsed.strategy}` : parsed.strategy;
+    return createPlaybook({
+        id: `distilled-${randomUUID()}`,
+        name: slugify(parsed.title),
+        applicability: {
+            situations: parsed.applicability.situations,
+            triggers: parsed.applicability.triggers,
+            antiPatterns: parsed.antiPatterns,
+            domains: parsed.applicability.domains,
+        },
+        guidance: {
+            strategy,
+            tactics: isFailure ? [] : parsed.tactics,
+            steps: isFailure ? [] : undefined,
+        },
+        verification: {
+            successIndicators: isFailure ? [] : [`Strategy from successful trajectory ${trajectory.id}`],
+            failureIndicators: isFailure
+                ? [`Trajectory ${trajectory.id} failed: ${trajectory.outcome.errorInfo ?? 'unknown error'}`]
+                : [],
+        },
+        evolution: {
+            version: '1.0.0',
+            createdFrom: [trajectory.id],
+            failures: [],
+            refinements: [],
+            successCount: isFailure ? 0 : 1,
+            failureCount: isFailure ? 1 : 0,
+        },
+        provenance: {
+            origin: 'extracted',
+            extractionMethod: 'trajectory-distiller',
+            recordedAt: now,
+        },
+        confidence: isFailure ? initialConfidence * 0.8 : initialConfidence,
+        complexity: 'moderate',
+        estimatedEffort: 3,
+        createdAt: now,
+        updatedAt: now,
+    });
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Build a stable canonical form of a trajectory for cache keying.
+ * Uses (id, task description, step actions, outcome.success) — stable across
+ * metadata changes, but changes whenever the substance of the trajectory does.
+ */
+function buildCanonicalForm(trajectory) {
+    const parts = [
+        trajectory.id,
+        trajectory.task.description,
+        trajectory.steps.map((s) => s.action).join('|'),
+        String(trajectory.outcome.success),
+    ];
+    return parts.join('\0');
+}
+function sha256(input) {
+    return createHash('sha256').update(input, 'utf8').digest('hex');
+}
+/** Convert a title to a kebab-case playbook name, max 80 chars. */
+function slugify(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, '')
+        .replace(/\s+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 80);
+}
+//# sourceMappingURL=distiller.js.map

package/dist/learning/distiller.js.map

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

package/dist/learning/effectiveness.d.ts

@@ -30,7 +30,9 @@ export interface TaskAnnotation {
         playbookIds: string[];
         playbookNames: string[];
         experienceIds: string[];
-        /** Total number of knowledge items retrieved */
+        /** Knowledge-note ids surfaced for this task (isolates the knowledge path). */
+        knowledgeNoteIds: string[];
+        /** Total number of knowledge items retrieved (playbooks + experiences + notes) */
         totalItems: number;
     };
     /** What was actually applied (inferred from trajectory analysis) */
@@ -80,6 +82,14 @@ export interface EffectivenessMetrics {
     knowledgeApplicationRate: number;
     /** Of applied knowledge, how often did the task succeed? */
     appliedKnowledgeSuccessRate: number;
+    /** Tasks where knowledge NOTES (not playbooks/experiences) were surfaced. */
+    knowledgeNoteGuidedTasks: number;
+    /** Success rate on tasks with knowledge notes surfaced. */
+    knowledgeNoteGuidedSuccessRate: number;
+    /** Success rate on tasks WITHOUT knowledge notes surfaced. */
+    noKnowledgeNoteSuccessRate: number;
+    /** Isolated knowledge-note lift (note-guided − not). Positive ⇒ notes help. */
+    knowledgeNoteSuccessDelta: number;
     /** Error recovery */
     guidedAvgErrorRecoveries: number;
     unguidedAvgErrorRecoveries: number;
@@ -118,7 +128,7 @@ export declare class LearningEffectivenessTracker {
      * Annotate a completed trajectory with knowledge usage data.
      * Call this after a task finishes and usage inference has run.
      */
-    annotate(trajectory: Trajectory, surfacedPlaybooks: PlaybookMatch[], surfacedExperienceIds: string[], appliedPlaybookIds: string[]): Promise<TaskAnnotation>;
+    annotate(trajectory: Trajectory, surfacedPlaybooks: PlaybookMatch[], surfacedExperienceIds: string[], appliedPlaybookIds: string[], surfacedKnowledgeNoteIds?: string[]): Promise<TaskAnnotation>;
     /**
      * Add a reflection to an existing annotation.
      * Called after human review or agent self-reflection.

package/dist/learning/effectiveness.d.ts.map

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

package/dist/learning/effectiveness.js

@@ -39,7 +39,7 @@ export class LearningEffectivenessTracker {
      * Annotate a completed trajectory with knowledge usage data.
      * Call this after a task finishes and usage inference has run.
      */
-    async annotate(trajectory, surfacedPlaybooks, surfacedExperienceIds, appliedPlaybookIds) {
+    async annotate(trajectory, surfacedPlaybooks, surfacedExperienceIds, appliedPlaybookIds, surfacedKnowledgeNoteIds = []) {
         await this.init();
         const errorRecoveries = countErrorRecoveries(trajectory);
         const annotation = {
@@ -50,7 +50,8 @@ export class LearningEffectivenessTracker {
                 playbookIds: surfacedPlaybooks.map((m) => m.playbook.id),
                 playbookNames: surfacedPlaybooks.map((m) => m.playbook.name),
                 experienceIds: surfacedExperienceIds,
-                totalItems: surfacedPlaybooks.length + surfacedExperienceIds.length,
+                knowledgeNoteIds: surfacedKnowledgeNoteIds,
+                totalItems: surfacedPlaybooks.length + surfacedExperienceIds.length + surfacedKnowledgeNoteIds.length,
             },
             knowledgeApplied: {
                 playbookIdsUsed: appliedPlaybookIds,
@@ -100,12 +101,8 @@ export class LearningEffectivenessTracker {
         const unguided = annotations.filter((a) => a.knowledgeSurfaced.totalItems === 0);
         const guidedSuccesses = guided.filter((a) => a.outcome.success);
         const unguidedSuccesses = unguided.filter((a) => a.outcome.success);
-        const guidedSuccessRate = guided.length > 0
-            ? guidedSuccesses.length / guided.length
-            : 0;
-        const unguidedSuccessRate = unguided.length > 0
-            ? unguidedSuccesses.length / unguided.length
-            : 0;
+        const guidedSuccessRate = guided.length > 0 ? guidedSuccesses.length / guided.length : 0;
+        const unguidedSuccessRate = unguided.length > 0 ? unguidedSuccesses.length / unguided.length : 0;
         const guidedAvgSteps = guided.length > 0
             ? guided.reduce((sum, a) => sum + a.outcome.stepCount, 0) / guided.length
             : 0;
@@ -114,18 +111,21 @@ export class LearningEffectivenessTracker {
             : 0;
         const applied = annotations.filter((a) => a.knowledgeApplied.anyKnowledgeUsed);
         const appliedSuccesses = applied.filter((a) => a.outcome.success);
-        const knowledgeApplicationRate = guided.length > 0
-            ? applied.length / guided.length
-            : 0;
-        const appliedKnowledgeSuccessRate = applied.length > 0
-            ? appliedSuccesses.length / applied.length
-            : 0;
+        const knowledgeApplicationRate = guided.length > 0 ? applied.length / guided.length : 0;
+        const appliedKnowledgeSuccessRate = applied.length > 0 ? appliedSuccesses.length / applied.length : 0;
         const guidedAvgErrors = guided.length > 0
             ? guided.reduce((sum, a) => sum + a.outcome.errorRecoveries, 0) / guided.length
             : 0;
         const unguidedAvgErrors = unguided.length > 0
             ? unguided.reduce((sum, a) => sum + a.outcome.errorRecoveries, 0) / unguided.length
             : 0;
+        // Knowledge-note isolation: note-guided vs not (independent of playbooks/experiences).
+        const noteGuided = annotations.filter((a) => a.knowledgeSurfaced.knowledgeNoteIds.length > 0);
+        const noNote = annotations.filter((a) => a.knowledgeSurfaced.knowledgeNoteIds.length === 0);
+        const noteGuidedSuccessRate = noteGuided.length > 0
+            ? noteGuided.filter((a) => a.outcome.success).length / noteGuided.length
+            : 0;
+        const noNoteSuccessRate = noNote.length > 0 ? noNote.filter((a) => a.outcome.success).length / noNote.length : 0;
         // Per-playbook effectiveness
         const playbookEffectiveness = this.computePlaybookEffectiveness(annotations);
         return {
@@ -140,6 +140,10 @@ export class LearningEffectivenessTracker {
             stepCountDelta: guidedAvgSteps - unguidedAvgSteps,
             knowledgeApplicationRate,
             appliedKnowledgeSuccessRate,
+            knowledgeNoteGuidedTasks: noteGuided.length,
+            knowledgeNoteGuidedSuccessRate: noteGuidedSuccessRate,
+            noKnowledgeNoteSuccessRate: noNoteSuccessRate,
+            knowledgeNoteSuccessDelta: noteGuidedSuccessRate - noNoteSuccessRate,
             guidedAvgErrorRecoveries: guidedAvgErrors,
             unguidedAvgErrorRecoveries: unguidedAvgErrors,
             playbookEffectiveness,

package/dist/learning/effectiveness.js.map

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

package/dist/learning/escalation.d.ts

@@ -0,0 +1,89 @@
+/**
+ * runEscalation — a stall-triggered operator ladder over the GEPA-like proposer.
+ *
+ * No single operator dominates: bounded+gate+single is cheapest on *additive*
+ * deficiencies but stalls on *coupled-constraint* ones, where frontier+rewrite is
+ * more reliable (see docs/DESIGN-skillopt-headtohead.md §9d/§9e). Rather than
+ * predict the regime up front (only partly knowable), we **start cheap and
+ * escalate on stall**: run each tier with a sub-budget, carry the best skill
+ * forward, and step up the ladder whenever a tier fails to reach a perfect score.
+ *
+ * Memory is a *gated tier* — consulted only on late tiers (after cheaper ones
+ * stalled), so it never taxes easy tasks that exit at tier 1 (the "memory is a
+ * tax on easy/cold seeds" finding).
+ *
+ * Every run emits a `routingRecord` ({features, tierReached, ...}) — the training
+ * signal for a future meta-learned router (MoEGate/MetaLearner). `tierReached` is
+ * the supervised label: the cheapest tier that achieved the final best.
+ */
+import { type GepaOperatorConfig, type GepaEvaluator, type GepaReflector } from './gepa-proposer.js';
+export interface EscalationTier {
+    /** display/routing label. */
+    label: string;
+    /** operator toggles for this tier. */
+    operator: GepaOperatorConfig;
+    /** fraction of the total metric-call budget allotted to this tier. */
+    budgetFraction: number;
+    /** consult memoryContext on this tier (gated — keep false for cheap tiers). */
+    useMemory?: boolean;
+}
+/** Default ladder: cheap additive fix → holistic rewrite → frontier → +memory. */
+export declare const DEFAULT_ESCALATION_LADDER: EscalationTier[];
+export interface EscalationConfig<T> {
+    seedSkill: string;
+    trainset: T[];
+    valset: T[];
+    evaluate: GepaEvaluator<T>;
+    propose: GepaReflector;
+    describeTask: (task: T) => string;
+    perfectScore?: number;
+    /** TOTAL metric-call budget across all tiers. */
+    maxMetricCalls?: number;
+    reflectionMinibatchSize?: number;
+    rng?: () => number;
+    /** Retrieval context; consulted only on tiers with `useMemory`. */
+    memoryContext?: (tasks: T[]) => Promise<string> | string;
+    /** The ladder (defaults to DEFAULT_ESCALATION_LADDER). */
+    tiers?: EscalationTier[];
+    /** Start partway up the ladder (e.g. from an a-priori/probe prior). */
+    startTier?: number;
+    /** Task features, attached to the routing record for meta-learning. */
+    features?: Record<string, unknown>;
+    /**
+     * Fix 2 (slow-update / meta-skill): at each tier boundary that didn't reach
+     * perfect, run a longitudinal meta-reflection over *persistent* failures
+     * (SkillOpt's night-2 mechanism) and feed the resulting meta-rule into later
+     * tiers' reflection context. Targets coupled-constraint seeds (thorough-analyst)
+     * where myopic per-minibatch reflection stalls.
+     */
+    slowUpdate?: boolean;
+}
+export interface EscalationRoutingRecord {
+    features?: Record<string, unknown>;
+    /** cheapest tier that produced the final best (the routing label). */
+    tierReached: string;
+    tierIndex: number;
+    metricCalls: number;
+    finalScore: number;
+    reachedPerfect: boolean;
+}
+export interface EscalationResult {
+    bestSkill: string;
+    bestValScore: number;
+    metricCalls: number;
+    tierReached: string;
+    tierIndex: number;
+    perTier: Array<{
+        label: string;
+        valScore: number;
+        metricCalls: number;
+        improved: boolean;
+    }>;
+    routingRecord: EscalationRoutingRecord;
+}
+/** Run the operator ladder, escalating on stall, until perfect or budget spent. */
+export declare function runEscalation<T>(cfg: EscalationConfig<T>): Promise<EscalationResult>;
+export declare function createEscalation<T>(cfg: EscalationConfig<T>): {
+    run: () => Promise<EscalationResult>;
+};
+//# sourceMappingURL=escalation.d.ts.map

package/dist/learning/escalation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escalation.d.ts","sourceRoot":"","sources":["../../src/learning/escalation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,aAAa,EACnB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,kFAAkF;AAClF,eAAO,MAAM,yBAAyB,EAAE,cAAc,EAsBrD,CAAC;AAEF,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,CAAC,EAAE,CAAC;IACd,MAAM,EAAE,CAAC,EAAE,CAAC;IACZ,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAC3B,OAAO,EAAE,aAAa,CAAC;IACvB,YAAY,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,mEAAmE;IACnE,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IACzD,0DAA0D;IAC1D,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC5F,aAAa,EAAE,uBAAuB,CAAC;CACxC;AAuBD,mFAAmF;AACnF,wBAAsB,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA8G1F;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,GAAG,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG;IAC7D,GAAG,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACtC,CAEA"}