@manyoars/oars 0.2.0 → 0.4.0

package/dist/sessions/recall-consequence.js

@@ -0,0 +1,179 @@
+// What a recall led to (recall spec Sections 2.7 and 4). A pure function of `recalls.jsonl` and the capture records, computed at derive and never captured live, so
+// `recalls.jsonl` stays append-only and a change here needs no re-deposit. Held recalls get a consequence too: they are the baseline a shown recall reads against. Only a
+// shown recall touches the graph, because a held one reached nobody: it adds no `recall.*` step and exposes no cell.
+import { motifsOf, stepsOfCall } from './motif.js';
+import { bucketOf, floorOf } from './pool-wire.js';
+import { harnessOf } from './schema.js';
+/** A consequence window ends at the prompt's end or after this many calls (spec Section 2.7). */
+export const WINDOW_CALLS = 20;
+const callKey = (tool) => `${tool.session}#${String(tool.n)}`;
+const promptKey = (session, index) => `${session}#${String(index)}`;
+/**
+ * Each session's main line, in order. A hook inside a subagent reports the parent's session id, so a subagent's push is placed on the parent's line by its time; that is
+ * a weak spot of the window, not of the arm.
+ */
+const mainLines = (store) => {
+    const lines = new Map();
+    for (const tool of store.tools) {
+        if (tool.side)
+            continue;
+        const line = lines.get(tool.session);
+        if (line === undefined)
+            lines.set(tool.session, [tool]);
+        else
+            line.push(tool);
+    }
+    for (const line of lines.values())
+        line.sort((a, b) => a.n - b.n);
+    return lines;
+};
+/**
+ * The first call stamped after the recall. A call's line is written before its pre-tool hook runs, and a hook's text reaches the model after that call was already decided, so
+ * the call a push fired on is behind it and the window opens on the next decision.
+ */
+const positionOf = (line, at) => {
+    const next = line.findIndex((tool) => tool.ts !== null && tool.ts > at);
+    return next < 0 ? line.length : next;
+};
+const outcomeOf = (prompt) => ({
+    errors: prompt?.errors ?? null,
+    verify: prompt?.verify ?? null,
+    stopped: prompt?.stopped ?? null,
+    commits: prompt?.commits ?? null,
+    redo: prompt?.redo ?? null,
+});
+const consequenceOf = (recall, session, line, position, harness, prompts) => {
+    const prompt = (line[position - 1] ?? line[position])?.prompt ?? null;
+    const calls = [];
+    let end = 'session';
+    for (const tool of line.slice(position)) {
+        if (calls.length === WINDOW_CALLS) {
+            end = 'calls';
+            break;
+        }
+        if (tool.prompt !== prompt) {
+            end = 'prompt';
+            break;
+        }
+        calls.push(tool);
+    }
+    const steps = calls.flatMap((tool) => stepsOfCall(tool, harness));
+    const names = new Set(recall.answer.names);
+    const measured = calls.flatMap((tool) => tool.steps ?? []).flatMap((step) => step.cost.tokens ?? []);
+    return {
+        window: { from: position, to: position + calls.length, calls: calls.length, end },
+        // Shape level only: it is the ID that joins across accounts, and named windows would multiply a row that exists per recall.
+        motifs: [...new Set(motifsOf(steps).flatMap(({ motif }) => (motif.level === 'shape' ? [motif.motifId] : [])))],
+        followed: steps.some((step) => names.has(step.action)),
+        cost: { tokens: measured.length === 0 ? null : measured.reduce((sum, tokens) => sum + tokens, 0), durationMs: steps.reduce((sum, step) => sum + step.durationMs, 0) },
+        outcome: outcomeOf(prompts.get(promptKey(session, prompt))),
+    };
+};
+/** Fills `n` and `consequence`. A recall with no session, or from a session this store does not hold, has nothing to read and comes back as it was. */
+export const deriveConsequences = (store, recalls) => {
+    const lines = mainLines(store);
+    const prompts = new Map(store.prompts.map((prompt) => [promptKey(prompt.session, prompt.index), prompt]));
+    const sessions = new Map(store.sessions.map((session) => [session.session, session]));
+    return recalls.map((recall) => {
+        const session = recall.sid === null ? undefined : sessions.get(recall.sid);
+        if (session === undefined)
+            return recall;
+        const line = lines.get(session.session) ?? [];
+        const position = positionOf(line, recall.at);
+        return { ...recall, n: position, consequence: consequenceOf(recall, session.session, line, position, harnessOf(session), prompts) };
+    });
+};
+export const NO_RECALLS = {
+    place: (_tool, steps) => steps.map((step) => ({ step, exposed: false })),
+    exposedPrompt: () => false,
+};
+const pushTo = (map, key, step) => {
+    const found = map.get(key);
+    if (found === undefined)
+        map.set(key, [step]);
+    else
+        found.push(step);
+};
+/** The step enters a cell after the store is floored, so its own count is floored here: no cell holds a number finer than its bucket's floor (rule 5). */
+const recallStep = (recall) => ({
+    step: { action: recall.mode === 'pull' ? 'recall.pull' : 'recall.push', identity: null, status: 'ok', tokens: floorOf('tokens', bucketOf('tokens', recall.answer.tokens)), durationMs: 0 },
+    exposed: true,
+});
+/**
+ * Takes recalls that have been through `deriveConsequences`. An MCP pull has no session id, so the only step it has is the one in its transcript; a pull that names its session
+ * (`--session`) has no MCP call, so its step is this one.
+ */
+export const recallGraphOf = (store, recalls) => {
+    const lines = mainLines(store);
+    const exposedCalls = new Set();
+    const exposedPrompts = new Set();
+    const before = new Map();
+    const after = new Map();
+    for (const recall of recalls) {
+        const line = recall.sid === null ? undefined : lines.get(recall.sid);
+        if (recall.arm === 'held' || recall.consequence === undefined || line === undefined)
+            continue;
+        const { from, to } = recall.consequence.window;
+        // A shown miss showed no evidence, so its window is not an exposure; the step stays, since the pull happened.
+        if (recall.answer.kind !== 'miss') {
+            for (const tool of line.slice(from, to)) {
+                exposedCalls.add(callKey(tool));
+                exposedPrompts.add(promptKey(tool.session, tool.prompt));
+            }
+        }
+        const previous = line[from - 1];
+        const first = line[from];
+        if (previous !== undefined)
+            pushTo(after, callKey(previous), recallStep(recall));
+        else if (first !== undefined)
+            pushTo(before, callKey(first), recallStep(recall));
+    }
+    return {
+        place: (tool, steps) => {
+            const key = callKey(tool);
+            const exposed = exposedCalls.has(key);
+            return [...(before.get(key) ?? []), ...steps.map((step) => ({ step, exposed })), ...(after.get(key) ?? [])];
+        },
+        exposedPrompt: (session, index) => exposedPrompts.has(promptKey(session, index)),
+    };
+};
+const sharesACall = (one, other) => Math.max(one.from, other.from) < Math.min(one.to, other.to);
+/** Takes recalls that have been through `deriveConsequences`; `day` is a UTC day, so one day of hooks reads as one set of rows. A shown window from any day can overlap a held one. */
+export const recallCounts = (recalls, day) => {
+    const rows = new Map();
+    const shown = new Map();
+    for (const recall of recalls) {
+        if (recall.arm === 'shown' && recall.consequence !== undefined)
+            shown.set(recall.sid, [...(shown.get(recall.sid) ?? []), recall.consequence.window]);
+    }
+    for (const recall of recalls) {
+        if (day !== undefined && !recall.at.startsWith(day))
+            continue;
+        const key = [recall.mode, recall.arm, recall.answer.kind].join(' ');
+        const held = rows.get(key) ?? { row: { mode: recall.mode, arm: recall.arm, kind: recall.answer.kind, recalls: 0, sessions: 0, tokens: 0, windows: 0, followed: 0, windowCalls: 0, windowTokens: null, overlapped: 0 }, sessions: new Set() };
+        rows.set(key, held);
+        const { row, sessions } = held;
+        row.recalls += 1;
+        row.tokens += recall.answer.tokens;
+        if (recall.sid !== null)
+            sessions.add(recall.sid);
+        row.sessions = sessions.size;
+        const { consequence } = recall;
+        if (consequence === undefined)
+            continue;
+        row.windows += 1;
+        if (consequence.followed)
+            row.followed += 1;
+        row.windowCalls += consequence.window.calls;
+        if (consequence.cost.tokens !== null)
+            row.windowTokens = (row.windowTokens ?? 0) + consequence.cost.tokens;
+        if (recall.arm === 'held' && (shown.get(recall.sid) ?? []).some((window) => sharesACall(consequence.window, window)))
+            row.overlapped += 1;
+    }
+    return [...rows.entries()].sort(([a], [b]) => (a < b ? -1 : 1)).map(([, { row }]) => row);
+};
+export const formatRecallCounts = (rows) => rows.length === 0
+    ? 'No recalls in that span.'
+    : rows
+        .map((row) => `${row.mode} ${row.arm} ${row.kind} | ${String(row.recalls)} recalls, ${String(row.sessions)} sessions, ${String(row.tokens)} tokens | ${String(row.windows)} windows, ${String(row.followed)} followed, ${String(row.windowCalls)} calls, ${row.windowTokens === null ? 'window tokens unmeasured' : `${String(row.windowTokens)} window tokens`}, ${String(row.overlapped)} overlapped`)
+        .join('\n');

