@pasko70/pibo 3.4.4 → 3.5.0

package/dist/data/telemetry-maintenance.js

@@ -0,0 +1,110 @@
+export const TELEMETRY_MAINTENANCE_SCHEMA = `CREATE TABLE IF NOT EXISTS telemetry_maintenance_job (
+ id INTEGER PRIMARY KEY CHECK(id=1),retention_scope TEXT,cutoff TEXT NOT NULL,status TEXT NOT NULL,table_index INTEGER NOT NULL DEFAULT 0,class_index INTEGER NOT NULL DEFAULT 0,cursor_time TEXT NOT NULL DEFAULT '',cursor_row INTEGER NOT NULL DEFAULT 0,
+ scanned INTEGER NOT NULL DEFAULT 0,deleted INTEGER NOT NULL DEFAULT 0,protected INTEGER NOT NULL DEFAULT 0,batches INTEGER NOT NULL DEFAULT 0,updated_at TEXT NOT NULL
+);`;
+const CLASSES = ["live", "diagnostic", "provider_event", "payload_preview", "incident"];
+/** A live owner updates the job on every bounded batch, so a stale stamp proves it stopped. */
+export const TELEMETRY_MAINTENANCE_OWNER_LEASE_MS = 30_000;
+const TABLES = [
+    { name: "telemetry_provider_events", time: "received_at", status: false },
+    { name: "telemetry_tool_calls", time: "updated_at", status: true },
+    { name: "telemetry_provider_requests", time: "updated_at", status: true },
+    { name: "telemetry_phases", time: "updated_at", status: true },
+    { name: "telemetry_turns", time: "updated_at", status: true },
+];
+/** Only optional telemetry rows are eligible. No product, receipt, retry or payload deletion. */
+export class TelemetryMaintenance {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    status() { return this.db.prepare("SELECT * FROM telemetry_maintenance_job WHERE id=1").get(); }
+    start(cutoff, retentionScope) {
+        if (retentionScope && !CLASSES.includes(retentionScope))
+            throw Error("Invalid maintenance retention scope");
+        if (!Number.isFinite(Date.parse(cutoff)))
+            throw Error("Invalid telemetry cutoff");
+        const existing = this.status();
+        if (existing && (existing.status === "running" || existing.status === "paused")) {
+            if (existing.retention_scope === (retentionScope ?? null))
+                return existing;
+            if (existing.status === "paused")
+                throw Error("Telemetry maintenance is paused; resume or cancel it explicitly before changing scope");
+            // A different scope only conflicts while its owner still steps the job. A persisted job whose
+            // owner stopped updating it is reclaimable, so one narrow manual prune that outlived its process
+            // cannot disable automatic retention permanently.
+            if (Date.now() - Date.parse(existing.updated_at) < TELEMETRY_MAINTENANCE_OWNER_LEASE_MS)
+                throw Error("Another retention scope is already running");
+        }
+        this.db.prepare(`INSERT INTO telemetry_maintenance_job(id,cutoff,status,updated_at,retention_scope,class_index) VALUES(1,?,'running',?,?,?)
+   ON CONFLICT(id) DO UPDATE SET cutoff=excluded.cutoff,status='running',table_index=0,retention_scope=excluded.retention_scope,class_index=excluded.class_index,cursor_time='',cursor_row=0,scanned=0,deleted=0,protected=0,batches=0,updated_at=excluded.updated_at`).run(cutoff, new Date().toISOString(), retentionScope ?? null, retentionScope ? CLASSES.indexOf(retentionScope) : 0);
+        return this.status();
+    }
+    control(action) {
+        const status = action === "pause" ? "paused" : action === "resume" ? "running" : "cancelled";
+        this.db.prepare("UPDATE telemetry_maintenance_job SET status=?,updated_at=? WHERE id=1 AND status IN ('running','paused')").run(status, new Date().toISOString());
+        return this.status();
+    }
+    step(options = {}) {
+        const limit = options.rows ?? 128, budget = options.milliseconds ?? 4;
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 512 || !Number.isFinite(budget) || budget <= 0 || budget > 20)
+            throw Error("Invalid maintenance batch budget");
+        if (this.status()?.status !== "running")
+            return this.status();
+        this.db.exec("BEGIN IMMEDIATE");
+        try {
+            const state = this.status();
+            if (state.status !== "running") {
+                this.db.exec("COMMIT");
+                return state;
+            }
+            const spec = TABLES[state.table_index];
+            const rows = this.db.prepare(`SELECT rowid AS cursor_row,${spec.time} AS cursor_time,pibo_session_id,turn_id ${spec.name !== "telemetry_turns" ? ",provider_request_id" : ""} ${spec.status ? ',status' : ''} FROM ${spec.name}
+    WHERE retention_class=? AND (${spec.time},rowid)>(?,?) AND ${spec.time}<? ORDER BY ${spec.time},rowid LIMIT ?`).all(CLASSES[state.class_index], state.cursor_time, state.cursor_row, state.cutoff, limit);
+            const activeSession = this.db.prepare("SELECT 1 FROM sessions WHERE id=? AND status='running'");
+            const activeTurn = this.db.prepare("SELECT 1 FROM telemetry_turns WHERE turn_id=? AND status IN ('queued','running')");
+            const activeProvider = this.db.prepare("SELECT 1 FROM telemetry_provider_requests p WHERE p.provider_request_id=? AND (p.status NOT IN ('completed','error','aborted','timeout') OR EXISTS (SELECT 1 FROM telemetry_turns t WHERE t.turn_id=p.turn_id AND t.status IN ('queued','running'))) ");
+            const remove = this.db.prepare(`DELETE FROM ${spec.name} WHERE rowid=? AND ${spec.time}=?`);
+            const started = performance.now();
+            let scanned = 0, deleted = 0, protectedRows = 0;
+            let cursorTime = state.cursor_time, cursorRow = state.cursor_row;
+            for (const row of rows) {
+                const terminal = !spec.status || ["ok", "completed", "error", "aborted", "timeout"].includes(row.status ?? "");
+                if (!terminal || (row.pibo_session_id && activeSession.get(row.pibo_session_id)) || (row.turn_id && activeTurn.get(row.turn_id)) || (row.provider_request_id && activeProvider.get(row.provider_request_id)))
+                    protectedRows++;
+                else
+                    deleted += Number(remove.run(row.cursor_row, row.cursor_time).changes);
+                scanned++;
+                cursorTime = row.cursor_time;
+                cursorRow = row.cursor_row;
+                if (performance.now() - started >= budget)
+                    break;
+            }
+            let tableIndex = state.table_index, classIndex = state.class_index;
+            let status = state.status;
+            if (scanned === rows.length && rows.length < limit) {
+                cursorTime = "";
+                cursorRow = 0;
+                if (state.retention_scope) {
+                    tableIndex++;
+                }
+                else {
+                    classIndex++;
+                    if (classIndex >= CLASSES.length) {
+                        classIndex = 0;
+                        tableIndex++;
+                    }
+                }
+                if (tableIndex >= TABLES.length)
+                    status = "completed";
+            }
+            this.db.prepare(`UPDATE telemetry_maintenance_job SET table_index=?,class_index=?,cursor_time=?,cursor_row=?,status=?,scanned=scanned+?,deleted=deleted+?,protected=protected+?,batches=batches+1,updated_at=? WHERE id=1`).run(tableIndex, classIndex, cursorTime, cursorRow, status, scanned, deleted, protectedRows, new Date().toISOString());
+            this.db.exec("COMMIT");
+            return this.status();
+        }
+        catch (error) {
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+}

package/dist/data/telemetry-retention.js

@@ -1,3 +1,4 @@
+import { TelemetryMaintenance, TELEMETRY_MAINTENANCE_SCHEMA } from "./telemetry-maintenance.js";
 const RETENTION_CLASSES = ["live", "diagnostic", "provider_event", "incident", "payload_preview"];
 const PRUNE_TABLES = [
     { table: "telemetry_provider_events", cutoffColumn: "received_at", byteExpression: "byte_size" },
@@ -23,16 +24,24 @@ export function getTelemetryRetentionStats(db) {
     };
 }
 export function pruneTelemetryRetention(db, input) {
-    const plan = telemetryPrunePlan(db, input.retentionClass, input.before);
     if (!input.apply) {
+        const plan = telemetryPrunePlan(db, input.retentionClass, input.before);
         return { retentionClass: input.retentionClass, before: input.before, applied: false, rowsMatched: plan.rows, bytesMatched: plan.bytes, rowsDeleted: 0 };
     }
-    let rowsDeleted = 0;
-    for (const spec of PRUNE_TABLES) {
-        const result = db.prepare(`DELETE FROM ${spec.table} WHERE retention_class = ? AND ${spec.cutoffColumn} < ?`).run(input.retentionClass, input.before);
-        rowsDeleted += Number(result.changes ?? 0);
-    }
-    return { retentionClass: input.retentionClass, before: input.before, applied: true, rowsMatched: plan.rows, bytesMatched: plan.bytes, rowsDeleted };
+    db.exec(TELEMETRY_MAINTENANCE_SCHEMA);
+    const maintenance = new TelemetryMaintenance(db);
+    let state = maintenance.start(input.before, input.retentionClass);
+    if (state.status === "paused")
+        state = maintenance.control("resume");
+    const previous = state.deleted, started = performance.now();
+    let scanned = 0;
+    do {
+        const before = state.scanned;
+        state = maintenance.step({ rows: Math.min(128 - scanned, 128), milliseconds: 4 });
+        scanned += state.scanned - before;
+    } while (state.status === "running" && scanned < 128 && performance.now() - started < 20);
+    const rowsDeleted = state.deleted - previous;
+    return { retentionClass: input.retentionClass, before: state.cutoff, applied: true, rowsMatched: scanned, bytesMatched: 0, rowsDeleted, completed: state.status === "completed" };
 }
 function statsForTable(db, table, sqlTable, byteExpression, retentionClass) {
     const row = db.prepare(`SELECT COUNT(*) AS row_count, COALESCE(SUM(${byteExpression}), 0) AS byte_count FROM ${sqlTable} WHERE retention_class = ?`).get(retentionClass);

package/dist/data/telemetry-worker.js

@@ -0,0 +1,111 @@
+import { dirname, join } from "node:path";
+import { TelemetryCaptureWriter } from "./telemetry-capture.js";
+import { statSync } from "node:fs";
+import { parentPort, workerData, threadId } from "node:worker_threads";
+import { DatabaseSync } from "node:sqlite";
+import { TelemetryStore } from "./telemetry.js";
+import { PiboRuntimeTelemetryRecorder } from "../core/runtime-telemetry.js";
+import { PiboProviderTelemetryRecorder } from "../core/provider-telemetry.js";
+const db = new DatabaseSync(workerData.path);
+db.exec("PRAGMA busy_timeout=10; PRAGMA synchronous=FULL; PRAGMA foreign_keys=ON");
+const store = new TelemetryStore(db);
+const capture = new TelemetryCaptureWriter(join(dirname(workerData.path), "telemetry-captures"));
+const captureTimer = setInterval(() => capture.append([]), 1000);
+captureTimer.unref();
+const measured = Boolean(workerData.measure);
+let currentKind = "startup";
+const measurements = {};
+if (measured) {
+    const prepare = db.prepare.bind(db);
+    db.prepare = (sql) => {
+        const statement = prepare(sql);
+        for (const method of ["run", "get", "all"]) {
+            const original = statement[method].bind(statement);
+            statement[method] = (...args) => {
+                const kind = measurements[currentKind];
+                const verb = sql.trim().split(/\s/, 1)[0].toLowerCase();
+                if (kind) {
+                    const label = ["insert", "update", "delete", "select"].includes(verb) ? verb : "other";
+                    kind.sql[label] = (kind.sql[label] ?? 0) + 1;
+                }
+                return original(...args);
+            };
+        }
+        return statement;
+    };
+}
+let errors = 0;
+let transactions = 0;
+let operations = 0;
+let busy = 0;
+const runtimes = new Map();
+function runtimeFor(input) {
+    const key = `${input.providerEventMode}:${input.progressFlushIntervalMs}`;
+    let runtime = runtimes.get(key);
+    if (!runtime) {
+        if (runtimes.size >= 4)
+            runtimes.delete(runtimes.keys().next().value);
+        runtime = new PiboRuntimeTelemetryRecorder(store, () => { errors++; }, { providerEventMode: input.providerEventMode, progressFlushIntervalMs: input.progressFlushIntervalMs });
+        runtimes.set(key, runtime);
+    }
+    return runtime;
+}
+parentPort.on("message", (request) => {
+    const started = performance.now();
+    let processed = 0;
+    const initialErrors = errors;
+    try {
+        if (request.command.commands.length > 64)
+            throw Error("Telemetry batch count exceeded");
+        if (started > request.deadline)
+            throw Error("Telemetry batch expired");
+        try {
+            store.transaction(() => {
+                for (const input of request.command.commands) {
+                    if (processed && performance.now() - started >= 8)
+                        break;
+                    currentKind = input.recorder === "runtime" && input.command.kind === "output" ? input.command.event.type : `${input.recorder}.${input.command.kind}`;
+                    if (measured && !measurements[currentKind]) {
+                        if (Object.keys(measurements).length >= 32)
+                            currentKind = "other";
+                        measurements[currentKind] ??= { operations: 0, sql: {}, executionMs: 0 };
+                    }
+                    const operationStart = performance.now();
+                    if (input.recorder === "runtime")
+                        runtimeFor(input).executeTelemetryCommand(input.command);
+                    else
+                        new PiboProviderTelemetryRecorder({ store, session: input.session, model: input.model, onError: () => { errors++; } }).executeTelemetryCommand(input.command);
+                    if (measured) {
+                        measurements[currentKind].operations++;
+                        measurements[currentKind].executionMs += performance.now() - operationStart;
+                    }
+                    processed++;
+                }
+            });
+            transactions++;
+            operations += processed;
+        }
+        catch (error) {
+            runtimes.clear();
+            if (error instanceof Error && /busy|locked/i.test(error.message)) {
+                busy++;
+                processed = 0;
+            }
+            else
+                throw error;
+        }
+        if (processed)
+            capture.append(request.command.commands.slice(0, processed));
+        const result = { processed, errors: Math.min(processed, errors - initialErrors), ms: performance.now() - started, stats: { pid: process.pid, threadId, capture: capture.status(), transactions, operations, busy, rssBytes: process.memoryUsage.rss(), heapUsedBytes: process.memoryUsage().heapUsed, synchronous: "FULL", ...(measured ? { measurements, walBytes: (() => { try {
+                        return statSync(workerData.path + "-wal").size;
+                    }
+                    catch {
+                        return 0;
+                    } })() } : {}) } };
+        parentPort.postMessage({ id: request.id, value: result });
+    }
+    catch {
+        parentPort.postMessage({ id: request.id, error: { code: "telemetry_failed", message: "Optional telemetry batch failed" } });
+    }
+});
+parentPort.postMessage({ ready: true, worker: { pid: process.pid, threadId, kind: "telemetry" } });

package/dist/data/telemetry-writer.js

@@ -1,114 +1,181 @@
-const DEFAULT_FLUSH_INTERVAL_MS = 25;
-const DEFAULT_MAX_PENDING_OPERATIONS = 1_024;
-/**
- * Gateway-scoped, ordered telemetry writer.
- *
- * Normal writes are deferred briefly so telemetry from multiple routed sessions
- * shares one SQLite transaction. The queue never drops lifecycle events: when
- * the hard bound is reached, it drains immediately in the caller instead.
- */
+import { BoundedWorkerClient, boundedMessageBytes } from "./bounded-worker-client.js";
+import { isTelemetryProgress } from "./telemetry-command.js";
+/** Optional diagnostic projection. Product lifecycle/final events remain owned by the durable output outbox. */
 export class AsyncTelemetryWriter {
     store;
     options;
-    flushIntervalMs;
-    maxPendingOperations;
+    client;
+    path;
+    restartAfter = 0;
+    restarts = 0;
     pending = [];
+    pendingBytes = 0;
+    inFlight = 0;
     flushTimer;
-    flushing = false;
+    flushing;
     closed = false;
+    limit;
+    byteLimit;
+    ageLimit;
+    interval;
+    accepted = 0;
+    completed = 0;
+    rejected = 0;
+    failed = 0;
+    expired = 0;
+    batches = 0;
+    maxBatchMs = 0;
+    workerStats;
     constructor(store, options = {}) {
         this.store = store;
         this.options = options;
-        this.flushIntervalMs = nonNegativeFinite(options.flushIntervalMs, DEFAULT_FLUSH_INTERVAL_MS);
-        this.maxPendingOperations = positiveInteger(options.maxPendingOperations, DEFAULT_MAX_PENDING_OPERATIONS);
+        this.limit = options.maxPendingOperations ?? 1024;
+        this.byteLimit = options.maxPendingBytes ?? 4 * 1024 * 1024;
+        this.ageLimit = options.maxAgeMs ?? 2000;
+        this.interval = options.flushIntervalMs ?? 25;
+        for (const n of [this.limit, this.byteLimit, this.ageLimit])
+            if (!Number.isSafeInteger(n) || n <= 0)
+                throw Error("Telemetry budgets must be positive integers");
+        if (!Number.isFinite(this.interval) || this.interval < 0)
+            throw Error("Invalid telemetry batching interval");
+        this.path = store.databasePath;
+        if (this.path)
+            this.startWorker();
     }
+    startWorker() {
+        this.restartAfter = Date.now() + 1000;
+        this.client = new BoundedWorkerClient(new URL("./telemetry-worker.js", import.meta.url), { maxPending: 1, maxPendingBytes: 512 * 1024, maxMessageBytes: 512 * 1024, maxAgeMs: this.ageLimit, workerOptions: { workerData: { path: this.path, measure: this.options.measure === true } } });
+    }
+    /** Compatibility for the local in-memory adapter only; closures never execute on a file-backed producer. */
     enqueue(write, onError) {
-        if (this.closed) {
-            this.reportError(new Error("Telemetry writer is closed."), onError);
+        if (this.client) {
+            this.reject(Error("File telemetry requires a structured command"), onError);
             return false;
         }
-        this.pending.push({ write, onError });
-        if (this.pending.length >= this.maxPendingOperations) {
-            this.flushNow();
+        return this.append({ write, onError, bytes: 64, at: performance.now() }, false);
+    }
+    record(command, fallback, onError) {
+        try {
+            const bytes = boundedMessageBytes(command, 64 * 1024);
+            return this.append({ ...(this.client ? { command: structuredClone(command) } : { write: fallback }), bytes, onError, at: performance.now() }, isTelemetryProgress(command));
         }
-        else {
-            this.scheduleFlush();
+        catch (error) {
+            this.reject(error, onError);
+            return false;
         }
-        return true;
     }
-    async flush() {
-        this.flushNow();
-    }
-    async dispose() {
-        if (this.closed)
-            return;
-        this.flushNow();
-        this.closed = true;
+    append(item, progress) {
+        const reserve = progress ? Math.min(128, Math.floor(this.limit / 4)) : 0;
+        const reserveBytes = progress ? Math.min(512 * 1024, Math.floor(this.byteLimit / 4)) : 0;
+        if (this.closed || this.pending.length + this.inFlight >= this.limit - reserve || this.pendingBytes + item.bytes > this.byteLimit - reserveBytes) {
+            this.reject(Error(this.closed ? "Telemetry writer is closed" : "Optional telemetry capacity exhausted"), item.onError);
+            return false;
+        }
+        item.sequence = ++this.accepted;
+        this.pending.push(item);
+        this.pendingBytes += item.bytes;
+        // Pressure only schedules asynchronous work; it never drains SQLite in the producer.
+        this.schedule(this.pending.length >= 64 ? 0 : this.interval);
+        return true;
     }
-    scheduleFlush() {
-        if (this.flushTimer)
+    schedule(delay) {
+        if (this.flushTimer || this.flushing || this.closed)
             return;
-        this.flushTimer = setTimeout(() => {
-            this.flushTimer = undefined;
-            this.flushNow();
-        }, this.flushIntervalMs);
-        this.flushTimer.unref();
+        this.flushTimer = setTimeout(() => { this.flushTimer = undefined; void this.flush(); }, delay);
+        this.flushTimer.unref?.();
     }
-    flushNow() {
-        if (this.flushing)
-            return;
+    async flush() {
+        const target = this.accepted;
         if (this.flushTimer)
             clearTimeout(this.flushTimer);
         this.flushTimer = undefined;
-        this.flushing = true;
-        try {
-            while (this.pending.length > 0) {
-                const batch = this.pending;
-                this.pending = [];
-                try {
-                    this.store.transaction(() => {
-                        for (const operation of batch) {
-                            try {
-                                operation.write();
-                            }
-                            catch (error) {
-                                this.reportError(error, operation.onError);
-                            }
-                        }
-                    });
+        for (;;) {
+            if (this.flushing) {
+                await this.flushing;
+                continue;
+            }
+            if (!this.pending.length || this.pending[0].sequence > target)
+                return;
+            this.flushing = this.drain(target).finally(() => { this.flushing = undefined; if (this.pending.length && !this.closed)
+                this.schedule(0); });
+            await this.flushing;
+        }
+    }
+    async drain(target) {
+        while (this.pending.length && this.pending[0].sequence <= target) {
+            const batch = [];
+            let bytes = 0;
+            while (this.pending.length && this.pending[0].sequence <= target && batch.length < 64 && bytes + this.pending[0].bytes <= 256 * 1024) {
+                const item = this.pending.shift();
+                bytes += item.bytes;
+                batch.push(item);
+            }
+            this.inFlight = batch.length;
+            const live = batch.filter(item => { if (performance.now() - item.at <= this.ageLimit)
+                return true; this.expired++; return false; });
+            let processed = live.length;
+            try {
+                if (live.length && this.client) {
+                    if (this.client.status().closed && this.client.status().exited && Date.now() >= this.restartAfter) {
+                        this.restarts++;
+                        this.startWorker();
+                    }
+                    // Startup consumes the same bounded queue age, without loading a second schema owner on the gateway thread.
+                    while (!this.client.status().ready && !this.client.status().closed && performance.now() - live[0].at < this.ageLimit)
+                        await new Promise(resolve => setTimeout(resolve, 5));
+                    const remainingAge = this.ageLimit - (performance.now() - live[0].at);
+                    if (remainingAge < Math.min(50, this.ageLimit / 4)) {
+                        this.expired += live.length;
+                    }
+                    else {
+                        const result = await this.client.request({ commands: live.map(item => item.command) }, { priority: "background", timeoutMs: remainingAge });
+                        processed = result.processed;
+                        this.failed += result.errors;
+                        this.completed += processed - result.errors;
+                        this.maxBatchMs = Math.max(this.maxBatchMs, result.ms);
+                        this.workerStats = result.stats;
+                        this.batches++;
+                    }
                 }
-                catch (error) {
-                    for (const operation of batch)
-                        this.reportError(error, operation.onError);
+                else if (live.length) {
+                    // Explicit in-memory test adapter uses the same bounded batches and asynchronous entry boundary.
+                    await new Promise(resolve => setImmediate(resolve));
+                    this.store.transaction(() => { for (const item of live) {
+                        try {
+                            item.write?.();
+                            this.completed++;
+                        }
+                        catch (error) {
+                            this.failed++;
+                            this.report(error, item.onError);
+                        }
+                    } });
+                    this.batches++;
                 }
             }
-        }
-        finally {
-            this.flushing = false;
-            if (!this.closed && this.pending.length > 0)
-                this.scheduleFlush();
+            catch (error) {
+                this.failed += live.length;
+                for (const item of live)
+                    this.report(error, item.onError);
+            }
+            const remaining = live.slice(processed);
+            this.pending.unshift(...remaining);
+            this.pendingBytes -= bytes - remaining.reduce((sum, item) => sum + item.bytes, 0);
+            this.inFlight = 0;
+            if (remaining.length)
+                await new Promise(resolve => setTimeout(resolve, 10));
         }
     }
-    reportError(error, operationHandler) {
-        try {
-            operationHandler?.(error);
-        }
-        catch {
-            // Telemetry error reporting must not affect runtime work.
-        }
-        if (operationHandler === this.options.onError)
-            return;
+    status() { return { mode: this.client ? "worker" : "in-memory", closed: this.closed, queued: this.pending.length, inFlight: this.inFlight, pendingBytes: this.pendingBytes, oldestAgeMs: this.pending.length ? performance.now() - this.pending[0].at : 0, accepted: this.accepted, restarts: this.restarts, completed: this.completed, rejected: this.rejected, failed: this.failed, expired: this.expired, batches: this.batches, maxBatchMs: this.maxBatchMs, worker: this.workerStats, transport: this.client ? { ready: this.client.status().ready, closed: this.client.status().closed, exited: this.client.status().exited } : undefined, limits: { count: this.limit, bytes: this.byteLimit, ageMs: this.ageLimit, batchCount: 64, batchBytes: 256 * 1024, batchTimeMs: 8 } }; }
+    async dispose() { if (this.closed)
+        return; this.closed = true; await this.flush(); await this.client?.close(); }
+    reject(error, handler) { this.rejected++; this.report(error, handler); }
+    report(error, handler) { try {
+        handler?.(error);
+    }
+    catch { } if (handler !== this.options.onError)
         try {
             this.options.onError?.(error);
         }
-        catch {
-            // Telemetry error reporting must not affect runtime work.
-        }
-    }
-}
-function nonNegativeFinite(value, fallback) {
-    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : fallback;
-}
-function positiveInteger(value, fallback) {
-    return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : fallback;
+        catch { } }
 }

package/dist/data/telemetry.js

@@ -8,6 +8,11 @@ export class TelemetryStore {
     constructor(db) {
         this.db = db;
     }
+    /** SQLite-owned path; empty for the explicitly local in-memory test adapter. */
+    get databasePath() {
+        const row = this.db.prepare("PRAGMA database_list").all().find(row => row.name === "main");
+        return typeof row?.file === "string" && row.file ? row.file : undefined;
+    }
     transaction(action) {
         if (this.db.isTransaction)
             return action();

package/dist/debug/index.js

@@ -8,6 +8,11 @@ export async function runDebugCli(argv = process.argv) {
             printDebugDiscovery();
             return;
         }
+        if (args[0] === "backup") {
+            const { runStorageBackupCli } = await import("./storage-backup.js");
+            await runStorageBackupCli(args.slice(1));
+            return;
+        }
         if (args[0] === "db") {
             await runDebugDb(args.slice(1));
             return;
@@ -536,11 +541,55 @@ async function runDebugSignals(args) {
         console.log(formatSignalSnapshotText(payload));
     }
 }
+async function runDebugTelemetryMaintenance(args) {
+    if (!args.length || args.includes("--help") || args.includes("-h")) {
+        console.log(`pibo debug telemetry maintenance - bounded optional diagnostic cleanup
+Commands:
+  status                         Read the durable job and progress
+  start --before <iso> --apply    Start a job; no deletion until step or gateway worker
+  step --apply                   Execute at most 128 rows / 4 ms cooperatively
+  pause --apply                  Pause between batches
+  resume --apply                 Mark the paused job ready
+  cancel --apply                 Cancel without undoing committed batches
+Use --json for structured output. Product history, receipts and payload files are excluded.`);
+        return;
+    }
+    const action = args[0];
+    if (!["status", "start", "step", "pause", "resume", "cancel"].includes(action))
+        throw Error("Unknown maintenance action; use maintenance --help");
+    const options = parseOptions(args.slice(1));
+    if (action !== "status" && !options.apply)
+        throw Error("Maintenance mutations require --apply; inspect status first");
+    const store = resolveDebugStore("pibo-data");
+    if (!store.exists)
+        throw Error("Pibo data store is missing");
+    const { DatabaseSync } = await import("node:sqlite");
+    const { TelemetryMaintenance } = await import("../data/telemetry-maintenance.js");
+    const db = new DatabaseSync(store.path, { readOnly: action === "status" });
+    db.exec("PRAGMA busy_timeout=10; PRAGMA synchronous=FULL; PRAGMA foreign_keys=ON");
+    try {
+        const maintenance = new TelemetryMaintenance(db);
+        const result = action === "status" ? maintenance.status() : action === "start" ? maintenance.start(options.before ?? "") : action === "step" ? maintenance.step() : maintenance.control(action);
+        console.log(JSON.stringify(result ?? { status: "not_started" }, null, options.json ? 2 : undefined));
+    }
+    finally {
+        db.close();
+    }
+}
 async function runDebugTelemetry(args) {
     if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
         printDebugTelemetryDiscovery();
         return;
     }
+    if (args[0] === "maintenance") {
+        await runDebugTelemetryMaintenance(args.slice(1));
+        return;
+    }
+    if (args[0] === "capture") {
+        const { runTelemetryCaptureCli } = await import("./telemetry-capture.js");
+        await runTelemetryCaptureCli(args.slice(1));
+        return;
+    }
     const command = args[0];
     const options = parseOptions(args.slice(1));
     const { formatJson } = await import("./sql.js");
@@ -1311,6 +1360,7 @@ function printDebugDiscovery() {
     console.log(`pibo debug - inspect local Pibo data
 
 Commands:
+  backup   Create, verify or restore an explicit SQLite and payload snapshot
   db       Inspect and query local SQLite stores
   session  Inspect one Pibo Session by id or Chat URL
   summary  Show compact session diagnosis and drill-down commands
@@ -1491,6 +1541,8 @@ Commands:
   stale     List read-only stale active work
   stats     Show telemetry retention counts and byte estimates
   prune     Dry-run telemetry retention cleanup unless --apply is explicit
+  maintenance  Inspect or control bounded cleanup; use maintenance --help
+  capture   Scope provider detail and inspect inert archives; use capture --help
 
 Next:
   pibo debug telemetry sessions --active