@manyoars/oars 0.2.0 → 0.3.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-object.d.ts

@@ -0,0 +1,137 @@
+import type { Frame } from './schema.js';
+export declare const recallsPath: (storeDir: string) => string;
+/** The share of pushes held back (spec Section 8, open parameter). */
+export declare const HOLDBACK_RATE = 0.1;
+export declare const RECALL_CLASSES: {
+    readonly A: readonly ["sid", "at", "query.text"];
+    readonly P: readonly ["id", "n", "frame", "mode", "query.form", "query.prefix", "query.entity", "query.family", "query.slice", "poolVersion", "arm", "answer", "evidence", "consequence"];
+};
+export type RecallMode = 'pull' | 'push';
+export type RecallArm = 'shown' | 'held';
+export type RecallForm = 'pattern' | 'entity' | 'question' | 'text';
+/** Which frames a read covers. Each name is held to the public vocabulary before it is shown. */
+export interface RecallSlice {
+    harnessVersion?: string;
+    model?: string;
+    tool?: string;
+    cls?: string;
+    sinceDays?: number;
+}
+export interface RecallQueryObject {
+    form: RecallForm;
+    /** What the asker's steps so far name: motif IDs, stored read IDs, or the shape and signature hashes `recall-reads.ts` computes. */
+    prefix?: string[];
+    /** A public name: package, tool, MCP server, or model. */
+    entity?: string;
+    family?: string;
+    slice?: RecallSlice;
+    /** Class A, local only. */
+    text?: string;
+}
+export interface RecallAnswer {
+    kind: 'hit' | 'miss';
+    /** Read IDs, in the order shown. */
+    reads: string[];
+    /** The size of what was injected, or of what a held recall would have injected. */
+    tokens: number;
+    /** What the asker saw, or for a held recall would have seen. It holds structured fields only (`recall-render.ts`). */
+    rendered: string;
+    /** The closed names a follow can match: canonical actions, in the order shown. */
+    names: string[];
+}
+export type DeltaAxis = 'same' | 'differs' | 'unknown';
+/** How far the evidence sits from the asker, per axis, never collapsed into a score (spec Section 3). */
+export interface RecallDelta {
+    harness: DeltaAxis;
+    /** The asker's version minus the evidence's newest, when only the last component differs; null when that does not read as a count. */
+    harnessVersions: number | null;
+    model: DeltaAxis;
+    /** How many of the evidence's models are not the asker's; null when the asker's is unknown. */
+    modelVersions: number | null;
+    platform: DeltaAxis;
+    shell: DeltaAxis;
+    stack: DeltaAxis;
+    /** No record states a tool's version yet. */
+    toolVersion: number | null;
+    ageDays: number | null;
+}
+export interface FrameRange {
+    harnesses: string[];
+    harnessVersions: string[];
+    models: string[];
+}
+export interface RecallEvidence {
+    /** A read, cell, or recall ID. Never another account's session. */
+    ref: string;
+    frameRange: FrameRange;
+    firstDay: string | null;
+    lastDay: string | null;
+    n: number;
+    clusters: number;
+    delta: RecallDelta;
+}
+/** The outcome signals of the window's prompt, held separately: no composite (spec Section 2.7). */
+export interface RecallOutcome {
+    errors: number | null;
+    verify: string | null;
+    stopped: string | null;
+    commits: number | null;
+    redo: boolean | null;
+}
+/** Derived from the capture records, never captured live. */
+export interface RecallConsequence {
+    /** The calls the window holds, by position, and why it ended. */
+    window: {
+        from: number;
+        to: number;
+        calls: number;
+        end: 'prompt' | 'calls' | 'session';
+    };
+    motifs: string[];
+    followed: boolean;
+    /** `tokens` is null when no call in the window measured any: an older capture has no step costs, and zero would read as a free window. */
+    cost: {
+        tokens: number | null;
+        durationMs: number;
+    };
+    outcome: RecallOutcome;
+}
+export interface Recall {
+    id: string;
+    /** The session the asker ran in; null for a pull made outside one, which no consequence can be read for. Class A. */
+    sid: string | null;
+    /** Class A. */
+    at: string;
+    /** The asker's position among its calls. A hook cannot know it without reading the transcript, so derive fills it from `at`. */
+    n: number | null;
+    frame: Frame | null;
+    mode: RecallMode;
+    query: RecallQueryObject;
+    /** The snapshot answered from: the deposit time of the store or index, so "older than the recall" is a comparison. */
+    poolVersion: string;
+    arm: RecallArm;
+    answer: RecallAnswer;
+    evidence: RecallEvidence[];
+    consequence?: RecallConsequence;
+}
+export interface RecallInput {
+    sid: string | null;
+    at: string;
+    frame: Frame | null;
+    mode: RecallMode;
+    query: RecallQueryObject;
+    poolVersion: string;
+    arm: RecallArm;
+    reads: readonly string[];
+    rendered: string;
+    names: readonly string[];
+    evidence: readonly RecallEvidence[];
+}
+export declare const makeRecall: (input: RecallInput) => Recall;
+/** `held` for the hash's first 32 bits under the rate. One session asking from one prefix against one pool always lands on one arm. */
+export declare const armOf: (sid: string, prefix: readonly string[], poolVersion: string, rate?: number) => RecallArm;
+/** Evidence must come from a pool older than the recall (spec Section 3): that one rule is why the commons holds no cycles. */
+export declare const evidencePredates: (recall: Recall) => boolean;
+export declare const appendRecall: (storeDir: string, recall: Recall) => Promise<void>;
+export declare const parseRecalls: (text: string) => Recall[];
+export declare const readRecalls: (storeDir: string) => Promise<Recall[]>;

