@omnitron-dev/omnitron 0.2.0 → 0.3.0

package/dist/services/sync.service.js

@@ -5,29 +5,146 @@
  * - Every slave daemon collects ALL metrics, logs, events, alerts locally
  * - Data is buffered in a local append-only WAL (write-ahead log) in omnitron-pg
  * - Periodically, slave attempts to push buffered data to master via Netron TCP
- * - On success: WAL entries marked as synced
- * - On failure: exponential backoff, retry later — data is NEVER lost
- * - All sync batches are idempotent (safe to retry)
+ * - On success: the entries the master confirms are marked as synced
+ * - On failure: exponential backoff, retry later — the entries stay pending
+ * - Sync batches are idempotent: the master keeps a ledger of what it took
  *
  * Guarantees:
- * 1. Zero data loss — local WAL persists through daemon restarts
+ * 1. No loss on delivery failure — an entry is released only once the master
+ *    has confirmed it holds it. Bounded by (5): when the buffer is over
+ *    budget, undelivered entries are dropped oldest-first, loudly.
  * 2. Autonomous operation — slave works normally without master
  * 3. Eventual consistency — master sees all data when connectivity restores
  * 4. Conflict-free — operational data is append-only, config uses master-wins
  * 5. Bounded buffer — oldest entries evicted when maxBufferSize reached
  *
+ * Four of these were stated here long before anything implemented them, and
+ * every one of the failures was silent: replication that drops data still
+ * reports a successful cycle, because what would have noticed is what was
+ * missing. Guarantee 1 said "zero data loss" while both transports discarded
+ * whatever the master rejected; the batches were called idempotent with
+ * `batchId` used only inside log strings; and `maxBufferSize` was read from
+ * config, defaulted to 500 MB, and never referenced again.
+ *
+ * Guarantee 1 is now stated as what it can be. "Zero data loss" was not
+ * achievable alongside a bounded buffer, and writing it down did not make it
+ * so — a slave that cannot reach its master eventually has to choose between
+ * dropping data and filling the disk. It drops, oldest first, at warning
+ * level with a count. See `sync-policy.ts`.
+ *
  * WAL table: `sync_buffer` in slave's local omnitron-pg
  * Each entry: { id, category, payload (jsonb), createdAt, syncedAt (null until synced) }
+ * Dedup ledger (master side): `sync_ingested`, keyed on (nodeId, slave entry id)
  */
+import { toIsoUtc } from '../database/sqlite-date-binding.js';
+import { describeError } from '../shared/describe-error.js';
+import { classifyIngestFailure, deliveredIds, sweepMadeProgress, planEviction, SYNCED_RETENTION_MS, LEDGER_WINDOW_DAYS, LEDGER_FIRST_PASS_DELAY_MS, LEDGER_INTERVAL_MS, LEDGER_BACKLOG_INTERVAL_MS, } from './sync-policy.js';
+import { planRetention, batchesPerPass } from './log-retention.js';
 /** Max batches per node per minute */
 const RATE_LIMIT_PER_MINUTE = 60;
