@manyoars/oars 0.2.0 → 0.4.0

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

@@ -0,0 +1,54 @@
+import { type DeltaEntry, type SessionRecords } from './pool-wire.js';
+/** `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 declare const DELTA_DAYS = 7;
+export declare const DELTA_MIN_SESSIONS = 5;
+/** A session as a window sees it: when it began (epoch milliseconds) and an id that orders two sessions of one instant. */
+export interface Placed {
+    id: string;
+    at: number;
+}
+/** A before and an after window, each of `DELTA_DAYS`, the after window's place on the grid (its index), and the session that brought the after window to its minimum. */
+export interface Windows<T> {
+    index: number;
+    before: T[];
+    after: T[];
+    filler: T;
+}
+/**
+ * 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 declare const windowsOf: <T extends Placed>(sessions: readonly T[], days?: number, min?: number) => Windows<T>[];
+/**
+ * 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 declare const deltasOf: (before: readonly SessionRecords[], after: readonly SessionRecords[]) => DeltaEntry[];
+/**
+ * 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 declare const deltaMark: (account: string, { deltaKind, field, name, registry, metric }: DeltaEntry, index: number) => string;
+/** 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 declare const sentDeltas: (outbox: string) => Promise<Set<string>>;
+/** 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 declare const markDeltasSent: (outbox: string, marks: readonly string[]) => Promise<void>;
+/** A session that passed the session gates, placed for the windows: its records, when it began, and its id. */
+export interface Gated extends Placed {
+    records: SessionRecords;
+}
+/** 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 declare const placedOf: (records: SessionRecords) => Gated | undefined;
+/** What one batch carries: its delta entries and the marks to write once the batch is written. */
+export interface Carried {
+    entries: DeltaEntry[];
+    marks: string[];
+}
+/**
+ * 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 declare const carriedDeltas: (account: string, sessions: readonly Gated[], sent: ReadonlySet<string>) => Map<string, Carried>;

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-nightly-deps.d.ts

@@ -0,0 +1,3 @@
+import type { RunDeps } from '../cli.js';
+import type { SessionsRuntime } from './store.js';
+export declare const nightlyPoolDeps: (env: NodeJS.ProcessEnv, sessions: SessionsRuntime, version: string, now: () => number) => RunDeps;

package/dist/sessions/pool-nightly-deps.js

@@ -0,0 +1,11 @@
+export const nightlyPoolDeps = (env, sessions, version, now) => ({
+    env,
+    io: { stdout: () => undefined, stderr: () => undefined },
+    store: { read: () => Promise.resolve(undefined), write: () => Promise.resolve(), delete: () => Promise.resolve() },
+    version,
+    sleep: () => Promise.resolve(),
+    random: () => 0,
+    now,
+    openBrowser: () => Promise.resolve(),
+    sessions,
+});

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

@@ -0,0 +1,10 @@
+import type { RunDeps } from '../cli.js';
+import { type Sender } from './pool-command.js';
+export type NightlyOutcome = 'no-server' | 'not-signed-in' | 'not-accepted' | 'failed' | 'sent';
+export interface NightlyPool {
+    outcome: NightlyOutcome;
+    /** Batches and raw copies this night sent. */
+    batches: number;
+    raw: number;
+}
+export declare const nightlyPoolSend: (deps: RunDeps, via?: Sender) => Promise<NightlyPool>;

package/dist/sessions/pool-nightly.js