package/dist/sessions/recall-object.js

@@ -0,0 +1,77 @@
+// The recall object (recall spec Section 2.7): one event in the asker's graph, with edges back to the evidence it drew on and forward to what the asker
+// did next. A pull and a push are the same object, and both land in `recalls.jsonl`, append-only, whether or not anything was injected.
+import { createHash } from 'node:crypto';
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const RECALLS_FILE = 'recalls.jsonl';
+export const recallsPath = (storeDir) => join(storeDir, RECALLS_FILE);
+/** The share of pushes held back (spec Section 8, open parameter). */
+export const HOLDBACK_RATE = 0.1;
+export const RECALL_CLASSES = {
+    A: ['sid', 'at', 'query.text'],
+    P: ['id', 'n', 'frame', 'mode', 'query.form', 'query.prefix', 'query.entity', 'query.family', 'query.slice', 'poolVersion', 'arm', 'answer', 'evidence', 'consequence'],
+};
+/** Characters per token, the rule of thumb: the size is a count for comparing arms, not a bill. */
+const CHARS_PER_TOKEN = 4;
+const hash = (parts) => createHash('sha256').update(JSON.stringify(parts)).digest('hex');
+export const makeRecall = (input) => ({
+    id: hash([input.sid, input.at, input.mode, input.query, input.poolVersion]).slice(0, 16),
+    sid: input.sid,
+    at: input.at,
+    n: null,
+    frame: input.frame,
+    mode: input.mode,
+    query: input.query,
+    poolVersion: input.poolVersion,
+    arm: input.arm,
+    answer: {
+        kind: input.reads.length === 0 ? 'miss' : 'hit',
+        reads: [...input.reads],
+        tokens: Math.ceil(input.rendered.length / CHARS_PER_TOKEN),
+        rendered: input.rendered,
+        names: [...input.names],
+    },
+    evidence: [...input.evidence],
+});
+const SCALE = 0x1_0000_0000;
+/** `held` for the hash's first 32 bits under the rate. One session asking from one prefix against one pool always lands on one arm. */
+export const armOf = (sid, prefix, poolVersion, rate = HOLDBACK_RATE) => Number.parseInt(hash([sid, prefix, poolVersion]).slice(0, 8), 16) / SCALE < rate ? 'held' : 'shown';
+/** Evidence must come from a pool older than the recall (spec Section 3): that one rule is why the commons holds no cycles. */
+export const evidencePredates = (recall) => {
+    const day = recall.at.slice(0, 10);
+    return recall.poolVersion <= recall.at && recall.evidence.every((item) => item.lastDay === null || item.lastDay <= day);
+};
+export const appendRecall = async (storeDir, recall) => {
+    await mkdir(storeDir, { recursive: true });
+    await appendFile(recallsPath(storeDir), `${JSON.stringify(recall)}\n`, { mode: 0o600 });
+};
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** The file is ours, so a line's shape is checked only as far as telling a recall from a torn or foreign line. */
+const isRecall = (value) => isRecord(value) && typeof value.id === 'string' && typeof value.at === 'string' && isRecord(value.answer) && isRecord(value.query);
+export const parseRecalls = (text) => {
+    const recalls = [];
+    for (const line of text.split('\n')) {
+        if (line === '')
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (isRecall(parsed))
+                recalls.push(parsed);
+        }
+        catch {
+            // A torn line is skipped.
+        }
+    }
+    return recalls;
+};
+export const readRecalls = async (storeDir) => {
+    let text = '';
+    try {
+        text = await readFile(recallsPath(storeDir), 'utf8');
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
+            throw error;
+    }
+    return parseRecalls(text);
+};

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