package/dist/sessions/recall-frames.d.ts

@@ -0,0 +1,18 @@
+import { type Pool } from './cells.js';
+import { type Position, type RecoveryEdges } from './recall-next.js';
+import type { Store } from './store.js';
+/** The positions one frame keeps: a table prints at most eight, so twelve leaves room for the bundle's to rank ahead without carrying every position a store has. */
+export declare const PER_FRAME_POSITIONS = 12;
+export interface NextByFrame {
+    recovery: {
+        [frame: string]: RecoveryEdges;
+    };
+    positions: {
+        [frame: string]: Position[];
+    };
+}
+/**
+ * The recovery edges and split positions for each harness (key `<harness>/*`, for a session whose version is not stated) and each harness version bucket (`<harness>/<bucket>`).
+ * Every recovery key is kept, a below-floor one included, so a hook can tell "a cell, too thin to serve" from "no cell".
+ */
+export declare const nextByFrame: (pool: Pool, store: Store) => NextByFrame;

package/dist/sessions/recall-frames.js

@@ -0,0 +1,44 @@
+// The local half of a next-node read, in the asker's frame (t926 Item 9). The pool's next-step and recovery reads sum every harness and version a store holds, so a table built from
+// them would tell a Codex session what Claude Code sessions did. This derives the two families again over the cells of each harness and version bucket, once per deposit, and the
+// hook index keeps the result by frame key; a hook then reads the one entry for the session it serves. It is its own module because the families it imports are the pool's,
+// which a lookup hook must not load (the index step imports this one lazily, as it does `pool.js`).
+import { bucketFields } from './cells.js';
+import { makeRead, orderResolver } from './read.js';
+import { deriveNextStep } from './read-next-step.js';
+import { deriveRecoveryEdges } from './read-recovery-edge.js';
+import { positionsOf, recoveryEdgesOf } from './recall-next.js';
+/** The positions one frame keeps: a table prints at most eight, so twelve leaves room for the bundle's to rank ahead without carrying every position a store has. */
+export const PER_FRAME_POSITIONS = 12;
+const readsOf = (pool, store) => {
+    const asOf = { pool: pool.version, day: pool.lastDay };
+    const orderOf = orderResolver([]);
+    return [...deriveNextStep({ pool, store }), ...deriveRecoveryEdges({ pool, store })].map((body) => makeRead({ ...body, asOf }, orderOf));
+};
+/**
+ * The recovery edges and split positions for each harness (key `<harness>/*`, for a session whose version is not stated) and each harness version bucket (`<harness>/<bucket>`).
+ * Every recovery key is kept, a below-floor one included, so a hook can tell "a cell, too thin to serve" from "no cell".
+ */
+export const nextByFrame = (pool, store) => {
+    const frames = new Map();
+    for (const cell of pool.cells) {
+        if (cell.frameBucket.startsWith('env:'))
+            continue;
+        const { harness, harnessBucket } = bucketFields(cell.frameBucket);
+        for (const key of [`${harness}/*`, `${harness}/${harnessBucket}`]) {
+            const buckets = frames.get(key) ?? new Set();
+            frames.set(key, buckets);
+            buckets.add(cell.frameBucket);
+        }
+    }
+    const out = { recovery: {}, positions: {} };
+    for (const [key, buckets] of frames) {
+        const reads = readsOf({ ...pool, cells: pool.cells.filter((cell) => buckets.has(cell.frameBucket)) }, store);
+        const recovery = recoveryEdgesOf(reads);
+        const positions = positionsOf(reads).slice(0, PER_FRAME_POSITIONS);
+        if (Object.keys(recovery).length > 0)
+            out.recovery[key] = recovery;
+        if (positions.length > 0)
+            out.positions[key] = positions;
+    }
+    return out;
+};

