@manyoars/oars 0.2.0 → 0.4.0

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

@@ -0,0 +1,139 @@
+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;
+    /** The UTF-8 bytes of `rendered`: what a hook injected, or would have. Absent on rows written before it was recorded. */
+    bytes?: 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,78 @@
+// 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),
+        bytes: Buffer.byteLength(input.rendered),
+        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';
+import { tailOf } from './transcript-tail.js';
+export { tailOf };
+/**
+ * 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,47 @@
+// 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 { 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';
+import { statedOf, tailOf } from './transcript-tail.js';
+export { tailOf };
+/**
+ * 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) => {
+    const { harnessVersion, model, effort } = statedOf(tail);
+    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;
+};

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

@@ -0,0 +1,124 @@
+import { type CanonicalAction } from './actions.js';
+import { type RecallQuery, type RecallResult } from './query.js';
+import { type Family } from './read.js';
+import { type CurrentPool } from './recall-pool.js';
+import { type Recall, type RecallForm, type RecallSlice } from './recall-object.js';
+import { type ErrorObservation, type Frame, type ToolObservation } from './schema.js';
+import type { Store } from './store.js';
+export type ReadFamily = Family | 'entity';
+export interface RecallRead {
+    readId: string;
+    family: ReadFamily;
+    /** The native tool name, as recorded. A renderer holds it to the public vocabulary, because a name can carry text. */
+    tool: string;
+    /** The call's input key names; empty for a read not about a call shape. */
+    keys: string[];
+    /** Sessions. */
+    n: number;
+    /** Errors, for recovery and fit; calls, for entity. */
+    count: number;
+    /** All calls of the shape, the denominator of `count`; null when the read has none. */
+    calls: number | null;
+    /** One operator's store is one cluster (spec Section 6). */
+    clusters: number;
+    firstDay: string | null;
+    lastDay: string | null;
+    harnesses: string[];
+    harnessVersions: string[];
+    models: string[];
+    /** Native tool names that came next, most common first. */
+    followed: Array<[string, number]>;
+}
+/** A signature's stand-in: the hash a stored recovery read holds as `slice.sig`. */
+export declare const readIdOf: (sig: string) => string;
+/** The ID of a call's shape: its tool and input key names, nothing the caller typed as a value. */
+export declare const toolShapeId: (tool: string, keys: readonly string[]) => string;
+export declare const recoveryReads: (store: Store, keep?: (error: ErrorObservation) => boolean) => RecallRead[];
+/** The main-line calls of each session, one row per call, in call order. */
+export declare const callsBySession: (store: Store) => Map<string, ToolObservation[]>;
+export interface FitFloors {
+    minFailedSessions: number;
+    minFailedShare: number;
+    minCalls: number;
+}
+/**
+ * The floors a call shape needs before it is pushed. On the operator's store (6,264 sessions, 361,914 calls) they keep 14 shapes, among them the wrong-input
+ * calls that always fail (`Monitor` with `query`, `Read` with `path`), and leave Bash, whose failures do not depend on its shape. Open parameters.
+ */
+export declare const FIT_FLOORS: FitFloors;
+/**
+ * The floors the pre-tool push holds a shape to (t926). The pre-tool hook fires after the call is decided, so a push is a warning or nothing: a shape that fails less than half
+ * its calls is a base rate (the two broad shell shapes, `Bash` and `PowerShell` with a command, fail about a third of theirs whatever the command) and warning on it tells the
+ * agent nothing it can act on. A shape that fails at least half its calls is a defect of the call itself (`Monitor` with `query`, `Read` with `path`). Pulls and the pool keep
+ * `FIT_FLOORS`: a base rate is still a fact to read on request.
+ */
+export declare const PUSH_FLOORS: FitFloors;
+/** `keep` narrows which calls are tallied, not what can come next: the call after a kept one is what followed it, wherever the slice ends. */
+export declare const fitReads: (store: Store, floors?: FitFloors, keep?: (call: ToolObservation) => boolean) => RecallRead[];
+/** The action of a tool under the first of its harnesses whose table lists it, else under the first harness (the default one when a read names none). */
+export declare const actionOfShape: (tool: string, harnesses: readonly string[]) => CanonicalAction;
+/**
+ * What a push must beat: a shape is pushed only when its failure share is at least this many times the share of all calls of its action. The floors above keep
+ * a shape that fails often; this keeps one that fails more often than its action does, and guards a store whose base rate is high. On the replay of 2026-11-02 it kept
+ * 79 of 79 pushes, at 4.5x and 8.6x their action's share: a real signal, not a defect. Open parameter, like the floors.
+ */
+export declare const PUSH_MIN_LIFT = 2;
+/**
+ * The reads whose shape fails at `lift` times the share of its whole action or more, where the action's share counts every call of every shape of it, those under the floors too.
+ * A tool no table lists is the action `other` (or `mcp.call`), so it is held to that action's share like any other and can enter the index and fire. Compared in integers, so a tie is exact.
+ */
+export declare const aboveBaseRate: (store: Store, reads: readonly RecallRead[], lift?: number) => RecallRead[];
+/** The snapshot a store answers from: its latest deposit. A deposit time compares with a recall's `at`, which is what "older than the recall" needs. */
+export declare const poolVersionOf: (store: Store) => string;
+export interface ClosedQuery {
+    form: RecallForm;
+    prefix?: readonly string[];
+    entity?: string;
+    family?: string;
+    slice?: RecallSlice;
+    text?: string;
+}
+export type PullInput = ClosedQuery | RecallQuery;
+/** The closed form a command line asks for; undefined when it names none, and only `recall()`'s inputs are left. */
+export declare const closedQueryOf: (options: {
+    pattern: readonly string[];
+    entity?: string | undefined;
+    family?: string | undefined;
+    text?: string | undefined;
+    cls?: string | undefined;
+    sinceDays?: number | undefined;
+}) => ClosedQuery | undefined;
+/** The reads a query's form asks for, best first, over the local store: an empty list is a miss, which a recall keeps. */
+export declare const answerQuery: (store: Store, input: ClosedQuery, now: number, current?: CurrentPool) => RecallRead[];
+/** The families a question can answer. `lead-lag` is experimental, so it stays with `oars sessions read`. */
+export declare const RECALL_FAMILIES: readonly Family[];
+/**
+ * Why this pull cannot be asked; undefined when it can. Only `recovery` and `fit` count their answers from the store's own rows, so any other closed form or family cannot apply a
+ * slice, and answering them anyway would state counts the slice did not narrow. The text names a form or a family that has passed `isFamily`, so it holds nothing an asker typed.
+ */
+export declare const pullRefusal: (input: PullInput) => string | undefined;
+/** The forms a pull can name, in the order a refusal lists them. `error` with `path` is one form: the signature lookup. */
+export declare const FORM_NAMES: readonly ["prefix", "entity", "family", "text", "error or path"];
+/**
+ * Why a pull naming several forms cannot be asked; undefined when it names at most one. Answering the first form and dropping the rest would state counts for a question the asker did
+ * not put, and the rendered answer names no signature to show it. The text lists fixed form names, so it holds nothing an asker typed.
+ */
+export declare const formsRefusal: (named: readonly (typeof FORM_NAMES)[number][]) => string | undefined;
+export interface PullContext {
+    /** The session asking; null when the pull came from outside one, which is every pull until the MCP path can name it. */
+    sid: string | null;
+    now: number;
+    /** The asker's frame, when the caller knows it; otherwise `sid` may name a stored session, whose frame stands in. */
+    frame: Frame | null;
+    redactDomains?: readonly string[];
+    /** The pool an answer's stored read comes from; without one, an answer keeps its stand-in hash. */
+    current?: CurrentPool | undefined;
+}
+export interface PullResult {
+    recall: Recall;
+    reads: RecallRead[];
+    /** What `recall()` found, when the pull came through its `error`, `path`, or `cls` inputs. */
+    legacy?: RecallResult;
+}
+/** A pull always answers (spec 2.7): the holdback runs on pushes alone. */
+export declare const pull: (store: Store, input: PullInput, context: PullContext) => PullResult;