@@ -0,0 +1,19 @@
+import { type Pool } from './cells.js';
+import type { Read } from './read.js';
+import type { RecallRead } from './recall-reads.js';
+export interface CurrentPool {
+    pool: Pool;
+    reads: readonly Read[];
+}
+/** Each answer under its stored read's ID, where the pool holds one. */
+export declare const resolveReads: (reads: readonly RecallRead[], stored: readonly Read[]) => RecallRead[];
+/** The answers to a question about a family only the pool holds, best first. */
+export declare const readsOfFamily: (family: string, current: CurrentPool) => RecallRead[];
+/**
+ * What a prefix names in the pool: a stored read by its ID, or a motif by its ID. A stored read with a stand-in goes back through it, because the store's own counts answer those;
+ * `standIns` holds those hashes for the caller to match, and `reads` every other answer.
+ */
+export declare const namedByPrefix: (prefix: readonly string[], current: CurrentPool) => {
+    standIns: string[];
+    reads: RecallRead[];
+};

package/dist/sessions/recall-pool.js

@@ -0,0 +1,96 @@
+// What ties a recall's answer to the stored read of the current pool. A store-wide count answers the asker, and the read it rests on is what `lineage` can
+// walk, so each answer carries that read's ID. Without a stored read for it, an answer keeps its stand-in hash, which `lineage` reports as evidence with no further hop.
+import { bucketFields, cellIdOf, lastDayOfCell, UNKNOWN } from './cells.js';
+import { motifName } from './motif.js';
+/** The stand-in hash a stored read answers for: a recovery read's signature hash and a call-shape read's shape are the values `recall-reads.ts` computes from the store. */
+const standInOf = (read) => {
+    if (read.family === 'recovery')
+        return read.slice.sig;
+    return read.family === 'fit' ? read.slice.shape : undefined;
+};
+const keyOf = (family, standIn) => `${family}/${standIn}`;
+/** Each answer under its stored read's ID, where the pool holds one. */
+export const resolveReads = (reads, stored) => {
+    const ids = new Map(stored.flatMap((read) => {
+        const standIn = standInOf(read);
+        return standIn === undefined ? [] : [[keyOf(read.family, standIn), read.readId]];
+    }));
+    return reads.map((read) => ({ ...read, readId: ids.get(keyOf(read.family, read.readId)) ?? read.readId }));
+};
+const countIn = (value) => (typeof value === 'number' ? value : 0);
+const nextOf = (read) => {
+    const { next } = read.value;
+    if (typeof next !== 'object' || next === null)
+        return [];
+    return Object.entries(next).sort(([a, one], [b, two]) => two - one || a.localeCompare(b));
+};
+const FOLLOWED = 3;
+const presentOf = (values) => [...new Set(values.filter((value) => value !== UNKNOWN && value !== ''))].sort();
+/** A stored read as an answer. Its evidence's frames and days come from the cells it cites; a daily session count cannot be summed, so `n` is the floor those cells prove. */
+const answerOfStored = (read, cells) => {
+    const cited = read.inputs.flatMap((input) => cells.get(input) ?? []);
+    const frames = cited.map((cell) => bucketFields(cell.frameBucket));
+    // `firstDay` over a week cell is that week's Monday: the earliest day the evidence can hold, which the evidence may not have touched.
+    const days = presentOf(cited.map((cell) => cell.day));
+    // A week cell may hold any of its seven days, so the last day the evidence can hold is the week's end, but never past the pool the read was made from: a read cannot hold a day its pool
+    // had not seen, and a recall made on the Wednesday of its evidence's week must not find that evidence dated after itself.
+    const lastDays = presentOf(cited.map((cell) => (read.asOf.day !== null && lastDayOfCell(cell) > read.asOf.day ? read.asOf.day : lastDayOfCell(cell))));
+    const isRate = read.family === 'fit';
+    const failed = countIn(read.value.failed);
+    return {
+        readId: read.readId,
+        family: read.family,
+        tool: read.slice.motif ?? read.slice.prefix ?? read.slice.class ?? read.slice.action ?? read.family,
+        keys: [],
+        n: cited.reduce((highest, cell) => Math.max(highest, cell.sessions), 0),
+        count: isRate ? failed : read.n,
+        calls: isRate ? failed + countIn(read.value.ok) : null,
+        clusters: read.clusters,
+        firstDay: days[0] ?? null,
+        lastDay: lastDays[lastDays.length - 1] ?? null,
+        harnesses: presentOf(frames.map((frame) => frame.harness)),
+        harnessVersions: [],
+        models: presentOf(frames.map((frame) => frame.model)),
+        followed: nextOf(read).slice(0, FOLLOWED),
+    };
+};
+/** A pull can answer an agent, and an experimental read goes to no agent (`docs/sessions-store.md`), so a recall never serves one; `oars sessions read` still prints it. */
+const isServed = (read) => read.value.label !== 'experimental';
+const cellsOf = (pool) => new Map(pool.cells.map((cell) => [cellIdOf(cell), cell]));
+const ranked = (reads) => [...reads].sort((a, b) => b.n - a.n || b.count - a.count || a.readId.localeCompare(b.readId));
+/** The answers to a question about a family only the pool holds, best first. */
+export const readsOfFamily = (family, current) => {
+    const cells = cellsOf(current.pool);
+    return ranked(current.reads.filter((read) => read.family === family && isServed(read)).map((read) => answerOfStored(read, cells)));
+};
+const ofMotif = (motif, reads) => {
+    const name = motifName(motif);
+    return reads.filter((read) => (read.family === 'fit' && read.slice.motif === name && read.slice.level === motif.level) || (read.family === 'next-step' && motif.level === 'shape' && read.slice.prefix === name));
+};
+/**
+ * What a prefix names in the pool: a stored read by its ID, or a motif by its ID. A stored read with a stand-in goes back through it, because the store's own counts answer those;
+ * `standIns` holds those hashes for the caller to match, and `reads` every other answer.
+ */
+export const namedByPrefix = (prefix, current) => {
+    const named = new Set();
+    for (const id of prefix) {
+        for (const read of current.reads)
+            if (read.readId === id && isServed(read))
+                named.add(read);
+        const motif = current.pool.motifs.get(id);
+        if (motif !== undefined)
+            for (const read of ofMotif(motif, current.reads))
+                named.add(read);
+    }
+    const cells = cellsOf(current.pool);
+    const standIns = [];
+    const reads = [];
+    for (const read of named) {
+        const standIn = standInOf(read);
+        if (standIn === undefined)
+            reads.push(answerOfStored(read, cells));
+        else
+            standIns.push(standIn);
+    }
+    return { standIns, reads: ranked(reads) };
+};

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

