@graphorin/memory 0.6.1 → 0.7.0

package/src/consolidator/phases/induce.ts

@@ -0,0 +1,423 @@
+/**
+ * Procedural memory extraction (P2-2) - AWM-style workflow induction. From
+ * a **successful** agent trajectory, distil a reusable procedure: a goal, a
+ * value-abstracted step sequence (`"search for {product}"`), the variable
+ * names that abstraction introduced, and Voyager-style success criteria the
+ * reuse can self-verify against. The induced procedure is stored in the
+ * procedural tier **quarantined** + `provenance: 'induction'` (P1-4) -
+ * procedures drive *actions*, so this is the highest-poisoning-risk write in
+ * the system and must never bypass the quarantine gate.
+ *
+ * Provider-agnostic seam, mirroring the P2-3 / P2-4 retrieval seams: pure
+ * request builder ({@link buildInductionRequest}) + tolerant pure parser
+ * ({@link parseInducedProcedure}) + a resilient provider-backed inducer
+ * ({@link createProviderWorkflowInducer}) + a pure orchestrator
+ * ({@link runWorkflowInduction}) that does no I/O of its own. The module
+ * imports only `@graphorin/core` types, so the default (no-inducer) path is
+ * fully offline - induction only ever calls a model when a provider is wired
+ * via `createMemory({ procedureInduction: { provider } })`.
+ *
+ * "Capture the trajectory + success signal" (the proposal's agent-side
+ * dependency) needs **no agent change**: the agent already emits the full,
+ * serializable {@link RunState} (`steps[]` + `messages[]` + `status`).
+ * {@link trajectoryFromRunState} distils it into the minimal
+ * {@link Trajectory} the inducer consumes - `succeeded = status ===
+ * 'completed'` is the AWM online-mode success signal (no ground truth
+ * needed).
+ *
+ * @packageDocumentation
+ */
+
+import type { Message, Provider, ProviderRequest, RunState } from '@graphorin/core';
+import { stripFence } from '../../internal/llm-json.js';
+
+/** Output-token ceiling for one induction call. */
+export const DEFAULT_INDUCTION_MAX_TOKENS = 512;
+
+/** Hard cap on steps in an induced procedure (defends against runaway output). */
+export const MAX_PROCEDURE_STEPS = 50;
+
+/** Upper bound on trajectory steps rendered into the induction prompt. */
+export const MAX_TRAJECTORY_STEPS_SHOWN = 60;
+
+/** Matches `{snake_case}` / `{kebab-case}` variable placeholders in a step. */
+const VARIABLE_PLACEHOLDER = /\{([a-zA-Z][\w-]*)\}/gu;
+
+/**
+ * One distilled step of an agent trajectory - model-agnostic, so the
+ * inducer never sees raw provider/tool wire formats.
+ *
+ * @stable
+ */
+export interface TrajectoryStep {
+  /** Tool invoked at this step, when the step was a tool call. */
+  readonly tool?: string;
+  /** Concrete args / observation rendered to text (the value-abstraction source). */
+  readonly detail?: string;
+}
+
+/**
+ * The minimal trajectory an inducer needs: the goal, the ordered steps, and
+ * whether the run succeeded. Induction fires on **success only** (AWM online
+ * mode) - {@link runWorkflowInduction} returns `null` for a failed run.
+ *
+ * @stable
+ */
+export interface Trajectory {
+  /** What the run set out to do (typically the first user message). */
+  readonly goal: string;
+  /** Ordered steps the agent took. */
+  readonly steps: ReadonlyArray<TrajectoryStep>;
+  /** Whether the run succeeded - the induction gate. */
+  readonly succeeded: boolean;
+}
+
+/**
+ * A reusable workflow distilled from a successful trajectory.
+ *
+ * @stable
+ */
+export interface InducedProcedure {
+  /** Short imperative title / goal of the reusable workflow. */
+  readonly title: string;
+  /** Ordered, value-abstracted steps (`"search for {product}"`, …). */
+  readonly steps: ReadonlyArray<string>;
+  /** Variable names abstracted from concrete values (`"product"`, `"day"`). */
+  readonly variables: ReadonlyArray<string>;
+  /** Voyager-style verifiable success criteria for self-verification on reuse. */
+  readonly successCriteria: ReadonlyArray<string>;
+}
+
+/** Per-call options for an induction request. */
+export interface WorkflowInductionOptions {
+  /** Output-token ceiling. Default {@link DEFAULT_INDUCTION_MAX_TOKENS}. */
+  readonly maxTokens?: number;
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * Provider-agnostic seam: turn one successful trajectory into a procedure.
+ * Returns `null` when nothing inducible (degraded provider, empty output) -
+ * never throws.
+ *
+ * @stable
+ */
+export interface WorkflowInducer {
+  induce(
+    trajectory: Trajectory,
+    options?: WorkflowInductionOptions,
+  ): Promise<InducedProcedure | null>;
+}
+
+/** Result of self-verifying a reuse against an induced procedure's criteria. */
+export interface VerificationResult {
+  /** True only when the procedure has criteria and every one is met. */
+  readonly verified: boolean;
+  /** Criteria not satisfied by the observed signals. */
+  readonly unmet: ReadonlyArray<string>;
+}
+
+export const INDUCTION_SYSTEM_PROMPT = [
+  'You are the workflow-induction step of a long-running agent memory. Given the goal and the',
+  'sequence of steps an agent took to SUCCEED at a task, distil a reusable procedure a future',
+  'agent could follow for the same kind of task. Abstract concrete values into {snake_case}',
+  'variables (e.g. "dry cat food" → {product}, "Monday" → {day}) so the procedure generalizes;',
+  'keep the steps short and imperative. Also state a few verifiable success criteria - concrete,',
+  'checkable conditions that indicate the task is done. Do NOT invent steps that did not occur.',
+  'Return strictly JSON: { "title": string, "steps": string[], "variables": string[],',
+  '"successCriteria": string[] }.',
+].join(' ');
+
+/**
+ * Build the (pure) induction request. Renders the trajectory as numbered
+ * steps; caps the rendered steps to keep the prompt bounded.
+ */
+export function buildInductionRequest(
+  trajectory: Trajectory,
+  options: WorkflowInductionOptions = {},
+): ProviderRequest {
+  const stepLines = trajectory.steps
+    .slice(0, MAX_TRAJECTORY_STEPS_SHOWN)
+    .map((step, i) => {
+      const head = step.tool !== undefined && step.tool.length > 0 ? step.tool : 'step';
+      return step.detail !== undefined && step.detail.length > 0
+        ? `[${i + 1}] ${head}: ${step.detail}`
+        : `[${i + 1}] ${head}`;
+    })
+    .join('\n');
+  const content = [
+    `Goal: ${trajectory.goal.length > 0 ? trajectory.goal : '(unstated)'}`,
+    '',
+    'Trajectory (the steps the agent took to succeed):',
+    stepLines.length > 0 ? stepLines : '(none)',
+    '',
+    'Distil the reusable procedure.',
+  ].join('\n');
+  return {
+    messages: [{ role: 'user', content }],
+    systemMessage: INDUCTION_SYSTEM_PROMPT,
+    temperature: 0,
+    maxTokens: options.maxTokens ?? DEFAULT_INDUCTION_MAX_TOKENS,
+    ...(options.signal !== undefined ? { signal: options.signal } : {}),
+    outputType: { kind: 'structured' },
+  };
+}
+
+/**
+ * Parse the induction response into an {@link InducedProcedure}, tolerating
+ * chatty / fenced output. Returns `null` when absent / unparseable / it
+ * yields no steps. **Never throws on model output** - only normalizes.
+ *
+ * The returned `variables` are reconciled with the steps: every `{name}`
+ * placeholder actually present in the steps is guaranteed to appear, so the
+ * abstraction is grounded in the procedure rather than in a model-declared
+ * list that may drift from it.
+ *
+ * @internal
+ */
+export function parseInducedProcedure(text: string | undefined): InducedProcedure | null {
+  if (text === undefined || text.length === 0) return null;
+  const parsed = tryParseObject(stripFence(text).trim());
+  if (!isRecord(parsed)) return null;
+  return normalizeInducedProcedure({
+    title: typeof parsed.title === 'string' ? parsed.title : '',
+    steps: toStringArray(parsed.steps),
+    variables: toStringArray(parsed.variables),
+    successCriteria: toStringArray(parsed.successCriteria ?? parsed.success_criteria),
+  });
+}
+
+/**
+ * Normalize a raw induced procedure: trim + drop empty entries, cap step
+ * count, and reconcile the variable list with the placeholders actually used
+ * in the steps. Returns `null` when no usable steps remain (nothing to
+ * induce).
+ *
+ * @internal
+ */
+export function normalizeInducedProcedure(raw: {
+  title: string;
+  steps: ReadonlyArray<string>;
+  variables: ReadonlyArray<string>;
+  successCriteria: ReadonlyArray<string>;
+}): InducedProcedure | null {
+  const steps = raw.steps
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0)
+    .slice(0, MAX_PROCEDURE_STEPS);
+  if (steps.length === 0) return null;
+
+  // Variables = placeholders actually in the steps (source of truth, keeps
+  // the abstraction grounded), unioned with any extra model-declared names.
+  const fromSteps = extractPlaceholders(steps);
+  const declared = raw.variables.map((v) => normalizeVariableName(v)).filter((v) => v.length > 0);
+  const variables = dedupe([...fromSteps, ...declared]);
+
+  const successCriteria = dedupe(
+    raw.successCriteria.map((c) => c.trim()).filter((c) => c.length > 0),
+  );
+  const title = raw.title.trim().length > 0 ? raw.title.trim() : (steps[0] ?? 'induced procedure');
+  return { title, steps, variables, successCriteria };
+}
+
+/**
+ * Resilient provider-backed inducer. A provider throw or unparseable output
+ * degrades to `null` (no procedure) - induction never breaks the write path.
+ */
+export function createProviderWorkflowInducer(
+  provider: Provider,
+  options: {
+    readonly maxTokens?: number;
+    /**
+     * Usage callback (MCON-15) - induction is the framework's highest
+     * poisoning-risk LLM spend and previously flowed past every budget
+     * envelope. `createMemory` wires this into the consolidator budget
+     * when one is enabled; standalone callers can record it themselves.
+     * Best-effort: a throwing callback never breaks induction.
+     */
+    readonly onUsage?: (usage: {
+      readonly promptTokens: number;
+      readonly completionTokens: number;
+    }) => void;
+  } = {},
+): WorkflowInducer {
+  return {
+    async induce(trajectory, callOptions = {}): Promise<InducedProcedure | null> {
+      const merged: WorkflowInductionOptions = {
+        maxTokens: callOptions.maxTokens ?? options.maxTokens ?? DEFAULT_INDUCTION_MAX_TOKENS,
+        ...(callOptions.signal !== undefined ? { signal: callOptions.signal } : {}),
+      };
+      try {
+        const res = await provider.generate(buildInductionRequest(trajectory, merged));
+        try {
+          options.onUsage?.({
+            promptTokens: res.usage.promptTokens,
+            completionTokens: res.usage.completionTokens,
+          });
+        } catch {
+          // Accounting is advisory; never break the induction result.
+        }
+        return parseInducedProcedure(res.text);
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+/**
+ * Pure orchestrator: induce a procedure from a trajectory.
+ *
+ * **Gate - successful trajectories only** (AWM online mode): a failed /
+ * aborted run, or one with no steps, yields `null` without calling the
+ * inducer. Otherwise the inducer runs and the result is normalized.
+ */
+export async function runWorkflowInduction(
+  trajectory: Trajectory,
+  inducer: WorkflowInducer,
+  options: WorkflowInductionOptions = {},
+): Promise<InducedProcedure | null> {
+  if (!trajectory.succeeded) return null;
+  if (trajectory.steps.length === 0) return null;
+  const induced = await inducer.induce(trajectory, options);
+  if (induced === null) return null;
+  return normalizeInducedProcedure({
+    title: induced.title,
+    steps: induced.steps,
+    variables: induced.variables,
+    successCriteria: induced.successCriteria,
+  });
+}
+
+/**
+ * Distil a {@link RunState} into the minimal {@link Trajectory} the inducer
+ * needs. Pure - consumes the agent's already-emitted run state, so capturing
+ * a trajectory + its success signal needs no agent-loop change. The success
+ * signal is `status === 'completed'`.
+ */
+export function trajectoryFromRunState(run: RunState): Trajectory {
+  const steps: TrajectoryStep[] = [];
+  for (const step of run.steps) {
+    for (const tc of step.toolCalls) {
+      const detail = renderArgs(tc.call.args);
+      steps.push({
+        tool: tc.call.toolName,
+        ...(detail !== undefined ? { detail } : {}),
+      });
+    }
+  }
+  return {
+    goal: firstUserText(run.messages) ?? '',
+    steps,
+    succeeded: run.status === 'completed',
+  };
+}
+
+/**
+ * Self-verify a reuse against an induced procedure's success criteria. A
+ * criterion is met when any observed signal contains it (case-insensitive
+ * substring) - a deterministic, offline check the agent runtime can feed
+ * actual run observations into on reuse. With **no criteria**, the reuse
+ * cannot be self-verified, so `verified` is `false`.
+ */
+export function checkSuccessCriteria(
+  procedure: { readonly successCriteria?: ReadonlyArray<string> },
+  observed: ReadonlyArray<string>,
+): VerificationResult {
+  const criteria = (procedure.successCriteria ?? [])
+    .map((c) => c.trim())
+    .filter((c) => c.length > 0);
+  if (criteria.length === 0) return { verified: false, unmet: [] };
+  const haystack = observed.map((o) => o.toLowerCase());
+  const unmet = criteria.filter((c) => !haystack.some((o) => o.includes(c.toLowerCase())));
+  return { verified: unmet.length === 0, unmet };
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────
+
+function extractPlaceholders(steps: ReadonlyArray<string>): string[] {
+  const out: string[] = [];
+  for (const step of steps) {
+    for (const match of step.matchAll(VARIABLE_PLACEHOLDER)) {
+      const name = match[1];
+      if (name !== undefined) out.push(name);
+    }
+  }
+  return out;
+}
+
+function normalizeVariableName(value: string): string {
+  // Accept either a bare name or a `{name}` placeholder.
+  const inner = /^\{([a-zA-Z][\w-]*)\}$/u.exec(value.trim());
+  return (inner?.[1] ?? value).trim();
+}
+
+function dedupe(values: ReadonlyArray<string>): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const v of values) {
+    if (seen.has(v)) continue;
+    seen.add(v);
+    out.push(v);
+  }
+  return out;
+}
+
+function renderArgs(args: unknown): string | undefined {
+  if (args === undefined || args === null) return undefined;
+  if (typeof args === 'string') return args.length > 0 ? truncate(args) : undefined;
+  try {
+    const json = JSON.stringify(args);
+    return json !== undefined && json !== '{}' ? truncate(json) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function truncate(value: string, max = 200): string {
+  return value.length > max ? `${value.slice(0, max)}…` : value;
+}
+
+function firstUserText(messages: ReadonlyArray<Message>): string | undefined {
+  for (const message of messages) {
+    if (message.role !== 'user') continue;
+    const text = messageText(message);
+    if (text.length > 0) return text;
+  }
+  return undefined;
+}
+
+function messageText(message: Message): string {
+  const content = message.content;
+  if (typeof content === 'string') return content.trim();
+  const parts: string[] = [];
+  for (const part of content) {
+    if (part.type === 'text' && typeof part.text === 'string') parts.push(part.text);
+  }
+  return parts.join(' ').trim();
+}
+
+function toStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((v): v is string => typeof v === 'string');
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function tryParseObject(candidate: string): unknown {
+  if (candidate.length === 0) return undefined;
+  try {
+    return JSON.parse(candidate);
+  } catch {
+    const start = candidate.indexOf('{');
+    const end = candidate.lastIndexOf('}');
+    if (start < 0 || end < start) return undefined;
+    try {
+      return JSON.parse(candidate.slice(start, end + 1));
+    } catch {
+      return undefined;
+    }
+  }
+}

package/src/consolidator/phases/learned-context.ts

@@ -0,0 +1,233 @@
+/**
+ * Learned-context pass (D3) - Letta-style sleep-time maintenance of a
+ * persistent, size-bounded, agent-editable digest block. The deep phase
+ * rewrites one reserved working-memory block (`learned_context`) from
+ * the previous digest + fresh evidence (recent episodes, active
+ * insights, active procedures), so every subsequent step's system
+ * prompt carries a compact "what I have learned about this user /
+ * project" summary inside the stable KV-cache prefix - without
+ * retrieval latency and without unbounded growth.
+ *
+ * The block itself is an ordinary working block: it is spliced into
+ * layer 3 of the assembled context automatically, re-anchored after
+ * compaction by the persona-block hook pattern, and remains editable by
+ * the agent through the existing `block_*` tools (the pass rewrites it
+ * on its own cadence, folding any agent edits into the next rewrite).
+ *
+ * Runs after the deep-phase reflection pass, reusing the same budget /
+ * lock / run-audit envelope. Gated off by default at every tier
+ * (`learnedContext: false`) - Wave-D trial discipline.
+ *
+ * @packageDocumentation
+ */
+
+import type { Provider, ProviderRequest, SessionScope, Tracer } from '@graphorin/core';
+import { withMemorySpan } from '../../internal/spans.js';
+import type { MemoryStoreAdapter } from '../../internal/storage-adapter.js';
+import type { EpisodicMemory } from '../../tiers/episodic-memory.js';
+import { defineBlock, type WorkingMemory } from '../../tiers/working-memory.js';
+import type { BudgetTracker } from '../budget.js';
+
+/** Reserved working-block label maintained by the pass. */
+export const LEARNED_CONTEXT_BLOCK_LABEL = 'learned_context';
+
+/** Default character bound for the digest block. */
+export const DEFAULT_LEARNED_CONTEXT_MAX_CHARS = 1200;
+
+/** How many recent episode summaries feed one rewrite. */
+const EPISODE_CONTEXT_LIMIT = 15;
+
+/** How many active insights / procedures feed one rewrite. */
+const INSIGHT_CONTEXT_LIMIT = 10;
+const PROCEDURE_CONTEXT_LIMIT = 8;
+
+const LEARNED_CONTEXT_SYSTEM_PROMPT = [
+  'You maintain the learned-context block of a long-running personal-assistant memory:',
+  'a compact standing digest of what is durably known about the user and their active',
+  'work (profile, preferences, ongoing projects, validated insights, working procedures).',
+  'Rewrite the digest by folding the new evidence into the previous digest: keep what is',
+  'still true, drop what is stale or superseded, and never invent anything the evidence',
+  'does not support. Write plain prose or short dashed lines - no markdown headings, no',
+  'code fences, no preamble. Stay strictly under the character budget.',
+].join(' ');
+
+/** Inputs accepted by {@link runLearnedContextPass}. */
+export interface LearnedContextDeps {
+  readonly provider: Provider;
+  readonly tracer: Tracer;
+  readonly scope: SessionScope;
+  /** Working tier that owns the digest block. */
+  readonly working: WorkingMemory;
+  /** Recent-episode evidence source. `null` ⇒ episodes are skipped. */
+  readonly episodic: EpisodicMemory | null;
+  /** Storage adapter - supplies active insights + procedures as evidence. */
+  readonly store: MemoryStoreAdapter;
+  readonly budget: BudgetTracker;
+  /** Character bound enforced on the stored digest. */
+  readonly maxChars: number;
+  readonly priceUsage?: (usage: { promptTokens: number; completionTokens: number }) => number;
+  /** Override the wall clock - used by tests. */
+  readonly now?: () => number;
+}
+
+/** Summary returned by {@link runLearnedContextPass}. */
+export interface LearnedContextOutcome {
+  /** True when the block was rewritten this pass. */
+  readonly updated: boolean;
+  /** Stored digest length after the pass (0 when skipped and absent). */
+  readonly chars: number;
+  readonly tokens: number;
+  readonly costUsd: number;
+  /** Why the pass made no LLM call, when it did not. */
+  readonly skippedReason?: 'budget' | 'no-evidence' | 'empty-rewrite' | 'provider-error';
+}
+
+/**
+ * Strip an accidental leading code fence from the model's digest and
+ * clamp it to the character budget. Returns `null` for an effectively
+ * empty rewrite (the previous digest is then left untouched).
+ */
+export function normalizeLearnedContext(raw: string, maxChars: number): string | null {
+  let text = raw.trim();
+  const fence = /^```[^\n]*\n([\s\S]*?)\n?```\s*$/.exec(text);
+  if (fence?.[1] !== undefined) text = fence[1].trim();
+  if (text.length === 0) return null;
+  return text.length > maxChars ? text.slice(0, maxChars).trimEnd() : text;
+}
+
+/** Build the single rewrite request (pure - testable offline). */
+export function buildLearnedContextRequest(args: {
+  readonly previous: string;
+  readonly episodes: ReadonlyArray<string>;
+  readonly insights: ReadonlyArray<string>;
+  readonly procedures: ReadonlyArray<string>;
+  readonly maxChars: number;
+}): ProviderRequest {
+  const sections: string[] = [
+    `Character budget: ${args.maxChars}.`,
+    args.previous.length > 0
+      ? `Previous digest:\n${args.previous}`
+      : 'Previous digest: (none yet - write the first one)',
+  ];
+  if (args.episodes.length > 0) {
+    sections.push(`Recent episodes:\n${args.episodes.map((s) => `- ${s}`).join('\n')}`);
+  }
+  if (args.insights.length > 0) {
+    sections.push(`Validated insights:\n${args.insights.map((s) => `- ${s}`).join('\n')}`);
+  }
+  if (args.procedures.length > 0) {
+    sections.push(`Active procedures:\n${args.procedures.map((s) => `- ${s}`).join('\n')}`);
+  }
+  sections.push('Return ONLY the rewritten digest text.');
+  return {
+    messages: [{ role: 'user', content: sections.join('\n\n') }],
+    systemMessage: LEARNED_CONTEXT_SYSTEM_PROMPT,
+    temperature: 0,
+    maxTokens: Math.max(256, Math.ceil(args.maxChars / 2)),
+  };
+}
+
+/**
+ * Run the learned-context rewrite. Resilient by construction: a
+ * provider failure or empty rewrite leaves the existing block untouched
+ * and never throws; only storage errors propagate.
+ */
+export async function runLearnedContextPass(
+  deps: LearnedContextDeps,
+): Promise<LearnedContextOutcome> {
+  return withMemorySpan(
+    deps.tracer,
+    'memory.consolidate.learned-context',
+    deps.scope,
+    { 'consolidator.phase': 'learned-context' },
+    async (span) => {
+      const skip = (
+        reason: NonNullable<LearnedContextOutcome['skippedReason']>,
+        chars = 0,
+      ): LearnedContextOutcome => {
+        span.setAttributes({ 'consolidator.learned_context.skipped': reason });
+        return { updated: false, chars, tokens: 0, costUsd: 0, skippedReason: reason };
+      };
+      if (deps.budget.snapshot().paused) return skip('budget');
+
+      // Ensure the reserved block is registered so write() can create it.
+      if (deps.working.definitionFor(LEARNED_CONTEXT_BLOCK_LABEL) === undefined) {
+        deps.working.define(
+          defineBlock({
+            label: LEARNED_CONTEXT_BLOCK_LABEL,
+            description:
+              'Standing digest of durable knowledge about the user and active work, ' +
+              'maintained by the deep-phase learned-context pass.',
+            charLimit: deps.maxChars,
+          }),
+        );
+      }
+      const previous = (await deps.working.read(deps.scope, LEARNED_CONTEXT_BLOCK_LABEL)) ?? '';
+
+      // Evidence: recent episodes (incl. quarantined auto-formed ones -
+      // they carry the importance signal), ACTIVE insights only (the
+      // digest drives behaviour, so quarantined synthesis stays out),
+      // and active procedures.
+      const episodes =
+        deps.episodic === null
+          ? []
+          : (
+              await deps.episodic.listRecent(deps.scope, EPISODE_CONTEXT_LIMIT, {
+                includeQuarantined: true,
+              })
+            ).map((episode) => episode.summary);
+      const insights =
+        deps.store.insights === undefined
+          ? []
+          : (await deps.store.insights.list(deps.scope, { limit: INSIGHT_CONTEXT_LIMIT })).map(
+              (insight) => insight.text,
+            );
+      const procedures = (await deps.store.procedural.list(deps.scope))
+        .filter((rule) => rule.status !== 'quarantined')
+        .slice(0, PROCEDURE_CONTEXT_LIMIT)
+        .map((rule) => rule.text.split('\n')[0] ?? rule.text);
+
+      const evidenceCount = episodes.length + insights.length + procedures.length;
+      span.setAttributes({ 'consolidator.learned_context.evidence': evidenceCount });
+      // Nothing new to fold and nothing written yet ⇒ no paid call.
+      if (evidenceCount === 0) return skip('no-evidence', previous.length);
+
+      let tokens = 0;
+      let costUsd = 0;
+      try {
+        const res = await deps.provider.generate(
+          buildLearnedContextRequest({
+            previous,
+            episodes,
+            insights,
+            procedures,
+            maxChars: deps.maxChars,
+          }),
+        );
+        tokens =
+          (res.usage.promptTokens ?? 0) +
+          (res.usage.completionTokens ?? 0) +
+          (res.usage.reasoningTokens ?? 0);
+        costUsd =
+          deps.priceUsage?.({
+            promptTokens: res.usage.promptTokens ?? 0,
+            completionTokens: res.usage.completionTokens ?? 0,
+          }) ?? 0;
+        deps.budget.record({ phase: 'deep', tokens, costUsd });
+        const next = normalizeLearnedContext(res.text ?? '', deps.maxChars);
+        if (next === null) {
+          return { ...skip('empty-rewrite', previous.length), tokens, costUsd };
+        }
+        await deps.working.write(deps.scope, LEARNED_CONTEXT_BLOCK_LABEL, next);
+        span.setAttributes({
+          'consolidator.learned_context.updated': true,
+          'consolidator.learned_context.chars': next.length,
+        });
+        return { updated: true, chars: next.length, tokens, costUsd };
+      } catch {
+        // Resilient: a provider failure must never fail the deep phase.
+        return { ...skip('provider-error', previous.length), tokens, costUsd };
+      }
+    },
+  );
+}