@phigon/observer 8.2.0 → 8.3.0

package/dist/src/event-spool.d.ts

@@ -1,14 +1,62 @@
 import { type EventEnvelope } from "./generated/phigon/v1/telemetry_pb.js";
-import { BoundedEventQueue } from "./event-queue.js";
+import { BoundedEventQueue, type QueueMetrics } from "./event-queue.js";
+/**
+ * What `restore` did instead of loading the spool as it was:
+ * - `other_machine`: an earlier pairing's spool, moved to `directory`.
+ * - `damaged`: a spool that could not be read, moved to `directory`.
+ * - `over_capacity`: more events than the queue holds; the newest were kept
+ *   and `dropped` of the oldest were left out.
+ */
+export type SpoolRestoreNotice = Readonly<{
+    reason: "other_machine" | "damaged";
+    directory: string;
+}> | Readonly<{
+    reason: "over_capacity";
+    dropped: number;
+}>;
 /**
  * An encrypted append-only delivery spool. The in-memory queue remains the hot
  * path, while this log makes unacknowledged events recoverable after an
  * observer restart without writing prompt or tool content as plaintext.
+ *
+ * Records are group-committed: they are buffered and written with one
+ * flushed append at most 100 ms later, or at once by `flush`. An event is
+ * durable only after a flush, so a source checkpoint may move past an event
+ * only after `flush` returns (the collector's `flushDelivery`). Events the
+ * server already acknowledged are safe either way, and a lost
+ * acknowledgement or discard record only sends an event again.
  */
 export declare class FileBackedEventQueue extends BoundedEventQueue<EventEnvelope> {
     #private;
-    constructor(dataDirectory: string, capacity?: number);
-    restore(tenantID: string, machineID: string, credential: string): void;
+    constructor(dataDirectory: string, capacity?: number, maxBytes?: number);
+    /**
+     * Writes every buffered record with one flushed append. Throws when the
+     * spool cannot be written; the records stay buffered and the next write
+     * retries them.
+     */
+    flush(): void;
+    /**
+     * Adds the spool's size by bytes: the stored size of the unacknowledged
+     * events, which is what a compaction keeps, and the budget it must fit.
+     */
+    metrics(): QueueMetrics;
+    /**
+     * Loads the spool for this machine. None of these stops the observer, and
+     * the returned notice says which one happened:
+     * - A spool that an earlier pairing of this data directory left for
+     *   another machine cannot be delivered as this one: it is moved aside
+     *   with its stream cursor.
+     * - A spool that is too large to read safely, or holds a record that does
+     *   not verify before its last line, is moved aside on its own and the
+     *   queue starts empty. Its events were written before their sources'
+     *   checkpoints moved, so they are not read again; the moved copy keeps
+     *   them for an administrator.
+     * - A spool with more events than the queue holds, as after lowering
+     *   PHIGON_ACTIVITY_QUEUE_CAPACITY, keeps the newest events, as a full
+     *   queue does while running. The control plane records the skipped
+     *   sequence numbers as a gap.
+     */
+    restore(tenantID: string, machineID: string, credential: string): SpoolRestoreNotice | undefined;
     enqueue(value: EventEnvelope, sequence: bigint, coalesceKey?: string): void;
     acknowledge(throughSequence: bigint): void;
     discard(sequence: bigint): boolean;
@@ -16,4 +64,14 @@ export declare class FileBackedEventQueue extends BoundedEventQueue<EventEnvelop
     replacePending(replace: (value: EventEnvelope) => EventEnvelope): void;
 }
 export declare function clearEventSpool(dataDirectory: string): void;