@@ -0,0 +1,26 @@
+import type { HookIndex } from './hook-index.js';
+import { type Recall } from './recall-object.js';
+import { type Frame } from './schema.js';
+/** A file's last bytes; a first line this cuts in two fails to parse and is skipped by whoever reads it. */
+export declare const tailOf: (file: string) => Promise<string>;
+/**
+ * The asker's frame, as far as a transcript's tail states it. The stack and the shell need the whole transcript, which a hook has no time to read, so they stay
+ * unknown here; `delta` says unknown for them, and derive reads the session's real frame.
+ */
+export declare const frameOfTail: (tail: string, platform: string, at: string) => Frame;
+export interface PushInput {
+    storeDir: string;
+    sid: string;
+    tool: string;
+    /** The call's input key names, never their values. */
+    keys: readonly string[];
+    transcript: string | undefined;
+    platform: string;
+    at: string;
+    index: HookIndex;
+}
+/**
+ * The recall a call about to run gets, written before anything is injected: an exposure with no record is the one failure the arms cannot survive. Undefined when no read
+ * covers the shape, which keeps no row (no one asked, so it is not a want, and it would be a row per call), and when this session has already been told about this shape.
+ */
+export declare const pushRecall: (input: PushInput) => Promise<Recall | undefined>;

package/dist/sessions/recall-push.js

