@manyoars/oars 0.4.1 → 0.5.2

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

@@ -52,3 +52,10 @@ export interface Carried {
  * 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>;
+/** The delta entries the batch under `key` in this outbox already carries; none when it has no batch, or one this reader does not take. */
+export declare const heldDeltas: (outbox: string, key: string) => Promise<DeltaEntry[]>;
+/**
+ * What a machine's Stop writes for the one open session it builds again: the deltas its own earlier batch carried, then the new ones. A session keeps exactly what its own batch carried, so the batch that replaces its own never loses a delta, and one that did
+ * not carry a held delta never takes it, whichever session fills the window now. A delta that appears in both (a batch written before its mark was) is written once.
+ */
+export declare const keptDeltas: (held: readonly DeltaEntry[], fresh: readonly DeltaEntry[]) => DeltaEntry[];

package/dist/sessions/pool-delta.js

@@ -1,8 +1,9 @@
-import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { isMissing } from './pool-outbox.js';
+import { heldBatchOf, isMissing } from './pool-outbox.js';
+import { appendOwnerOnly, mkdirOwnerOnly } from './owner-only.js';
 import { contentHash } from './read.js';
-import { bucketOf, PACKAGE_REGISTRIES } from './pool-wire.js';
+import { bucketOf, PACKAGE_REGISTRIES, parseSkeleton } 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
@@ -157,8 +158,8 @@ export const sentDeltas = async (outbox) => {
 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');
+    await mkdirOwnerOnly(outbox);
+    await appendOwnerOnly(join(outbox, MARKS_FILE), marks.map((mark) => `${mark}\n`).join(''));
 };
 /** 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) => {
@@ -188,3 +189,25 @@ export const carriedDeltas = (account, sessions, sent) => {
     }
     return carried;
 };
+/** The delta entries the batch under `key` in this outbox already carries; none when it has no batch, or one this reader does not take. */
+export const heldDeltas = async (outbox, key) => {
+    const held = await heldBatchOf(outbox, key);
+    if (held === undefined)
+        return [];
+    const parsed = parseSkeleton(JSON.parse(held.bytes));
+    return parsed.ok ? parsed.skeleton.deltas : [];
+};
+/**
+ * What a machine's Stop writes for the one open session it builds again: the deltas its own earlier batch carried, then the new ones. A session keeps exactly what its own batch carried, so the batch that replaces its own never loses a delta, and one that did
+ * not carry a held delta never takes it, whichever session fills the window now. A delta that appears in both (a batch written before its mark was) is written once.
+ */
+export const keptDeltas = (held, fresh) => {
+    const seen = new Set();
+    return [...held, ...fresh].filter(({ deltaKind, field, name, registry, metric, change }) => {
+        const identity = JSON.stringify([deltaKind, field, name, registry, metric, change]);
+        if (seen.has(identity))
+            return false;
+        seen.add(identity);
+        return true;
+    });
+};

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

@@ -0,0 +1,43 @@
+/** The part of `child_process.spawn` the sender start uses, so a test can hand in a child that never starts or one that fails to. */
+export type SenderSpawn = (command: string, args: string[], options: {
+    detached: true;
+    stdio: 'ignore';
+    windowsHide: true;
+    cwd: string;
+}) => {
+    on: (event: 'error', listener: (error: Error) => void) => unknown;
+    unref: () => void;
+};
+/** The debounce: a sweep is started at most once in this long. */
+export declare const SEND_EVERY_MS: number;
+export type CatchUpResult = 'started' | 'not-due' | 'claimed' | 'not-ready' | 'failed';
+export interface CatchUpDeps {
+    storeDir: string;
+    now: () => number;
+    /** Whether this machine has a session store the person made (a deposit or a hook install ran): nothing is swept into a store nobody asked for. */
+    ready: () => Promise<boolean>;
+    /** Starts the sender detached and returns at once; nothing waits for it. */
+    start: () => void;
+}
+/** True once the person ran `oars sessions hook install --schedule off` and has not run `--schedule on` since. A record that cannot be read or parsed counts as no opt-out. */
+export declare const scheduleOptedOut: (storeDir: string) => Promise<boolean>;
+/** Records the choice of `--schedule`: `off` writes the opt-out; `on` clears it. */
+export declare const recordSchedule: (storeDir: string, mode: "on" | "off") => Promise<void>;
+/** One masked line in `pool-send.log`, the place a failure of the trigger or the sender goes. Never throws. */
+export declare const logFailure: (storeDir: string, at: number, error: unknown) => Promise<void>;
+/**
+ * Never throws. Bound: the claim is per window and the mark is written after it, so two callers on either side of an hour boundary can both start a sender in the worst case; the send lock
+ * (`pool-send-lock.ts`) makes the second sender wait for the first, so nothing is posted twice.
+ */
+export declare const catchUp: (deps: CatchUpDeps) => Promise<CatchUpResult>;
+/** What the hook and the command line call: the check on the real store, clock, and spawner, with the sender being `hook-bin.js nightly`. Never throws, and returns once the sender is started. */
+export declare const catchUpOnStore: (storeDir: string, hookBin: string, now?: () => number, start?: SenderSpawn) => Promise<CatchUpResult>;
+/** What the session-end hook calls after its deposit: the same check, returning once the sender is started and writing nothing to stdout (the hook's output is its deposit's, unchanged). */
+export declare const afterStop: (storeDir: string, hookBin: string, now?: () => number, start?: SenderSpawn) => Promise<CatchUpResult>;
+/** The store counts once `state.json` is there and the person has not opted out with `--schedule off`. */
+export declare const storeReady: (storeDir: string) => (() => Promise<boolean>);
+/**
+ * Starts `node <hook-bin> nightly` detached with no stdio and never waits for it, as telemetry's sender and the gate's helper are started. The sender inherits this process's environment but runs in the home folder, so it never holds the caller's project folder or worktree open (Windows cannot remove a folder that is a running process's working directory). A child that cannot
+ * start (its `error` event) is written to `pool-send.log` like any other failure; the retry is the next trigger after the debounce.
+ */
+export declare const startSender: (hookBin: string, storeDir: string, now: () => number, start?: SenderSpawn) => (() => void);

package/dist/sessions/pool-due.js

@@ -0,0 +1,113 @@
+// The one due check behind every trigger. oars installs no OS scheduler: the SessionEnd hook, after its deposit, and any `oars` command call `catchUp`, which decides whether a sweep and
+// send is due (at most about hourly) and starts it detached, so the caller never waits and its exit code and output never change. The detached process is `hook-bin.js nightly` (the name
+// is the persisted trigger word in the step log): it deposits every harness the person allowed, including those with no session-end hook, derives, sends telemetry when telemetry is on,
+// and sends the pool outbox after the covenant is accepted; each of those gates itself, so a start by this check sends nothing a person has not agreed to.
+// Fail-open: an error is written to `pool-send.log` in the session store (masked, one line). The mark is written before the start, so a failed start is retried by the next trigger after the debounce, about an hour later.
+import { spawn } from 'node:child_process';
+import { appendFile, mkdir, open, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { errorLine } from './steps.js';
+/** The debounce: a sweep is started at most once in this long. */
+export const SEND_EVERY_MS = 60 * 60 * 1000;
+const MARK = 'pool-due.json';
+const LOG = 'pool-send.log';
+const CLAIM = /^pool-due\.(\d+)\.claim$/;
+/** Where `--schedule off` is remembered: a file of its own in the sessions store, because `state.json` is rewritten whole by every deposit. */
+const OPT_OUT = 'schedule.json';
+/** True once the person ran `oars sessions hook install --schedule off` and has not run `--schedule on` since. A record that cannot be read or parsed counts as no opt-out. */
+export const scheduleOptedOut = async (storeDir) => {
+    try {
+        const parsed = JSON.parse(await readFile(join(storeDir, OPT_OUT), 'utf8'));
+        return typeof parsed === 'object' && parsed !== null && Reflect.get(parsed, 'schedule') === 'off';
+    }
+    catch {
+        return false;
+    }
+};
+/** Records the choice of `--schedule`: `off` writes the opt-out; `on` clears it. */
+export const recordSchedule = async (storeDir, mode) => {
+    if (mode === 'on') {
+        await rm(join(storeDir, OPT_OUT), { force: true });
+        return;
+    }
+    await mkdir(storeDir, { recursive: true });
+    await writeFile(join(storeDir, OPT_OUT), `${JSON.stringify({ schedule: 'off' })}\n`, { encoding: 'utf8', mode: 0o600 });
+};
+/** One masked line in `pool-send.log`, the place a failure of the trigger or the sender goes. Never throws. */
+export const logFailure = async (storeDir, at, error) => {
+    const line = await errorLine(storeDir, error).catch(() => 'unknown error');
+    await mkdir(storeDir, { recursive: true }).then(() => appendFile(join(storeDir, LOG), `${new Date(at).toISOString()} ${line}\n`, 'utf8')).catch(() => undefined);
+};
+/** When the last sender was started; a missing, unreadable, or future mark is no mark. */
+const lastStart = async (storeDir, now) => {
+    try {
+        const parsed = JSON.parse(await readFile(join(storeDir, MARK), 'utf8'));
+        const at = typeof parsed === 'object' && parsed !== null ? Reflect.get(parsed, 'startedAt') : undefined;
+        return typeof at === 'number' && at <= now ? at : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * One caller per window wins: the claim is a file named for the window and created with `wx`, so two callers in one window (two hooks that end together, a hook and a command) cannot both
+ * create it. Claims of earlier windows are swept away by the winner.
+ */
+const claim = async (storeDir, window) => {
+    try {
+        await (await open(join(storeDir, `pool-due.${String(window)}.claim`), 'wx')).close();
+    }
+    catch (error) {
+        if (error instanceof Error && Reflect.get(error, 'code') === 'EEXIST')
+            return false;
+        throw error;
+    }
+    for (const name of await readdir(storeDir)) {
+        const found = CLAIM.exec(name);
+        if (found !== null && Number(found[1]) < window)
+            await rm(join(storeDir, name), { force: true });
+    }
+    return true;
+};
+/**
+ * Never throws. Bound: the claim is per window and the mark is written after it, so two callers on either side of an hour boundary can both start a sender in the worst case; the send lock
+ * (`pool-send-lock.ts`) makes the second sender wait for the first, so nothing is posted twice.
+ */
+export const catchUp = async (deps) => {
+    try {
+        if (!(await deps.ready()))
+            return 'not-ready';
+        const now = deps.now();
+        const last = await lastStart(deps.storeDir, now);
+        if (last !== undefined && now - last < SEND_EVERY_MS)
+            return 'not-due';
+        if (!(await claim(deps.storeDir, Math.floor(now / SEND_EVERY_MS))))
+            return 'claimed';
+        await writeFile(join(deps.storeDir, MARK), `${JSON.stringify({ startedAt: now })}\n`, 'utf8');
+        deps.start();
+        return 'started';
+    }
+    catch (error) {
+        // The mark is already written when the start itself failed; the debounce holds until SEND_EVERY_MS after the mark, and the next trigger after that retries.
+        await logFailure(deps.storeDir, deps.now(), error);
+        return 'failed';
+    }
+};
+/** What the hook and the command line call: the check on the real store, clock, and spawner, with the sender being `hook-bin.js nightly`. Never throws, and returns once the sender is started. */
+export const catchUpOnStore = (storeDir, hookBin, now = Date.now, start = spawn) => catchUp({ storeDir, now, ready: storeReady(storeDir), start: startSender(hookBin, storeDir, now, start) });
+/** What the session-end hook calls after its deposit: the same check, returning once the sender is started and writing nothing to stdout (the hook's output is its deposit's, unchanged). */
+export const afterStop = (storeDir, hookBin, now = Date.now, start = spawn) => catchUpOnStore(storeDir, hookBin, now, start);
+/** The store counts once `state.json` is there and the person has not opted out with `--schedule off`. */
+export const storeReady = (storeDir) => async () => (await stat(join(storeDir, 'state.json')).then(() => true, () => false)) && !(await scheduleOptedOut(storeDir));
+/**
+ * Starts `node <hook-bin> nightly` detached with no stdio and never waits for it, as telemetry's sender and the gate's helper are started. The sender inherits this process's environment but runs in the home folder, so it never holds the caller's project folder or worktree open (Windows cannot remove a folder that is a running process's working directory). A child that cannot
+ * start (its `error` event) is written to `pool-send.log` like any other failure; the retry is the next trigger after the debounce.
+ */
+export const startSender = (hookBin, storeDir, now, start = spawn) => () => {
+    const child = start(process.execPath, [hookBin, 'nightly'], { detached: true, stdio: 'ignore', windowsHide: true, cwd: homedir() });
+    child.on('error', (error) => {
+        void logFailure(storeDir, now(), error);
+    });
+    child.unref();
+};

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

@@ -1,10 +1,18 @@
 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 type NightlyOutcome = 'no-server' | 'machine' | 'not-signed-in' | 'not-accepted' | 'failed' | 'sent';
 export interface NightlyPool {
     outcome: NightlyOutcome;
     /** Batches and raw copies this night sent. */
     batches: number;
     raw: number;
+    /** Pulled batches the pool refused for its closed vocabulary or its format this night: each stays in the outbox, unsent, and is asked again the next night. Set only when there were some. */
+    refused?: number;
+    /** Pulled batches removed this night because they now hold a term of the exclusion file. Set only when there were some. */
+    removed?: number;
+    /** Set when a raw yes was held back because it was given under another covenant than the one in force; `oars pool raw --consent yes` answers for the covenant now in force. The sender prints nothing, so this note is where it shows. */
+    rawHeld?: true;
 }
+/** One night's send. `nightlyPoolSend` folds what it throws into a note, so a test reads the thrown error here. */
+export declare const night: (deps: RunDeps, net: Sender, tally: NightlyPool) => Promise<NightlyPool>;
 export declare const nightlyPoolSend: (deps: RunDeps, via?: Sender) => Promise<NightlyPool>;

package/dist/sessions/pool-nightly.js

@@ -1,24 +1,30 @@
-// 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.
+// The detached sender (`hook-bin.js nightly`). After the person has accepted the pool's covenant, the sender 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 { CliError } from '../errors.js';
+import { machineOf } from './machine.js';
+import { ask, currentTerms, DEPOSIT, isObject, networkSender, poolDeposit, poolServer, postBatch, postRaw, runtimeOf, signedIn, textIn, vocabularyExpired } from './pool-command.js';
+import { rawStale } from './pool-choices.js';
+import { heldAcross, lockedBatch, outboxFolder, rescanPulled } 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 { markSent, retirePulled, 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. */
+/** The covenant version in force when the pool says this account has accepted it. Anything else, a closed pool and a refusal included, is `undefined`. */
 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;
+    return reply.status === 200 && isObject(reply.body) && Reflect.get(reply.body, 'accepted') === true ? textIn(reply.body, 'version') : undefined;
 };
-const night = async (deps, net, tally) => {
+/** The pool's 422 for a value or a format its closed vocabulary does not read (a format older than it reads is the same code, on the field `format`). */
+const isVocabularyRefusal = (error) => error instanceof CliError && error.problem.code === 'closed_vocabulary';
+/** One night's send. `nightlyPoolSend` folds what it throws into a note, so a test reads the thrown error here. */
+export const night = async (deps, net, tally) => {
     const none = (outcome) => ({ outcome, batches: 0, raw: 0 });
     let server;
     try {
@@ -27,6 +33,9 @@ const night = async (deps, net, tally) => {
     catch {
         return none('no-server');
     }
+    // A machine's batches wait in the outbox: its Stop builds them for open sessions and allow-listed repositories only, and none of that is checked here, so this sender must never post them.
+    if (machineOf(deps.env) !== undefined)
+        return none('machine');
     const { storeDir } = runtimeOf(deps);
     let token;
     try {
@@ -37,32 +46,67 @@ const night = async (deps, net, tally) => {
     }
     if (vocabularyExpired(deps) !== undefined)
         return none('failed');
-    if (!(await accepted(deps, server, token, net)))
+    const version = await accepted(deps, server, token, net);
+    if (version === undefined)
         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 });
+        await poolDeposit(deps, { server, covenant: version });
         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;
+        // The current stamp's batches, then those `hold pull` filed under another stamp that outlived a vocabulary or field-list change.
+        // A pulled batch can wait as long as the covenant stays closed, so each pass reads it against the term file as it is now: one that holds a term goes, and with no terms none is sent.
+        const scan = await rescanPulled(outbox, await currentTerms(deps));
+        if (scan.removed.length > 0)
+            tally.removed = scan.removed.length;
+        let ended;
+        try {
+            for (const batch of (await heldAcross(outbox)).batches) {
+                if (done.has(batch.hash) || (batch.pulled && !scan.open))
+                    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, stamp: batch.stamp });
+                if (!locked.ok)
+                    continue;
+                try {
+                    await postBatch(deps, { server, token, bytes: locked.bytes, hash: batch.hash, via: net });
+                }
+                catch (error) {
+                    // A pulled batch cannot be rebuilt (its raw is gone), and one the pool no longer reads must not stop the batches after it on every night: it stays, unsent and unmarked, and the note counts it.
+                    if (batch.pulled && isVocabularyRefusal(error)) {
+                        tally.refused = (tally.refused ?? 0) + 1;
+                        continue;
+                    }
+                    throw error;
+                }
+                await markSent(outbox, batch.hash, deps.now());
+                tally.batches += 1;
+            }
+        }
+        catch (error) {
+            ended = { error };
+        }
+        // A pulled batch whose hash is in `sent.log` is done, however the night ended. A `pulled.json` that cannot be read now must not replace the error that ended the loop; after a clean loop it is the night's error.
+        try {
+            await retirePulled(outbox, 'pool-nightly');
+        }
+        catch (error) {
+            if (ended === undefined)
+                throw error;
         }
+        if (ended !== undefined)
+            throw ended.error;
         // 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') {
+        const choices = (await readState(storeDir)).pool;
+        if (rawStale(choices, version))
+            tally.rawHeld = true;
+        if (choices.rawConsent === 'granted' && !rawStale(choices, version)) {
             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 postRaw(deps, { server, token, hash: copy.hash, body: copy.body, bytes: copy.bytes, consent: version, via: net });
                 await markSent(outbox, copy.hash, deps.now());
                 tally.raw += 1;
             }

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

@@ -31,7 +31,7 @@ export declare const writeBatch: (outbox: string, key: string, batch: unknown, s
 }>;
 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>;
+export declare const removeBatchesExcept: (outbox: string, kept: ReadonlySet<string> | (() => Promise<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. */
@@ -39,20 +39,40 @@ export declare const unchangedBytes: (file: string, hash: string) => Promise<str
 export interface Held {
     /** The session's key in the outbox (the batch's account-hashed id). */
     key: string;
+    /** The stamp folder the batch is filed under. */
+    stamp: string;
+    /** Whether `oars pool hold pull` admitted it (its key is listed in `pulled.json` at this stamp), as against a batch this machine built. */
+    pulled: boolean;
     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. */
+/**
+ * The batches filed under this stamp, 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. Under the current stamp that is every batch this client built;
+ * under any other stamp it is only a batch `pulled.json` lists there, since anything else in that folder is stale and is never printed or sent.
+ */
 export declare const heldBatches: (outbox: string, stamp?: string) => Promise<{
     batches: Held[];
     edited: number;
 }>;
+/** The stamps a send reads: the current one, then every other stamp `pulled.json` lists. A listed name that is not a stamp folder is not a path this reads. */
+export declare const sendStamps: (outbox: string) => Promise<string[]>;
+/** `heldBatches` over every stamp a send reads, the current one first. */
+export declare const heldAcross: (outbox: string) => Promise<{
+    batches: Held[];
+    edited: number;
+}>;
+/** The held batch of one session under this stamp, read whole only when its file still hashes to its name; undefined when the session has none, or its file was edited. */
+export declare const heldBatchOf: (outbox: string, key: string, stamp?: string) => Promise<Omit<Held, "stamp" | "pulled"> | undefined>;
+/** The batch keys a machine's Stop built, one per line. A person's `oars pool deposit` shares the outbox and cannot recompute them (the machine's name is in the key), so its sweep keeps these instead of treating them as batches of sessions the store lost. */
+export declare const machineKeys: (outbox: string) => Promise<Set<string>>;
+/** Notes that a machine built this key; a key already noted adds no line. */
+export declare const noteMachineKey: (outbox: string, key: string) => Promise<void>;
 /** 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`,
+ * 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 detached sender (hook-bin.js nightly) 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?: {
@@ -66,11 +86,37 @@ export declare const lockedBatch: (outbox: string, hash: string, options?: {
     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. */
+/** The batches `oars pool hold pull` admitted and has not seen sent: each `id` (the outbox key) and the stamp folder it is filed under. */
+export interface Pulled {
+    [id: string]: string;
+}
+/** `pulled.json` as it stands; none when the file is missing. A file that is not a list of ids and stamps fails the command that reads it, so nothing is pruned or sent on a guess. */
+export declare const readPulled: (outbox: string, step: string) => Promise<Pulled>;
+/** Staged and renamed, so a crash leaves the whole old file or the whole new one. */
+export declare const writePulled: (outbox: string, pulled: Pulled) => Promise<void>;
+/** Whether any string or key in `value` holds one of `terms`, compared lowercased the way the local gate compares a transcript. */
+export declare const holdsTerm: (value: unknown, terms: readonly string[]) => boolean;
+/**
+ * The exclusion rescan of a send pass: every pulled batch is read against the trusted machine's current term file, and one that now holds a term is removed, with its `pulled.json` entry, and its hash returned. A batch can wait as long as the covenant
+ * stays closed, so the terms it was admitted under may not be the terms now. With no terms (a missing or empty file) nothing can be checked: `open` is false, nothing is removed, and the caller sends no pulled batch.
+ */
+export declare const rescanPulled: (outbox: string, terms: readonly string[]) => Promise<{
+    open: boolean;
+    removed: string[];
+}>;
+/** The keys `pulled.json` lists at this stamp: the batches of that folder that no local build made and no stale pass may touch. */
+export declare const pulledAt: (outbox: string, stamp?: string) => Promise<Set<string>>;
+/** `lockedBatch` over every stamp a send reads: the first stamp that holds the hash answers, whether it locks or refuses. */
+export declare const lockedAcross: (outbox: string, hash: string, options?: {
+    requireShown?: boolean;
+}) => ReturnType<typeof lockedBatch>;
+/** The name of a stamp folder: a vocabulary version, then eight hex digits of the field list and format. No dot or slash, so a name that matches is one path segment. */
+export declare const STAMP_FOLDER: RegExp;
+/** Batches in one server's outbox that were built under another vocabulary, field list, or skeleton format: never printed, never sent. A pulled batch is not one of them, at the stamp it is listed under. */
 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. */
+/** Removes one server's stale batches, and returns how many there were. A folder that holds a pulled batch loses only the files of the others; one that holds none goes whole. */
 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[];