package/dist/sessions/recall-next.d.ts

@@ -0,0 +1,145 @@
+import type { Read } from './read.js';
+import { type Recall } from './recall-object.js';
+import { type RecallRead } from './recall-reads.js';
+import type { Frame, Harness } from './schema.js';
+/**
+ * The count a recovery edge needs before it is served from the local pool. The pool's own served floor is `K_CELL` (5 accounts, `packages/pool/src/derive.ts`); a bundle's read has
+ * cleared it already, so only a local edge is held to this, counted in followed steps because one operator's store is one account.
+ */
+export declare const RECOVERY_FLOOR = 5;
+/** The steps a position needs behind it before it can be called split: t782's qualifying cell is a cell topped up to 20 sessions. */
+export declare const POSITION_MIN_N = 20;
+/** The band of t782 plan 1.7: the leading option's share, 20 to 80 percent inclusive. A settled position (above) and a diffuse one (below) are not listed. */
+export declare const POSITION_BAND: {
+    readonly low: 0.2;
+    readonly high: 0.8;
+};
+/**
+ * The bytes a table may add to a turn's context. Eight lines of about 70 bytes: a session start or a prompt carries it every time it is sent, and a table the agent has to
+ * read past is one it stops reading. Bundle positions come first, then local ones, each by observations; the cap cuts from the end, so a local position goes before a bundle one.
+ */
+export declare const TABLE_CAP_BYTES = 600;
+export interface RecoveryEdge {
+    next: string;
+    followed: number;
+    /** The failures of this action and code over every week, the one denominator of every edge's share. */
+    of: number;
+    clusters: number;
+    /** The heaviest week's read, the one the row cites. */
+    readId: string;
+    day: string | null;
+}
+export interface RecoveryEdges {
+    [actionAndCode: string]: RecoveryEdge[];
+}
+export interface Position {
+    prefix: string;
+    n: number;
+    /** The three most common next steps with their counts. */
+    next: Array<[string, number]>;
+    clusters: number;
+    readId: string;
+    day: string | null;
+}
+/** The reads one source (the kept bundle, or the local pool) gives the two hooks. */
+export interface NextReads {
+    poolVersion: string;
+    recovery: RecoveryEdges;
+    positions: Position[];
+}
+/**
+ * The recovery edges of a set of reads, by `action/errorCode`, each next step summed over its weeks. A next step that is not a canonical action (or `none`) is left out, so the
+ * names a hook shows are the closed ones whatever a store holds.
+ */
+export declare const recoveryEdgesOf: (reads: readonly Read[], keep?: (followed: number) => boolean) => RecoveryEdges;
+/** The positions of a set of reads where the next step is split by t782's rule: enough observations, and the leading step's share inside the band. */
+export declare const positionsOf: (reads: readonly Read[]) => Position[];
+export type RecoveryDecision = {
+    kind: 'serve';
+    source: 'bundle' | 'local';
+    edges: RecoveryEdge[];
+    poolVersion: string;
+}
+/** The top next step is the failed action again: nothing to add to what the agent does anyway. */
+ | {
+    kind: 'retry';
+}
+/** A local edge under the floor. */
+ | {
+    kind: 'floor';
+}
+/** A cell covers this action and error class and its top next step is that nothing followed: the failure is covered, so no older line answers it either. */
+ | {
+    kind: 'ended';
+}
+/** No cell for this action and error class. */
+ | {
+    kind: 'none';
+};
+/**
+ * What a failure is answered with: the bundle's edges for this action and error class if it holds any (they cleared the pool's floor), else the local pool's. Silent when the top
+ * next step is a same-step retry (direction 13c), when a local edge is under `RECOVERY_FLOOR`, or when the top is that nothing followed (`ended`).
+ */
+export declare const recoveryDecision: (bundle: NextReads | undefined, local: {
+    recovery: RecoveryEdges;
+    poolVersion: string;
+} | undefined, action: string, code: string) => RecoveryDecision;
+/** The recovery read as text: names (closed) and numbers. */
+export declare const renderRecovery: (action: string, code: string, edges: readonly RecoveryEdge[]) => {
+    rendered: string;
+    names: string[];
+};
+/** The positions table, with every position that fits under the cap and nothing when none does. */
+export declare const renderPositions: (positions: readonly Position[]) => {
+    rendered: string;
+    listed: Position[];
+    names: string[];
+};
+/**
+ * The key a hook index files the local pool's reads under for a session: its harness and the bucket of the version it runs (`recall-frames.ts`). A session whose version is not
+ * stated is read across every version of its harness, which is the filter that can be applied honestly.
+ */
+export declare const frameKeyOf: (asker: Asker) => string;
+/** The bundle's and the local pool's positions as one list, a prefix once: the bundle's positions by observations, then the local ones it lacks by observations. */
+export declare const mergePositions: (bundle: readonly Position[], local: readonly Position[]) => Position[];
+export interface Asker {
+    harness: Harness;
+    harnessVersion: string | null;
+}
+export interface NextInput {
+    storeDir: string;
+    sid: string;
+    /** The tail of the transcript the hook was given, which states the version and model; empty when it gave none. */
+    tail: string;
+    platform: string;
+    at: string;
+}
+/** The asker's frame, from the tail of its transcript. */
+export declare const frameFor: (input: Pick<NextInput, "tail" | "platform" | "at">) => Frame;
+/** The reads of the kept bundle for the asker's harness and version; undefined with no version stated, no bundle, or a bundle that does not verify (never an error). */
+export declare const bundleNext: (storeDir: string, asker: Asker) => Promise<NextReads | undefined>;
+/**
+ * A served or held read: the row is written before anything is injected, and the arm is the session's for this query against this pool. The row is the recall's exposure record
+ * (ids and counts, and the rendered text a held read would have shown); an arm that kept it back is returned so the hook injects nothing.
+ */
+export declare const recordRead: (input: NextInput, frame: Frame, query: Recall["query"], armPrefix: readonly string[], poolVersion: string, rendered: string, names: readonly string[], reads: readonly RecallRead[]) => Promise<Recall>;
+/** The recovery read for one failure, as a recall row. */
+export declare const recoveryRecall: (input: NextInput, setup: Asker, action: string, code: string, decision: Extract<RecoveryDecision, {
+    kind: "serve";
+}>) => Promise<Recall>;
+/** The old signature line's recall: the local signature index, held to the same retry rule and floor. */
+export declare const signatureRecall: (input: NextInput, setup: Asker, tool: string, sig: string, found: {
+    sessions: number;
+    followed: Array<[string, number]>;
+}, poolVersion: string) => Promise<Recall>;
+/**
+ * The signature line is a same-step retry when the tool that failed is the one that most often followed, strictly: a tie with another tool is not a retry-only cell. It keeps its
+ * own floor, the index's two sessions: it states how many sessions saw the error, so a thin count is printed as thin, which a cell's share is not.
+ */
+export declare const isSignatureRetry: (tool: string, found: {
+    followed: Array<[string, number]>;
+}) => boolean;
+/** The positions table for a session, as a recall row; undefined when no position qualifies or the table is the one `previous` already sent. */
+export declare const positionsRecall: (input: NextInput, setup: Asker, positions: readonly Position[], poolVersion: string, previous?: string) => Promise<Recall | undefined>;
+/** The text the session was last sent a table with, from `recalls.jsonl`; undefined when it was never sent one. */
+export declare const lastTable: (storeDir: string, sid: string) => Promise<string | undefined>;

