@manyoars/oars 0.2.0 → 0.3.0

package/dist/sessions/pool-delta.js

@@ -0,0 +1,190 @@
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isMissing } from './pool-outbox.js';
+import { contentHash } from './read.js';
+import { bucketOf, PACKAGE_REGISTRIES } from './pool-wire.js';
+import { PRIVATE, PUBLIC_PACKAGES, publicEffort } from './public-vocabulary.js';
+import { harnessOf } from './schema.js';
+// Local deltas (spec Section 2, "Deltas"): the client compares its own before and after windows and builds each change once. Nothing here reads a store or sends a byte; `pool deposit` hands it the
+// sessions that passed the session gates and carries what comes back in the batch of the session that filled the after window.
+/** `delta_days` and `delta_min_sessions` (spec Section 7): a week on each side spans a work cycle, and five sessions keep one session from being the delta. */
+export const DELTA_DAYS = 7;
+export const DELTA_MIN_SESSIONS = 5;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * The pairs of windows a set of sessions holds. Windows are consecutive spans of `days` on a grid counted from the epoch, not from any session, so a session belongs to exactly one window and the grid does
+ * not move when a session is added, lost to a gate, or not yet ended: the `index` of a window is the same whenever the deposit runs. A pair is two windows next to each other that each hold at least
+ * `min` sessions; a gap of an empty window, or of one with too few, compares nothing across it. The `filler` is the `min`th session of the after window in time order. It chooses which batch carries
+ * the delta and can change from one deposit to the next, so nothing that must hold still is keyed on it.
+ */
+export const windowsOf = (sessions, days = DELTA_DAYS, min = DELTA_MIN_SESSIONS) => {
+    const ordered = [...sessions].sort((a, b) => a.at - b.at || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    const span = days * DAY_MS;
+    const windows = new Map();
+    for (const session of ordered) {
+        const index = Math.floor(session.at / span);
+        const held = windows.get(index);
+        if (held === undefined)
+            windows.set(index, [session]);
+        else
+            held.push(session);
+    }
+    const pairs = [];
+    for (const [index, after] of windows) {
+        const before = windows.get(index - 1);
+        const filler = after[min - 1];
+        if (before !== undefined && before.length >= min && filler !== undefined)
+            pairs.push({ index, before, after, filler });
+    }
+    return pairs;
+};
+const sum = (values) => values.reduce((total, value) => total + value, 0);
+const mean = (values, count) => (count === 0 ? 0 : sum(values) / count);
+/** The signed bucket of a move: the bucket of its size, negative when it fell. Zero stays zero, never negative zero. */
+const signed = (kind, move) => {
+    const bucket = bucketOf(kind, Math.abs(move));
+    return move < 0 && bucket > 0 ? -bucket : bucket;
+};
+/** The value most sessions hold; the smaller of two that tie, so two runs agree. */
+const modal = (values) => {
+    const counts = new Map();
+    for (const value of values)
+        counts.set(value, (counts.get(value) ?? 0) + 1);
+    return [...counts].sort(([a, countA], [b, countB]) => countB - countA || (a < b ? -1 : 1))[0]?.[0];
+};
+const callsOf = (window) => mean(window.map((records) => sum(records.transcripts.map(({ tools }) => tools.length))), window.length);
+const thinkingOf = (window) => {
+    const prompts = window.flatMap((records) => records.transcripts.flatMap((transcript) => transcript.prompts));
+    return mean(prompts.map(({ usage }) => usage.thinking), prompts.length);
+};
+/** The effort a session ran at: the one most of its main run's prompts held, read through the public list so a value outside it is one word. */
+const effortOf = (records) => modal((records.transcripts[0]?.prompts ?? []).flatMap(({ efforts }) => efforts.flatMap((effort) => publicEffort(effort) ?? [])));
+const entryOf = (name, field, deltaKind, metric, change, registry = null) => ({ deltaKind, field, name, registry, metric, change });
+/** Only Claude Code records `setup.plugins`; another harness holds none because it records none, not because none were loaded, so it says nothing of a plugin. */
+const recordsPlugins = ({ main }) => harnessOf(main) === 'claude-code';
+const pluginsIn = (window) => new Set(window.filter(recordsPlugins).flatMap(({ main }) => main.setup?.plugins ?? []));
+/** A stored `<ecosystem>:<name>` as the wire spells it: the public name and its registry, else the word `private` with no registry. */
+const packageNamed = (stored) => {
+    const colon = stored.indexOf(':');
+    const registry = PACKAGE_REGISTRIES.find((entry) => entry === stored.slice(0, colon));
+    const name = stored.slice(colon + 1);
+    return registry !== undefined && PUBLIC_PACKAGES.has(name) ? { name, registry } : { name: PRIVATE, registry: null };
+};
+/** The manifests a window's calls showed, in the order they ran. A call that did not come back clean shows none. */
+const manifestsIn = (window) => window.flatMap((records) => records.transcripts.flatMap(({ tools }) => [...tools].sort((a, b) => a.n - b.n).flatMap(({ manifest, status, target, tool }) => (manifest === undefined || status !== 'ok' ? [] : [{ tool, target, seen: manifest.seen, added: manifest.added, removed: manifest.removed }]))));
+/**
+ * Whether the manifests of the after window leave a package gone. An edit that removes it, or a Write that lists a file that held it in the before window and no longer does, says gone; a later edit that
+ * adds it back, or any listing that holds it, says it stayed. A Read says nothing of what is missing, since it may have shown part of the file (an `offset` or a `limit`), and a listing of any other
+ * file says nothing, since one repository's manifest is not another's.
+ */
+const goneFrom = (stored, before, after) => {
+    const held = new Set(before.flatMap(({ target, seen }) => (target !== null && seen.includes(stored) ? [target] : [])));
+    let gone = false;
+    for (const { tool, target, seen, added, removed } of after) {
+        if (removed.includes(stored))
+            gone = true;
+        else if (added.includes(stored) || seen.includes(stored))
+            gone = false;
+        else if (tool === 'Write' && seen.length > 0 && target !== null && held.has(target))
+            gone = true;
+    }
+    return gone;
+};
+/** A package's calls per session: tool calls of the window that install or run it. */
+const callsNaming = (window, stored) => mean(window.map((records) => sum(records.transcripts.map(({ tools }) => tools.filter(({ packages }) => packages?.some(({ package: held }) => held === stored) === true).length))), window.length);
+const packagesCalledIn = (window) => [...new Set(window.flatMap((records) => records.transcripts.flatMap(({ tools }) => tools.flatMap(({ packages }) => (packages ?? []).map(({ package: held }) => held)))))].sort();
+const order = (a, b) => {
+    const key = (entry) => [entry.field, entry.deltaKind, entry.name ?? '', entry.registry ?? ''].join(' ');
+    return key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0;
+};
+/**
+ * The entries a pair of windows holds, each window in time order (the caller sorts). A plugin is added or removed, a `permissionMode` or `effort` changed by name alone (the most common value of each
+ * window differs, a value outside its list read as one word), and a `package` removed. Each entry carries the move of one metric in its field's own buckets: calls per session for a plugin, a permission
+ * mode, and a package, thinking per prompt for an effort. A name outside its list is `private`, and everything that is `private` in one field is one entry.
+ */
+export const deltasOf = (before, after) => {
+    const calls = signed('count', callsOf(after) - callsOf(before));
+    const entries = [];
+    // No plugin registry is pinned, so a plugin's name never passes its row: it goes as the word `private`. Plugins are compared only when both windows hold a session that records them.
+    if (before.some(recordsPlugins) && after.some(recordsPlugins)) {
+        const pluginsBefore = pluginsIn(before);
+        const pluginsAfter = pluginsIn(after);
+        if ([...pluginsAfter].some((plugin) => !pluginsBefore.has(plugin)))
+            entries.push(entryOf(PRIVATE, 'plugin', 'added', 'callsPerSession', calls));
+        if ([...pluginsBefore].some((plugin) => !pluginsAfter.has(plugin)))
+            entries.push(entryOf(PRIVATE, 'plugin', 'removed', 'callsPerSession', calls));
+    }
+    const modeBefore = modal(before.flatMap(({ main }) => main.setup?.permissionMode ?? []));
+    const modeAfter = modal(after.flatMap(({ main }) => main.setup?.permissionMode ?? []));
+    if (modeBefore !== undefined && modeAfter !== undefined && modeBefore !== modeAfter)
+        entries.push(entryOf(null, 'permissionMode', 'changed', 'callsPerSession', calls));
+    const effortBefore = modal(before.flatMap((records) => effortOf(records) ?? []));
+    const effortAfter = modal(after.flatMap((records) => effortOf(records) ?? []));
+    if (effortBefore !== undefined && effortAfter !== undefined && effortBefore !== effortAfter)
+        entries.push(entryOf(null, 'effort', 'changed', 'thinking', signed('tokens', thinkingOf(after) - thinkingOf(before))));
+    const manifestsBefore = manifestsIn(before);
+    const manifestsAfter = manifestsIn(after);
+    const moves = new Map();
+    for (const stored of packagesCalledIn(before)) {
+        if (!goneFrom(stored, manifestsBefore, manifestsAfter))
+            continue;
+        const { name, registry } = packageNamed(stored);
+        const key = `${registry ?? ''}:${name}`;
+        moves.set(key, { name, registry, move: (moves.get(key)?.move ?? 0) + callsNaming(after, stored) - callsNaming(before, stored) });
+    }
+    for (const { name, registry, move } of moves.values())
+        entries.push(entryOf(name, 'package', 'removed', 'callsPerSession', signed('count', move), registry));
+    return entries.sort(order);
+};
+const MARKS_FILE = 'deltas-sent.log';
+/**
+ * The once-only mark of a delta: a hash of the account, the entry without the size of its move, and the index of its after window on the grid. The move is left out so a recount of the same windows is
+ * the same delta, and the index is in so a later pair that shows the same change is a new one. The filler is not in it: which session fills a window moves with the sessions ready, a window's index does not.
+ */
+export const deltaMark = (account, { deltaKind, field, name, registry, metric }, index) => contentHash([account, deltaKind, field, name, registry, metric, index]);
+/** The marks of the deltas this outbox has already carried in a written batch. A folder with no log holds none; a log that cannot be read is an error, not an empty one, so a delta is never built twice by mistake. */
+export const sentDeltas = async (outbox) => {
+    try {
+        return new Set((await readFile(join(outbox, MARKS_FILE), 'utf8')).split('\n').filter((line) => line !== ''));
+    }
+    catch (error) {
+        if (isMissing(error))
+            return new Set();
+        throw error;
+    }
+};
+/** Marks deltas as sent, one line each. The caller writes this only after the batch that carries them is written, so a deposit that stopped before it builds them again. */
+export const markDeltasSent = async (outbox, marks) => {
+    if (marks.length === 0)
+        return;
+    await mkdir(outbox, { recursive: true });
+    await appendFile(join(outbox, MARKS_FILE), marks.map((mark) => `${mark}\n`).join(''), 'utf8');
+};
+/** The session placed by when it began (epoch milliseconds) and its own id; none when it has no start that reads as a time, since no window can hold it. */
+export const placedOf = (records) => {
+    const at = records.main.tsFirst === null ? Number.NaN : Date.parse(records.main.tsFirst);
+    return Number.isNaN(at) ? undefined : { id: records.main.session, at, records };
+};
+/**
+ * The deltas not yet sent, by the id of the session that filled their after window: that session's batch carries them, and the mark is the window's index, so it holds whichever session fills. A delta whose mark is held is dropped, so a rebuilt session, or a batch written
+ * again under the same key, builds none it already carried. Nothing is marked here: the caller marks them once the batch is written.
+ */
+export const carriedDeltas = (account, sessions, sent) => {
+    const carried = new Map();
+    for (const { index, before, after, filler } of windowsOf(sessions)) {
+        const entries = [];
+        const marks = [];
+        for (const entry of deltasOf(before.map(({ records }) => records), 
+        // The outcome is fixed at the fill: sessions after the filler change nothing, so a delta is the same whenever it is built.
+        after.slice(0, DELTA_MIN_SESSIONS).map(({ records }) => records))) {
+            const mark = deltaMark(account, entry, index);
+            if (sent.has(mark))
+                continue;
+            entries.push(entry);
+            marks.push(mark);
+        }
+        if (entries.length > 0)
+            carried.set(filler.id, { entries, marks });
+    }
+    return carried;
+};

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

@@ -0,0 +1,63 @@
+/** The batch as one canonical JSON line: sorted keys, no optional whitespace, UTF-8 when written, and a newline at the end. These are the bytes that are hashed, printed, and sent. */
+export declare const canonicalBytes: (batch: unknown) => string;
+export declare const batchHash: (bytes: string) => string;
+/**
+ * `oars pool outbox --explain`: one row for each field name a batch holds, at any depth, saying what admits its values. A field with no row fails the command, so a field added to the batch adds its row here.
+ * A name that sits at more than one depth (`status`, `harness`, `frame`) has one row that reads true at each.
+ */
+export declare const FIELD_ROWS: {
+    readonly [field: string]: string;
+};
+/**
+ * Every field name a batch holds, at any depth, sorted: the rows above. A batch is filed under this list, the skeleton format, and `VOCAB_VERSION`, so one built under an older list, form, or vocabulary is never printed or sent.
+ * A test holds this list equal to the fields of a real batch, so a field the sample holds without its row fails there.
+ */
+export declare const BATCH_FIELDS: readonly string[];
+/** The folder name of the batches this client builds now. A folder of any other name holds batches built under an older vocabulary, field list, or skeleton format. */
+export declare const currentStamp: (fields?: readonly string[], format?: number) => string;
+/** One server's outbox: batches are per server, since a printed batch carries that server's credential. */
+export declare const outboxFolder: (storeDir: string, server: string) => string;
+/** Writes one session's batch under the current stamp. A session has one batch: an older batch of it is removed, and an identical one is written again, so an edited file is restored. */
+export declare const writeBatch: (outbox: string, key: string, batch: unknown, stamp?: string) => Promise<{
+    hash: string;
+    folder: string;
+}>;
+export declare const isMissing: (error: unknown) => boolean;
+/** Removes every batch under this stamp whose session is not in `kept`, and returns how many went. A session that fails a gate, leaves the allowlist, or is gone from the store never enters the outbox, so an earlier pass's batch of it cannot stay. */
+export declare const removeBatchesExcept: (outbox: string, kept: ReadonlySet<string>, stamp?: string, only?: string) => Promise<number>;
+/** Removes the batch of one session, if it has one under this stamp, and returns how many files went. */
+export declare const removeBatchOf: (outbox: string, key: string, stamp?: string) => Promise<number>;
+/** The bytes of a batch file, when they still hash to the name the file was written under; undefined when the file is gone or was edited. */
+export declare const unchangedBytes: (file: string, hash: string) => Promise<string | undefined>;
+export interface Held {
+    /** The session's key in the outbox (the batch's account-hashed id). */
+    key: string;
+    hash: string;
+    file: string;
+    bytes: string;
+}
+/** The batches built under this client's vocabulary, field list, and skeleton format, and how many of their files no longer hash to their names. An edited file is not printed and cannot be sent: run `deposit` again to rebuild it. */
+export declare const heldBatches: (outbox: string, stamp?: string) => Promise<{
+    batches: Held[];
+    edited: number;
+}>;
+/** Records that this hash was printed, one line for each print: the lock below sends only a hash that appears here. */
+export declare const markShown: (outbox: string, hash: string, at: number) => Promise<void>;
+export type LockRefusal = 'batch_unknown' | 'batch_not_shown' | 'batch_changed';
+/** The lock on `deposit --send`: a batch goes only if it is in the outbox, its hash was printed, and its file still hashes to that hash. The first check that fails names why. */
+export declare const lockedBatch: (outbox: string, hash: string, stamp?: string) => Promise<{
+    ok: true;
+    file: string;
+    bytes: string;
+} | {
+    ok: false;
+    code: LockRefusal;
+}>;
+/** Batches in one server's outbox that were built under another vocabulary, field list, or skeleton format: never printed, never sent. */
+export declare const staleBatches: (outbox: string, stamp?: string) => Promise<number>;
+/** Every server's stale batches, for `verify`. */
+export declare const staleBatchesAnywhere: (storeDir: string, stamp?: string) => Promise<number>;
+/** Removes one server's stale batches, and returns how many there were. */
+export declare const discardStale: (outbox: string, stamp?: string) => Promise<number>;
+/** Every field name in a batch, at any depth, each once and sorted. */
+export declare const fieldsOf: (batchBytes: string) => string[];

package/dist/sessions/pool-outbox.js

@@ -0,0 +1,260 @@
+// The outbox (`oars pool deposit` and `oars pool outbox`): every batch that may leave this machine is first written here, as canonical JSON lines, and `deposit` stops. Nothing in this file
+// looks inside a batch except to name its fields, at every depth, for `--explain`; what a batch holds is the projection's business.
+import { createHash } from 'node:crypto';
+import { appendFile, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { SKELETON_FORMAT, VOCAB_VERSION } from './pool-wire.js';
+import { contentHash } from './read.js';
+/** What `JSON.stringify` writes for a value, or undefined for one JSON cannot hold (the lib types call this a string always). */
+const encoded = (value) => JSON.stringify(value);
+/**
+ * JSON with keys sorted at every depth, so two writers of one batch write the same bytes. The sorted entries are written out directly: rebuilding an object would put an integer-like key such as `10` before `9` whatever the sort said.
+ * A value JSON cannot hold is left out of an object and written as null in an array, as `JSON.stringify` does.
+ */
+const canonical = (value) => {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (typeof value === 'object' && value !== null) {
+        const entries = Object.entries(value)
+            .filter(([, entry]) => encoded(entry) !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : 1));
+        return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${canonical(entry)}`).join(',')}}`;
+    }
+    return encoded(value) ?? 'null';
+};
+/** The batch as one canonical JSON line: sorted keys, no optional whitespace, UTF-8 when written, and a newline at the end. These are the bytes that are hashed, printed, and sent. */
+export const canonicalBytes = (batch) => `${canonical(batch)}\n`;
+export const batchHash = (bytes) => createHash('sha256').update(Buffer.from(bytes, 'utf8')).digest('hex');
+/**
+ * `oars pool outbox --explain`: one row for each field name a batch holds, at any depth, saying what admits its values. A field with no row fails the command, so a field added to the batch adds its row here.
+ * A name that sits at more than one depth (`status`, `harness`, `frame`) has one row that reads true at each.
+ */
+export const FIELD_ROWS = {
+    action: 'The canonical action of a step, one of a closed list this client holds; never the harness tool text.',
+    agentType: 'The type of the subagent whose run holds a step: a built-in type of the harness, else the word custom; null on a step of the main run.',
+    cacheRead: 'A bucket of the tokens read from the cache in a prompt, a number.',
+    cacheWrite: 'A bucket of the tokens written to the cache in a prompt, a number.',
+    change: 'How far a delta moved, a signed bucket of its metric (a lower bound) in a number from -7 to 7 for calls per session and from -11 to 11 for thinking tokens; never the exact count.',
+    cls: 'The class of a prompt, one of a closed list of eight, computed from the kinds of tools it used; never its words.',
+    day: 'The UTC calendar day of the session as YYYY-MM-DD, or null; never a time of day.',
+    deltaKind: 'How a delta changed what the client ran: added, removed, or changed, one of a closed list the field allows; never a value.',
+    deltas: 'The changes the client found between its own before and after windows, each sent once with the session that filled the after window: a kind, a field, a name, a registry, a metric, and a bucketed change; never a session id, a root, a date, or an exact value.',
+    durationMs: 'The time of one tool call in milliseconds, exact, a number or null.',
+    effort: 'The effort level the model ran at, only when it is a public one; else the literal placeholder.',
+    errors: 'A bucket of how many tool calls failed in a prompt, a number.',
+    explore: 'A bucket of how many steps of a prompt only looked (read a file, searched files, searched the web, or fetched a page), a number or null; never the exact count.',
+    field: 'What a delta is about, one of plugin, package, permissionMode, and effort: the field alone, never its value.',
+    flags: 'The flags of a shell command, each a public flag or a short flag; never an argument.',
+    format: 'The skeleton format number: a constant of this client, never a value from a session.',
+    frame: 'Where a session ran: the harness and its version, the model, the effort, the day, the platform, the shell, and the stack, every value checked against the closed vocabulary.',
+    frameworks: 'The frameworks of the project, each from a closed public list; never a path or a name of yours.',
+    harness: 'Which harness wrote the session, one of a closed list.',
+    harnessVersion: 'The harness version, only when it is a public release; else the literal placeholder.',
+    host: 'The host of a web fetch or search, only when it is on the public list; else private, or null when the step names no host.',
+    id: "A hash the client computes per account from the account and the session, so a redeposit replaces and two accounts' sessions cannot be joined. Never the session id.",
+    identity: 'What a step called, in closed vocabulary: a shell program with its subcommand and flags, an MCP server and tool, a skill, or a web host; null for an action with none.',
+    input: 'A bucket of the input tokens in a prompt, a number.',
+    language: 'A programming language of the project, from a closed public list, or other for any language off the list, beside its share bucket.',
+    languageShare: 'How much of the files a session touched are in one language, one of four buckets: none, under 10 percent, 10 up to 50, or 50 and over; never a count of files.',
+    languageShares: 'The share bucket of each language of the project whose share is known; a language with no share is in the languages list alone.',
+    languages: 'The programming languages of the project, each from a closed public list.',
+    leaves: 'How many lines of a transcript its root covers, a count.',
+    merkleRoot: 'The Merkle root of a transcript: a SHA-256 over the hashes of its lines, one root for each transcript, the main one first; never a line.',
+    metric: 'What a delta measures, calls per session or thinking tokens, one of a closed list the field fixes.',
+    model: 'The model name, only when it is a public one; else the literal placeholder.',
+    ms: 'A bucket of the milliseconds a step took (a lower bound), a number or null; never the exact time.',
+    name: 'The name of a package a shell command pulled or a delta removed, only when it is on the public list; else private. A plugin in a delta is always private, and null when a delta names its field alone.',
+    native: "The name the harness gave the tool, only when it is in this client's action table; else private.",
+    output: 'A bucket of the output tokens in a prompt, a number.',
+    parent: 'The position of the main-run call that spawned this step, a number, or null (also null for a subagent a subagent spawned).',
+    platform: 'The operating system family, one of a closed list.',
+    program: 'The program a shell command ran, when it is on the public list; else the word private.',
+    prompt: 'Which prompt of the batch a tool call follows, a position in this batch, or null.',
+    prompts: 'The prompts of a transcript: each a class, bucketed counts and tokens, and a frame; never their words.',
+    pulls: 'The packages a shell command pulled from a registry: the registry, the public package name, and its version.',
+    registry: 'Which registry a pull or a removed package came from, one of a closed list; null for a delta whose name is private or absent.',
+    remainingTokens: 'A bucket of the tokens the run spent after a step (a lower bound), a number: the bucket of the exact sum, with the subagent runs a main-run step spawned later in the session.',
+    server: 'The MCP server a call went to, only when it is on the public list; else private.',
+    shell: 'The shell a command ran in, one of a closed list, or null.',
+    side: 'Whether a tool call ran as a side call, true or false.',
+    size: 'A size class of the repository, one of a closed list, or null; never a count of files.',
+    skill: 'The skill a step ran, only when it is on the public list; else private.',
+    stack: 'The languages, frameworks, and size class of the project.',
+    status: 'Whether a tool call or a step succeeded: ok, error, or none.',
+    steps: 'The steps of a tool call, each an action in closed vocabulary with its bucketed cost and spawner.',
+    sub: 'The subcommand of a shell program, only when it is on the public list for that program; else null.',
+    thinking: 'A bucket of the thinking tokens in a prompt, a number.',
+    timingPrint: 'A hash of the call durations of the main transcript in the order they ran, or null under 50 timed calls; the calls of a subagent are not in it.',
+    tokens: 'A bucket of tokens (a lower bound of the count), a number or null; a step holds one, never the exact count.',
+    tool: 'The tool of an MCP call, only when it is on the public list for that server; else the literal placeholder.',
+    tools: 'The tool calls of a transcript, each a status and duration and its steps, in the order they ran; never their targets or arguments.',
+    transcripts: 'The main transcript, then each subagent: its frame, prompts, and tool calls, every value checked against the closed vocabulary before the batch is built.',
+    usage: 'The tokens of a prompt as buckets (lower bounds): input, cache write, cache read, output, and thinking.',
+    version: 'The version of a pulled package, only when it is a registry version; else the literal placeholder or null.',
+    wallSec: 'A bucket of the seconds a prompt took, or null.',
+};
+/**
+ * Every field name a batch holds, at any depth, sorted: the rows above. A batch is filed under this list, the skeleton format, and `VOCAB_VERSION`, so one built under an older list, form, or vocabulary is never printed or sent.
+ * A test holds this list equal to the fields of a real batch, so a field the sample holds without its row fails there.
+ */
+export const BATCH_FIELDS = Object.keys(FIELD_ROWS).sort();
+const fieldsStamp = (fields, format) => createHash('sha256').update(`${String(format)}:${fields.join(',')}`).digest('hex').slice(0, 8);
+/** The folder name of the batches this client builds now. A folder of any other name holds batches built under an older vocabulary, field list, or skeleton format. */
+export const currentStamp = (fields = BATCH_FIELDS, format = SKELETON_FORMAT) => `v${VOCAB_VERSION}-${fieldsStamp(fields, format)}`;
+/** One server's outbox: batches are per server, since a printed batch carries that server's credential. */
+export const outboxFolder = (storeDir, server) => join(storeDir, 'pool-outbox', contentHash(server));
+const BATCH_FILE = /^([0-9a-f]{16})\.([0-9a-f]{64})\.jsonl$/;
+/** Writes one session's batch under the current stamp. A session has one batch: an older batch of it is removed, and an identical one is written again, so an edited file is restored. */
+export const writeBatch = async (outbox, key, batch, stamp = currentStamp()) => {
+    const bytes = canonicalBytes(batch);
+    const hash = batchHash(bytes);
+    const folder = join(outbox, stamp);
+    await mkdir(folder, { recursive: true });
+    for (const name of await readdir(folder)) {
+        const found = BATCH_FILE.exec(name);
+        if (found?.[1] === key && found[2] !== hash)
+            await rm(join(folder, name), { force: true });
+    }
+    await writeFile(join(folder, `${key}.${hash}.jsonl`), bytes, 'utf8');
+    return { hash, folder };
+};
+export const isMissing = (error) => error instanceof Error && 'code' in error && error.code === 'ENOENT';
+/** A path that is missing, or has a file where a folder should be, holds nothing. */
+const isAbsent = (error) => isMissing(error) || (error instanceof Error && 'code' in error && error.code === 'ENOTDIR');
+/** The names in a folder; a folder that does not exist yet holds none. */
+const namesIn = async (folder) => {
+    try {
+        return (await readdir(folder)).sort();
+    }
+    catch (error) {
+        if (isAbsent(error))
+            return [];
+        throw error;
+    }
+};
+/** Removes every batch under this stamp whose session is not in `kept`, and returns how many went. A session that fails a gate, leaves the allowlist, or is gone from the store never enters the outbox, so an earlier pass's batch of it cannot stay. */
+export const removeBatchesExcept = async (outbox, kept, stamp = currentStamp(), only) => {
+    const folder = join(outbox, stamp);
+    let removed = 0;
+    for (const name of await namesIn(folder)) {
+        const found = BATCH_FILE.exec(name);
+        if (found !== null && !kept.has(found[1] ?? '') && (only === undefined || found[1] === only)) {
+            await rm(join(folder, name), { force: true });
+            removed += 1;
+        }
+    }
+    return removed;
+};
+/** Removes the batch of one session, if it has one under this stamp, and returns how many files went. */
+export const removeBatchOf = async (outbox, key, stamp = currentStamp()) => removeBatchesExcept(outbox, new Set(), stamp, key);
+/** The bytes of a batch file, when they still hash to the name the file was written under; undefined when the file is gone or was edited. */
+export const unchangedBytes = async (file, hash) => {
+    let bytes;
+    try {
+        bytes = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+    return batchHash(bytes) === hash ? bytes : undefined;
+};
+/** The batches built under this client's vocabulary, field list, and skeleton format, and how many of their files no longer hash to their names. An edited file is not printed and cannot be sent: run `deposit` again to rebuild it. */
+export const heldBatches = async (outbox, stamp = currentStamp()) => {
+    const folder = join(outbox, stamp);
+    const batches = [];
+    let edited = 0;
+    for (const name of await namesIn(folder)) {
+        const found = BATCH_FILE.exec(name);
+        if (found === null)
+            continue;
+        const [, key = '', hash = ''] = found;
+        const file = join(folder, name);
+        const bytes = await unchangedBytes(file, hash);
+        if (bytes === undefined)
+            edited += 1;
+        else
+            batches.push({ key, hash, file, bytes });
+    }
+    return { batches, edited };
+};
+const shownFile = (outbox) => join(outbox, 'shown.log');
+/** Records that this hash was printed, one line for each print: the lock below sends only a hash that appears here. */
+export const markShown = async (outbox, hash, at) => {
+    await mkdir(outbox, { recursive: true });
+    await appendFile(shownFile(outbox), `${hash} ${new Date(at).toISOString()}\n`, 'utf8');
+};
+const wasShown = async (outbox, hash) => {
+    try {
+        return (await readFile(shownFile(outbox), 'utf8')).split('\n').some((line) => line.split(' ')[0] === hash);
+    }
+    catch (error) {
+        if (isMissing(error))
+            return false;
+        throw error;
+    }
+};
+/** The lock on `deposit --send`: a batch goes only if it is in the outbox, its hash was printed, and its file still hashes to that hash. The first check that fails names why. */
+export const lockedBatch = async (outbox, hash, stamp = currentStamp()) => {
+    const folder = join(outbox, stamp);
+    const name = (await namesIn(folder)).find((entry) => BATCH_FILE.exec(entry)?.[2] === hash);
+    if (name === undefined)
+        return { ok: false, code: 'batch_unknown' };
+    if (!(await wasShown(outbox, hash)))
+        return { ok: false, code: 'batch_not_shown' };
+    const file = join(folder, name);
+    const bytes = await unchangedBytes(file, hash);
+    return bytes === undefined ? { ok: false, code: 'batch_changed' } : { ok: true, file, bytes };
+};
+/** Folders of an outbox other than the current stamp's: batches built under another vocabulary, field list, or skeleton format. */
+const staleFolders = async (outbox, stamp) => {
+    const names = [];
+    for (const name of await namesIn(outbox)) {
+        if (name !== stamp && STAMP_FOLDER.test(name))
+            names.push(join(outbox, name));
+    }
+    return names;
+};
+const STAMP_FOLDER = /^v[^./]+-[0-9a-f]{8}$/;
+const batchesIn = async (folder) => (await namesIn(folder)).filter((name) => BATCH_FILE.test(name)).length;
+/** Batches in one server's outbox that were built under another vocabulary, field list, or skeleton format: never printed, never sent. */
+export const staleBatches = async (outbox, stamp = currentStamp()) => {
+    let count = 0;
+    for (const folder of await staleFolders(outbox, stamp))
+        count += await batchesIn(folder);
+    return count;
+};
+/** Every server's stale batches, for `verify`. */
+export const staleBatchesAnywhere = async (storeDir, stamp = currentStamp()) => {
+    const root = join(storeDir, 'pool-outbox');
+    let count = 0;
+    for (const name of await namesIn(root))
+        count += await staleBatches(join(root, name), stamp);
+    return count;
+};
+/** Removes one server's stale batches, and returns how many there were. */
+export const discardStale = async (outbox, stamp = currentStamp()) => {
+    const count = await staleBatches(outbox, stamp);
+    for (const folder of await staleFolders(outbox, stamp))
+        await rm(folder, { recursive: true, force: true });
+    return count;
+};
+const collect = (value, into) => {
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            collect(entry, into);
+    }
+    else if (typeof value === 'object' && value !== null) {
+        for (const [key, entry] of Object.entries(value)) {
+            into.add(key);
+            collect(entry, into);
+        }
+    }
+};
+/** Every field name in a batch, at any depth, each once and sorted. */
+export const fieldsOf = (batchBytes) => {
+    const names = new Set();
+    collect(JSON.parse(batchBytes), names);
+    return [...names].sort();
+};

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

@@ -0,0 +1,26 @@
+/** One request as it will leave this machine. */
+export interface Outgoing {
+    method: 'GET' | 'POST';
+    url: URL;
+    /** Every header this code sets. The HTTP layer adds `host`, `connection`, and `content-length` itself, and `printed` lists those too. */
+    headers: Array<[string, string]>;
+    body?: string;
+}
+/**
+ * The headers Node's `fetch` would otherwise add on its own, set here so the print lists all of them. `identity` also means a reply is never compressed, so the bytes read are the bytes signed.
+ * `sec-fetch-mode` and `accept-language` carry no information; they are pinned to what `fetch` sends anyway. A conditional request also gets `cache-control: no-cache` and `pragma: no-cache` from `fetch`; `ask` sets both beside `if-none-match`.
+ * `pool-socket.test.ts` compares the print with the headers a loopback server reads off the socket, so a header a later Node adds fails there.
+ */
+export declare const TRANSPORT_HEADERS: ReadonlyArray<[string, string]>;
+/** The credential's size, and nothing else about it. */
+export declare const maskOf: (secret: string) => string;
+/** The secrets of one run. A value added once is masked in every print after, wherever it appears. */
+export declare class Masker {
+    private readonly secrets;
+    add(secret: string): void;
+    mask(text: string): string;
+}
+/** The request as the wire carries it: the request line, `host` and `connection` first as the HTTP layer writes them, then the headers set here, then the length of a body. */
+export declare const printed: (request: Outgoing, masker: Masker) => string;
+/** The line the operator reads when the pool says to wait: a count of seconds, or an HTTP date, in plain words. Undefined when it is neither. */
+export declare const waitWords: (retryAfter: string, now: number) => string | undefined;

package/dist/sessions/pool-print.js

@@ -0,0 +1,68 @@
+// What `oars pool fetch` and `oars pool login` print before they send: the request line and every header, then the body, with a credential
+// masked as `<credential: n bytes>`. The text printed is built from the very headers and body handed to `fetch`, so the two cannot drift apart.
+/**
+ * The headers Node's `fetch` would otherwise add on its own, set here so the print lists all of them. `identity` also means a reply is never compressed, so the bytes read are the bytes signed.
+ * `sec-fetch-mode` and `accept-language` carry no information; they are pinned to what `fetch` sends anyway. A conditional request also gets `cache-control: no-cache` and `pragma: no-cache` from `fetch`; `ask` sets both beside `if-none-match`.
+ * `pool-socket.test.ts` compares the print with the headers a loopback server reads off the socket, so a header a later Node adds fails there.
+ */
+export const TRANSPORT_HEADERS = [
+    ['accept-encoding', 'identity'],
+    ['accept-language', '*'],
+    ['sec-fetch-mode', 'cors'],
+];
+/** The credential's size, and nothing else about it. */
+export const maskOf = (secret) => `<credential: ${String(Buffer.byteLength(secret))} bytes>`;
+/** Every way a secret can be written into a header or a body: bare, form-encoded, percent-encoded, and as the inside of a JSON string. */
+const spellings = (secret) => {
+    const form = new URLSearchParams({ k: secret }).toString().slice('k='.length);
+    const inJson = JSON.stringify(secret).slice(1, -1);
+    return [...new Set([secret, form, encodeURIComponent(secret), inJson])];
+};
+/** The secrets of one run. A value added once is masked in every print after, wherever it appears. */
+export class Masker {
+    secrets = new Set();
+    add(secret) {
+        if (secret !== '')
+            this.secrets.add(secret);
+    }
+    mask(text) {
+        // Longest first, so a secret that holds another is replaced whole.
+        const found = [...this.secrets].flatMap((secret) => spellings(secret).map((spelling) => ({ spelling, mask: maskOf(secret) }))).sort((a, b) => b.spelling.length - a.spelling.length);
+        return found.reduce((masked, { spelling, mask }) => masked.split(spelling).join(mask), text);
+    }
+}
+/** The request as the wire carries it: the request line, `host` and `connection` first as the HTTP layer writes them, then the headers set here, then the length of a body. */
+export const printed = (request, masker) => {
+    const { method, url, headers, body } = request;
+    const lines = [`${method} ${url.pathname}${url.search} HTTP/1.1`, `host: ${url.host}`, 'connection: keep-alive', ...headers.map(([name, value]) => `${name}: ${value}`)];
+    if (body !== undefined)
+        lines.push(`content-length: ${String(Buffer.byteLength(body))}`);
+    return masker.mask(`${lines.join('\n')}\n${body === undefined ? '' : `\n${body}\n`}`);
+};
+/** The line the operator reads when the pool says to wait: a count of seconds, or an HTTP date, in plain words. Undefined when it is neither. */
+export const waitWords = (retryAfter, now) => {
+    const seconds = /^\d+$/.test(retryAfter.trim()) ? Number(retryAfter.trim()) : Math.ceil((Date.parse(retryAfter) - now) / 1000);
+    if (!Number.isFinite(seconds))
+        return undefined;
+    if (seconds <= 0)
+        return 'now';
+    const units = [
+        ['day', 86_400],
+        ['hour', 3_600],
+        ['minute', 60],
+    ];
+    // Only two units are shown, so the last one shown is rounded up: an operator who retries at the time named must not get another 429.
+    const lead = units.findIndex(([, size]) => seconds >= size);
+    const step = lead < 0 ? 1 : (units[Math.min(lead + 1, units.length - 1)]?.[1] ?? 1);
+    const parts = [];
+    let left = Math.ceil(seconds / step) * step;
+    for (const [name, size] of units) {
+        const count = Math.floor(left / size);
+        left -= count * size;
+        if (count > 0)
+            parts.push(`${String(count)} ${name}${count === 1 ? '' : 's'}`);
+    }
+    if (parts.length === 0)
+        parts.push(`${String(left)} second${left === 1 ? '' : 's'}`);
+    return `in ${parts.slice(0, 2).join(' and ')}`;
+};