@manyoars/oars 0.3.0 → 0.4.1

package/dist/sessions/public-vocabulary.d.ts

@@ -23,8 +23,6 @@ export declare const PUBLIC_PROGRAMS: ReadonlySet<string>;
 export declare const PUBLIC_SUBCOMMANDS: ReadonlyMap<string, ReadonlySet<string>>;
 /** Flag names of common public programs. A flag name on another program can be a private script's, so an unlisted name reads as the literal. */
 export declare const PUBLIC_FLAGS: ReadonlySet<string>;
-/** Hosts that say nothing about who asked. Matched whole: `acme.github.io` names a customer even though `github.io` is public. */
-export declare const PUBLIC_HOSTS: ReadonlySet<string>;
 /** MCP servers published for anyone to install. A server someone named themselves can name their company, so it reads as the literal. */
 export declare const PUBLIC_MCP_SERVERS: ReadonlySet<string>;
 /**
@@ -68,6 +66,7 @@ export declare const CUSTOM_AGENT = "custom";
 export declare const projectedAgentType: (agentType: string) => string;
 /**
  * The input keys each built-in tool's published schema lists, by the tool's name. Curated from the harness's tool reference. A key outside the tool's list, and every
- * key of an MCP tool (no pinned registry lists their schemas), is counted and never named (spec Section 1.3).
+ * key of an MCP tool (no pinned registry lists their schemas), is counted and never named (spec Section 1.3). That is the local projection; the wire (t870) sends the names that pass
+ * the name gate and counts the rest in `keysDropped`.
  */
 export declare const TOOL_INPUT_KEYS: ReadonlyMap<string, ReadonlySet<string>>;

package/dist/sessions/public-vocabulary.js

@@ -187,14 +187,6 @@ export const PUBLIC_FLAGS = words(`
   -NoNewline -Property -Seconds -SimpleMatch -Skip -TotalCount -Unique -Value -Wait
   -Command -Depth -ErrorAction -ExecutionPolicy -Filter -Force -Include -LiteralPath -NoLogo -NoProfile -NonInteractive -Path -Pattern -Raw -Recurse -Tail
 `);