@@ -0,0 +1,85 @@
+// The nightly send (t884 Item 4). After the person has accepted the pool's covenant, the nightly task builds the outbox and sends what is new: skeleton batches, and, only after a yes to the raw prompt, the locally redacted raw copies.
+// Acceptance is the consent: this module never accepts a covenant, and with an unusable server URL, no sign-in, or no acceptance it makes one request at most (the covenant read) and sends nothing. `oars pool outbox` still prints everything that is queued.
+// It never throws, and what it records is counts and an outcome word, never a path, a host, or a byte of a transcript.
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ask, DEPOSIT, isObject, networkSender, poolDeposit, poolServer, postBatch, postRaw, runtimeOf, signedIn, textIn, vocabularyExpired } from './pool-command.js';
+import { heldBatches, lockedBatch, outboxFolder } from './pool-outbox.js';
+import { heldRaw } from './pool-raw.js';
+import { withSendLock } from './pool-send-lock.js';
+import { markSent, sentHashes } from './pool-sent.js';
+import { readState } from './store.js';
+const record = async (storeDir, result, at) => {
+    // A note that cannot be written changes nothing about the night.
+    await writeFile(join(storeDir, 'pool-nightly.json'), `${JSON.stringify({ at: new Date(at).toISOString(), ...result })}\n`, 'utf8').catch(() => undefined);
+};
+/** Whether the pool says this account has accepted the covenant now in force. Anything else, a closed pool and a refusal included, is no. */
+const accepted = async (deps, server, token, via) => {
+    const reply = await ask(deps, DEPOSIT, server, '/v1/covenant', { token }, via);
+    return reply.status === 200 && isObject(reply.body) && textIn(reply.body, 'version') !== undefined && Reflect.get(reply.body, 'accepted') === true;
+};
+const night = async (deps, net, tally) => {
+    const none = (outcome) => ({ outcome, batches: 0, raw: 0 });
+    let server;
+    try {
+        server = poolServer(deps.env, DEPOSIT);
+    }
+    catch {
+        return none('no-server');
+    }
+    const { storeDir } = runtimeOf(deps);
+    let token;
+    try {
+        ({ token } = await signedIn(deps, storeDir, server, DEPOSIT));
+    }
+    catch {
+        return none('not-signed-in');
+    }
+    if (vocabularyExpired(deps) !== undefined)
+        return none('failed');
+    if (!(await accepted(deps, server, token, net)))
+        return none('not-accepted');
+    const outbox = outboxFolder(storeDir, server);
+    tally.outcome = 'sent';
+    // One sender at a time per outbox, the lock `deposit --send` takes: a second run waits, then finds `sent.log` full and sends nothing twice.
+    await withSendLock(outbox, async () => {
+        // The outbox is built only for an account that has accepted, then sent: the same gates `oars pool deposit` runs, so nothing queues that a person could not print.
+        await poolDeposit(deps, { server });
+        const done = await sentHashes(outbox);
+        for (const batch of (await heldBatches(outbox)).batches) {
+            if (done.has(batch.hash))
+                continue;
+            // Acceptance is the consent, so nothing was printed first; the file is still read and hashed again just before the request.
+            const locked = await lockedBatch(outbox, batch.hash, { requireShown: false });
+            if (!locked.ok)
+                continue;
+            await postBatch(deps, { server, token, bytes: locked.bytes, hash: batch.hash, via: net });
+            await markSent(outbox, batch.hash, deps.now());
+            tally.batches += 1;
+        }
+        // Raw goes only with its own yes, read again here so an answer changed since the build wins.
+        if ((await readState(storeDir)).pool.rawConsent === 'granted') {
+            for (const copy of (await heldRaw(outbox)).copies) {
+                if (done.has(copy.hash) || copy.bytes === 0)
+                    continue;
+                await postRaw(deps, { server, token, hash: copy.hash, body: copy.body, bytes: copy.bytes, via: net });
+                await markSent(outbox, copy.hash, deps.now());
+                tally.raw += 1;
+            }
+        }
+    });
+    return tally;
+};
+export const nightlyPoolSend = async (deps, via) => {
+    // The tally is filled as sends land, so a night that fails halfway still records what it did send.
+    const tally = { outcome: 'failed', batches: 0, raw: 0 };
+    let result;
+    try {
+        result = await night(deps, via ?? networkSender(deps, DEPOSIT), tally);
+    }
+    catch {
+        result = { ...tally, outcome: 'failed' };
+    }
+    await record(runtimeOf(deps).storeDir, result, deps.now());
+    return result;
+};

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

@@ -0,0 +1,76 @@
+/** 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;
+/** The most bytes one request of a deposit carries. The pool refuses a request past 1 MiB, so a batch past this goes in parts, each of them under that cap. */
+export declare const PART_BYTES: number;
+/**
+ * The batch cut into parts of at most `limit` UTF-8 bytes, never inside a character, so the parts join back to exactly the bytes that were hashed. A batch within the limit is one part.
+ */
+export declare const partsOf: (bytes: string, limit?: number) => 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;
+    bytes: number;
+}>;
+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 a 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. The nightly task sends with `requireShown: false`,
+ * because covenant acceptance is its consent and it prints nothing; the other two checks still hold.
+ */
+export declare const lockedBatch: (outbox: string, hash: string, options?: {
+    stamp?: string;
+    requireShown?: boolean;
+}) => 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[];