+/**
+ * Moves what an earlier pairing of this data directory left behind out of
+ * the way, so a computer paired again as a new machine starts with an empty
+ * queue instead of refusing to read the old one. The encrypted spool, the
+ * stream cursor and `extraFiles` (such as the old credential, the only key
+ * that can still decrypt that spool) go to `retired-pairings/<time>-<machine>/`.
+ * Only the newest few pairings are kept. Returns that directory, or
+ * undefined when there was nothing to move.
+ */
+export declare function retirePairingState(dataDirectory: string, machineID: string | undefined, extraFiles?: readonly string[]): string | undefined;
 //# sourceMappingURL=event-spool.d.ts.map

package/dist/src/event-spool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-spool.d.ts","sourceRoot":"","sources":["../../src/event-spool.ts"],"names":[],"mappings":"AAqBA,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAoCrD;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,iBAAiB,CAAC,aAAa,CAAC;;gBAa5D,aAAa,EAAE,MAAM,EAAE,QAAQ,SAAO;IAMlD,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAgD7D,OAAO,CACd,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,MAAM,GACnB,IAAI;IAeE,WAAW,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI;IAO1C,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAUlC,qBAAqB,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI;IAMpD,cAAc,CACrB,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,aAAa,GAC/C,IAAI;CAoNR;AAED,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAkB3D"}
+{"version":3,"file":"event-spool.d.ts","sourceRoot":"","sources":["../../src/event-spool.ts"],"names":[],"mappings":"AAuBA,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAoBxE;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAC1B,QAAQ,CAAC;IAAE,MAAM,EAAE,eAAe,GAAG,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,GACpE,QAAQ,CAAC;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AA8B3D;;;;;;;;;;;GAWG;AACH,qBAAa,oBAAqB,SAAQ,iBAAiB,CAAC,aAAa,CAAC;;gBAqBtE,aAAa,EAAE,MAAM,EACrB,QAAQ,SAAO,EACf,QAAQ,SAAuB;IAejC;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAuBb;;;OAGG;IACM,OAAO,IAAI,YAAY;IAQhC;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CACL,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,kBAAkB,GAAG,SAAS;IAwExB,OAAO,CACd,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,MAAM,GACnB,IAAI;IAuBE,WAAW,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI;IAO1C,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAUlC,qBAAqB,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI;IAMpD,cAAc,CACrB,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,aAAa,GAC/C,IAAI;CA6RR;AAED,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAE3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,UAAU,GAAE,SAAS,MAAM,EAAO,GACjC,MAAM,GAAG,SAAS,CAQpB"}

package/dist/src/event-spool.js

@@ -1,37 +1,125 @@
 import { makeDirectoryPrivateSync } from "./private-directory.js";
 import { createCipheriv, createDecipheriv, createHash, randomBytes, } from "node:crypto";