package/dist/sessions/recall-next.js

@@ -0,0 +1,241 @@
+// The next-node read (t926): what the agent is shown at the moments before it decides. Two reads, both from cells and never from text: the recovery edge (what followed this
+// failure, for this action and error class) and the split positions (the places in a repo's earlier work where the next step is not settled). A read is built from the kept
+// bundle for the session's setup first and the local pool's reads second, and every shown or held one is a `Recall` row, so the holdback arms are real.
+import { CANONICAL_ACTIONS } from './actions.js';
+import { harnessBucket } from './cells.js';
+import { appendRecall, armOf, makeRecall, parseRecalls, recallsPath } from './recall-object.js';
+import { frameOfTail, tailOf } from './recall-push.js';
+import { sessionBundle } from './pool-replica.js';
+import { readIdOf } from './recall-reads.js';
+import { closedName, count, evidenceOf } from './recall-render.js';
+import { LITERAL } from './public-vocabulary.js';
+/**
+ * The count a recovery edge needs before it is served from the local pool. The pool's own served floor is `K_CELL` (5 accounts, `packages/pool/src/derive.ts`); a bundle's read has
+ * cleared it already, so only a local edge is held to this, counted in followed steps because one operator's store is one account.
+ */
+export const RECOVERY_FLOOR = 5;
+/** The steps a position needs behind it before it can be called split: t782's qualifying cell is a cell topped up to 20 sessions. */
+export const POSITION_MIN_N = 20;
+/** The band of t782 plan 1.7: the leading option's share, 20 to 80 percent inclusive. A settled position (above) and a diffuse one (below) are not listed. */
+export const POSITION_BAND = { low: 0.2, high: 0.8 };
+/**
+ * The bytes a table may add to a turn's context. Eight lines of about 70 bytes: a session start or a prompt carries it every time it is sent, and a table the agent has to
+ * read past is one it stops reading. Bundle positions come first, then local ones, each by observations; the cap cuts from the end, so a local position goes before a bundle one.
+ */
+export const TABLE_CAP_BYTES = 600;
+const TOP_NEXT = 3;
+const MAX_FOLLOWED = 3;
+const isCount = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0;
+const isAction = (name) => CANONICAL_ACTIONS.some((action) => action === name);
+const byWeight = (a, b) => b.followed - a.followed || a.next.localeCompare(b.next);
+/**
+ * The recovery edges of a set of reads, by `action/errorCode`, each next step summed over its weeks. A next step that is not a canonical action (or `none`) is left out, so the
+ * names a hook shows are the closed ones whatever a store holds.
+ */
+export const recoveryEdgesOf = (reads, keep = () => true) => {
+    const grouped = new Map();
+    // The failures of one action and error class, once: every week's reads of its next steps share a week's failures, so a next step seen in fewer weeks must not get a smaller denominator.
+    // A week's failures are the sum of what followed them, so the total over every next step is that sum over all its weeks.
+    const failures = new Map();
+    for (const read of reads) {
+        if (read.family !== 'recovery')
+            continue;
+        const { action, errorCode, next } = read.slice;
+        const { followed, of } = read.value;
+        if (action === undefined || errorCode === undefined || next === undefined || !isCount(followed) || !isCount(of) || followed === 0)
+            continue;
+        const key = `${action}/${errorCode}`;
+        failures.set(key, (failures.get(key) ?? 0) + followed);
+        if (!(next === 'none' || isAction(next)))
+            continue;
+        const edges = grouped.get(key) ?? new Map();
+        grouped.set(key, edges);
+        const have = edges.get(next);
+        if (have === undefined) {
+            edges.set(next, { edge: { next, followed, of, clusters: read.clusters, readId: read.readId, day: read.asOf.day }, heaviest: followed });
+            continue;
+        }
+        have.edge.followed += followed;
+        have.edge.clusters = Math.max(have.edge.clusters, read.clusters);
+        if (followed > have.heaviest) {
+            have.heaviest = followed;
+            have.edge.readId = read.readId;
+        }
+        if (read.asOf.day !== null && (have.edge.day === null || read.asOf.day > have.edge.day))
+            have.edge.day = read.asOf.day;
+    }
+    const edges = {};
+    for (const [key, byNext] of grouped) {
+        const sorted = [...byNext.values()].map((weighted) => ({ ...weighted.edge, of: failures.get(key) ?? weighted.edge.of })).sort(byWeight);
+        if (sorted[0] !== undefined && keep(sorted[0].followed))
+            edges[key] = sorted.slice(0, MAX_FOLLOWED);
+    }
+    return edges;
+};
+/** True when a position's prefix names only canonical actions (no identity, no class): the table prints names and numbers and nothing a store wrote. */
+const closedPrefix = (prefix) => prefix.split('>').every(isAction);
+/** The positions of a set of reads where the next step is split by t782's rule: enough observations, and the leading step's share inside the band. */
+export const positionsOf = (reads) => {
+    const positions = [];
+    for (const read of reads) {
+        if (read.family !== 'next-step')
+            continue;
+        const { prefix } = read.slice;
+        const { next, topShare } = read.value;
+        if (prefix === undefined || !closedPrefix(prefix) || !isCount(topShare) || topShare < POSITION_BAND.low || topShare > POSITION_BAND.high || read.n < POSITION_MIN_N)
+            continue;
+        if (typeof next !== 'object' || next === null)
+            continue;
+        const ranked = Object.entries(next)
+            .filter(([action, times]) => isAction(action) && isCount(times))
+            .sort(([a, one], [b, two]) => two - one || a.localeCompare(b))
+            .slice(0, TOP_NEXT);
+        if (ranked.length < 2)
+            continue;
+        positions.push({ prefix, n: read.n, next: ranked, clusters: read.clusters, readId: read.readId, day: read.asOf.day });
+    }
+    return positions.sort((a, b) => b.n - a.n || a.prefix.localeCompare(b.prefix));
+};
+/**
+ * What a failure is answered with: the bundle's edges for this action and error class if it holds any (they cleared the pool's floor), else the local pool's. Silent when the top
+ * next step is a same-step retry (direction 13c), when a local edge is under `RECOVERY_FLOOR`, or when the top is that nothing followed (`ended`).
+ */
+export const recoveryDecision = (bundle, local, action, code) => {
+    const key = `${action}/${code}`;
+    const fromBundle = bundle?.recovery[key];
+    const source = fromBundle === undefined || bundle === undefined ? undefined : { edges: fromBundle, source: 'bundle', poolVersion: bundle.poolVersion };
+    const fromLocal = local?.recovery[key];
+    const chosen = source ?? (fromLocal === undefined || local === undefined ? undefined : { edges: fromLocal, source: 'local', poolVersion: local.poolVersion });
+    const top = chosen?.edges[0];
+    if (chosen === undefined || top === undefined)
+        return { kind: 'none' };
+    // A tie with another next step is not a retry-only cell, so it is served; the strict lead is what direction 13c silences.
+    const second = chosen.edges[1];
+    if (top.next === action && (second === undefined || top.followed > second.followed))
+        return { kind: 'retry' };
+    if (top.next === 'none')
+        return { kind: 'ended' };
+    if (chosen.source === 'local' && top.followed < RECOVERY_FLOOR)
+        return { kind: 'floor' };
+    return { kind: 'serve', ...chosen };
+};
+const percent = (part, whole) => `${String(Math.round((part / whole) * 100))}%`;
+/** The recovery read as text: names (closed) and numbers. */
+export const renderRecovery = (action, code, edges) => {
+    const shown = edges.filter((edge) => closedName(edge.next) !== LITERAL);
+    const total = shown[0]?.of ?? 0;
+    const lines = shown.map((edge) => `${edge.next} x${String(edge.followed)}${total > 0 ? ` (${percent(edge.followed, total)})` : ''}`);
+    const rendered = [`oars recall, counts from earlier sessions: after a failed ${action} (${code})${total > 0 ? ` in ${count(total, 'failure')}` : ''}, the next step was`, `  ${lines.join(', ')}`, `  read ${shown[0]?.readId ?? ''} (recovery)`].join('\n');
+    return { rendered, names: shown.map((edge) => edge.next) };
+};
+/** The positions table, with every position that fits under the cap and nothing when none does. */
+export const renderPositions = (positions) => {
+    const header = 'oars recall, next steps that earlier sessions split on (counts, not advice):';
+    const listed = [];
+    let used = Buffer.byteLength(header);
+    const lines = [];
+    for (const position of positions) {
+        const line = `- after ${position.prefix}: ${position.next.map(([action, times]) => `${action} ${percent(times, position.n)}`).join(', ')} (n ${String(position.n)})`;
+        const size = Buffer.byteLength(line) + 1;
+        if (used + size > TABLE_CAP_BYTES)
+            break;
+        used += size;
+        listed.push(position);
+        lines.push(line);
+    }
+    return { rendered: listed.length === 0 ? '' : [header, ...lines].join('\n'), listed, names: [...new Set(listed.flatMap((position) => position.next.map(([action]) => action)))] };
+};
+/**
+ * The key a hook index files the local pool's reads under for a session: its harness and the bucket of the version it runs (`recall-frames.ts`). A session whose version is not
+ * stated is read across every version of its harness, which is the filter that can be applied honestly.
+ */
+export const frameKeyOf = (asker) => `${asker.harness}/${asker.harnessVersion === null ? '*' : harnessBucket(asker.harnessVersion)}`;
+/** The bundle's and the local pool's positions as one list, a prefix once: the bundle's positions by observations, then the local ones it lacks by observations. */
+export const mergePositions = (bundle, local) => {
+    const byObservations = (a, b) => b.n - a.n || a.prefix.localeCompare(b.prefix);
+    const seen = new Set(bundle.map((position) => position.prefix));
+    return [...[...bundle].sort(byObservations), ...local.filter((position) => !seen.has(position.prefix)).sort(byObservations)];
+};
+/** A read as the evidence record wants it: counts and closed names only. */
+const evidenceRead = (read, setup) => ({
+    readId: read.readId,
+    family: read.family,
+    tool: read.tool,
+    keys: [],
+    n: read.n,
+    count: read.count,
+    calls: read.calls,
+    clusters: read.clusters,
+    firstDay: null,
+    lastDay: read.day,
+    harnesses: [setup.harness],
+    harnessVersions: setup.harnessVersion === null ? [] : [setup.harnessVersion],
+    models: [],
+    followed: read.followed,
+});
+/** The asker's frame, from the tail of its transcript. */
+export const frameFor = (input) => frameOfTail(input.tail, input.platform, input.at);
+/** The reads of the kept bundle for the asker's harness and version; undefined with no version stated, no bundle, or a bundle that does not verify (never an error). */
+export const bundleNext = async (storeDir, asker) => {
+    const bundle = asker.harnessVersion === null ? undefined : await sessionBundle(storeDir, { harness: asker.harness, harnessVersion: asker.harnessVersion });
+    return bundle === undefined ? undefined : { poolVersion: bundle.asOf.pool, recovery: recoveryEdgesOf(bundle.reads), positions: positionsOf(bundle.reads) };
+};
+/**
+ * A served or held read: the row is written before anything is injected, and the arm is the session's for this query against this pool. The row is the recall's exposure record
+ * (ids and counts, and the rendered text a held read would have shown); an arm that kept it back is returned so the hook injects nothing.
+ */
+export const recordRead = async (input, frame, query, armPrefix, poolVersion, rendered, names, reads) => {
+    const recall = makeRecall({
+        sid: input.sid,
+        at: input.at,
+        frame,
+        mode: 'push',
+        query,
+        poolVersion,
+        arm: armOf(input.sid, armPrefix, poolVersion),
+        reads: reads.map((read) => read.readId),
+        rendered,
+        names,
+        evidence: reads.map((read) => evidenceOf(read, frame)),
+    });
+    await appendRecall(input.storeDir, recall);
+    return recall;
+};
+/** The recovery read for one failure, as a recall row. */
+export const recoveryRecall = (input, setup, action, code, decision) => {
+    const frame = frameFor(input);
+    const { rendered, names } = renderRecovery(action, code, decision.edges);
+    const top = decision.edges[0];
+    const read = evidenceRead({ readId: top?.readId ?? '', family: 'recovery', tool: action, n: top?.followed ?? 0, count: top?.followed ?? 0, calls: top?.of ?? null, clusters: top?.clusters ?? 1, day: top?.day ?? null, followed: decision.edges.map((edge) => [edge.next, edge.followed]) }, setup);
+    return recordRead(input, frame, { form: 'question', family: 'recovery', prefix: [`${action}/${code}`] }, [`${action}/${code}`], decision.poolVersion, rendered, names, [read]);
+};
+/** The old signature line's recall: the local signature index, held to the same retry rule and floor. */
+export const signatureRecall = (input, setup, tool, sig, found, poolVersion) => {
+    const frame = frameFor(input);
+    const followed = found.followed.map(([next]) => next).join(', ');
+    const rendered = `oars recall: seen in ${String(found.sessions)} sessions; what followed: ${followed === '' ? 'nothing recorded' : followed}`;
+    const read = evidenceRead({ readId: readIdOf(sig), family: 'recovery', tool, n: found.sessions, count: found.sessions, calls: null, clusters: 1, day: null, followed: found.followed }, setup);
+    return recordRead(input, frame, { form: 'question', family: 'recovery', prefix: [readIdOf(sig)] }, [readIdOf(sig)], poolVersion, rendered, found.followed.map(([next]) => next), [read]);
+};
+/**
+ * The signature line is a same-step retry when the tool that failed is the one that most often followed, strictly: a tie with another tool is not a retry-only cell. It keeps its
+ * own floor, the index's two sessions: it states how many sessions saw the error, so a thin count is printed as thin, which a cell's share is not.
+ */
+export const isSignatureRetry = (tool, found) => {
+    const [first, second] = found.followed;
+    return first?.[0] === tool && (second === undefined || first[1] > second[1]);
+};
+/** The positions table for a session, as a recall row; undefined when no position qualifies or the table is the one `previous` already sent. */
+export const positionsRecall = (input, setup, positions, poolVersion, previous) => {
+    const { rendered, listed, names } = renderPositions(positions);
+    if (listed.length === 0 || rendered === previous)
+        return Promise.resolve(undefined);
+    const frame = frameFor(input);
+    const reads = listed.map((position) => evidenceRead({ readId: position.readId, family: 'next-step', tool: position.next[0]?.[0] ?? '', n: position.n, count: position.next[0]?.[1] ?? 0, calls: position.n, clusters: position.clusters, day: position.day, followed: position.next }, setup));
+    return recordRead(input, frame, { form: 'question', family: 'next-step', prefix: ['positions'] }, ['positions'], poolVersion, rendered, names, reads);
+};
+/** The text the session was last sent a table with, from `recalls.jsonl`; undefined when it was never sent one. */
+export const lastTable = async (storeDir, sid) => {
+    const mine = parseRecalls(await tailOf(recallsPath(storeDir))).filter((recall) => recall.mode === 'push' && recall.sid === sid && recall.query.family === 'next-step');
+    return mine.at(-1)?.answer.rendered;
+};