@animalabs/agent-framework 0.23.2 → 0.24.0

package/dist/src/recovery/discord-awareness-outbox.js

@@ -1,354 +1,1261 @@
-import { mkdirSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
+import { readFileSync } from 'node:fs';
+import { mkdir, open, rename, unlink } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { OperatorActionError } from '../operator-log.js';
+/**
+ * Discord awareness marks: a reaction (💤 by default) that an operator may
+ * choose to place on Discord messages a surgery removed from a resident's
+ * context, so the people who wrote them can see the resident no longer has
+ * them in view.
+ *
+ * Marks are an explicit publication choice, separate from the surgery itself
+ * (`DiscordAwarenessMarks`, default `none`). Once requested, they are
+ * one-shot: branch moves and restarts never derive new requests from branch
+ * state, and a restart never activates a surgery's marks. A batch a crash
+ * left prepared is retired at startup, unsent, and the operator redoes the
+ * surgery from its source to choose marks again (see recoverAtStartup).
+ * Requests an activated batch owes go out with any delivery pass, a start's
+ * included. What a restart does finish is an interrupted suppression's body,
+ * on its own branch. An operator retracts or cancels explicitly. A version 2
+ * ledger's batches are kept as history when it is rewritten as version 3,
+ * and the work it had still to do is dropped, none of it sent, since nobody
+ * chose it (see migrateLedger).
+ *
+ * The ledger is a table with one entry per reaction, keyed by (MCPL server
+ * id, channel, message, emoji): what the acts that still stand want of it,
+ * whether Discord is owed a request for that, and what Discord last
+ * answered. It is never a model of what is on Discord: an answer is kept as
+ * an answer, and a request never answered is kept as one that may land,
+ * which nothing takes back. The server id is the configured route to a bot,
+ * not the bot's identity: if the route is re-pointed at another bot, owed
+ * requests act as that bot, and nothing here can detect it.
+ *
+ * Acts are ordered by the ledger's own counter (`moment`), never the clock:
+ * a surgery's marks choice (its prepare), its activation and each retract
+ * take the next moment. Between opposite wishes for one reaction the later
+ * act wins, and an activation never revives a reaction that a retract made
+ * after the surgery's choice decided against, even once that retract is
+ * cancelled.
+ *
+ * One instance is the file's only writer: the running framework, or the
+ * offline recovery while the host is stopped. It keeps the document in
+ * memory, reads the file when it first needs it and again after a write
+ * fails, and answers views from memory. Acts run one at a time, each written
+ * before the next starts: compact JSON to a temporary file, synced, renamed
+ * over the ledger, then the ledger's directory and its parent synced, by the
+ * rule the framework's own recovery files follow (writeRecoveryFile). A
+ * write that activates, completes or retires a batch syncs the store first,
+ * so the ledger never outlives the branch state it relies on. A write that
+ * throws has left the file as it was, and the act's change is dropped with
+ * it; a directory that can't be synced after the rename is reported
+ * (onUnsyncedWrite), and the write stands.
+ */
 export const DEFAULT_DISCORD_AWARENESS_EMOJI = '💤';
+/**
+ * Bound text that came from elsewhere (a Discord error body, a filesystem
+ * error) before it is written to the ledger, logged or returned in a
+ * receipt: the ledger keeps its entries for the store's life, and a server's
+ * error text has no length limit of its own. Head and tail are kept, with
+ * the omitted length stated; a cut never splits a surrogate pair.
+ */
+export function boundDiscordAwarenessText(text, max = 500) {
+    if (text.length <= max)
+        return text;
+    const tailLength = Math.min(100, Math.floor(max / 4));
+    let head = text.slice(0, Math.max(0, max - tailLength - 40));
+    let tail = text.slice(text.length - tailLength);
+    if (/[\uD800-\uDBFF]$/.test(head))
+        head = head.slice(0, -1);
+    if (/^[\uDC00-\uDFFF]/.test(tail))
+        tail = tail.slice(1);
+    return `${head} … [${text.length - head.length - tail.length} chars omitted] … ${tail}`;
+}
+/**
+ * A Discord answer that the reaction can never succeed: the message or
+ * channel is gone or inaccessible, the emoji can't be used, or the message
+ * takes no more reactions (or blocks this one). Retrying cannot help.
+ */
+export function isPermanentDiscordReactionFailure(message) {
+    return /unknown message|unknown channel|unknown emoji|missing access|missing permission|cannot access|maximum number of reactions|reaction was blocked|channel .* not found|message .* not found/i
+        .test(message);
+}
+/**
+ * An operator's request the ledger won't carry out: an unknown batch or
+ * retract request. Nothing was written. Any other error from an operator
+ * control is a failure to read or write the ledger.
+ */
+export class DiscordAwarenessRefusal extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DiscordAwarenessRefusal';
+    }
+}
+/** Where a store's awareness ledger lives: the path every release used. */
 export function defaultDiscordAwarenessOutboxPath(storePath) {
     return join(storePath, 'recovery', 'discord-awareness-outbox.json');
 }