@@ -0,0 +1,95 @@
+// The push: a pre-tool hook's recall (spec Section 2.7). The harness tells the hook only the call it is about to run, so the query is the call's shape, and a shape
+// with a read over the floors and `PUSH_MIN_LIFT` is the one thing that can arm a push. A held push stores what it would have shown and injects nothing, which is the unexposed baseline.
+import { open } from 'node:fs/promises';
+import { closedFrame, closedStack, utcDay } from './frame.js';
+import { appendRecall, armOf, makeRecall, parseRecalls, recallsPath } from './recall-object.js';
+import { toolShapeId } from './recall-reads.js';
+import { evidenceOf, renderAnswer } from './recall-render.js';
+import { harnessOf } from './schema.js';
+/** How far back a hook looks in a growing file: enough for the session's latest lines, and a bound on what a hook on every call can cost. */
+const TAIL_BYTES = 64 * 1024;
+const isMissing = (error) => error instanceof Error && 'code' in error && error.code === 'ENOENT';
+const openIfThere = async (file) => {
+    try {
+        return await open(file, 'r');
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+};
+/** A file's last bytes; a first line this cuts in two fails to parse and is skipped by whoever reads it. */
+export const tailOf = async (file) => {
+    const handle = await openIfThere(file);
+    if (handle === undefined)
+        return '';
+    try {
+        const { size } = await handle.stat();
+        const length = Math.min(size, TAIL_BYTES);
+        const buffer = Buffer.alloc(length);
+        await handle.read(buffer, 0, length, size - length);
+        return buffer.toString('utf8');
+    }
+    finally {
+        await handle.close();
+    }
+};
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const text = (value) => (typeof value === 'string' && value !== '' ? value : null);
+const parsedLines = (tail) => tail.split('\n').flatMap((line) => {
+    try {
+        const parsed = JSON.parse(line);
+        return isRecord(parsed) ? [parsed] : [];
+    }
+    catch {
+        return [];
+    }
+});
+/**
+ * The asker's frame, as far as a transcript's tail states it. The stack and the shell need the whole transcript, which a hook has no time to read, so they stay
+ * unknown here; `delta` says unknown for them, and derive reads the session's real frame.
+ */
+export const frameOfTail = (tail, platform, at) => {
+    let harnessVersion = null;
+    let model = null;
+    let effort = null;
+    // Oldest first, so the newest line that states a field wins.
+    for (const line of parsedLines(tail)) {
+        harnessVersion = text(line.version) ?? harnessVersion;
+        effort = text(line.effort) ?? effort;
+        if (isRecord(line.message))
+            model = text(line.message.model) ?? model;
+    }
+    return closedFrame({ harness: harnessOf({}), harnessVersion, model, effort, day: utcDay(at), platform, shell: null, stack: closedStack({ languages: [], frameworks: [], size: null }) });
+};
+/**
+ * The recall a call about to run gets, written before anything is injected: an exposure with no record is the one failure the arms cannot survive. Undefined when no read
+ * covers the shape, which keeps no row (no one asked, so it is not a want, and it would be a row per call), and when this session has already been told about this shape.
+ */
+export const pushRecall = async (input) => {
+    const shape = toolShapeId(input.tool, input.keys);
+    const read = input.index.fit?.[shape];
+    if (read === undefined)
+        return undefined;
+    const earlier = parseRecalls(await tailOf(recallsPath(input.storeDir)));
+    if (earlier.some((recall) => recall.mode === 'push' && recall.sid === input.sid && recall.query.prefix?.[0] === shape))
+        return undefined;
+    const frame = frameOfTail(input.transcript === undefined ? '' : await tailOf(input.transcript), input.platform, input.at);
+    const { rendered, names } = renderAnswer([read], frame);
+    const recall = makeRecall({
+        sid: input.sid,
+        at: input.at,
+        frame,
+        mode: 'push',
+        query: { form: 'pattern', prefix: [shape] },
+        poolVersion: input.index.at,
+        arm: armOf(input.sid, [shape], input.index.at),
+        reads: [read.readId],
+        rendered,
+        names,
+        evidence: [evidenceOf(read, frame)],
+    });
+    await appendRecall(input.storeDir, recall);
+    return recall;
+};