+/**
+ * The most parameters one statement binds.
+ *
+ * Postgres takes 65 535 and SQLite 32 766 (better-sqlite3 13.0.3 / SQLite
+ * 3.53.4, measured: 32 767 is refused with «too many SQL variables»). This
+ * service writes to both — a master on Postgres, a slave on SQLite — so the
+ * smaller one bounds every statement it builds from a list, with room.
+ */
+const MAX_BOUND_PARAMETERS = 30_000;
+/** Rows split into statements that each stay within `MAX_BOUND_PARAMETERS`. */
+function statementsOf(rows) {
+    if (rows.length === 0)
+        return [];
+    const perRow = Math.max(1, Object.keys(rows[0]).length);
+    const size = Math.max(1, Math.floor(MAX_BOUND_PARAMETERS / perRow));
+    const parts = [];
+    for (let i = 0; i < rows.length; i += size)
+        parts.push(rows.slice(i, i + size));
+    return parts;
+}
+function logRow(nodeId, entry) {
+    return {
+        timestamp: entry.payload['timestamp'] ?? entry.createdAt,
+        nodeId,
+        app: entry.payload['app'] ?? 'unknown',
+        level: entry.payload['level'] ?? 'info',
+        message: entry.payload['message'] ?? '',
+        labels: JSON.stringify(entry.payload['labels'] ?? {}),
+        traceId: entry.payload['traceId'] ?? null,
+        spanId: entry.payload['spanId'] ?? null,
+        metadata: entry.payload['metadata'] ? JSON.stringify(entry.payload['metadata']) : null,
+    };
+}
+/**
+ * A remote alert, with the machine that raised it.
+ *
+ * `nodeId` was `_nodeId` here: accepted and discarded. `alert_events` has
+ * no node column, so it goes into `annotations`, which is the jsonb this
+ * table already carries context in — an alert that says "disk above 90%"
+ * and cannot say whose disk is an alert an operator cannot act on.
+ *
+ * `ruleId` keeps its `?? 'unknown'` only so the shape is unchanged; the
+ * column is a `uuid` with a foreign key to `alert_rules`, so that literal
+ * is refused by the database and the entry is now discarded by
+ * `classifyIngestFailure` instead of being offered forever. A slave's
+ * rules are its own, so the same is true of any real ruleId the master
+ * does not share — which is what makes the permanent-failure path the
+ * important half of this.
+ */
+function alertRow(nodeId, entry) {
+    const annotations = {
+        ...entry.payload['annotations'],
+        node: nodeId,
+    };
+    return {
+        ruleId: entry.payload['ruleId'] ?? 'unknown',
+        status: entry.payload['status'] ?? 'firing',
+        value: entry.payload['value'] != null ? String(entry.payload['value']) : null,
+        annotations: JSON.stringify(annotations),
+        firedAt: entry.payload['firedAt'] ?? entry.createdAt,
+        resolvedAt: entry.payload['resolvedAt'] ?? null,
+        acknowledgedAt: null,
+        acknowledgedBy: null,
+    };
+}
+/**
+ * A remote span, with the machine that produced it.
+ *
+ * The node went into `tags` as `entry.payload['tags'] ?? { nodeId }` — a
+ * fallback, so it was recorded ONLY for a span that carried no tags at
+ * all, and dropped for every span that carried any. The `??` fires exactly
+ * when there is nothing to lose and is skipped exactly when there is.
+ * Merged now, and the node wins the key, because the span's own view of
+ * which node it ran on is the one thing about it the master can check.
+ */
+function traceRow(nodeId, entry) {
+    return {
+        traceId: entry.payload['traceId'] ?? 'unknown',
+        spanId: entry.payload['spanId'] ?? 'unknown',
+        parentSpanId: entry.payload['parentSpanId'] ?? null,
+        operationName: entry.payload['operationName'] ?? 'unknown',
+        serviceName: entry.payload['serviceName'] ?? 'unknown',
+        startTime: entry.payload['startTime'] ?? entry.createdAt,
+        endTime: entry.payload['endTime'] ?? entry.createdAt,
+        duration: Number(entry.payload['duration'] ?? 0),
+        status: entry.payload['status'] ?? 'ok',
+        tags: JSON.stringify({ ...entry.payload['tags'], node: nodeId }),
+        logs: entry.payload['logs'] ? JSON.stringify(entry.payload['logs']) : null,
+    };
+}
 export class SyncService {
     db;
     logger;
     nodeId;
     role;
+    /** Set on a master; see `setMetricsSink`. */
+    metricsSink = null;
     config;
     syncTimer = null;
+    /** The master's ledger pruning, re-armed after each pass. See `pruneLedger`. */
+    ledgerTimer = null;
+    /** Whether this database keeps the buffer's figures; null until asked. See `keptBufferStats`. */
+    bufferStatsKept = null;
     isSyncing = false;
     backoff = { attempt: 0, nextRetryAt: 0 };
     lastSyncAt = null;
@@ -60,22 +177,31 @@ export class SyncService {
     // ===========================================================================
     /**
      * Start the sync loop.
-     * Only runs on slave daemons — master is a no-op.
+     *
+     * On a slave, the buffer's pass: bound it, then try to drain it. On a
+     * master, the ledger's: `sync_ingested` pruned to its dedup window. The
+     * master used to return here, and its half of the pipeline was never
+     * maintained at all.
      */
     start() {
-        if (this.role !== 'slave') {
-            this.logger.debug({ role: this.role }, 'Sync not needed for this daemon role');
+        if (this.role === 'master') {
+            this.scheduleLedgerPrune(LEDGER_FIRST_PASS_DELAY_MS);
             return;
         }
         this.logger.info({ interval: this.config.interval, batchSize: this.config.batchSize, categories: this.config.categories }, 'Starting sync service');
         this.syncTimer = setInterval(() => {
-            this.syncCycle().catch((err) => {
+            this.syncTick().catch((err) => {
                 this.logger.error({ error: err.message }, 'Sync cycle failed');
             });
         }, this.config.interval);
         this.syncTimer.unref();
-        // Initial sync attempt
-        this.syncCycle().catch(() => { });
+        // Initial sync attempt — reported like every other one. The recurring
+        // call four lines above logs its failure; this one swallowed it, and it
+        // is the more informative of the two: it is the first evidence that a
+        // slave can reach its master at all.
+        this.syncTick().catch((err) => {
+            this.logger.error({ error: err.message }, 'Initial sync cycle failed');
+        });
     }
     /**
      * Stop the sync loop and flush remaining buffer.
@@ -86,6 +212,10 @@ export class SyncService {
             clearInterval(this.syncTimer);
             this.syncTimer = null;
         }
+        if (this.ledgerTimer) {
+            clearTimeout(this.ledgerTimer);
+            this.ledgerTimer = null;
+        }
         // Final sync attempt before shutdown
         if (this.role === 'slave' && this.masterInvoke) {
             try {
@@ -132,9 +262,26 @@ export class SyncService {
             }).execute();
         }
         catch (err) {
-            this.logger.warn({ category: entry.category, error: err.message }, 'Failed to buffer sync entry');
+            this.logger.error({ nodeId: this.nodeId, category: entry.category, error: err.message }, 'Failed to buffer sync entry — it will not reach the master');
         }
     }
+    /**
+     * Where ingested remote metrics are recorded, on a master.
+     *
+     * Set by the daemon to `MetricsService.recordTyped` — the store the
+     * console's charts read, with the node as a label. It is the only place a
+     * remote metric goes: the `metrics_raw` table it was also written to had
+     * no reader and no pruning (migration 010). Without a sink, remote metrics
+     * are claimed and go nowhere.
+     *
+     * A sink rather than a constructor dependency: this service is built by
+     * hand in `daemon.ts` with five positional arguments, and a sixth is a
+     * change every caller has to get right at runtime rather than at compile
+     * time.
+     */
+    setMetricsSink(sink) {
+        this.metricsSink = sink;
+    }
     /**
      * Buffer multiple entries at once (batch optimization).
      */
@@ -151,28 +298,79 @@ export class SyncService {
             }))).execute();
         }
         catch (err) {
-            this.logger.warn({ count: entries.length, error: err.message }, 'Failed to buffer sync batch');
+            // ERROR, with the node and the size. A buffer that refuses is data
+            // this node will never replicate, and on the master it looks exactly
+            // like a node that had nothing to say — someone reads an empty screen
+            // and draws a conclusion about the system rather than about the pipe.
+            this.logger.error({ nodeId: this.nodeId, count: filteredEntries.length, category: filteredEntries[0]?.category, error: err.message }, 'Failed to buffer sync batch — these entries will not reach the master');
         }
     }
     // ===========================================================================
     // Pull API (master pulls buffered data from slave)
     // ===========================================================================
     /**
-     * Drain pending buffer entries — called by master via RPC.
-     * Returns a batch of unsynced entries and marks them as synced.
-     * Idempotent: entries are only drained once.
+     * Hand pending entries to the master — called by the master via RPC.
+     *
+     * This used to mark the entries synced before returning them, and called
+     * that idempotent. It is the opposite: a response lost in transit, a
+     * checksum mismatch or a rate-limit rejection left the data marked
+     * delivered on the slave and absent on the master, to be evicted twenty-
+     * four hours later. The caller logged the failure at debug level.
+     *
+     * Entries are released only by `ackDrained`, after the master has them.
+     * Re-draining before that returns the same entries, which is correct and
+     * is what the deduplication ledger on the master side is for.
      */
     async drainBuffer(limit) {
-        const batch = await this.fetchPendingBatch(limit);
-        if (batch.entries.length > 0) {
-            await this.markSynced(batch.entries.map((e) => e.id));
-            this.lastSyncAt = Date.now();
-        }
-        return batch;
+        return this.fetchPendingBatch(limit);
+    }
+    /**
+     * Release entries the master has confirmed it holds.
+     *
+     * Called after `receiveBatch` succeeds. Split from `drainBuffer` so that
+     * everything between the two — the network, the checksum, the ingestion —
+     * can fail without the slave forgetting the data.
+     */
+    async ackDrained(ids) {
+        if (ids.length === 0)
+            return { released: 0 };
+        await this.markSynced(ids);
+        this.lastSyncAt = Date.now();
+        return { released: ids.length };
     }
     // ===========================================================================
     // Sync Cycle (push to master — legacy, kept for backward compatibility)
     // ===========================================================================