-import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { appendFileSync, chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
 import { fromBinary, toBinary } from "@bufbuild/protobuf";
+import { atomicReplaceSync } from "./atomic-replace.js";
 import { EventEnvelopeSchema, } from "./generated/phigon/v1/telemetry_pb.js";
 import { BoundedEventQueue } from "./event-queue.js";
+import { streamStateFileName } from "./stream-state.js";
 const spoolVersion = 1;
 const spoolFileName = "telemetry-spool.jsonl";
-const maxSpoolBytes = 64 << 20;
-const compactAfterOperations = 1024;
+const defaultMaxSpoolBytes = 64 << 20;
+// Buffered records are written together, at most this long after the first.
+const flushDelayMs = 100;
+// A burst this large is written at once rather than held in memory.
+const flushAfterBytes = 1 << 20;
+// The spool is rewritten once records that no longer matter (acknowledged,
+// discarded or replaced events, and acknowledgements) outweigh the queued
+// events and pass this size, or a quarter of the budget if that is smaller.
+const compactAfterDeadBytes = 1 << 20;
 const scopedIDPattern = /^[A-Za-z0-9._:-]{1,128}$/u;
+const retiredPairingsDirectory = "retired-pairings";
+const damagedSpoolsDirectory = "damaged-spools";
+// Each retired or damaged spool can be as large as the spool budget.
+const retainedRetiredPairings = 3;
 /**
  * An encrypted append-only delivery spool. The in-memory queue remains the hot
  * path, while this log makes unacknowledged events recoverable after an
  * observer restart without writing prompt or tool content as plaintext.
+ *
+ * Records are group-committed: they are buffered and written with one
+ * flushed append at most 100 ms later, or at once by `flush`. An event is
+ * durable only after a flush, so a source checkpoint may move past an event
+ * only after `flush` returns (the collector's `flushDelivery`). Events the
+ * server already acknowledged are safe either way, and a lost
+ * acknowledgement or discard record only sends an event again.
  */
 export class FileBackedEventQueue extends BoundedEventQueue {
     #dataDirectory;
     #path;
+    #maxBytes;
+    #compactAfterDeadBytes;
     #scope;
     #key;
-    #operations = 0;
-    // Appends run synchronously on the event loop for every event and every
-    // acknowledgement. Prepare the private directory and secure the file once,
-    // and track the spool size here instead of stat-ing it before each append.
+    // Prepare the private directory and secure the file once, and track the
+    // spool size here instead of stat-ing it before each write.
     #directoryPrepared = false;
     #fileSecured = false;
     #size;
-    constructor(dataDirectory, capacity = 2048) {
+    // Records accepted in memory but not yet written, oldest first.
+    #buffer = [];
+    #bufferBytes = 0;
+    #flushTimer;
+    // Why the last write failed. A failed append can leave a partial record,
+    // so the next write rewrites the whole spool instead of appending.
+    #writeFailure;
+    constructor(dataDirectory, capacity = 2048, maxBytes = defaultMaxSpoolBytes) {
         super(capacity);
+        if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+            throw new Error("Telemetry spool byte budget must be a positive integer.");
+        }
         this.#dataDirectory = dataDirectory;
         this.#path = join(dataDirectory, spoolFileName);
+        this.#maxBytes = maxBytes;
+        this.#compactAfterDeadBytes = Math.min(compactAfterDeadBytes, Math.max(1, Math.floor(maxBytes / 4)));
+    }
+    /**
+     * Writes every buffered record with one flushed append. Throws when the
+     * spool cannot be written; the records stay buffered and the next write
+     * retries them.
+     */
+    flush() {
+        if (this.#flushTimer !== undefined) {
+            clearTimeout(this.#flushTimer);
+            this.#flushTimer = undefined;
+        }
+        if (this.#writeFailure !== undefined) {
+            this.#compact();
+            return;
+        }
+        if (this.#buffer.length === 0)
+            return;
+        const encoded = this.#buffer.join("");
+        try {
+            this.#appendToFile(encoded);
+        }
+        catch (error) {
+            this.#writeFailure = error;
+            this.#size = undefined;
+            throw error;
+        }
+        this.#size = this.#currentSize() + this.#bufferBytes;
+        this.#buffer = [];
+        this.#bufferBytes = 0;
+    }
+    /**
+     * Adds the spool's size by bytes: the stored size of the unacknowledged
+     * events, which is what a compaction keeps, and the budget it must fit.
+     */
+    metrics() {
+        return Object.freeze({
+            ...super.metrics(),
+            bytes: this.queuedBytes(),
+            byteCapacity: this.#maxBytes,
+        });
     }
+    /**
+     * Loads the spool for this machine. None of these stops the observer, and
+     * the returned notice says which one happened:
+     * - A spool that an earlier pairing of this data directory left for
+     *   another machine cannot be delivered as this one: it is moved aside
+     *   with its stream cursor.
+     * - A spool that is too large to read safely, or holds a record that does
+     *   not verify before its last line, is moved aside on its own and the
+     *   queue starts empty. Its events were written before their sources'
+     *   checkpoints moved, so they are not read again; the moved copy keeps
+     *   them for an administrator.
+     * - A spool with more events than the queue holds, as after lowering
+     *   PHIGON_ACTIVITY_QUEUE_CAPACITY, keeps the newest events, as a full
+     *   queue does while running. The control plane records the skipped
+     *   sequence numbers as a gap.
+     */
     restore(tenantID, machineID, credential) {
         validateScope(tenantID, machineID);
         if (!credential.startsWith("phg_m_") || credential.length > 256) {
@@ -45,34 +133,57 @@ export class FileBackedEventQueue extends BoundedEventQueue {
                 !this.#key?.equals(key)) {
                 throw new Error("Telemetry spool scope changed while the observer was running.");
             }
-            return;
+            return undefined;
         }
         this.#scope = scope;
         this.#key = key;
         try {
             if (!existsSync(this.#path))
-                return;
+                return undefined;
             const metadata = statSync(this.#path);
-            if (!metadata.isFile() || metadata.size > maxSpoolBytes) {
-                throw new Error("Telemetry spool exceeds its safe storage bound.");
+            if (!metadata.isFile() || metadata.size > this.#maxBytes) {
+                return this.#setAsideDamaged();
             }
             const restored = new BoundedEventQueue(this.metrics().capacity);
             const raw = readFileSync(this.#path, "utf8");
+            // Every record names its machine in plain text, so another machine's
+            // spool is told apart from a damaged one.
+            const owner = spoolOwner(raw);
+            if (owner !== undefined &&
+                (owner.tenantID !== tenantID || owner.machineID !== machineID)) {
+                this.#size = undefined;
+                const directory = retirePairingState(this.#dataDirectory, owner.machineID);
+                return directory === undefined
+                    ? undefined
+                    : { reason: "other_machine", directory };
+            }
             const lines = raw.split("\n");
             const completeLines = lines.slice(0, -1);
-            for (const line of completeLines) {
-                if (line.length === 0)
-                    continue;
-                const record = parseRecord(line, scope);
-                this.#restoreRecord(record, restored);
+            // Events left out because the queue was full, until a later record
+            // acknowledges or discards them.
+            const dropped = new Set();
+            try {
+                for (const line of completeLines) {
+                    if (line.length === 0)
+                        continue;
+                    const record = parseRecord(line, scope);
+                    this.#restoreRecord(record, restored, Buffer.byteLength(line) + 1, dropped);
+                }
+            }
+            catch {
+                return this.#setAsideDamaged();
             }
             if (!raw.endsWith("\n") && (lines.at(-1)?.length ?? 0) > 0) {
-                // A crash can leave only the final append incomplete. It was never a
-                // durable event, so ignore that tail and compact the verified prefix.
+                // A crash can leave only the final write incomplete. Its records
+                // were never flushed, so no source checkpoint moved past them:
+                // ignore that tail and compact the verified prefix.
             }
-            this.#writeCompactedQueue(restored);
+            const sizes = this.#writeCompactedQueue(restored);
             this.replaceState(restored);
-            this.#operations = 0;
+            this.reweigh(sizes);
+            const acknowledged = restored.metrics().acknowledged;
+            const lost = [...dropped].filter((sequence) => sequence > acknowledged).length;
+            return lost === 0 ? undefined : { reason: "over_capacity", dropped: lost };
         }
         catch (error) {
             this.#scope = undefined;
@@ -87,24 +198,33 @@ export class FileBackedEventQueue extends BoundedEventQueue {
                 "before an unacknowledged event could be discarded.");
         }
         validateEventScope(value, scope, sequence);
+        // While the disk refuses writes, refuse new events before they reach
+        // memory, as an unbuffered append did; the collector reads them again.
+        if (this.#writeFailure !== undefined)
+            this.flush();
         const record = this.#encryptedRecord(value, sequence, coalesceKey);
-        this.#append(record);
-        super.enqueue(value, sequence, coalesceKey);
+        const bytes = this.#append(record);
+        super.enqueue(value, sequence, coalesceKey, bytes);
         this.#compactIfNeeded();
     }
+    // Removals apply in memory before they are buffered. On a full spool the
+    // compaction that makes room for the record then already leaves the
+    // removed events out, so an acknowledgement can always drain the spool.
+    // A removal lost in a crash only sends the event again, so removals are
+    // written lazily with the next group of records.
     acknowledge(throughSequence) {
         if (throughSequence <= this.metrics().acknowledged)
             return;
-        this.#append(this.#sequenceRecord("acknowledge", throughSequence));
         super.acknowledge(throughSequence);
+        this.#append(this.#sequenceRecord("acknowledge", throughSequence));
         this.#compactIfNeeded();
     }
     discard(sequence) {
         if (!this.pending().some((event) => event.sequence === sequence)) {
             return false;
         }
-        this.#append(this.#sequenceRecord("discard", sequence));
         const discarded = super.discard(sequence);
+        this.#append(this.#sequenceRecord("discard", sequence));
         this.#compactIfNeeded();
         return discarded;
     }
@@ -122,7 +242,7 @@ export class FileBackedEventQueue extends BoundedEventQueue {
         });
         this.#compact();
     }
-    #restoreRecord(record, target) {
+    #restoreRecord(record, target, bytes, dropped) {
         const sequence = parseSequence(record.sequence);
         if (record.operation === "acknowledge") {
             target.acknowledge(sequence);
@@ -130,13 +250,28 @@ export class FileBackedEventQueue extends BoundedEventQueue {
         }
         if (record.operation === "discard") {
             target.discard(sequence);
+            dropped.delete(sequence);
             return;
         }
         const event = this.#decrypt(record);
-        if (!target.canEnqueue(record.coalesce_key)) {
-            throw new Error("Telemetry spool contains more events than the configured queue capacity.");
+        if (sequence > target.metrics().acknowledged &&
+            !target.canEnqueue(record.coalesce_key)) {
+            // A full queue makes room by leaving out its oldest event.
+            const oldest = target.metrics().oldestSequence;
+            if (oldest !== undefined)
+                dropped.add(oldest);
         }
-        target.enqueue(event, sequence, record.coalesce_key);
+        target.enqueue(event, sequence, record.coalesce_key, bytes);
+    }
+    /** Moves an unreadable spool aside so the queue can start empty. */
+    #setAsideDamaged() {
+        this.#size = undefined;
+        removeSpoolFiles(this.#dataDirectory, false);
+        const directory = moveAside(this.#dataDirectory, damagedSpoolsDirectory, "damaged", [spoolFileName]);
+        if (directory === undefined) {
+            throw new Error("Telemetry spool disappeared while it was being moved aside.");
+        }
+        return { reason: "damaged", directory };
     }
     #encryptedRecord(event, sequence, coalesceKey) {
         const scope = this.#requireScope();
@@ -191,16 +326,45 @@ export class FileBackedEventQueue extends BoundedEventQueue {
             sequence: sequence.toString(),
         };
     }
+    /** Buffer one record for the next group write and return its stored size. */
     #append(record) {
-        this.#prepareDirectory();
         const encoded = `${JSON.stringify(record)}\n`;
         const bytes = Buffer.byteLength(encoded);
-        if (this.#currentSize() + bytes > maxSpoolBytes) {
+        if (this.#storedBytes() + bytes > this.#maxBytes) {
             this.#compact();
         }
-        if (this.#currentSize() + bytes > maxSpoolBytes) {
+        if (this.#storedBytes() + bytes > this.#maxBytes) {
             throw new Error("Telemetry spool is full; collection stopped before data loss.");
         }
+        this.#buffer.push(encoded);
+        this.#bufferBytes += bytes;
+        if (this.#bufferBytes >= flushAfterBytes) {
+            this.#flushQuietly();
+        }
+        else {
+            this.#flushTimer ??= setTimeout(() => {
+                this.#flushTimer = undefined;
+                this.#flushQuietly();
+            }, flushDelayMs).unref();
+        }
+        return bytes;
+    }
+    /**
+     * A write that runs outside a caller who could handle its failure. The
+     * failure is kept: the next event is refused until a write succeeds, and
+     * no source checkpoint moves past an unwritten event.
+     */
+    #flushQuietly() {
+        try {
+            this.flush();
+        }
+        catch {
+            // Kept in #writeFailure; the next write retries.
+        }
+    }
+    /** One flushed append of `encoded`. */
+    #appendToFile(encoded) {
+        this.#prepareDirectory();
         if (this.#currentSize() === 0)
             this.#fileSecured = false;
         const options = {
@@ -225,8 +389,10 @@ export class FileBackedEventQueue extends BoundedEventQueue {
             chmodSync(this.#path, 0o600);
             this.#fileSecured = true;
         }
-        this.#size = this.#currentSize() + bytes;
-        this.#operations++;
+    }
+    /** The spool's size once the buffered records are written. */
+    #storedBytes() {
+        return this.#currentSize() + this.#bufferBytes;
     }
     #prepareDirectory() {
         if (this.#directoryPrepared)
@@ -249,13 +415,19 @@ export class FileBackedEventQueue extends BoundedEventQueue {
         return this.#size;
     }
     #compactIfNeeded() {
-        if (this.#operations >= compactAfterOperations)
+        // A compaction rewrites the queued events, so rewriting only once the
+        // records it drops outweigh them keeps its cost proportional to the
+        // records appended since the last one.
+        const live = this.queuedBytes();
+        const dead = this.#storedBytes() - live;
+        if (dead >= this.#compactAfterDeadBytes && dead > live)
             this.#compact();
     }
+    /** Rewrite the spool from memory, which also writes every buffered record. */
     #compact() {
-        this.#writeCompactedQueue(this);
-        this.#operations = 0;
+        this.reweigh(this.#writeCompactedQueue(this));
     }
+    /** Rewrite the spool as `queue` and return each queued event's stored size. */
     #writeCompactedQueue(queue) {
         this.#requireScope();
         mkdirSync(this.#dataDirectory, { recursive: true, mode: 0o700 });
@@ -264,8 +436,9 @@ export class FileBackedEventQueue extends BoundedEventQueue {
             this.#sequenceRecord("acknowledge", queue.metrics().acknowledged),
             ...queue.entries().map((entry) => this.#encryptedRecord(entry.value, entry.sequence, entry.coalesceKey)),
         ];
-        const encoded = `${records.map((record) => JSON.stringify(record)).join("\n")}\n`;
-        if (Buffer.byteLength(encoded) > maxSpoolBytes) {
+        const lines = records.map((record) => JSON.stringify(record));
+        const encoded = `${lines.join("\n")}\n`;
+        if (Buffer.byteLength(encoded) > this.#maxBytes) {
             throw new Error("Telemetry spool is full; collection stopped before data loss.");
         }
         const temporaryPath = `${this.#path}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
@@ -277,11 +450,19 @@ export class FileBackedEventQueue extends BoundedEventQueue {
                 flush: true,
             });
             this.#size = undefined;
-            renameSync(temporaryPath, this.#path);
+            atomicReplaceSync(temporaryPath, this.#path);
             chmodSync(this.#path, 0o600);
             this.#directoryPrepared = true;
             this.#fileSecured = true;
             this.#size = Buffer.byteLength(encoded);
+            // Memory already holds every buffered record's effect.
+            this.#buffer = [];
+            this.#bufferBytes = 0;
+            this.#writeFailure = undefined;
+            if (this.#flushTimer !== undefined) {
+                clearTimeout(this.#flushTimer);
+                this.#flushTimer = undefined;
+            }
         }
         catch (error) {
             try {
@@ -292,6 +473,8 @@ export class FileBackedEventQueue extends BoundedEventQueue {
             }
             throw error;
         }
+        // The first line is the acknowledgement; each event is one line.
+        return lines.slice(1).map((line) => Buffer.byteLength(line) + 1);
     }
     #requireScope() {
         if (this.#scope === undefined) {
@@ -307,6 +490,50 @@ export class FileBackedEventQueue extends BoundedEventQueue {
     }
 }
 export function clearEventSpool(dataDirectory) {
+    removeSpoolFiles(dataDirectory, true);
+}
+/**
+ * Moves what an earlier pairing of this data directory left behind out of
+ * the way, so a computer paired again as a new machine starts with an empty
+ * queue instead of refusing to read the old one. The encrypted spool, the
+ * stream cursor and `extraFiles` (such as the old credential, the only key
+ * that can still decrypt that spool) go to `retired-pairings/<time>-<machine>/`.
+ * Only the newest few pairings are kept. Returns that directory, or
+ * undefined when there was nothing to move.
+ */
+export function retirePairingState(dataDirectory, machineID, extraFiles = []) {
+    removeSpoolFiles(dataDirectory, false);
+    return moveAside(dataDirectory, retiredPairingsDirectory, machineID ?? "unknown", [spoolFileName, streamStateFileName, ...extraFiles]);
+}
+/**
+ * Moves the `names` that exist into a new `<rootName>/<time>-<label>-*`
+ * directory and keeps only the newest few such directories. Returns the new
+ * directory, or undefined when there was nothing to move.
+ */
+function moveAside(dataDirectory, rootName, label, names) {
+    const present = names.filter((name) => existsSync(join(dataDirectory, name)));
+    if (present.length === 0)
+        return undefined;
+    const root = join(dataDirectory, rootName);
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    chmodSync(root, 0o700);
+    // The time first, so names sort oldest first; Windows refuses ":" in names.
+    const stamp = new Date().toISOString().replace(/[:.]/gu, "-");
+    const safeLabel = label.replace(/[^A-Za-z0-9._-]/gu, "_");
+    const destination = mkdtempSync(join(root, `${stamp}-${safeLabel}-`));
+    for (const name of present) {
+        atomicReplaceSync(join(dataDirectory, name), join(destination, name));
+    }
+    const kept = readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort();
+    for (const name of kept.slice(0, -retainedRetiredPairings)) {
+        rmSync(join(root, name), { recursive: true, force: true });
+    }
+    return destination;
+}
+function removeSpoolFiles(dataDirectory, includeSpool) {
     let names;
     try {
         names = readdirSync(dataDirectory);
@@ -318,7 +545,7 @@ export function clearEventSpool(dataDirectory) {
     }
     for (const name of names) {
         const temporary = name.startsWith(`${spoolFileName}.`) && name.endsWith(".tmp");
-        if (name !== spoolFileName && !temporary)
+        if (!temporary && !(includeSpool && name === spoolFileName))
             continue;
         try {
             unlinkSync(join(dataDirectory, name));
@@ -329,6 +556,28 @@ export function clearEventSpool(dataDirectory) {
         }
     }
 }
+/** The machine that wrote a spool, from its first record. */
+function spoolOwner(raw) {
+    const end = raw.indexOf("\n");
+    if (end < 0)
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(raw.slice(0, end));
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof value !== "object" || value === null ||
+        !("version" in value) || value.version !== spoolVersion ||
+        !("tenant_id" in value) || typeof value.tenant_id !== "string" ||
+        !("machine_id" in value) || typeof value.machine_id !== "string" ||
+        !scopedIDPattern.test(value.tenant_id) ||
+        !scopedIDPattern.test(value.machine_id)) {
+        return undefined;
+    }
+    return { tenantID: value.tenant_id, machineID: value.machine_id };
+}
 function parseRecord(line, scope) {
     let value;
     try {