-/** Hosts that say nothing about who asked. Matched whole: `acme.github.io` names a customer even though `github.io` is public. */
-export const PUBLIC_HOSTS = words(`
-  github.com raw.githubusercontent.com gist.github.com docs.github.com api.github.com gitlab.com bitbucket.org stackoverflow.com superuser.com serverfault.com
-  en.wikipedia.org developer.mozilla.org npmjs.com www.npmjs.com registry.npmjs.org pypi.org docs.python.org crates.io docs.rs pkg.go.dev go.dev rubygems.org
-  docs.oracle.com spring.io docs.spring.io maven.apache.org kubernetes.io docs.docker.com hub.docker.com nodejs.org react.dev vite.dev vitejs.dev typescriptlang.org
-  www.typescriptlang.org docs.astro.build developers.cloudflare.com docs.stripe.com stripe.com docs.anthropic.com docs.claude.com code.claude.com learn.microsoft.com
-  docs.aws.amazon.com cloud.google.com platform.openai.com arxiv.org medium.com dev.to news.ycombinator.com reddit.com www.reddit.com youtube.com www.youtube.com
-`);
 /** MCP servers published for anyone to install. A server someone named themselves can name their company, so it reads as the literal. */
 export const PUBLIC_MCP_SERVERS = words(`
   claude-in-chrome playwright puppeteer github gitlab filesystem fetch memory sequential-thinking context7 sentry
@@ -272,7 +264,8 @@ export const CUSTOM_AGENT = 'custom';
 export const projectedAgentType = (agentType) => ([...HARNESS_AGENT_TYPES.values()].some((types) => types.has(agentType)) ? agentType : CUSTOM_AGENT);
 /**
  * The input keys each built-in tool's published schema lists, by the tool's name. Curated from the harness's tool reference. A key outside the tool's list, and every
- * key of an MCP tool (no pinned registry lists their schemas), is counted and never named (spec Section 1.3).
+ * key of an MCP tool (no pinned registry lists their schemas), is counted and never named (spec Section 1.3). That is the local projection; the wire (t870) sends the names that pass
+ * the name gate and counts the rest in `keysDropped`.
  */
 export const TOOL_INPUT_KEYS = new Map(Object.entries({
     Agent: 'description prompt subagent_type model run_in_background',

package/dist/sessions/query.d.ts

@@ -37,13 +37,23 @@ export interface BooksShare {
     of: number;
     share: number | null;
 }
-export interface BooksRow {
-    key: string;
-    prompts: number;
+/** The usage columns of a row. Each sums only the prompts that recorded the category, and is null when none did: absent, never a measured 0. */
+export declare const BOOKS_USAGE_FIELDS: readonly ["cacheRead", "cacheWrite", "output", "thinking"];
+export interface BooksUsageCoverage {
     cacheRead: number;
     cacheWrite: number;
     output: number;
     thinking: number;
+}
+export interface BooksRow {
+    key: string;
+    prompts: number;
+    cacheRead: number | null;
+    cacheWrite: number | null;
+    output: number | null;
+    thinking: number | null;
+    /** How many of `prompts` recorded each usage category; below `prompts` the column is a partial sum. */
+    usageRecorded: BooksUsageCoverage;
     wallSec: number;
     turns: number;
     errors: number;
@@ -78,8 +88,10 @@ export interface Signal {
     recurringPer100: number | null;
     /** Distinct signatures among those recurring errors in the window. */
     recurringSignatures: number | null;
-    /** Mean cache-write tokens of a session in the window. */
+    /** Mean cache-write tokens of the window's sessions that recorded them; null when none did. */
     cacheWritePerSession: number | null;
+    /** How many of `sessions` recorded cache-write tokens, the sessions `cacheWritePerSession` is a mean over. */
+    cacheWriteSessions: number;
     /** MCP recall calls made during the window, per session. */
     recallPerSession: number | null;
     /** Hook lookups (SessionStart injection and PostToolUse recall) made in the window's sessions, per session. */

package/dist/sessions/query.js

@@ -3,7 +3,7 @@ import { firstCopies } from './derive.js';
 import { errorKey } from './extract.js';
 import { makeRedactor } from './redact.js';
 import { SOURCES } from './sources.js';
-import { harnessOf } from './schema.js';
+import { harnessOf, observesUsage } from './schema.js';
 import { signatureRecord } from './store.js';
 const DAY_MS = 86_400_000;
 const sinceCutoff = (now, days) => (days === undefined ? undefined : new Date(now - days * DAY_MS).toISOString());
@@ -71,6 +71,8 @@ export const formatRecall = (result) => {
 };
 /** Below this many in its denominator a share is noise, so a cell has none and prints as too few. The counts stay in `--json`. */
 export const BOOKS_MIN_PROMPTS = 30;
+/** The usage columns of a row. Each sums only the prompts that recorded the category, and is null when none did: absent, never a measured 0. */
+export const BOOKS_USAGE_FIELDS = ['cacheRead', 'cacheWrite', 'output', 'thinking'];
 /** Each subagent's tokens, keyed by the parent prompt that spawned it (`<session>#<index>`). */
 const delegatedByPrompt = (store) => {
     const promptOf = new Map();
@@ -117,6 +119,9 @@ const callsByPrompt = (store) => {
     }
     return calls;
 };
+const recordedBy = (list, field) => list.filter((prompt) => observesUsage(prompt, field)).length;
+/** The sum of one usage category over the prompts that recorded it, or null when none did. */
+const usageSum = (list, field) => recordedBy(list, field) === 0 ? null : list.reduce((total, prompt) => total + (observesUsage(prompt, field) ? prompt.usage[field] : 0), 0);
 export const books = (store, by, now, sinceDays, survival = new Map()) => {
     const cutoff = sinceCutoff(now, sinceDays);
     const groups = new Map();
@@ -152,10 +157,11 @@ export const books = (store, by, now, sinceDays, survival = new Map()) => {
         return {
             key,
             prompts: list.length,
-            cacheRead: sum(list, (prompt) => prompt.usage.cacheRead),
-            cacheWrite: sum(list, (prompt) => prompt.usage.cacheWrite),
-            output: sum(list, (prompt) => prompt.usage.output),
-            thinking: sum(list, (prompt) => prompt.usage.thinking),
+            cacheRead: usageSum(list, 'cacheRead'),
+            cacheWrite: usageSum(list, 'cacheWrite'),
+            output: usageSum(list, 'output'),
+            thinking: usageSum(list, 'thinking'),
+            usageRecorded: { cacheRead: recordedBy(list, 'cacheRead'), cacheWrite: recordedBy(list, 'cacheWrite'), output: recordedBy(list, 'output'), thinking: recordedBy(list, 'thinking') },
             wallSec: Math.round(sum(list, (prompt) => prompt.wallSec ?? 0)),
             turns: sum(list, (prompt) => prompt.turns),
             errors: sum(list, (prompt) => prompt.errors),
@@ -174,14 +180,18 @@ export const books = (store, by, now, sinceDays, survival = new Map()) => {
 /** The closing line of `books` text: what the columns can and cannot be read as. */
 export const BOOKS_CAVEAT = "These are associations in one operator's logs, not measured lift.";
 const shareCell = (cell) => (cell.share === null ? 'too few' : `${String(Math.round(cell.share * 100))}%`);
+const USAGE_LABELS = { cacheRead: 'cache read', cacheWrite: 'cache write', output: 'output', thinking: 'thinking' };
 export const formatBooks = (rows, by) => {
     if (rows.length === 0)
         return by === 'pull' ? 'No pulls in the store.' : 'No prompts in the store.';
     // A pull name, unlike a class, has no length it stays under.
     const width = Math.max(14, ...rows.map((row) => row.key.length));
+    const usage = (row, field) => (row[field] === null ? 'n/a' : String(row[field]));
     const header = `${by.padEnd(width)} ${'prompts'.padStart(8)} ${'cache read'.padStart(14)} ${'cache write'.padStart(13)} ${'output'.padStart(11)} ${'thinking'.padStart(10)} ${'wall s'.padStart(9)} ${'turns'.padStart(7)} ${'errors'.padStart(7)} ${'verify'.padStart(7)} ${'delegated'.padStart(13)} ${'passed'.padStart(8)} ${'stop'.padStart(8)} ${'redo'.padStart(8)} ${'commits'.padStart(8)} ${'settled'.padStart(8)} ${'survived'.padStart(8)}`;
-    const lines = rows.map((row) => `${row.key.padEnd(width)} ${String(row.prompts).padStart(8)} ${String(row.cacheRead).padStart(14)} ${String(row.cacheWrite).padStart(13)} ${String(row.output).padStart(11)} ${String(row.thinking).padStart(10)} ${String(row.wallSec).padStart(9)} ${String(row.turns).padStart(7)} ${String(row.errors).padStart(7)} ${(row.verifyAfterEdit === null ? '-' : `${String(Math.round(row.verifyAfterEdit * 100))}%`).padStart(7)} ${String(row.delegated).padStart(13)} ${shareCell(row.verifyPassed).padStart(8)} ${shareCell(row.stopped).padStart(8)} ${shareCell(row.redone).padStart(8)} ${String(row.commits).padStart(8)} ${String(row.settled).padStart(8)} ${shareCell(row.survived).padStart(8)}`);
-    return [header, ...lines].join('\n');
+    const lines = rows.map((row) => `${row.key.padEnd(width)} ${String(row.prompts).padStart(8)} ${usage(row, 'cacheRead').padStart(14)} ${usage(row, 'cacheWrite').padStart(13)} ${usage(row, 'output').padStart(11)} ${usage(row, 'thinking').padStart(10)} ${String(row.wallSec).padStart(9)} ${String(row.turns).padStart(7)} ${String(row.errors).padStart(7)} ${(row.verifyAfterEdit === null ? '-' : `${String(Math.round(row.verifyAfterEdit * 100))}%`).padStart(7)} ${String(row.delegated).padStart(13)} ${shareCell(row.verifyPassed).padStart(8)} ${shareCell(row.stopped).padStart(8)} ${shareCell(row.redone).padStart(8)} ${String(row.commits).padStart(8)} ${String(row.settled).padStart(8)} ${shareCell(row.survived).padStart(8)}`);
+    // A column some prompts did not record is a partial sum: say how many did in a line under the table (a column no prompt recorded prints n/a and needs no line), so the table's columns stay aligned.
+    const coverage = rows.flatMap((row) => BOOKS_USAGE_FIELDS.filter((field) => row.usageRecorded[field] > 0 && row.usageRecorded[field] < row.prompts).map((field) => `${row.key} ${USAGE_LABELS[field]}: ${String(row.usageRecorded[field])} of ${String(row.prompts)} prompts recorded`));
+    return [header, ...lines, ...coverage].join('\n');
 };
 const order = (a, b) => (a.tsFirst ?? '').localeCompare(b.tsFirst ?? '') || a.session.localeCompare(b.session);
 /**
@@ -200,7 +210,7 @@ export const measure = (store, calls, hookCalls, window, since) => {
     }
     const signal = (slice) => {
         if (slice.length === 0)
-            return { sessions: 0, cursorSessions: 0, recurringPer100: null, recurringSignatures: null, cacheWritePerSession: null, recallPerSession: null, hookRecallPerSession: null, hookHitsPerSession: null, hookDepositsPerSession: null };
+            return { sessions: 0, cursorSessions: 0, recurringPer100: null, recurringSignatures: null, cacheWritePerSession: null, cacheWriteSessions: 0, recallPerSession: null, hookRecallPerSession: null, hookHitsPerSession: null, hookDepositsPerSession: null };
         const names = new Set(slice.map((session) => session.session));
         const recurringErrors = store.errors.filter((error) => names.has(error.session) && (index.get(error.session) ?? 0) > (firstSeen.get(error.sig) ?? 0));
         const recurring = recurringErrors.length;
@@ -208,6 +218,8 @@ export const measure = (store, calls, hookCalls, window, since) => {
         const to = slice.map((session) => session.tsLast).filter((ts) => ts !== null).sort().reverse()[0];
         const inWindow = from === undefined || to === undefined ? 0 : calls.filter((call) => call.at >= from && call.at <= to).length;
         const round = (value) => Math.round(value * 100) / 100;
+        // A session that never recorded cache writes holds a placeholder zero there, which would pull the mean down.
+        const recorded = slice.filter((session) => observesUsage(session, 'cacheWrite'));
         const lookups = hookCalls.filter((call) => call.session !== null && names.has(call.session) && (call.event === 'session-start' || call.event === 'post-tool'));
         return {
             sessions: slice.length,
@@ -215,7 +227,8 @@ export const measure = (store, calls, hookCalls, window, since) => {
             otherSessions: Object.fromEntries(SOURCES.filter((source) => source.harness !== 'cursor').map((source) => [source.harness, slice.filter((session) => harnessOf(session) === source.harness).length])),
             recurringPer100: round((recurring * 100) / slice.length),
             recurringSignatures: new Set(recurringErrors.map((error) => error.sig)).size,
-            cacheWritePerSession: Math.round(slice.reduce((total, session) => total + session.usage.cacheWrite, 0) / slice.length),
+            cacheWritePerSession: recorded.length === 0 ? null : Math.round(recorded.reduce((total, session) => total + session.usage.cacheWrite, 0) / recorded.length),
+            cacheWriteSessions: recorded.length,
             recallPerSession: round(inWindow / slice.length),
             hookRecallPerSession: round(lookups.length / slice.length),
             hookHitsPerSession: round(lookups.filter((call) => call.hit).length / slice.length),
@@ -229,7 +242,14 @@ export const measure = (store, calls, hookCalls, window, since) => {
 };
 export const formatMeasure = (result) => {
     const cell = (value) => (value === null ? '-' : String(value));
+    const cacheWrite = (signal) => {
+        if (signal.cacheWritePerSession === null)
+            return signal.sessions === 0 ? '-' : 'n/a';
+        return String(signal.cacheWritePerSession);
+    };
     const row = (label, pick) => `${label.padEnd(36)} ${cell(pick(result.last)).padStart(12)} ${cell(pick(result.before)).padStart(12)}`;
+    // A mean over only some of a window's sessions says so on its own line under the table, as `books` does, so a five-digit mean cannot push the `before` column out of line.
+    const coverage = ['last', 'before'].filter((name) => result[name].cacheWriteSessions > 0 && result[name].cacheWriteSessions < result[name].sessions).map((name) => `cache-write tokens per session, ${name}: ${String(result[name].cacheWriteSessions)} of ${String(result[name].sessions)} sessions recorded`);
     return [
         `${(result.since === null ? `G1 signals, last ${String(result.window)} sessions and the ${String(result.window)} before` : `G1 signals, ${String(result.window)} sessions from ${result.since} and the ${String(result.window)} before`).padEnd(36)} ${(result.since === null ? 'last' : 'from').padStart(12)} ${'before'.padStart(12)}`,
         row('sessions in the window', (signal) => signal.sessions),
@@ -237,10 +257,12 @@ export const formatMeasure = (result) => {
         ...SOURCES.filter((source) => source.harness !== 'cursor' && ((result.last.otherSessions?.[source.harness] ?? 0) > 0 || (result.before.otherSessions?.[source.harness] ?? 0) > 0)).map((source) => row(`  of which ${source.label}`, (signal) => signal.otherSessions?.[source.harness] ?? 0)),
         row('recurring errors per 100 sessions', (signal) => signal.recurringPer100),
         row('distinct recurring signatures', (signal) => signal.recurringSignatures),
-        row('cache-write tokens per session', (signal) => signal.cacheWritePerSession),
+        // `-` is an empty window; `n/a` is sessions in it that never recorded cache writes; a partial mean is named in a line under the table.
+        `${'cache-write tokens per session'.padEnd(36)} ${cacheWrite(result.last).padStart(12)} ${cacheWrite(result.before).padStart(12)}`,
         row('recall calls per session', (signal) => signal.recallPerSession),
         row('hook recall calls per session', (signal) => signal.hookRecallPerSession),
         row('hook hits per session', (signal) => signal.hookHitsPerSession),
         row('hook deposits per session', (signal) => signal.hookDepositsPerSession),
+        ...coverage,
     ].join('\n');
 };

package/dist/sessions/read-cost.js

@@ -1,6 +1,6 @@
 // Cost (rank 3): tokens and wall time per prompt, by prompt class, model, and ISO week. Confounders: class drift, subagent work outside the prompt's own usage, and
 // task size, which nothing here can see. Tokens are plain counts, not priced. A prompt with no wall time adds no seconds and stays in the denominator, so seconds per prompt understates.
-import { bucketFields, EFFORT_CLASS, UNKNOWN } from './cells.js';
+import { bucketFields, isPromptClass, UNKNOWN } from './cells.js';
 import { motifName } from './motif.js';
 import { body, atGrain, groupBy, rate, settled, total } from './read-support.js';
 const DAY_MS = 86_400_000;
@@ -14,10 +14,19 @@ export const isoWeek = (day) => {
     return `${String(year)}-W${String(week).padStart(2, '0')}`;
 };
 const weekOf = (cell) => (cell.day === UNKNOWN ? UNKNOWN : isoWeek(cell.day));
+const promptsWithTokens = (cells) => {
+    let sum = 0;
+    for (const cell of cells) {
+        if (cell.tokenPrompts === undefined)
+            return undefined;
+        sum += cell.tokenPrompts;
+    }
+    return sum;
+};
 export const deriveCost = ({ pool }) => {
     const classed = atGrain(pool, 'week').flatMap((cell) => {
         const motif = pool.motifs.get(cell.motifId);
-        return motif?.level === 'class' && !motif.cls?.startsWith(EFFORT_CLASS) ? [{ cell, motif, model: bucketFields(cell.frameBucket).model }] : [];
+        return motif?.level === 'class' && isPromptClass(motif.cls) ? [{ cell, motif, model: bucketFields(cell.frameBucket).model }] : [];
     });
     return [...groupBy(classed, ({ cell, model }) => `${cell.motifId}/${model}/${weekOf(cell)}`).values()].flatMap((group) => {
         const [first] = group;
@@ -25,10 +34,12 @@ export const deriveCost = ({ pool }) => {
             return [];
         const cells = group.map(({ cell }) => cell);
         const prompts = total(cells, settled);
+        // Tokens hold only the prompts that recorded input, so they are divided by those prompts. A cell read back from a pool row written before coverage was stored says no count, and the group's coverage is then unknown: no figure, never a guess at full coverage.
+        const covered = promptsWithTokens(cells);
         return [
             body('cost', cells, {
                 slice: { class: motifName(first.motif), model: first.model, week: weekOf(first.cell) },
-                value: { tokensPerPrompt: Math.round(total(cells, (cell) => cell.tokens) / prompts), secondsPerPrompt: Math.round(total(cells, (cell) => cell.durationMs) / prompts / 1000), errorShare: rate(total(cells, (cell) => cell.failed), prompts) },
+                value: { tokensPerPrompt: covered === undefined || covered === 0 ? null : Math.round(total(cells, (cell) => cell.tokens ?? 0) / covered), ...(covered === undefined ? { tokenCoverage: 'unknown' } : {}), secondsPerPrompt: Math.round(total(cells, (cell) => cell.durationMs) / prompts / 1000), errorShare: rate(total(cells, (cell) => cell.failed), prompts) },
                 n: prompts,
                 interval: null,
             }),

package/dist/sessions/read-recovery-edge.d.ts

@@ -0,0 +1,2 @@
+import { type DeriveFamily } from './read-support.js';
+export declare const deriveRecoveryEdges: DeriveFamily;

package/dist/sessions/read-recovery-edge.js

@@ -0,0 +1,26 @@
+// Recovery from cells (rank 1, t868): what others did next after a failed call, by (failed action, `errorCode`, next action). One read for each edge, citing its own week cell only, so a count under the floor in
+// another edge is not lifted by this one. It states counts, never a fix: there is no fix field, `none` means nothing followed in that prompt, and an edit that followed is not that the failure was resolved.
+// Confounders: the work the failure interrupted, the user's refusals and policy denials (their own codes), and that a call's next action is one of many a prompt may take.
+import { parseRecoveryClass } from './cells.js';
+import { RECOVERY_EDGE_METHOD } from './read.js';
+import { atGrain, body, groupBy, rate, total, wilson } from './read-support.js';
+export const deriveRecoveryEdges = ({ pool }) => {
+    const edges = atGrain(pool, 'week').flatMap((cell) => {
+        const cls = pool.motifs.get(cell.motifId)?.cls;
+        const parts = cls === undefined || cls === null ? null : parseRecoveryClass(cls);
+        return parts === null ? [] : [{ cell, ...parts }];
+    });
+    // The denominator is the failures of the same action and code in the same frame bucket and week, over the cells this pool holds. A bundle's pool holds served cells only (`bundleOf`), so no `of` sums a cell under the floor and subtraction reveals none; the local read has no floor and sums what it holds.
+    const keyOf = ({ cell, code, failed }) => `${cell.frameBucket}/${cell.day}/${code}/${failed}`;
+    const failures = new Map([...groupBy(edges, keyOf)].map(([key, group]) => [key, total(group.map(({ cell }) => cell), (cell) => cell.failed)]));
+    return edges.flatMap((edge) => {
+        const { cell, code, failed, next } = edge;
+        const followed = cell.failed;
+        const of = failures.get(keyOf(edge)) ?? 0;
+        return followed === 0
+            ? []
+            : [
+                body('recovery', [cell], { slice: { action: failed, errorCode: code, next, week: cell.day }, value: { followed, of, share: rate(followed, of) }, n: followed, interval: wilson(followed, of) }, RECOVERY_EDGE_METHOD),
+            ];
+    });
+};

package/dist/sessions/read.d.ts

@@ -16,6 +16,11 @@ export declare const METHODS: {
         readonly version: string;
     };
 };
+/** The recovery family's other method (`read-recovery-edge.ts`): what others did next after a failed call, from cells alone. The pool's version hashes it beside the table. */
+export declare const RECOVERY_EDGE_METHOD: {
+    readonly name: "next-action-after-failure";
+    readonly version: "1";
+};
 /** The fit family's other method (`read-call-shape.ts`). The pool's version hashes it beside the table, for the same reason. */
 export declare const CALL_SHAPE_METHOD: {
     readonly name: "call-shape";
@@ -27,7 +32,7 @@ export type ReadBasis = 'all' | 'unexposed';
 export interface ReadSlice {
     [axis: string]: string;
 }
-/** What a read says. Closed vocabulary and numbers only: a read never holds a path, a prompt, or an error's text. */
+/** What a read says. Names and numbers only: a read never holds a path, a prompt, or an error's text. A local read can name a long-tail program or native tool name (taken from the call's segments, through the open gate, which keeps the name shape but not your redaction or exclusion terms), and a pool read can also name a long-tail server or skill, which the pool serves only at the floor. */
 export interface ReadValue {
     [metric: string]: number | string | null | {
         [name: string]: number;
@@ -64,6 +69,8 @@ export interface Read {
     interval: ReadInterval | null;
     asOf: ReadAsOf;
     basis: ReadBasis;
+    /** The floor this read cleared (its family's, which is the public floor unless `floors.families` names the family): every cell it counts had at least this many clusters. Stated by a pool that serves the read, and absent from a read computed on one operator's own store, which applies no public floor. */
+    floor?: number;
 }
 /** A read before its inputs are checked and its ID and order are computed. */
 export type ReadDraft = Omit<Read, 'readId' | 'order'>;

package/dist/sessions/read.js

@@ -26,7 +26,7 @@ export const FAMILIES = [...FIRST_ORDER_FAMILIES, 'version-boundary', 'substitut
 export const METHODS = {
     recovery: { name: 'signature-record', version: '2' },
     fit: { name: 'failure-rate', version: '2' },
-    cost: { name: 'per-prompt-by-class', version: '1' },
+    cost: { name: 'per-prompt-by-class', version: '2' },
     change: { name: 'share-in-version-bucket', version: '2' },
     live: { name: 'day-against-trailing-week', version: '2' },
     adoption: { name: 'share-and-span', version: '2' },
@@ -39,6 +39,8 @@ export const METHODS = {
     'day-move': { name: 'move-to-next-day', version: '2' },
     'lead-lag': { name: 'failure-move-leads-share-move', version: '1' },
 };
+/** The recovery family's other method (`read-recovery-edge.ts`): what others did next after a failed call, from cells alone. The pool's version hashes it beside the table. */
+export const RECOVERY_EDGE_METHOD = { name: 'next-action-after-failure', version: '1' };
 /** The fit family's other method (`read-call-shape.ts`). The pool's version hashes it beside the table, for the same reason. */
 export const CALL_SHAPE_METHOD = { name: 'call-shape', version: '2' };
 const ORDER_OF_CELL = 0;
@@ -51,8 +53,9 @@ export const orderResolver = (reads) => {
     return (input) => (input.startsWith(CELL_PREFIX) ? ORDER_OF_CELL : orders.get(input));
 };
 export const readIdOf = (read) => {
-    const { family, method, methodVersion, inputs, order, slice, value, n, clusters, interval, asOf, basis } = read;
-    return `${READ_PREFIX}${contentHash({ family, method, methodVersion, inputs, order, slice, value, n, clusters, interval, asOf, basis })}`;
+    const { family, method, methodVersion, inputs, order, slice, value, n, clusters, interval, asOf, basis, floor } = read;
+    // The floor joins the hash only when stated, so a read with none keeps the ID it always had.
+    return `${READ_PREFIX}${contentHash({ family, method, methodVersion, inputs, order, slice, value, n, clusters, interval, asOf, basis, ...(floor === undefined ? {} : { floor }) })}`;
 };
 const deepFreeze = (value) => {
     if (typeof value !== 'object' || value === null)

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

@@ -0,0 +1,12 @@
+import { type Setup } from './pool-replica.js';
+import type { Bundle } from './pool-wire.js';
+import type { CurrentPool } from './recall-pool.js';
+import type { Store } from './store.js';
+/** The setup of the store's newest call that states a version: what a pull made outside a hook (the CLI, the MCP tool) is asked from. Undefined for a store with none. */
+export declare const storeSetup: (store: Pick<Store, "sessions" | "tools">) => Setup | undefined;
+/** A verified bundle as a pool: its served cells, motifs, and reads, as of the pool snapshot it was signed from. */
+export declare const bundlePool: (bundle: Bundle) => CurrentPool;
+/** The bundle's pool first, then the local one; either alone when the other is absent. */
+export declare const withBundle: (local: CurrentPool | undefined, bundle: Bundle | undefined) => CurrentPool | undefined;
+/** The pool a pull answers from: the local one `served` gives, with the kept bundle for the store's own setup ahead of it. */
+export declare const recallPool: (storeDir: string, store: Store, served: (storeDir: string, store: Store) => Promise<CurrentPool | undefined>) => Promise<CurrentPool | undefined>;

package/dist/sessions/recall-bundle.js

@@ -0,0 +1,33 @@
+import { sessionBundle } from './pool-replica.js';
+import { harnessOf } from './schema.js';
+/** The setup of the store's newest call that states a version: what a pull made outside a hook (the CLI, the MCP tool) is asked from. Undefined for a store with none. */
+export const storeSetup = (store) => {
+    const harnesses = new Map(store.sessions.map((session) => [session.session, harnessOf(session)]));
+    let newest;
+    for (const call of store.tools) {
+        if (call.harnessVersion === null || call.ts === null || (newest !== undefined && call.ts <= newest.ts))
+            continue;
+        newest = { ts: call.ts, setup: { harness: harnesses.get(call.session) ?? 'claude-code', harnessVersion: call.harnessVersion } };
+    }
+    return newest?.setup;
+};
+/** A verified bundle as a pool: its served cells, motifs, and reads, as of the pool snapshot it was signed from. */
+export const bundlePool = (bundle) => ({
+    pool: { cells: bundle.cells, motifs: new Map(bundle.motifs.map((motif) => [motif.motifId, motif])), version: bundle.asOf.pool, lastDay: bundle.asOf.day },
+    reads: bundle.reads,
+});
+/** The bundle's pool first, then the local one; either alone when the other is absent. */
+export const withBundle = (local, bundle) => {
+    if (bundle === undefined)
+        return local;
+    const kept = bundlePool(bundle);
+    if (local === undefined)
+        return kept;
+    const motifs = new Map([...local.pool.motifs, ...kept.pool.motifs]);
+    const cells = [...kept.pool.cells, ...local.pool.cells];
+    const pool = { cells, motifs, version: local.pool.version, lastDay: local.pool.lastDay };
+    const reads = [...kept.reads, ...local.reads];
+    return { pool, reads };
+};
+/** The pool a pull answers from: the local one `served` gives, with the kept bundle for the store's own setup ahead of it. */
+export const recallPool = async (storeDir, store, served) => withBundle(await served(storeDir, store), await sessionBundle(storeDir, storeSetup(store)));

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>;