+    /**
+     * One scheduled pass: bound the buffer, then try to drain it.
+     *
+     * The order is the whole point. `enforceBufferBounds` used to be the last
+     * statement of `syncCycle`'s `try`, which meant it ran on a SUCCESSFUL
+     * cycle and on nothing else — and a successful cycle is the one case where
+     * the buffer is being drained and needs no bound. Every path that leaves it
+     * growing skipped it:
+     *
+     *   - no master configured at all → `syncCycle` returns at its second line;
+     *   - master unreachable → the push throws and control leaves via `catch`;
+     *   - and then the backoff, which saturates at five minutes, returns at the
+     *     third line for most ticks after that.
+     *
+     * So the guarantee in this file's header — "bounded buffer, oldest entries
+     * evicted when maxBufferSize is reached" — held only while it was not
+     * needed. A slave that lost its master still buffered until the disk filled,
+     * which is the exact failure the bound was written to prevent and the
+     * reason it is not read as a replication bug when it happens: what fills is
+     * the disk, and what breaks is everything else sharing it.
+     *
+     * The bound is a local database operation. It needs no master, so it does
+     * not belong behind a check for one.
+     */
+    async syncTick() {
+        if (this.disposed)
+            return;
+        await this.enforceBufferBounds();
+        await this.syncCycle();
+    }
     async syncCycle() {
         if (this.disposed || this.isSyncing)
             return;
@@ -184,14 +382,27 @@ export class SyncService {
         this.isSyncing = true;
         try {
             let totalSynced = 0;
+            let totalRefused = 0;
+            const seenThisCycle = new Set();
             // Sync in batches until no more pending entries
             while (true) {
                 const batch = await this.fetchPendingBatch();
                 if (batch.entries.length === 0)
                     break;
-                await this.pushBatch(batch);
-                await this.markSynced(batch.entries.map((e) => e.id));
-                totalSynced += batch.entries.length;
+                const outcome = await this.pushBatch(batch);
+                const delivered = deliveredIds(outcome);
+                await this.markSynced(delivered);
+                totalSynced += delivered.length;
+                totalRefused += outcome.failed.length;
+                // Entries the master rejected stay pending, so the next fetch
+                // returns them again. Stop the sweep when a page yields nothing new
+                // — otherwise a permanently unacceptable entry loops here forever.
+                if (!sweepMadeProgress(seenThisCycle, batch.entries.map((e) => e.id))) {
+                    this.logger.warn({ nodeId: this.nodeId, pending: batch.entries.length }, 'Sync sweep stalled — the master is rejecting the oldest pending entries');
+                    break;
+                }
+                for (const e of batch.entries)
+                    seenThisCycle.add(e.id);
                 // Don't monopolize — yield after each batch
                 if (totalSynced >= this.config.batchSize * 5)
                     break;
@@ -199,25 +410,49 @@ export class SyncService {
             if (totalSynced > 0) {
                 this.logger.info({ synced: totalSynced }, 'Sync cycle completed');
             }
+            // A cycle that delivered NOTHING and was refused everything is not a
+            // success, even though nothing threw.
+            //
+            // Only one of the two ways to fail used to reach the backoff. An
+            // unreachable master makes the push throw, and the `catch` below grows
+            // the delay to five minutes. But a master that ANSWERS and says no to
+            // every entry returns normally — and control arrived here, at a reset
+            // of a backoff that had never been set. That is how 1000 entries were
+            // offered 94 times in 37 minutes while the master's own Postgres was
+            // down behind a stopped Docker: the RPC succeeded on every attempt,
+            // and only the ingest failed. The configured delay (5 s, doubling, to
+            // 300 s) would have made that about a dozen attempts; it was never
+            // consulted.
+            if (totalSynced === 0 && totalRefused > 0) {
+                this.noteSyncFailure(`master refused every entry (${totalRefused})`);
+                return;
+            }
             // Reset backoff on success
             this.backoff = { attempt: 0, nextRetryAt: 0 };
             this.lastSyncAt = Date.now();
             this.lastError = null;
-            // Evict old synced entries
-            await this.evictSynced();
         }
         catch (err) {
-            const message = err.message;
-            this.lastError = message;
-            this.backoff.attempt++;
-            const delay = Math.min(this.config.backoff.initial * Math.pow(this.config.backoff.factor, this.backoff.attempt), this.config.backoff.max);
-            this.backoff.nextRetryAt = Date.now() + delay;
-            this.logger.warn({ error: message, attempt: this.backoff.attempt, nextRetryMs: delay }, 'Sync failed — will retry');
+            this.noteSyncFailure(describeError(err));
         }
         finally {
             this.isSyncing = false;
         }
     }
+    /**
+     * Grow the retry delay and record why.
+     *
+     * Shared by both ways a cycle can fail — a master that cannot be reached,
+     * and a master that answers no — because the buffer does not care which
+     * one it was, and neither does the disk it is filling.
+     */
+    noteSyncFailure(message) {
+        this.lastError = message;
+        this.backoff.attempt++;
+        const delay = Math.min(this.config.backoff.initial * Math.pow(this.config.backoff.factor, this.backoff.attempt), this.config.backoff.max);
+        this.backoff.nextRetryAt = Date.now() + delay;
+        this.logger.warn({ error: message, attempt: this.backoff.attempt, nextRetryMs: delay }, 'Sync failed — will retry');
+    }
     async fetchPendingBatch(limit) {
         const rows = await this.db
             .selectFrom('sync_buffer')
@@ -231,7 +466,9 @@ export class SyncService {
             id: String(r.id),
             category: r.category,
             payload: (typeof r.payload === 'string' ? JSON.parse(r.payload) : r.payload),
-            createdAt: r.createdAt instanceof Date ? r.createdAt.toISOString() : String(r.createdAt),
+            // Whatever spelling the local column holds, the master receives a
+            // timestamp that states its zone. See `toIsoUtc`.
+            createdAt: toIsoUtc(r.createdAt),
         }));
         // Compute integrity checksum
         const checksum = await this.computeChecksum(entries);
@@ -243,10 +480,32 @@ export class SyncService {
         hash.update(JSON.stringify(entries));
         return hash.digest('hex');
     }
+    /**
+     * Push a batch and report what the master kept.
+     *
+     * The return value used to be discarded, and `receiveBatch` swallows
+     * per-entry ingestion failures into a warning — so the caller marked every
+     * entry delivered whether or not any of them arrived. A master response
+     * without the id lists is treated as "all delivered", which is what an
+     * older master would mean by it; that is the only reading that does not
+     * silently retry everything against a peer that cannot tell us otherwise.
+     */
     async pushBatch(batch) {
         if (!this.masterInvoke)
             throw new Error('No master connection');
-        await this.masterInvoke('OmnitronSync', 'receiveBatch', [batch]);
+        const response = (await this.masterInvoke('OmnitronSync', 'receiveBatch', [batch]));
+        const allIds = batch.entries.map((e) => e.id);
+        if (!response || !Array.isArray(response.acceptedIds)) {
+            return { accepted: allIds, duplicates: [], failed: [], discarded: [] };
+        }
+        return {
+            accepted: response.acceptedIds,
+            duplicates: Array.isArray(response.duplicateIds) ? response.duplicateIds : [],
+            failed: Array.isArray(response.failedIds) ? response.failedIds : [],
+            // An older master answers without this field. Treating a missing list
+            // as an empty one is right: it discarded nothing.
+            discarded: Array.isArray(response.discardedIds) ? response.discardedIds : [],
+        };
     }
     async markSynced(ids) {
         if (ids.length === 0)
@@ -258,19 +517,193 @@ export class SyncService {
             .execute();
     }
     /**
-     * Evict synced entries older than 24h to keep WAL bounded.
+     * Keep the WAL inside `maxBufferSize`.
+     *
+     * Guarantee 5 in the header of this file — "bounded buffer, oldest entries
+     * evicted when maxBufferSize reached" — had no implementation:
+     * `maxBufferSize` was read from config, defaulted to 500 MB, and never
+     * referenced again. The only eviction was of *synced* rows older than a
+     * day, so a slave that lost its master buffered until the disk filled. The
+     * failure lands on everything else sharing that disk, which is why it
+     * would never have been read as a replication bug.
+     *
+     * Two passes. The routine one removes delivered entries past their
+     * retention. The overflow one runs only when the table is still over
+     * budget and removes oldest-first regardless of delivery — at which point
+     * data is being dropped, so it is said at warning level with the count.
      */
-    async evictSynced() {
+    async enforceBufferBounds() {
         try {
-            const cutoff = new Date(Date.now() - 24 * 60 * 60 * 1000);
+            const cutoff = new Date(Date.now() - SYNCED_RETENTION_MS);
             await this.db
                 .deleteFrom('sync_buffer')
                 .where('syncedAt', 'is not', null)
                 .where('syncedAt', '<', cutoff)
                 .execute();
+            const stats = await this.bufferStats();
+            if (!stats)
+                return;
+            const plan = planEviction({
+                totalBytes: stats.totalBytes,
+                maxBytes: this.config.maxBufferSize,
+                totalRows: stats.totalRows,
+                syncedRows: stats.syncedRows,
+            });
+            if (plan.overflowRows === 0)
+                return;
+            // Delivered before undelivered, oldest first within each — so an
+            // overflow small enough to be absorbed by rows the master already has
+            // costs nothing.
+            const delivered = await this.dropOldest('delivered', plan.overflowRows);
+            const undelivered = delivered < plan.overflowRows ? await this.dropOldest('undelivered', plan.overflowRows - delivered) : 0;
+            const dropped = delivered + undelivered;
+            if (dropped === 0)
+                return;
+            // Counted, not predicted: the level follows what was actually dropped.
+            const level = undelivered > 0 ? 'warn' : 'info';
+            this.logger[level]({
+                dropped,
+                undelivered,
+                totalBytes: stats.totalBytes,
+                maxBytes: this.config.maxBufferSize,
+            }, undelivered > 0
+                ? 'Sync buffer over budget — dropped entries the master never received'
+                : 'Sync buffer over budget — dropped delivered entries');
         }
-        catch {
-            // Non-critical
+        catch (err) {
+            // Losing a retention pass is survivable; losing it in silence is how
+            // the unbounded growth stayed invisible in the first place.
+            this.logger.warn({ error: err.message }, 'Sync buffer retention pass failed');
+        }
+    }
+    /**
+     * Delete up to `limit` of the oldest rows of one kind; say how many went.
+     *
+     * By a subquery, not by a list. The ids used to be read into memory and
+     * deleted with `WHERE id IN (…)` — one bound parameter per row, where
+     * SQLite takes 32 766. So the pass worked for a small overflow and refused
+     * exactly the large one, which is the only kind a buffer cut off from its
+     * master produces. Measured on the test node, 2026-09-22: «too many SQL
+     * variables» on 558 passes in a row, 13:03–17:42 UTC, against 4 019 288
+     * rows and 555 MB of payload over a 500 MB budget. The bound bounded
+     * nothing, and said so every thirty seconds in a log nobody on the master
+     * reads.
+     *
+     * Two queries rather than one ordered `syncedAt DESC`, which put NULLs —
+     * the undelivered rows — last on SQLite and FIRST on Postgres, and among
+     * the delivered took the most recently delivered first, against the
+     * comment above it. Both of these are served by `idx_sync_pending
+     * (syncedAt, createdAt)`: delivered rows in the order they were delivered,
+     * which is the order the routine pass retires them in, only sooner; and
+     * undelivered ones in the order they were buffered.
+     */
+    async dropOldest(which, limit) {
+        const oldest = which === 'delivered'
+            ? this.db
+                .selectFrom('sync_buffer')
+                .select('id')
+                .where('syncedAt', 'is not', null)
+                .orderBy('syncedAt', 'asc')
+                .orderBy('createdAt', 'asc')
+                .limit(limit)
+            : this.db
+                .selectFrom('sync_buffer')
+                .select('id')
+                .where('syncedAt', 'is', null)
+                .orderBy('createdAt', 'asc')
+                .limit(limit);
+        const result = await this.db.deleteFrom('sync_buffer').where('id', 'in', oldest).executeTakeFirst();
+        return Number(result.numDeletedRows);
+    }
+    /**
+     * Size and row counts of the WAL, or null when the database cannot say.
+     *
+     * This asked `pg_total_relation_size('sync_buffer')` — a Postgres function,
+     * about the one table that only ever exists where the database is SQLite.
+     * A slave buffers and a master receives, so the measurement the bound above
+     * depends on threw `no such function: pg_total_relation_size` on every
+     * pass, on every slave. Observed on a provisioned node, every thirty
+     * seconds, immediately behind the `Date`-binding fix that let the pass get
+     * this far:
+     *
+     *     05:58:48  Sync buffer retention pass failed
+     *       error: "no such function: pg_total_relation_size"
+     *
+     * Three defects stacked on one guarantee: the bound ran only on the cycle
+     * that did not need it, then could not bind its own cutoff, and then could
+     * not measure. Each fix revealed the next, and only the last one makes
+     * "bounded buffer" true. The routine delete of synced rows sits before this
+     * call and was unaffected throughout.
+     *
+     * The replacement measures the same quantity in the same terms on both
+     * dialects: the bytes of the buffered payloads. That is deliberately not
+     * the relation's on-disk footprint — it excludes indexes, row headers and
+     * Postgres's TOAST compression — because one definition of `maxBufferSize`
+     * that means the same thing on a master and on a slave is worth more than
+     * two that each drift by whatever their storage engine adds. The payload is
+     * the term that grows.
+     *
+     * `cast(payload as text)` is required by both: the column is `jsonb` on
+     * Postgres, where `length()` has no jsonb form, and TEXT on SQLite, where
+     * the cast costs nothing. `octet_length` rather than `length` because the
+     * second counts CHARACTERS — a buffer of Cyrillic log lines measures at
+     * half its size, and a budget is about bytes. Verified against both engines
+     * (postgres:17-alpine, better-sqlite3 13.0.3 / SQLite 3.53.4).
+     */
+    async bufferStats() {
+        const kept = await this.keptBufferStats();
+        if (kept)
+            return kept;
+        const { sql } = await import('kysely');
+        const row = await sql `
+      SELECT coalesce(sum(octet_length(cast(payload as text))), 0) AS total_bytes,
+             count(*) AS total_rows,
+             count(*) FILTER (WHERE "syncedAt" IS NOT NULL) AS synced_rows
+      FROM sync_buffer
+    `.execute(this.db);
+        const first = row.rows[0];
+        if (!first)
+            return null;
+        return {
+            totalBytes: Number(first.total_bytes),
+            totalRows: Number(first.total_rows),
+            syncedRows: Number(first.synced_rows),
+        };
+    }
+    /**
+     * The buffer's figures as its triggers keep them, or null when this
+     * database keeps none (see `SlaveStorageService.createBufferStats`).
+     *
+     * One row instead of a pass over the table: 395–399 ms on the test node's
+     * 4 million rows, every thirty seconds, on the daemon's event loop. Null
+     * sends `bufferStats` back to that pass, and is remembered, so a database
+     * without the row — one this service did not create — costs one refused
+     * query per process rather than one per pass.
+     */
+    async keptBufferStats() {
+        if (this.bufferStatsKept === false)
+            return null;
+        try {
+            const { sql } = await import('kysely');
+            const row = await sql `
+        SELECT totalBytes, totalRows, syncedRows FROM sync_buffer_stats WHERE id = 1
+      `.execute(this.db);
+            const first = row.rows[0];
+            this.bufferStatsKept = Boolean(first);
+            if (!first)
+                return null;
+            return {
+                totalBytes: Number(first.totalBytes),
+                totalRows: Number(first.totalRows),
+                syncedRows: Number(first.syncedRows),
+            };
+        }
+        catch (err) {
+            // Remembered only when the table is not there. Any other refusal is
+            // this pass's, and the next one asks again.
+            if (/no such table|does not exist/i.test(describeError(err)))
+                this.bufferStatsKept = false;
+            return null;
         }
     }
     // ===========================================================================
@@ -285,6 +718,16 @@ export class SyncService {
         if (this.role !== 'master') {
             throw new Error('Only master daemon can receive sync batches');
         }
+        // A batch has to say which node it came from, and this is the only place
+        // that can insist. Everything downstream labels the data with `nodeId`:
+        // logs are stored under it, and metrics are recorded with it as a label
+        // that separates this node's readings from the master's own. An empty or
+        // missing value does not fail there — it quietly merges two machines into
+        // one, and a chart then shows the sum of both under a single name.
+        // Refused by name rather than defaulted.
+        if (typeof batch.nodeId !== 'string' || batch.nodeId.trim() === '') {
+            throw new Error('Sync batch rejected: `nodeId` is required and must be a non-empty string.');
+        }
         // Rate limiting — prevent flood from misbehaving slaves
         if (!this.checkRateLimit(batch.nodeId)) {
             throw new Error(`Rate limit exceeded for node ${batch.nodeId}. Max ${RATE_LIMIT_PER_MINUTE} batches/min.`);
@@ -294,92 +737,397 @@ export class SyncService {
         if (!batch.checksum || batch.checksum !== expectedChecksum) {
             throw new Error(`Checksum mismatch for batch ${batch.batchId}. Expected ${expectedChecksum}, got ${batch.checksum}. Batch rejected.`);
         }
-        let accepted = 0;
-        for (const entry of batch.entries) {
+        const { outcome, causes } = await this.ingest(batch.nodeId, batch.entries);
+        if (outcome.failed.length > 0) {
+            this.logger.warn({
+                nodeId: batch.nodeId,
+                batchId: batch.batchId,
+                failed: outcome.failed.length,
+                total: batch.entries.length,
+                causes: [...causes.entries()].map(([cause, count]) => `${cause} ×${count}`),
+            }, 'Sync batch partially ingested');
+        }
+        else {
+            this.logger.debug({
+                nodeId: batch.nodeId,
+                batchId: batch.batchId,
+                accepted: outcome.accepted.length,
+                duplicates: outcome.duplicates.length,
+                total: batch.entries.length,
+            }, 'Sync batch received');
+        }
+        return {
+            // Kept as a number for the existing RPC contract; the id lists are
+            // what the slave needs to know which entries it may release.
+            accepted: outcome.accepted.length,
+            duplicates: outcome.duplicates.length,
+            acceptedIds: outcome.accepted,
+            duplicateIds: outcome.duplicates,
+            failedIds: outcome.failed,
+            // Released, not stored. The slave must let these go or it offers them
+            // forever; the ERROR beside each one is the only record that they
+            // existed.
+            discardedIds: outcome.discarded,
+        };
+    }
+    /**
+     * Take a batch: as one transaction, or — when the database refuses it as
+     * a whole — one entry at a time, which is what finds the entry it refused.
+     *
+     * Every batch used to take the second road. Each entry was claimed and
+     * ingested in a transaction of its own, so that one entry the database
+     * refuses costs that entry and not its thousand neighbours — and so every
+     * batch cost a thousand `BEGIN … COMMIT`s, on a master whose omnitron-pg
+     * runs `synchronous_commit = on`: a WAL flush per entry, a thousand per
+     * pull. While the machine was idle that was 800–1 100 entries a second
+     * against 38 produced on the test node. Under load a pull outlasted the
+     * 15 s heartbeat, and the next heartbeat started another over the same
+     * entries (see `pullSyncData`). Measured 2026-09-22: nine pulls of the
+     * same 7 918 entries finishing within 122 ms of each other.
+     *
+     * The isolation is kept, and paid for only where it buys something: a
+     * batch the database refuses — a malformed uuid, a foreign key the master
+     * does not have — is retried entry by entry, and that path classifies
+     * each refusal exactly as it always has. The fast path is never worse
+     * than the old one; it falls back to it.
+     */
+    async ingest(nodeId, entries) {
+        try {
+            return { outcome: await this.ingestAsOne(nodeId, entries), causes: new Map() };
+        }
+        catch (err) {
+            // Debug: the path below says, per entry and at the right level, what
+            // was refused and why. That the batch had to take it is not news.
+            this.logger.debug({ nodeId, entries: entries.length, error: describeError(err) }, 'Sync batch refused as a whole — ingesting it entry by entry');
+            return this.ingestEntryByEntry(nodeId, entries);
+        }
+    }
+    /**
+     * The whole batch in one transaction: the claims in one statement, each
+     * destination table's rows in one more.
+     *
+     * An id that appears twice in a batch is taken once and its second
+     * occurrence reported a duplicate — what the per-entry path does, because
+     * there the first occurrence's claim is committed before the second's is
+     * tried.
+     */
+    async ingestAsOne(nodeId, entries) {
+        const outcome = { accepted: [], duplicates: [], failed: [], discarded: [] };
+        const taken = [];
+        await this.db.transaction().execute(async (trx) => {
+            const claimed = await this.claimAll(trx, nodeId, entries.map((e) => e.id));
+            for (const entry of entries) {
+                if (claimed.delete(entry.id)) {
+                    outcome.accepted.push(entry.id);
+                    taken.push(entry);
+                }
+                else {
+                    outcome.duplicates.push(entry.id);
+                }
+            }
+            await this.writeRows(trx, nodeId, taken);
+        });
+        this.recordMetrics(nodeId, taken);
+        return outcome;
+    }
+    /**
+     * One transaction per entry: the road for a batch the database refused.
+     *
+     * Slow on purpose. Each entry succeeds or fails on its own, so the one the
+     * database will never store is named, discarded and released, and a
+     * failure that may pass is left for the next pull — while everything else
+     * in the batch is taken.
+     */
+    async ingestEntryByEntry(nodeId, entries) {
+        const outcome = { accepted: [], duplicates: [], failed: [], discarded: [] };
+        // Why entries were refused, and how many times each reason came up. A
+        // thousand entries failing on one dead database is ONE event; naming the
+        // reason per entry buried the cause under its own repetitions.
+        const causes = new Map();
+        for (const entry of entries) {
             try {
-                switch (entry.category) {
-                    case 'metrics':
-                        await this.ingestMetric(batch.nodeId, entry);
-                        break;
-                    case 'logs':
-                        await this.ingestLog(batch.nodeId, entry);
-                        break;
-                    case 'alerts':
-                        await this.ingestAlert(batch.nodeId, entry);
-                        break;
-                    case 'traces':
-                        await this.ingestTrace(batch.nodeId, entry);
-                        break;
-                    case 'events':
-                    case 'state':
-                        // Events and state changes stored as logs with category label
-                        await this.ingestLog(batch.nodeId, { ...entry, payload: { ...entry.payload, _category: entry.category } });
-                        break;
-                    default:
-                        this.logger.debug({ category: entry.category }, 'Unknown sync category — skipping');
-                        break;
+                // Claim the entry, then ingest it, in one transaction. A failure
+                // rolls the claim back, so the entry is retried rather than recorded
+                // as taken; a conflicting claim means this batch repeats one already
+                // applied, which is what "idempotent" was always supposed to mean.
+                const result = await this.claimAndIngest(nodeId, entry);
+                if (result === 'duplicate')
+                    outcome.duplicates.push(entry.id);
+                else if (result === 'discarded')
+                    outcome.discarded.push(entry.id);
+                else {
+                    outcome.accepted.push(entry.id);
+                    this.recordMetrics(nodeId, [entry]);
                 }
-                accepted++;
             }
             catch (err) {
-                this.logger.warn({ nodeId: batch.nodeId, category: entry.category, error: err.message }, 'Failed to ingest sync entry');
+                // Not marked delivered. The slave keeps it and offers it again —
+                // previously this warning was the only trace of an entry that had
+                // just been dropped on both sides.
+                outcome.failed.push(entry.id);
+                // `(err as Error).message` was the empty string for the commonest
+                // failure of all — an unreachable database arrives as an
+                // `AggregateError` whose reasons live in `.errors`. 76 659 records in
+                // one hour carried `error: ""`, while the cause was named in three
+                // lines of the file next to it.
+                const cause = describeError(err);
+                causes.set(cause, (causes.get(cause) ?? 0) + 1);
+                this.logger.debug({ nodeId, entryId: entry.id, category: entry.category, error: cause }, 'Failed to ingest sync entry — left unacknowledged for retry');
+            }
+        }
+        return { outcome, causes };
+    }
+    /**
+     * Claim entries for this node; the ids that come back are the new ones.
+     *
+     * Sorted, so that two transactions claiming overlapping batches take the
+     * ledger's rows in the same order and cannot deadlock on each other.
+     */
+    async claimAll(db, nodeId, ids) {
+        const rows = [...new Set(ids)].sort().map((entryId) => ({ nodeId, entryId }));
+        const claimed = new Set();
+        for (const part of statementsOf(rows)) {
+            const taken = await db
+                .insertInto('sync_ingested')
+                .values(part)
+                .onConflict((oc) => oc.columns(['nodeId', 'entryId']).doNothing())
+                .returning('entryId')
+                .execute();
+            for (const row of taken)
+                claimed.add(String(row.entryId));
+        }
+        return claimed;
+    }
+    /**
+     * Store claimed entries in the tables the console reads, one statement per
+     * table (per `MAX_BOUND_PARAMETERS` rows). Both roads write through here,
+     * so an entry lands as the same row whichever one took it.
+     */
+    async writeRows(db, nodeId, entries) {
+        const logs = [];
+        const alerts = [];
+        const traces = [];
+        const unknown = [];
+        for (const entry of entries) {
+            switch (entry.category) {
+                case 'metrics':
+                    // No row: a metric's only store is the sink, after the claim
+                    // commits (`recordMetrics`). Its claim is what stops a retry from
+                    // recording it twice.
+                    break;
+                case 'logs':
+                    logs.push(logRow(nodeId, entry));
+                    break;
+                case 'alerts':
+                    alerts.push(alertRow(nodeId, entry));
+                    break;
+                case 'traces':
+                    traces.push(traceRow(nodeId, entry));
+                    break;
+                case 'events':
+                case 'state':
+                    // Stored as logs. The category itself is not kept: `logs` has no
+                    // column for it, and the `_category` this path once added to the
+                    // payload reached none.
+                    logs.push(logRow(nodeId, entry));
+                    break;
+                default:
+                    unknown.push(entry);
+                    break;
             }
         }
-        this.logger.debug({ nodeId: batch.nodeId, batchId: batch.batchId, accepted, total: batch.entries.length }, 'Sync batch received');
-        return { accepted };
+        for (const part of statementsOf(logs))
+            await db.insertInto('logs').values(part).execute();
+        for (const part of statementsOf(alerts))
+            await db.insertInto('alert_events').values(part).execute();
+        for (const part of statementsOf(traces))
+            await db.insertInto('traces').values(part).execute();
+        if (unknown.length > 0) {
+            // An unknown category is not a failure to retry — retrying cannot make
+            // it known. It is claimed and dropped, so the slave releases it, and
+            // said at warning level rather than debug: a category the master does
+            // not understand means the two are out of step.
+            this.logger.warn({
+                nodeId,
+                entries: unknown.length,
+                categories: [...new Set(unknown.map((e) => e.category))],
+                firstEntryId: unknown[0].id,
+            }, 'Unknown sync category — entries discarded');
+        }
+    }
+    /**
+     * Hand claimed remote metrics to the store the console reads.
+     *
+     * The sink records each sample into titan-metrics, which is what the
+     * console's `getSnapshot` and `querySeries` read, tagged with `node` so a
+     * remote reading is a label dimension rather than a second table. The
+     * `metrics_raw` table these were also written to was kept «until the
+     * console is observed showing the label»; it was observed (2026-09-23: 19
+     * series labelled with the test node), and the table — written ~0.93
+     * million rows a day, read and pruned by nothing — is gone (migration 010).
+     * History now lives in titan-metrics' store (in memory, 7 days, lost with a
+     * master restart); how long it should be kept is that store's question.
+     *
+     * AFTER the commit. The sink is not part of the transaction, and it used to
+     * be called inside it, before the row was written: an entry whose write
+     * then failed was recorded anyway, and recorded again by the retry that
+     * stored it. With a batch rolled back and retried entry by entry, that
+     * would have been every metric in it.
+     */
+    recordMetrics(nodeId, entries) {
+        if (!this.metricsSink)
+            return;
+        try {
+            for (const entry of entries) {
+                if (entry.category !== 'metrics')
+                    continue;
+                this.metricsSink({
+                    node: nodeId,
+                    name: String(entry.payload['name'] ?? 'unknown'),
+                    app: String(entry.payload['app'] ?? 'unknown'),
+                    labels: (entry.payload['labels'] ?? {}),
+                    value: Number(entry.payload['value'] ?? 0),
+                });
+            }
+        }
+        catch (err) {
+            // The entries are stored and will be acknowledged; a sink that throws
+            // must not turn that into a retry the ledger then calls a duplicate.
+            this.logger.warn({ nodeId, error: describeError(err) }, 'Stored remote metrics could not be recorded for the console');
+        }
+    }
+    /**
+     * Record the entry as taken and ingest it, atomically.
+     *
+     * Returns `'duplicate'` when the master already holds it — a retry after a
+     * lost acknowledgement, which is delivery, not failure. Throws when
+     * ingestion fails, leaving nothing recorded.
+     */
+    async claimAndIngest(nodeId, entry) {
+        try {
+            return await this.claimAndIngestOnce(nodeId, entry);
+        }
+        catch (err) {
+            if (classifyIngestFailure(err) !== 'permanent')
+                throw err;
+            // The database says this entry can never be stored. Leaving it
+            // unacknowledged would offer it again on every sweep, forever, with
+            // everything behind it in the buffer waiting — and the only symptom is
+            // one "Sync pull stalled" line per pull.
+            //
+            // The claim is made in its own transaction because the one above rolled
+            // back with the failure, taking the claim with it. Claiming it here is
+            // what stops it coming back.
+            await this.db
+                .insertInto('sync_ingested')
+                .values({ nodeId, entryId: entry.id })
+                .onConflict((oc) => oc.columns(['nodeId', 'entryId']).doNothing())
+                .execute()
+                .catch(() => undefined);
+            // ERROR, with everything needed to find the entry: this is data that
+            // will never arrive, and the node has been told to forget it.
+            this.logger.error({ nodeId, entryId: entry.id, category: entry.category, error: err.message }, 'Sync entry rejected permanently — discarded so the buffer can drain');
+            return 'discarded';
+        }
+    }
+    async claimAndIngestOnce(nodeId, entry) {
+        return this.db.transaction().execute(async (trx) => {
+            const claim = await trx
+                .insertInto('sync_ingested')
+                .values({ nodeId, entryId: entry.id })
+                .onConflict((oc) => oc.columns(['nodeId', 'entryId']).doNothing())
+                .returning('entryId')
+                .executeTakeFirst();
+            if (!claim)
+                return 'duplicate';
+            await this.writeRows(trx, nodeId, [entry]);
+            return 'accepted';
+        });
     }
     // ===========================================================================
-    // Master-Side: Data Ingestion
+    // Master-Side: the ledger's window
     // ===========================================================================
-    async ingestMetric(nodeId, entry) {
-        await this.db.insertInto('metrics_raw').values({
-            timestamp: entry.createdAt,
-            nodeId,
-            app: entry.payload['app'] ?? 'unknown',
-            name: entry.payload['name'] ?? 'unknown',
-            value: Number(entry.payload['value'] ?? 0),
-            labels: JSON.stringify(entry.payload['labels'] ?? {}),
-        }).execute();
-    }
-    async ingestLog(nodeId, entry) {
-        await this.db.insertInto('logs').values({
-            timestamp: entry.payload['timestamp'] ?? entry.createdAt,
-            nodeId,
-            app: entry.payload['app'] ?? 'unknown',
-            level: entry.payload['level'] ?? 'info',
-            message: entry.payload['message'] ?? '',
-            labels: JSON.stringify(entry.payload['labels'] ?? {}),
-            traceId: entry.payload['traceId'] ?? null,
-            spanId: entry.payload['spanId'] ?? null,
-            metadata: entry.payload['metadata'] ? JSON.stringify(entry.payload['metadata']) : null,
-        }).execute();
-    }
-    async ingestAlert(_nodeId, entry) {
-        await this.db.insertInto('alert_events').values({
-            ruleId: entry.payload['ruleId'] ?? 'unknown',
-            status: entry.payload['status'] ?? 'firing',
-            value: entry.payload['value'] != null ? String(entry.payload['value']) : null,
-            annotations: entry.payload['annotations'] ? JSON.stringify(entry.payload['annotations']) : null,
-            firedAt: entry.payload['firedAt'] ?? entry.createdAt,
-            resolvedAt: entry.payload['resolvedAt'] ?? null,
-            acknowledgedAt: null,
-            acknowledgedBy: null,
-        }).execute();
-    }
-    async ingestTrace(_nodeId, entry) {
-        await this.db.insertInto('traces').values({
-            traceId: entry.payload['traceId'] ?? 'unknown',
-            spanId: entry.payload['spanId'] ?? 'unknown',
-            parentSpanId: entry.payload['parentSpanId'] ?? null,
-            operationName: entry.payload['operationName'] ?? 'unknown',
-            serviceName: entry.payload['serviceName'] ?? 'unknown',
-            startTime: entry.payload['startTime'] ?? entry.createdAt,
-            endTime: entry.payload['endTime'] ?? entry.createdAt,
-            duration: Number(entry.payload['duration'] ?? 0),
-            status: entry.payload['status'] ?? 'ok',
-            tags: JSON.stringify(entry.payload['tags'] ?? { nodeId: _nodeId }),
-            logs: entry.payload['logs'] ? JSON.stringify(entry.payload['logs']) : null,
-        }).execute();
+    /**
+     * Arm the next ledger pass: in an hour, or in a minute when the last one
+     * hit its ceiling and more is waiting. Chained rather than an interval, so
+     * the cadence is decided with the last pass's result in hand.
+     */
+    scheduleLedgerPrune(delayMs) {
+        if (this.ledgerTimer)
+            clearTimeout(this.ledgerTimer);
+        if (this.disposed)
+            return;
+        this.ledgerTimer = setTimeout(() => {
+            void this.pruneLedger().then((removed) => {
+                if (this.disposed)
+                    return;
+                const plan = planRetention(LEDGER_WINDOW_DAYS);
+                this.scheduleLedgerPrune(plan && removed >= plan.maxThisPass ? LEDGER_BACKLOG_INTERVAL_MS : LEDGER_INTERVAL_MS);
+            });
+        }, delayMs);
+        this.ledgerTimer.unref();
+    }
+    /**
+     * Forget claims older than the dedup window (`LEDGER_WINDOW_DAYS`), in
+     * bounded batches, and say how many went.
+     *
+     * `sync_ingested` was written on every entry and pruned by nothing: 9.9
+     * million rows, 2.2 GB, and ~3.3 million more a day per node, beside an
+     * index on `ingestedAt` whose migration says it is there «for pruning». A
+     * claim is needed only while its node may offer the entry again — see the
+     * window's own comment for why a day covers that.
+     *
+     * By a subquery on the key, like the buffer's eviction, so no statement
+     * binds a parameter per row; `batchSize` rows at a time, so no statement
+     * holds the ingest path's inserts behind it for long.
+     *
+     * Said at info whenever it removed something, with the oldest claim left:
+     * a month from now, «the ledger is stable» must be tellable from «the
+     * pruner never ran» by reading the log rather than the code.
+     */
+    async pruneLedger(plan = planRetention(LEDGER_WINDOW_DAYS)) {
+        if (!plan || this.disposed)
+            return 0;
+        let removed = 0;
+        try {
+            for (let i = 0; i < batchesPerPass(plan); i++) {
+                if (this.disposed)
+                    break;
+                const oldest = this.db
+                    .selectFrom('sync_ingested')
+                    .select(['nodeId', 'entryId'])
+                    .where('ingestedAt', '<', plan.cutoff)
+                    .limit(plan.batchSize);
+                const result = await this.db
+                    .deleteFrom('sync_ingested')
+                    .where(({ eb, refTuple }) => eb(refTuple('nodeId', 'entryId'), 'in', oldest.$asTuple('nodeId', 'entryId')))
+                    .executeTakeFirst();
+                const n = Number(result.numDeletedRows);
+                removed += n;
+                if (n < plan.batchSize)
+                    break;
+            }
+            if (removed > 0) {
+                const left = await this.db
+                    .selectFrom('sync_ingested')
+                    .select((eb) => eb.fn.min('ingestedAt').as('oldest'))
+                    .executeTakeFirst();
+                this.logger.info({
+                    removed,
+                    cutoff: plan.cutoff.toISOString(),
+                    oldestKept: left?.oldest ? toIsoUtc(left.oldest) : null,
+                    windowDays: LEDGER_WINDOW_DAYS,
+                }, 'Pruned sync ledger claims past the dedup window');
+            }
+            else {
+                this.logger.debug({ cutoff: plan.cutoff.toISOString() }, 'Sync ledger holds nothing past the dedup window');
+            }
+        }
+        catch (err) {
+            // A pruner that keeps failing is the ledger growing again, quietly.
+            this.logger.error({ error: describeError(err), removed }, 'Sync ledger prune failed');
+        }
+        return removed;
     }
     // ===========================================================================
     // Rate Limiting (master-side)