-/** Extract Discord addressing metadata without reading message content. */
 export function extractDiscordAwarenessRefs(messages, forcedServerId) {
     const refs = new Map();
     for (const message of messages) {
-        const metadata = message.metadata ?? {};
-        const channelId = typeof metadata.channelId === 'string' ? metadata.channelId : '';
-        const messageId = typeof metadata.messageId === 'string' ? metadata.messageId : '';
-        const metadataServerId = typeof metadata.serverId === 'string' ? metadata.serverId : '';
-        const serverId = forcedServerId ?? metadataServerId;
-        if (!channelId || !messageId || !serverId)
+        const ref = discordRef(message, forcedServerId);
+        if (ref)
+            refs.set(refKey(ref), ref);
+    }
+    return [...refs.values()];
+}
+/**
+ * A surgery's marks choice as a caller passes it at runtime: `none` (or left
+ * out), or `{ scope: 'addressed' | 'all', refs? }` with each ref a Discord
+ * address. Anything else is refused, never guessed: a bare scope string (the
+ * host/command vocabulary) or a misspelled scope would otherwise skip the
+ * scope filter and mark every addressable message. Each entry point that
+ * takes a choice in this form checks it with this before it plans or
+ * changes anything: the framework's rollback and suppression, and the
+ * offline recovery. host/command's undo by messages takes the bare scope
+ * words instead and refuses any other, and the recovery CLI parses its --marks.
+ */
+export function checkedDiscordAwarenessMarks(marks) {
+    if (marks === undefined || marks === 'none')
+        return 'none';
+    if (marks && typeof marks === 'object' && !Array.isArray(marks)) {
+        const { scope, refs } = marks;
+        const isRef = (ref) => !!ref && typeof ref === 'object'
+            && typeof ref.serverId === 'string'
+            && typeof ref.channelId === 'string'
+            && typeof ref.messageId === 'string';
+        if ((scope === 'addressed' || scope === 'all') && (refs === undefined || (Array.isArray(refs) && refs.every(isRef)))) {
+            return marks;
+        }
+    }
+    throw new OperatorActionError('invalid', `marks must be 'none' or { scope: 'addressed' | 'all', refs? } (got ${boundDiscordAwarenessText(JSON.stringify(marks) ?? String(marks), 200)})`);
+}
+/**
+ * Select the refs a publication choice covers among removed messages.
+ * `addressed` means the message carried the MCPL `chat:addressed` tag (a
+ * mention, a reply to the bot, or a DM, as the server classified it); the
+ * same signal the framework uses for loci and wakes. With `marks.refs`, only
+ * those refs are eligible as well.
+ */
+export function selectDiscordAwarenessRefs(messages, marks, forcedServerId) {
+    const addressable = new Map();
+    for (const message of messages) {
+        const ref = discordRef(message, forcedServerId);
+        if (!ref)
             continue;
-        const isDiscord = serverId.toLowerCase().includes('discord') || channelId.startsWith('discord:');
-        if (!isDiscord)
+        const key = refKey(ref);
+        const addressed = isAddressed(message);
+        const existing = addressable.get(key);
+        addressable.set(key, { ref, addressed: addressed || existing?.addressed === true });
+    }
+    if (marks === 'none') {
+        return { refs: [], addressable: addressable.size, unmarked: addressable.size, notRemoved: 0 };
+    }
+    const authorized = marks.refs ? new Set(marks.refs.map(refKey)) : null;
+    const refs = [];
+    for (const [key, candidate] of addressable) {
+        if (marks.scope === 'addressed' && !candidate.addressed)
             continue;
-        const ref = { serverId, channelId, messageId };
-        refs.set(refKey(ref), ref);
+        if (authorized && !authorized.has(key))
+            continue;
+        refs.push(candidate.ref);
     }
-    return [...refs.values()];
+    const notRemoved = authorized
+        ? [...authorized].filter((key) => !addressable.has(key)).length
+        : 0;
+    return { refs, addressable: addressable.size, unmarked: addressable.size - refs.length, notRemoved };
+}
+function discordRef(message, forcedServerId) {
+    const metadata = message.metadata ?? {};
+    const channelId = typeof metadata.channelId === 'string' ? metadata.channelId : '';
+    const messageId = typeof metadata.messageId === 'string' ? metadata.messageId : '';
+    const metadataServerId = typeof metadata.serverId === 'string' ? metadata.serverId : '';
+    const serverId = forcedServerId ?? metadataServerId;
+    if (!channelId || !messageId || !serverId)
+        return null;
+    const isDiscord = serverId.toLowerCase().includes('discord') || channelId.startsWith('discord:');
+    if (!isDiscord)
+        return null;
+    return { serverId, channelId, messageId };
+}
+function isAddressed(message) {
+    const tags = message.metadata?.tags;
+    return Array.isArray(tags) && tags.includes('chat:addressed');
 }
 /**
- * A branch-independent, durable operation ledger for Discord awareness marks.
- *
- * Completed entries are retained. Reconciliation derives whether their emoji
- * should currently exist from Chronicle branch ancestry, queuing `remove`
- * after switching away from a recovery branch and `add` when returning to it.
+ * Unconfirmed attempts (Discord refused it, or no answer came, so it may
+ * have landed) at what one act owes, after which nothing more is sent for
+ * it. An attempt refused before it left the host (`not-sent`) isn't
+ * counted. Without a bound, a refusal Discord repeats, or a server that
+ * never answers, would be sent again at every drain.
+ */
+const MAX_UNCONFIRMED_ATTEMPTS = 3;
+/**
+ * The durable awareness-mark ledger (see the module comment). Writing calls
+ * are async and resolve once their write is on disk; each runs alone. Views
+ * are synchronous, from memory: one made while a write is in progress sees
+ * the act that write records.
  */
 export class DiscordAwarenessOutbox {
     path;
-    constructor(path) {
+    store;
+    /** Told what a version 2 ledger's rewrite drops, before it is written. */
+    announceImport;
+    /** Told of a directory that couldn't be synced after a write's rename. */
+    onUnsyncedWrite;
+    /** The document, or null until it is read, and after a failed write
+     *  whose file couldn't be read back: the next read tries again. */
+    state = null;
+    /** The tail of the acts queued so far: each act starts after it. */
+    queue = Promise.resolve();
+    /**
+     * @param path the ledger file (defaultDiscordAwarenessOutboxPath under a store).
+     * @param opts.store the store whose branch state activations, completions
+     *   and retirements rely on, synced before each is written.
+     * @param opts.announceImport told, before a version 2 ledger is rewritten
+     *   as version 3, which batches' undelivered work that drops, none of it sent.
+     * @param opts.onUnsyncedWrite told of a directory that couldn't be synced
+     *   after a write's rename: the write stands, though an operating system
+     *   crash could lose it. Logged to stderr when not given.
+     */
+    constructor(path, opts = {}) {
         this.path = path;
+        if (opts.store)
+            this.store = opts.store;
+        if (opts.announceImport)
+            this.announceImport = opts.announceImport;
+        this.onUnsyncedWrite = opts.onUnsyncedWrite ?? ((directory, error) => {
+            console.error(`[discord-awareness] ${unsyncedWriteText(directory, path, error)}`);
+        });
     }
-    prepare(input) {
+    // -- surgery side -----------------------------------------------------------
+    /**
+     * Record a surgery's choice before its body change. Returns null when it
+     * carries neither marks nor a suppression's removals. A prepared batch
+     * never delivers: only its surgery's activate() does. If its write fails it
+     * throws, saying what the ledger may hold (failedPrepare), and the surgery
+     * doesn't run.
+     */
+    async prepare(input) {
         const refs = dedupeRefs(input.refs);
         if (refs.length === 0 && !input.suppressionIntervals?.length)
             return null;
-        const document = this.read();
-        const batch = {
-            id: randomUUID(),
-            status: 'prepared',
-            agentName: input.agentName,
-            sourceBranch: input.sourceBranch,
-            targetBranch: input.targetBranch,
-            emoji: input.emoji ?? DEFAULT_DISCORD_AWARENESS_EMOJI,
-            createdAt: Date.now(),
-            refs: refs.map((ref) => ({
-                ...ref,
-                desired: false,
-                markerPresent: false,
-                deliveryStatus: 'applied',
-                attempts: 0,
-            })),
-            activationPolicy: input.activationPolicy ?? 'target-branch',
-            suppressionIntervals: input.suppressionIntervals?.map((interval) => ({ ...interval })),
-        };
-        document.batches.push(batch);
-        this.write(document);
-        return structuredClone(batch);
-    }
-    /** Activate after Chronicle has safely switched to the target branch. */
-    activate(batchId) {
-        const document = this.read();
-        const batch = document.batches.find((candidate) => candidate.id === batchId);
+        return this.act(async (state) => {
+            const batch = {
+                id: randomUUID(),
+                status: 'prepared',
+                agentName: input.agentName,
+                sourceBranch: input.sourceBranch,
+                targetBranch: input.targetBranch,
+                emoji: input.emoji ?? DEFAULT_DISCORD_AWARENESS_EMOJI,
+                createdAt: Date.now(),
+                chosen: ++state.doc.moment,
+                scope: input.scope,
+                refs,
+                ...(input.unmarked ? { unmarked: input.unmarked } : {}),
+                ...(input.notRemoved ? { notRemoved: input.notRemoved } : {}),
+                ...(input.suppressionIntervals?.length
+                    ? { suppressionIntervals: input.suppressionIntervals.map((interval) => ({ ...interval })) }
+                    : {}),
+            };
+            state.doc.batches.push(batch);
+            state.batches.set(batch.id, batch);
+            try {
+                // On disk before the surgery's switch: if the surgery is interrupted,
+                // a start finds the batch, retires it and alerts (recoverAtStartup),
+                // and finishes a suppression's removals. A write that fails leaves
+                // the file without it, so the surgery doesn't run.
+                await this.persist(state);
+            }
+            catch (error) {
+                throw new Error(`recording awareness batch ${batch.id} failed: ${errorText(error)}`, { cause: error });
+            }
+            return structuredClone(batch);
+        });
+    }
+    /**
+     * Activate a prepared batch after its body change landed: each of its
+     * refs is wanted present, and a request is owed for it, on disk before
+     * this returns. Activation completes the surgery's earlier choice; it is
+     * not a new one, so a reaction a retract reached after that choice, even
+     * one cancelled since, keeps what the retract decided. Returns how many
+     * requests it made owed.
+     */
+    async activate(batchId) {
+        return this.act((state) => this.activateIn(state, batchId));
+    }
+    async activateIn(state, batchId) {
+        const batch = state.batches.get(batchId);
         if (!batch)
-            throw new Error(`Discord awareness outbox batch not found: ${batchId}`);
+            throw new Error(`Discord awareness batch not found: ${batchId}`);
+        if (batch.status === 'active')
+            return 0;
+        if (batch.status !== 'prepared')
+            throw new Error(`Discord awareness batch ${batchId} is ${batch.status}, not prepared`);
+        // An operator cancelled it while its surgery was still running.
+        if (batch.cancelled)
+            throw new Error(`Discord awareness batch ${batchId} was cancelled before activation`);
+        const moment = ++state.doc.moment;
         batch.status = 'active';
-        for (const ref of batch.refs)
-            setDesired(ref, true);
-        this.write(document);
+        let queued = 0;
+        for (const ref of batch.refs) {
+            const existing = state.entries.get(markKey(ref, batch.emoji));
+            if (existing?.retracted !== undefined && existing.retracted > batch.chosen)
+                continue;
+            const entry = existing ?? addEntry(state, ref, batch.emoji);
+            if (entry.wanted === 'present') {
+                if (!entry.wantedBy.includes(batch.id))
+                    entry.wantedBy.push(batch.id);
+            }
+            else {
+                entry.wanted = 'present';
+                entry.wantedBy = [batch.id];
+            }
+            owe(entry, moment);
+            queued++;
+        }
+        // The activation asserts the body change just committed (the switch, or
+        // the last redaction): the store is synced first, so a crash can never
+        // leave marks owed for a change the store lost.
+        await this.persist(state, { afterCommittedState: true });
+        return queued;
+    }
+    /**
+     * Activate a batch after its body change landed, and if that cannot be
+     * recorded, retire it instead, so that what the caller reports is what
+     * the ledger will do: `queued`, or `not-scheduled`. A batch that can be
+     * neither activated nor retired stays prepared in the file, since a write
+     * that fails leaves it as it was, and a start retires it, none of its
+     * marks sent: the next start, or for a suppression the first start on its
+     * branch, once it finds the removals applied. Never throws.
+     */
+    async settleActivation(batchId) {
+        try {
+            return await this.act(async (state) => {
+                let detail;
+                try {
+                    return { status: 'queued', queued: await this.activateIn(state, batchId) };
+                }
+                catch (error) {
+                    detail = errorText(error);
+                }
+                // The file is as it was before the activation: the document read
+                // back after a failed write (persist), or unchanged by a refusal.
+                const batch = this.state?.batches.get(batchId);
+                if (batch?.status === 'prepared') {
+                    try {
+                        await this.retireIn(this.state, batchId);
+                    }
+                    catch (error) {
+                        return { status: 'not-scheduled', error: `${detail}; retiring it also failed (${errorText(error)}), so ${leftPrepared(batch)}` };
+                    }
+                    return { status: 'not-scheduled', error: `${detail}; it is retired instead, none of its marks sent` };
+                }
+                else if (!this.state) {
+                    return { status: 'not-scheduled', error: `${detail}; the ledger can't be read back, so ${leftPrepared()}` };
+                }
+                return { status: 'not-scheduled', error: detail };
+            });
+        }
+        catch (error) {
+            // The act never ran: the ledger can't be read.
+            return { status: 'not-scheduled', error: `${errorText(error)}; ${leftPrepared()}` };
+        }
+    }
+    /**
+     * Retire a batch whose surgery did not complete. Only a prepared batch can
+     * be retired; returns false when nothing was.
+     */
+    async discard(batchId) {
+        return this.act(async (state) => {
+            if (state.batches.get(batchId)?.status !== 'prepared')
+                return false;
+            await this.retireIn(state, batchId);
+            return true;
+        });
+    }
+    async retireIn(state, batchId) {
+        state.batches.get(batchId).status = 'retired';
+        // Retiring a batch retires its obligations (marks and any body resume):
+        // the branch state its surgery left (a restored source, or a completed
+        // body) is synced first, so a crash can never keep the retirement while
+        // losing the state it relies on.
+        await this.persist(state, { afterCommittedState: true });
     }
     /**
-     * Retire a batch that was prepared but whose operation did not complete
-     * (fork failed, a removal threw and the source branch was restored). A
-     * prepared batch is armed: it re-fires at boot or on branch switch through
-     * `activatePreparedForBranch` / `preparedSuppressionsForBranch`, and an
-     * un-completable suppression there aborts framework start. Only prepared
-     * batches can be discarded — an active batch owns delivered markers and
-     * must be reconciled, not dropped. Returns false when nothing was removed.
+     * The suppressions whose body a start on `branch` finishes: prepared
+     * batches that name removal intervals, cancelled or not, whose target is
+     * exactly that branch: a surgery's leftovers, or a version 2 ledger's that
+     * agent-framework 0.22.x never activated. Branch ancestry is never
+     * consulted. Throws when the ledger can't be read.
      */
-    discard(batchId) {
-        const document = this.read();
-        const index = document.batches.findIndex((candidate) => candidate.id === batchId);
-        if (index < 0)
-            return false;
-        if (document.batches[index].status !== 'prepared')
-            return false;
-        document.batches.splice(index, 1);
-        this.write(document);
-        return true;
+    pendingSuppressionsFor(branch) {
+        return this.loaded().doc.batches
+            .filter((batch) => isPendingSuppression(batch) && batch.targetBranch === branch)
+            .map((batch) => structuredClone(batch));
     }
     /**
-     * Reconcile every retained ledger entry against the active branch. A marker
-     * is desired when any active batch for the same ref+emoji has a target branch
-     * in the active branch's ancestry.
+     * Retire a suppression's batch once a start on its branch has finished
+     * its removals, none of its marks sent: a restart never activates a
+     * surgery's marks. `announceRetirement` is told before that is written,
+     * for the reason recoverAtStartup's `announce` is. Nothing is written for
+     * a batch that isn't prepared.
      */
-    reconcileForBranch(branchName, branches = []) {
-        const document = this.read();
-        let activated = 0;
-        for (const batch of document.batches) {
-            if (batch.status === 'prepared'
-                && (batch.activationPolicy ?? 'target-branch') === 'target-branch'
-                && isTargetActive(branchName, batch.targetBranch, branches)) {
-                batch.status = 'active';
-                activated++;
+    async completeSuppression(batchId, announceRetirement) {
+        return this.act(async (state) => {
+            if (state.batches.get(batchId)?.status !== 'prepared')
+                return;
+            announceRetirement?.();
+            // Certifies the redactions just made: written only after they are synced.
+            await this.retireIn(state, batchId);
+        });
+    }
+    /**
+     * Startup reconciliation, run once before any delivery. It derives nothing
+     * from branch ancestry, and it activates nothing:
+     * - a request a previous process left on the wire is recorded unanswered
+     *   (recordUnanswered): it may have reached Discord. It counts toward the
+     *   bound like any unanswered attempt, and `givenUp` is how many reactions
+     *   that brought there, which nothing more is sent for;
+     * - a prepared batch, which an interrupted surgery left, or a failed one
+     *   that couldn't retire it, is retired, none of its marks sent: the
+     *   operator redoes the surgery from its source to choose marks again. A
+     *   suppression whose body is pending is kept instead: a start on its
+     *   branch finishes its removals and then retires it (completeSuppression).
+     * Each retirement is reported in `retired`, and the store is synced before
+     * any is written. `announce` is told what it retires and records
+     * unanswered before that is written: each is written once, so a notice
+     * given after the write would be lost for good if the process ended
+     * between the two. If the write doesn't land, the next start says it
+     * again.
+     */
+    async recoverAtStartup(announce) {
+        return this.act(async (state) => {
+            let unknownAttempts = 0;
+            let givenUp = 0;
+            for (const entry of state.doc.entries) {
+                if (!entry.sending)
+                    continue;
+                unknownAttempts++;
+                if (recordUnanswered(entry))
+                    givenUp++;
             }
-        }
-        const desiredKeys = new Set();
-        for (const batch of document.batches) {
-            if (batch.status !== 'active')
-                continue;
-            if (!isTargetActive(branchName, batch.targetBranch, branches))
-                continue;
-            for (const ref of batch.refs)
-                desiredKeys.add(markerKey(batch.emoji, ref));
-        }
-        let queued = 0;
-        for (const batch of document.batches) {
-            if (batch.status !== 'active')
-                continue;
-            for (const ref of batch.refs) {
-                setDesired(ref, desiredKeys.has(markerKey(batch.emoji, ref)));
-                if (ref.deliveryStatus === 'pending')
-                    queued++;
+            const retired = [];
+            for (const batch of state.doc.batches) {
+                if (batch.status !== 'prepared' || isPendingSuppression(batch))
+                    continue;
+                batch.status = 'retired';
+                retired.push({
+                    batchId: batch.id,
+                    agentName: batch.agentName,
+                    sourceBranch: batch.sourceBranch,
+                    targetBranch: batch.targetBranch,
+                    // A version 2 ledger's marks were reported when its rewrite dropped them.
+                    marks: !batch.cancelled && batch.scope !== 'legacy' ? batch.refs.length : 0,
+                    suppression: !!batch.suppressionIntervals?.length,
+                    ...(batch.scope === 'legacy' ? { imported: true } : {}),
+                });
             }
-        }
-        this.write(document);
-        return { activated, queued };
+            announce?.({ retired, unknownAttempts, givenUp });
+            if (unknownAttempts > 0 || retired.length > 0) {
+                await this.persist(state, { afterCommittedState: retired.length > 0 });
+            }
+            return { retired, unknownAttempts, givenUp };
+        });
     }
-    /** Backward-compatible startup helper. */
-    activatePreparedForBranch(branchName, branches = []) {
-        return this.reconcileForBranch(branchName, branches).activated;
+    // -- operator controls ------------------------------------------------------
+    /**
+     * Stop a batch's marks, or a retract's removals (by its request id), from
+     * being sent or sent again: the act is taken out of each reaction it
+     * wants, and a reaction no act wants any more is owed nothing. A request
+     * on the wire still has its answer recorded, before anything else goes for
+     * that reaction. Nothing is ever removed from Discord by a cancel: the
+     * receipt reports what may already have landed, and retract removes it.
+     */
+    async cancel(target, by) {
+        return this.act(async (state) => {
+            const retract = state.retracts.get(target);
+            const batch = state.batches.get(target);
+            if (!retract && !batch) {
+                throw new DiscordAwarenessRefusal(`Discord awareness batch or retract request not found: ${target}; the marks list (listDiscordAwareness()) names them`);
+            }
+            const kind = retract ? 'retract' : 'batch';
+            const subject = (retract ?? batch);
+            const wanted = retract ? 'absent' : 'present';
+            // The reactions the act still wants: those no later act has taken
+            // over. A prepared batch wants none yet, and a cancelled act none any
+            // more.
+            const reached = state.doc.entries.filter((entry) => entry.wantedBy.includes(target));
+            const receipt = {
+                target,
+                kind,
+                cancelled: 0,
+                confirmed: reached.filter((entry) => entry.confirmed === wanted).length,
+                mayStillLand: reached.filter(mayStillLand).length,
+            };
+            // A repeated cancel finds nothing the act still wants, and writes nothing.
+            if (subject.cancelled)
+                return receipt;
+            subject.cancelled = { at: Date.now(), ...(by ? { by } : {}) };
+            if (batch?.status === 'prepared') {
+                // Its surgery is still running, or it was left for a start to
+                // retire: none of its marks was requested, and none will be.
+                receipt.cancelled = batch.refs.length;
+            }
+            else {
+                for (const entry of state.doc.entries) {
+                    const index = entry.wantedBy.indexOf(target);
+                    if (index < 0)
+                        continue;
+                    entry.wantedBy.splice(index, 1);
+                    if (entry.wantedBy.length > 0)
+                        continue;
+                    if (entry.due !== null && entry.attempts === 0 && entry.sending?.due !== entry.due)
+                        receipt.cancelled++;
+                    entry.wanted = null;
+                    entry.due = null;
+                    entry.attempts = 0;
+                }
+            }
+            await this.persist(state);
+            return receipt;
+        });
+    }
+    /**
+     * Remove this bot's mark (through the configured route) from a batch's
+     * refs, or (`all`) from every ref of every batch not retired, whether
+     * prepared or active, and every reaction the ledger holds. That covers
+     * every mark a version 2 ledger recorded: one of its batches that
+     * agent-framework 0.22.x activated stays active, and 0.22.x attempted only
+     * an active batch's refs. A reaction is one per (route, message, emoji),
+     * whichever batches asked for it, so this acts across batches. A removal
+     * is owed for every selected reaction, whatever was answered before: an
+     * answer can't establish what is on Discord now, and removing an absent
+     * reaction does nothing. It is the latest act on those reactions: an add
+     * owed there is replaced, and a batch whose choice came before it, once
+     * activated, leaves them as this decides. The receipt reports the adds
+     * that may still land.
+     */
+    async retract(target, by) {
+        return this.act(async (state) => {
+            const keys = new Map();
+            const select = (ref, emoji) => {
+                keys.set(markKey(ref, emoji), {
+                    serverId: ref.serverId,
+                    channelId: ref.channelId,
+                    messageId: ref.messageId,
+                    emoji,
+                });
+            };
+            if (target === 'all') {
+                for (const batch of state.doc.batches) {
+                    if (batch.status === 'retired')
+                        continue;
+                    for (const ref of batch.refs)
+                        select(ref, batch.emoji);
+                }
+                for (const entry of state.doc.entries)
+                    select(entry, entry.emoji);
+            }
+            else {
+                const batch = state.batches.get(target);
+                if (!batch) {
+                    throw new DiscordAwarenessRefusal(`Discord awareness batch not found: ${target}; the marks list (listDiscordAwareness()) names them, or retract all`);
+                }
+                for (const ref of batch.refs)
+                    select(ref, batch.emoji);
+            }
+            const retract = {
+                id: randomUUID(),
+                target,
+                at: Date.now(),
+                ...(by ? { by } : {}),
+                moment: ++state.doc.moment,
+                keys: keys.size,
+            };
+            const receipt = {
+                requestId: retract.id,
+                removalsQueued: keys.size,
+                addsSuperseded: 0,
+                keysWithUnresolvedAdds: 0,
+            };
+            for (const [key, ref] of keys) {
+                const entry = state.entries.get(key) ?? addEntry(state, ref, ref.emoji);
+                if (entry.wanted === 'present' && entry.due !== null)
+                    receipt.addsSuperseded++;
+                if (entry.sending?.action === 'add' || entry.mayLand?.includes('add'))
+                    receipt.keysWithUnresolvedAdds++;
+                entry.retracted = retract.moment;
+                if (entry.wanted === 'absent')
+                    entry.wantedBy.push(retract.id);
+                else {
+                    entry.wanted = 'absent';
+                    entry.wantedBy = [retract.id];
+                }
+                owe(entry, retract.moment);
+            }
+            state.doc.retracts.push(retract);
+            state.retracts.set(retract.id, retract);
+            await this.persist(state);
+            return receipt;
+        });
+    }
+    // -- delivery ---------------------------------------------------------------
+    /**
+     * The requests owed and not on the wire, oldest act first, for one server
+     * or every one. Throws when the ledger can't be read.
+     */
+    due(serverId) {
+        return owedRequests(this.loaded(), serverId);
+    }
+    /**
+     * Choose a server's next owed request and write it ahead, in one act:
+     * what is owed is read as the ledger holds it now, so a cancel or retract
+     * made while an earlier request was on the wire is never overridden by an
+     * older list. A reaction with a request on the wire is never chosen again
+     * until its answer is written. `skip` excludes requests already tried in
+     * this pass. Resolves once the write-ahead is on disk, with the request to
+     * send, or null when nothing is owed.
+     *
+     * A delivery pass claims only once its last request's answer is written,
+     * so a request of this server still marked on the wire here is one whose
+     * answer couldn't be written. It is recorded as unanswered first, as a
+     * start records one an earlier process left: it may land, and what it
+     * served is owed again.
+     */
+    async claim(serverId, skip = () => false) {
+        return this.act(async (state) => {
+            let released = false;
+            for (const entry of state.doc.entries) {
+                if (entry.sending && entry.serverId === serverId) {
+                    recordUnanswered(entry);
+                    released = true;
+                }
+            }
+            const request = owedRequests(state, serverId).find((candidate) => !skip(candidate));
+            if (!request) {
+                if (released)
+                    await this.persist(state);
+                return null;
+            }
+            const entry = state.entries.get(markKey(request, request.emoji));
+            entry.sending = { action: request.action, due: request.due };
+            await this.persist(state);
+            return request;
+        });
+    }
+    /**
+     * Record a claimed request's answer. An answer ends what is owed only if
+     * it is for the act its request served: one for an older act updates what
+     * Discord last answered, and what may land, alone, so an act made while a
+     * request was out still gets its own request. Resolves to whether this
+     * ended what is owed without a confirmation (refused for good, or at the
+     * third unconfirmed attempt), so nothing more is sent for it.
+     */
+    async recordOutcome(request, outcome, detail = {}) {
+        return this.act(async (state) => {
+            const entry = state.entries.get(markKey(request, request.emoji));
+            if (!entry?.sending || entry.sending.due !== request.due || entry.sending.action !== request.action) {
+                throw new Error(`No ${request.action} for ${request.channelId}/${request.messageId} is on the wire to record an answer for`);
+            }
+            let ended = false;
+            if (outcome === 'confirmed') {
+                delete entry.sending;
+                entry.confirmed = request.action === 'add' ? 'present' : 'absent';
+                if (request.due === entry.due) {
+                    entry.due = null;
+                    entry.attempts = 0;
+                }
+            }
+            else if (outcome === 'unknown') {
+                ended = recordUnanswered(entry);
+            }
+            else {
+                delete entry.sending;
+                // A request refused before it left the host isn't an attempt.
+                if (outcome === 'failed')
+                    ended = countAttempt(entry, request.due, detail.permanent === true);
+            }
+            await this.persist(state);
+            return ended;
+        });
     }
-    pending(serverId) {
-        const operations = [];
-        for (const batch of this.read().batches) {
-            if (batch.status !== 'active')
+    // -- views ------------------------------------------------------------------
+    batches() {
+        return this.loaded().doc.batches.map((batch) => structuredClone(batch));
+    }
+    view() {
+        const state = this.loaded();
+        const views = [];
+        for (const batch of state.doc.batches) {
+            if (batch.status === 'retired')
                 continue;
+            const reactions = emptyCounts();
+            let landing = 0;
             for (const ref of batch.refs) {
-                if (ref.deliveryStatus !== 'pending')
-                    continue;
-                if (serverId !== undefined && ref.serverId !== serverId)
+                const entry = state.entries.get(markKey(ref, batch.emoji));
+                reactions[reactionState(entry)]++;
+                if (entry && mayStillLand(entry))
+                    landing++;
+            }
+            views.push({
+                kind: 'batch',
+                id: batch.id,
+                status: batch.status,
+                scope: batch.scope,
+                agentName: batch.agentName,
+                sourceBranch: batch.sourceBranch,
+                targetBranch: batch.targetBranch,
+                emoji: batch.emoji,
+                createdAt: batch.createdAt,
+                refs: batch.refs.length,
+                ...(batch.unmarked !== undefined ? { unmarked: batch.unmarked } : {}),
+                ...(batch.notRemoved !== undefined ? { notRemoved: batch.notRemoved } : {}),
+                ...(batch.cancelled ? { cancelled: { ...batch.cancelled } } : {}),
+                reactions,
+                mayStillLand: landing,
+                ...(batch.legacyAdded !== undefined ? { legacyAdded: batch.legacyAdded } : {}),
+            });
+        }
+        for (const retract of state.doc.retracts) {
+            const reactions = emptyCounts();
+            let landing = 0;
+            for (const entry of state.doc.entries) {
+                if (!entry.wantedBy.includes(retract.id))
                     continue;
-                operations.push({
-                    batchId: batch.id,
-                    emoji: batch.emoji,
-                    action: ref.desired ? 'add' : 'remove',
-                    ref: { ...ref },
-                });
+                reactions[reactionState(entry)]++;
+                if (mayStillLand(entry))
+                    landing++;
             }
+            views.push({
+                kind: 'retract',
+                id: retract.id,
+                target: retract.target,
+                at: retract.at,
+                ...(retract.by ? { by: retract.by } : {}),
+                ...(retract.cancelled ? { cancelled: { ...retract.cancelled } } : {}),
+                keys: retract.keys,
+                reactions,
+                mayStillLand: landing,
+            });
         }
-        return operations;
-    }
-    recordSuccess(batchId, ref, action) {
-        const document = this.read();
-        const entry = findEntry(document, batchId, ref);
-        if (!entry)
-            return;
-        entry.markerPresent = action === 'add';
-        entry.deliveryStatus = entry.markerPresent === entry.desired ? 'applied' : 'pending';
-        entry.attempts++;
-        entry.lastAction = action;
-        entry.lastAttemptAt = Date.now();
-        delete entry.lastError;
-        this.write(document);
-    }
-    recordFailure(batchId, ref, action, error, permanent) {
-        const document = this.read();
-        const entry = findEntry(document, batchId, ref);
-        if (!entry)
-            return;
-        entry.deliveryStatus = permanent ? 'permanent-failure' : 'pending';
-        entry.attempts++;
-        entry.lastAction = action;
-        entry.lastAttemptAt = Date.now();
-        entry.lastError = error;
-        this.write(document);
-    }
-    /** Compatibility alias for older callers that only acknowledged adds. */
-    acknowledge(batchId, ref) {
-        this.recordSuccess(batchId, ref, 'add');
+        return views;
     }
-    batches() {
-        return structuredClone(this.read().batches);
+    // -- internals --------------------------------------------------------------
+    /**
+     * Run one act after every act queued before it, on the document as it is
+     * then (read first if it isn't held). A version 2 ledger is rewritten as
+     * version 3 by the first act, before the act's own change.
+     */
+    act(fn) {
+        const run = this.queue.then(async () => {
+            const state = this.state ?? await this.open();
+            try {
+                return await fn(state);
+            }
+            catch (error) {
+                // An act that throws has left the file as it was, so whatever it
+                // changed in memory goes too: the document is read back.
+                this.forget();
+                throw error;
+            }
+        });
+        this.queue = run.catch(() => undefined);
+        return run;
     }
-    preparedSuppressionsForBranch(branchName, branches = []) {
-        return structuredClone(this.read().batches.filter((batch) => batch.status === 'prepared'
-            && batch.activationPolicy === 'explicit'
-            && !!batch.suppressionIntervals?.length
-            && isTargetActive(branchName, batch.targetBranch, branches)));
+    /** Drop the document held in memory and read the file back; if it can't
+     *  be read, the next read tries again. */
+    forget() {
+        this.state = null;
+        try {
+            this.loaded();
+        }
+        catch { /* unread: the next read tries again */ }
     }
-    read() {
-        let parsed;
+    /**
+     * Read the ledger for an act. A version 2 ledger is rewritten as version
+     * 3 (migrateLedger), the work it drops announced before the write; the
+     * rewritten document is held only once its write is on disk.
+     */
+    async open() {
+        const read = readLedger(this.path);
+        if (read.version === 3)
+            return (this.state = read.state);
+        const { state, unsent } = migrateLedger(read.document);
+        // Said before it's written: the rewrite is made once, so a notice given
+        // after it would be lost for good if the process ended between the two.
+        // If the write doesn't land, the next act says it again.
+        if (unsent.length > 0) {
+            console.error(`[discord-awareness] rewriting ${this.path} as version 3: ${unsent.length} batch(es) had marks ` +
+                'agent-framework 0.22.x had still to add or remove, and none of them will be sent, since nobody chose them: ' +
+                unsent.map((batch) => `batch ${batch.batchId} (${batch.agentName}, ${batch.sourceBranch} to ` +
+                    `${batch.targetBranch}): ${batch.adds} to add, ${batch.removals} to remove`).join('; ') +
+                '. A batch 0.22.x never activated placed no marks; retracting a batch takes off the mark of its emoji ' +
+                'from each of its messages, whichever batch placed it');
+            this.announceImport?.(unsent);
+        }
+        await writeLedgerFile(this.path, state.doc, this.onUnsyncedWrite);
+        return (this.state = state);
+    }
+    /**
+     * The document for a view: as held, or read now. A version 2 ledger is
+     * refused here: only an act rewrites it.
+     */
+    loaded() {
+        if (this.state)
+            return this.state;
+        const read = readLedger(this.path);
+        if (read.version !== 3) {
+            throw new Error(`Discord awareness ledger ${this.path} is version 2, which its first write rewrites as version 3, at a ` +
+                'start or an offline recovery; nothing is read from it before that');
+        }
+        return (this.state = read.state);
+    }
+    /**
+     * Write the document. A write that throws has left the file as it was, so
+     * the act's change, already made in memory, is dropped: the document is
+     * read back from the file, and if it can't be read, the next read tries
+     * again. `afterCommittedState` syncs the store first.
+     */
+    async persist(state, opts = {}) {
         try {
-            parsed = JSON.parse(readFileSync(this.path, 'utf8'));
+            if (opts.afterCommittedState)
+                this.store?.sync();
+            await writeLedgerFile(this.path, state.doc, this.onUnsyncedWrite);
         }
         catch (error) {
-            if (error.code === 'ENOENT') {
-                return { version: 2, batches: [] };
+            this.forget();
+            throw error;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Entries
+// ---------------------------------------------------------------------------
+function addEntry(state, ref, emoji) {
+    const entry = {
+        serverId: ref.serverId,
+        channelId: ref.channelId,
+        messageId: ref.messageId,
+        emoji,
+        wanted: null,
+        wantedBy: [],
+        due: null,
+        attempts: 0,
+    };
+    state.doc.entries.push(entry);
+    state.entries.set(markKey(ref, emoji), entry);
+    return entry;
+}
+/** An act at `moment` owes Discord a request, whatever was answered before. */
+function owe(entry, moment) {
+    entry.due = moment;
+    entry.attempts = 0;
+    delete entry.failed;
+}
+/**
+ * The request on the wire for this entry went unanswered: its action may
+ * land, or have landed, and what Discord holds is unknown. It counts toward
+ * the bound if it served what is owed now. This is the one place both an
+ * answer the connection couldn't get and a request a previous process left
+ * on the wire (recoverAtStartup) are recorded. Returns whether that ended
+ * what is owed.
+ */
+function recordUnanswered(entry) {
+    const sent = entry.sending;
+    delete entry.sending;
+    const mayLand = entry.mayLand ?? [];
+    if (!mayLand.includes(sent.action))
+        mayLand.push(sent.action);
+    entry.mayLand = mayLand;
+    entry.confirmed = 'unknown';
+    return countAttempt(entry, sent.due, false);
+}
+/**
+ * Count an unconfirmed attempt at what `due` owed. Only an attempt at what
+ * is owed now counts: one for an older act changes nothing owed. Discord's
+ * refusal for good, or the bound, ends what is owed: nothing more is sent
+ * for it, and the entry is `failed` until a new act owes a request.
+ * Returns whether it ended.
+ */
+function countAttempt(entry, due, permanent) {
+    if (due !== entry.due)
+        return false;
+    entry.attempts++;
+    if (!permanent && entry.attempts < MAX_UNCONFIRMED_ATTEMPTS)
+        return false;
+    entry.due = null;
+    entry.failed = true;
+    return true;
+}
+function mayStillLand(entry) {
+    return !!entry.sending || !!entry.mayLand?.length;
+}
+function reactionState(entry) {
+    if (!entry)
+        return 'untouched';
+    if (entry.sending)
+        return 'sending';
+    if (entry.due !== null)
+        return 'queued';
+    if (entry.failed)
+        return 'failed';
+    return entry.confirmed ?? 'untouched';
+}
+/** The requests owed and not on the wire, oldest act first, then in the
+ *  order the ledger first held their reactions. */
+function owedRequests(state, serverId) {
+    const owed = [];
+    for (const entry of state.doc.entries) {
+        if (entry.due === null || entry.sending || entry.wanted === null)
+            continue;
+        if (serverId !== undefined && entry.serverId !== serverId)
+            continue;
+        owed.push({
+            serverId: entry.serverId,
+            channelId: entry.channelId,
+            messageId: entry.messageId,
+            emoji: entry.emoji,
+            action: entry.wanted === 'present' ? 'add' : 'remove',
+            due: entry.due,
+        });
+    }
+    // A stable sort: reactions owed by one act keep the ledger's order.
+    return owed.sort((a, b) => a.due - b.due);
+}
+/** Requests a batch's activation made owed that are still owed. */
+function emptyCounts() {
+    return { queued: 0, sending: 0, present: 0, absent: 0, unknown: 0, failed: 0, untouched: 0 };
+}
+/**
+ * A suppression whose body may still need applying on its target branch: a
+ * prepared batch that names removal intervals. Its surgery's activation
+ * means the body completed, and a retired batch is never resumed: its
+ * surgery gave the body up after putting the source back, or
+ * completeSuppression retired it once a start finished its body. A version
+ * 2 ledger's batch that 0.22.x activated is taken as finished, as 0.22.x
+ * took it.
+ */
+function isPendingSuppression(batch) {
+    return batch.status === 'prepared' && !!batch.suppressionIntervals?.length;
+}
+function errorText(error) {
+    return boundDiscordAwarenessText(error instanceof Error ? error.message : String(error));
+}
+/** What becomes of a batch left prepared after its surgery's body landed:
+ *  none of its marks is ever sent. */
+function leftPrepared(batch) {
+    if (!batch)
+        return 'it stays prepared, and a start that can read the ledger retires it, none of its marks sent';
+    return batch.suppressionIntervals?.length
+        ? `it stays prepared, and the first start on ${batch.targetBranch} finds its removals applied and retires it, none of its marks sent`
+        : 'it stays prepared, and the next start retires it, none of its marks sent';
+}
+// ---------------------------------------------------------------------------
+// The file
+// ---------------------------------------------------------------------------
+/**
+ * Read and check the ledger file: a missing file is an empty ledger. A file
+ * this build can't read for its meaning is refused, never guessed at: one
+ * it can't read or parse, one that isn't the shape its version promises,
+ * and any version but 2 and 3, version 1 with its own reason.
+ */
+function readLedger(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return { version: 3, state: indexed({ version: 3, moment: 0, batches: [], retracts: [], entries: [] }) };
+        }
+        throw new Error(`Could not read Discord awareness ledger ${path}: ${errorText(error)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Invalid Discord awareness ledger ${path}: it isn't JSON`);
+    }
+    const version = !!parsed && typeof parsed === 'object' ? parsed.version : undefined;
+    if (version === 3) {
+        if (!isLedgerDocument(parsed))
+            throw new Error(`Invalid Discord awareness ledger ${path}`);
+        return { version: 3, state: indexed(parsed) };
+    }
+    if (version === 2) {
+        // A ledger the released readers would have refused is refused here too,
+        // never read for a meaning: a malformed field (`activationPolicy:
+        // 'explicit '`) would otherwise retire a suppression whose removals a
+        // start on its branch still owes.
+        if (!isLegacyLedger(parsed))
+            throw new Error(`Invalid Discord awareness ledger ${path}`);
+        return { version: 2, document: parsed };
+    }
+    if (version === 1) {
+        throw new Error(`Discord awareness ledger ${path} is version 1, which only agent-framework commit b16731b2 wrote ` +
+            '(2026-07-15, before any release). Every release rewrites it as version 2 at its next write, and this ' +
+            'build reads versions 2 and 3. Nothing is read from it until the file is moved away. Moving it gives up ' +
+            'only work it still had to send, which this build would retire unsent anyway, since that commit took each ' +
+            'mark out of the file once Discord confirmed it. A mark added just before that process ended, before its ' +
+            'confirmation was written, stays on Discord, and retract can\'t find it');
+    }
+    throw new Error(`Discord awareness ledger ${path} is ${version === undefined ? 'of no version' : `version ${JSON.stringify(version)}`}, ` +
+        'which this build can\'t read: it reads versions 2 and 3');
+}
+function indexed(doc) {
+    return {
+        doc,
+        batches: new Map(doc.batches.map((batch) => [batch.id, batch])),
+        retracts: new Map(doc.retracts.map((retract) => [retract.id, retract])),
+        entries: new Map(doc.entries.map((entry) => [markKey(entry, entry.emoji), entry])),
+    };
+}
+/**
+ * Write the document: compact JSON to a temporary file beside the ledger,
+ * synced, renamed over it, then its directory synced, for the ledger's entry
+ * in it, and that directory's parent, for the directory's own entry, which
+ * is new when a write, this one or an earlier one, had to make it. This is
+ * the framework's writeRecoveryFile rule. A failure before the rename removes
+ * the temporary file and throws, leaving the ledger as it was. A directory
+ * that can't be synced after it is reported, and the write stands: the new
+ * ledger is in place, though an operating system crash could lose it.
+ * Serialized before the first await, so the text is the document as the act
+ * left it.
+ */
+async function writeLedgerFile(path, doc, onUnsynced) {
+    const text = `${JSON.stringify(doc)}\n`;
+    const directory = dirname(path);
+    await mkdir(directory, { recursive: true });
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        const file = await open(temporary, 'w', 0o600);
+        try {
+            await file.writeFile(text, 'utf8');
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await rename(temporary, path);
+    }
+    catch (error) {
+        await unlink(temporary).catch(() => undefined);
+        throw error;
+    }
+    for (const synced of [directory, dirname(directory)]) {
+        try {
+            await syncDirectory(synced);
+        }
+        catch (error) {
+            try {
+                onUnsynced(synced, error);
             }
-            throw new Error(`Could not read Discord awareness outbox ${this.path}: ${error instanceof Error ? error.message : String(error)}`);
+            catch { /* the write stands: a report that fails changes nothing in the file */ }
         }
-        if (isDocumentV2(parsed))
-            return parsed;
-        if (isDocumentV1(parsed))
-            return migrateV1(parsed);
-        throw new Error(`Invalid Discord awareness outbox document: ${this.path}`);
-    }
-    write(document) {
-        mkdirSync(dirname(this.path), { recursive: true });
-        const temporary = `${this.path}.${process.pid}.${randomUUID()}.tmp`;
-        writeFileSync(temporary, `${JSON.stringify(document, null, 2)}\n`, { mode: 0o600 });
-        renameSync(temporary, this.path);
-    }
-}
-function setDesired(ref, desired) {
-    const changed = ref.desired !== desired;
-    ref.desired = desired;
-    if (ref.markerPresent === desired) {
-        ref.deliveryStatus = 'applied';
+    }
+}
+/**
+ * Sync a directory, so its entries reach the disk, as the framework's
+ * syncRecoveryDirectory does: not on win32, where a directory can't be
+ * opened, and a sync refused with EINVAL or EBADF, the answer where the
+ * filesystem can't sync a directory, is let go, since it would come again on
+ * every write. Any other failure throws, for the write to report.
+ */
+async function syncDirectory(directory) {
+    if (process.platform === 'win32')
         return;
+    const handle = await open(directory, 'r');
+    try {
+        await handle.sync();
     }
-    const action = desired ? 'add' : 'remove';
-    if (changed || ref.lastAction !== action || ref.deliveryStatus !== 'permanent-failure') {
-        ref.deliveryStatus = 'pending';
-    }
-}
-function isTargetActive(activeName, targetName, branches) {
-    if (activeName === targetName)
-        return true;
-    const byName = new Map(branches.map((branch) => [branch.name, branch]));
-    const byId = new Map(branches.map((branch) => [branch.id, branch]));
-    let cursor = byName.get(activeName);
-    const visited = new Set();
-    while (cursor?.parentId && !visited.has(cursor.id)) {
-        visited.add(cursor.id);
-        cursor = byId.get(cursor.parentId);
-        if (cursor?.name === targetName)
-            return true;
+    catch (error) {
+        const code = error.code;
+        if (code !== 'EINVAL' && code !== 'EBADF')
+            throw error;
     }
-    return false;
+    finally {
+        await handle.close();
+    }
+}
+/** The report of a directory that couldn't be synced, in the words of the
+ *  framework's recovery-sync alert. */
+export function unsyncedWriteText(directory, path, error) {
+    return `syncing ${directory} failed, so ${path} may not survive a crash: ${errorText(error)}`;
+}
+const isString = (value) => typeof value === 'string';
+const isNumber = (value) => typeof value === 'number' && Number.isFinite(value);
+const isRecord = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const isOptional = (value, check) => value === undefined || check(value);
+const isRefShape = (value) => isRecord(value)
+    && isString(value.serverId) && isString(value.channelId) && isString(value.messageId);
+const isAction = (value) => value === 'add' || value === 'remove';
+const isCancelled = (value) => isRecord(value) && isNumber(value.at) && isOptional(value.by, isString);
+const isInterval = (value) => isRecord(value) && isString(value.fromId) && isString(value.toId);
+/** Whether a parsed version 3 document has the shape this build writes. */
+function isLedgerDocument(value) {
+    if (!isRecord(value) || value.version !== 3 || !isNumber(value.moment))
+        return false;
+    const { batches, retracts, entries } = value;
+    return Array.isArray(batches) && batches.every((batch) => isRecord(batch)
+        && isString(batch.id)
+        && (batch.status === 'prepared' || batch.status === 'active' || batch.status === 'retired')
+        && isString(batch.agentName) && isString(batch.sourceBranch) && isString(batch.targetBranch)
+        && isString(batch.emoji) && isNumber(batch.createdAt) && isNumber(batch.chosen)
+        && (batch.scope === 'none' || batch.scope === 'addressed' || batch.scope === 'all' || batch.scope === 'legacy')
+        && Array.isArray(batch.refs) && batch.refs.every(isRefShape)
+        && isOptional(batch.unmarked, isNumber) && isOptional(batch.notRemoved, isNumber)
+        && isOptional(batch.suppressionIntervals, (intervals) => Array.isArray(intervals) && intervals.every(isInterval))
+        && isOptional(batch.cancelled, isCancelled) && isOptional(batch.legacyAdded, isNumber))
+        && Array.isArray(retracts) && retracts.every((retract) => isRecord(retract)
+        && isString(retract.id) && isString(retract.target) && isNumber(retract.at)
+        && isOptional(retract.by, isString) && isNumber(retract.moment) && isNumber(retract.keys)
+        && isOptional(retract.cancelled, isCancelled))
+        && Array.isArray(entries) && entries.every((entry) => isRefShape(entry) && isRecord(entry)
+        && isString(entry.emoji)
+        && (entry.wanted === 'present' || entry.wanted === 'absent' || entry.wanted === null)
+        && Array.isArray(entry.wantedBy) && entry.wantedBy.every(isString)
+        && isOptional(entry.retracted, isNumber)
+        && (entry.due === null || isNumber(entry.due)) && isNumber(entry.attempts)
+        && isOptional(entry.sending, (sending) => isRecord(sending) && isAction(sending.action) && isNumber(sending.due))
+        && isOptional(entry.confirmed, (confirmed) => confirmed === 'present' || confirmed === 'absent' || confirmed === 'unknown')
+        && isOptional(entry.mayLand, (mayLand) => Array.isArray(mayLand) && mayLand.every(isAction))
+        && isOptional(entry.failed, (failed) => typeof failed === 'boolean'));
 }
-function findEntry(document, batchId, ref) {
-    return document.batches
-        .find((batch) => batch.id === batchId)
-        ?.refs.find((candidate) => refKey(candidate) === refKey(ref));
+/**
+ * Whether a parsed ledger is a version 2 ledger the released readers
+ * accepted (every release with the outbox, 0.6.7 to 0.22.3, checked these
+ * fields alike): batches `prepared` or `active`, with an activation policy
+ * and suppression intervals of the shapes they wrote, and refs that are
+ * full entries.
+ */
+function isLegacyLedger(value) {
+    if (!isRecord(value) || value.version !== 2 || !Array.isArray(value.batches))
+        return false;
+    return value.batches.every((batch) => isRecord(batch)
+        && isString(batch.id)
+        && (batch.status === 'prepared' || batch.status === 'active')
+        && isString(batch.agentName) && isString(batch.sourceBranch) && isString(batch.targetBranch)
+        && isString(batch.emoji) && typeof batch.createdAt === 'number'
+        && Array.isArray(batch.refs)
+        && (batch.activationPolicy === undefined || batch.activationPolicy === 'target-branch'
+            || batch.activationPolicy === 'explicit')
+        && isOptional(batch.suppressionIntervals, (intervals) => Array.isArray(intervals) && intervals.every(isInterval))
+        && batch.refs.every(isLegacyEntry));
+}
+/** Whether a version 2 ledger's ref is an entry as the released readers required it. */
+function isLegacyEntry(value) {
+    return isRefShape(value) && isRecord(value)
+        && typeof value.desired === 'boolean'
+        && typeof value.markerPresent === 'boolean'
+        && (value.deliveryStatus === 'pending' || value.deliveryStatus === 'applied'
+            || value.deliveryStatus === 'permanent-failure')
+        && typeof value.attempts === 'number'
+        && (value.lastAction === undefined || isAction(value.lastAction))
+        && (value.lastAttemptAt === undefined || typeof value.lastAttemptAt === 'number')
+        && (value.lastError === undefined || typeof value.lastError === 'string');
+}
+/**
+ * Rewrite a version 2 ledger as version 3. Batches keep their ids, take
+ * scope `legacy`, and keep, of what the old ledger recorded about each ref's
+ * attempts, only how many refs the last attempt saw added (`legacyAdded`):
+ * never a judgment about what is on Discord. No entries are made: a retract
+ * of a batch reaches its refs, and one of `all` the refs of every batch it
+ * activated, the only ones 0.22.x marked. The work the old ledger had
+ * still to do (its pending adds and removals, and every mark of a batch it
+ * never activated) is dropped, none of it sent, and returned in `unsent`:
+ * it was queued before marks were an explicit choice, so nobody chose it. A
+ * batch it activated stays active. One it never activated is retired,
+ * except a suppression whose body may be pending on its branch, which stays
+ * prepared, as an interrupted surgery's does, for a start on that branch to
+ * finish and retire (see pendingSuppressionsFor). A second listing of a
+ * batch id is skipped.
+ */
+function migrateLedger(document) {
+    const doc = { version: 3, moment: 0, batches: [], retracts: [], entries: [] };
+    const unsent = [];
+    const seen = new Set();
+    for (const raw of document.batches) {
+        if (seen.has(raw.id))
+            continue;
+        seen.add(raw.id);
+        const legacyActive = raw.status === 'active';
+        const pendingBody = raw.activationPolicy === 'explicit' && !!raw.suppressionIntervals?.length;
+        doc.batches.push({
+            id: raw.id,
+            status: legacyActive ? 'active' : pendingBody ? 'prepared' : 'retired',
+            agentName: raw.agentName,
+            sourceBranch: raw.sourceBranch,
+            targetBranch: raw.targetBranch,
+            emoji: raw.emoji,
+            createdAt: raw.createdAt,
+            chosen: ++doc.moment,
+            scope: 'legacy',
+            refs: dedupeRefs(raw.refs),
+            ...(raw.suppressionIntervals?.length
+                ? { suppressionIntervals: raw.suppressionIntervals.map((interval) => ({ fromId: interval.fromId, toId: interval.toId })) }
+                : {}),
+            // Only `lastError` speaks to the last attempt's outcome: the old
+            // writer cleared it on success and set it on failure, and nothing else
+            // touched it. `deliveryStatus` was its reconciliation state, rewritten
+            // by branch switches without any request.
+            legacyAdded: new Set(raw.refs
+                .filter((entry) => !!entry.attempts && entry.lastAction === 'add' && entry.lastError === undefined)
+                .map((entry) => refKey(entry))).size,
+        });
+        let adds = 0;
+        let removals = 0;
+        const counted = new Set();
+        for (const entry of raw.refs) {
+            // A ref listed twice is one ref.
+            if (counted.has(refKey(entry)))
+                continue;
+            counted.add(refKey(entry));
+            // What 0.22.x had still to do for this ref, dropped here.
+            if ((!legacyActive || entry.deliveryStatus === 'pending') && (!legacyActive || entry.desired || entry.markerPresent)) {
+                if (entry.desired || !legacyActive)
+                    adds++;
+                else
+                    removals++;
+            }
+        }
+        if (adds + removals > 0) {
+            unsent.push({
+                batchId: raw.id,
+                agentName: raw.agentName,
+                sourceBranch: raw.sourceBranch,
+                targetBranch: raw.targetBranch,
+                adds,
+                removals,
+            });
+        }
+    }
+    return { state: indexed(doc), unsent };
 }
+// ---------------------------------------------------------------------------
+// Keys
+// ---------------------------------------------------------------------------
 function dedupeRefs(refs) {
     const deduped = new Map();
     for (const ref of refs) {
         if (!ref.serverId || !ref.channelId || !ref.messageId)
             continue;
-        deduped.set(refKey(ref), { ...ref });
+        deduped.set(refKey(ref), { serverId: ref.serverId, channelId: ref.channelId, messageId: ref.messageId });
     }
     return [...deduped.values()];
 }
+/** The Discord channel id a ref's channel names: its last part, when it's
+ *  spelled `discord:<guild>:<channel>`. Delivery sends it, and keys use it. */
+export function discordChannelOf(channelId) {
+    return channelId.startsWith('discord:') ? channelId.split(':').at(-1) : channelId;
+}
+/** A ref's key, by its channel's Discord id, so one channel spelled two ways
+ *  is one channel. */
 function refKey(ref) {
-    return `${ref.serverId}\0${ref.channelId}\0${ref.messageId}`;
+    return `${ref.serverId}\0${discordChannelOf(ref.channelId)}\0${ref.messageId}`;
 }
-function markerKey(emoji, ref) {
+function markKey(ref, emoji) {
     return `${emoji}\0${refKey(ref)}`;
 }
-function isEntry(value) {
-    if (!value || typeof value !== 'object')
-        return false;
-    const entry = value;
-    return typeof entry.serverId === 'string'
-        && typeof entry.channelId === 'string'
-        && typeof entry.messageId === 'string'
-        && typeof entry.desired === 'boolean'
-        && typeof entry.markerPresent === 'boolean'
-        && (entry.deliveryStatus === 'pending'
-            || entry.deliveryStatus === 'applied'
-            || entry.deliveryStatus === 'permanent-failure')
-        && typeof entry.attempts === 'number'
-        && (entry.lastAction === undefined || entry.lastAction === 'add' || entry.lastAction === 'remove')
-        && (entry.lastAttemptAt === undefined || typeof entry.lastAttemptAt === 'number')
-        && (entry.lastError === undefined || typeof entry.lastError === 'string');
-}
-function isDocumentV2(value) {
-    if (!value || typeof value !== 'object')
-        return false;
-    const document = value;
-    if (document.version !== 2 || !Array.isArray(document.batches))
-        return false;
-    return document.batches.every((batch) => {
-        if (!batch || typeof batch !== 'object')
-            return false;
-        const candidate = batch;
-        return typeof candidate.id === 'string'
-            && (candidate.status === 'prepared' || candidate.status === 'active')
-            && typeof candidate.agentName === 'string'
-            && typeof candidate.sourceBranch === 'string'
-            && typeof candidate.targetBranch === 'string'
-            && typeof candidate.emoji === 'string'
-            && typeof candidate.createdAt === 'number'
-            && Array.isArray(candidate.refs)
-            && (candidate.activationPolicy === undefined
-                || candidate.activationPolicy === 'target-branch'
-                || candidate.activationPolicy === 'explicit')
-            && (candidate.suppressionIntervals === undefined
-                || (Array.isArray(candidate.suppressionIntervals)
-                    && candidate.suppressionIntervals.every((interval) => !!interval
-                        && typeof interval.fromId === 'string'
-                        && typeof interval.toId === 'string')))
-            && candidate.refs.every(isEntry);
-    });
-}
-function isDocumentV1(value) {
-    if (!value || typeof value !== 'object')
-        return false;
-    const document = value;
-    if (document.version !== 1 || !Array.isArray(document.batches))
-        return false;
-    return document.batches.every((batch) => {
-        if (!batch || typeof batch !== 'object')
-            return false;
-        const candidate = batch;
-        return typeof candidate.id === 'string'
-            && (candidate.status === 'prepared' || candidate.status === 'pending')
-            && typeof candidate.agentName === 'string'
-            && typeof candidate.sourceBranch === 'string'
-            && typeof candidate.targetBranch === 'string'
-            && typeof candidate.emoji === 'string'
-            && typeof candidate.createdAt === 'number'
-            && Array.isArray(candidate.refs)
-            && candidate.refs.every((ref) => !!ref
-                && typeof ref.serverId === 'string'
-                && typeof ref.channelId === 'string'
-                && typeof ref.messageId === 'string');
-    });
-}
-function migrateV1(document) {
-    return {
-        version: 2,
-        batches: document.batches.map((batch) => ({
-            ...batch,
-            status: batch.status === 'pending' ? 'active' : 'prepared',
-            refs: batch.refs.map((ref) => ({
-                ...ref,
-                desired: batch.status === 'pending',
-                markerPresent: false,
-                deliveryStatus: batch.status === 'pending' ? 'pending' : 'applied',
-                attempts: 0,
-            })),
-        })),
-    };
-}
 //# sourceMappingURL=discord-awareness-outbox.js.map