larkin 0.2.70

package/dist/platform/telemetry-spool.mjs

@@ -0,0 +1,653 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import zlib from "node:zlib";
+import { inspectProcess } from "./process-state.mjs";
+const READY = /^(?:span-[0-9a-f-]+|import-[0-9a-f]{64})\.json$/;
+const REMNANT = /^\.(?:corrupt|write|ack|delete|stale-lock|purge)-[0-9A-Za-z-]+(?:\.(?:json|tmp|dir))?$/;
+const HEX_TRACE = /^[0-9a-f]{32}$/;
+const HEX_SPAN = /^[0-9a-f]{16}$/;
+const SPAN_NAMES = new Set(["larkin.message.process", "feishu.receive", "runtime.deliver", "agent.turn", "model.activity", "tool.execute", "inbox.consume", "feishu.send",
+    "document.comment.receive", "document.comment.gate", "document.comment.pending", "document.comment.replay", "document.comment.resolve", "document.comment.inbox", "document.comment.reply",
+    "pi.prompt.wait", "pi.compaction", "pi.rpc.submit", "pi.rpc.lifecycle", "pi.output.wait", "pi.generation", "pi.tool.wait", "pi.rpc.settle"]);
+const ATTRIBUTE_KEYS = new Set(["service.name", "service.version", "service.instance.id", "larkin.agent.id_hash", "messaging.message.id_hash", "larkin.message.relation", "larkin.message.source",
+    "larkin.observation.boundary", "larkin.activity.type", "larkin.filter.reason", "larkin.runtime.id", "larkin.runtime.distribution", "larkin.operation.outcome",
+    "larkin.pi.preflight.outcome", "larkin.pi.preflight.progress"]);
+const SENSITIVE = /(?:bearer\s|(?:api[_-]?key|authorization|password|token|secret|cookie)\s*[=:]|(?:sk|ghp|github_pat)-?[a-z0-9_-]{8})/i;
+const ABSOLUTE_PATH = /(?:^|[\s"'=])(?:\/(?!\/)[^\s"']+|[A-Za-z]:[\\/][^\s"']+)/;
+const emptyDiagnostics = () => ({ droppedFiles: 0, cleanedRemnantFiles: 0, droppedSpans: 0, lastUploadAt: null, lastErrorCategory: null });
+const invalidPayload = () => { throw new Error("invalid telemetry payload"); };
+function validateValue(value, depth = 0) {
+    if (depth > 6 || !value || typeof value !== "object" || Array.isArray(value))
+        invalidPayload();
+    const object = value;
+    const keys = Object.keys(object);
+    if (keys.length !== 1 || !["stringValue", "boolValue", "intValue", "doubleValue", "arrayValue"].includes(keys[0]))
+        invalidPayload();
+    if ("stringValue" in object) {
+        const text = object.stringValue;
+        if (typeof text !== "string" || text.length > 128 || ABSOLUTE_PATH.test(text) || SENSITIVE.test(text))
+            invalidPayload();
+    }
+    else if ("boolValue" in object && typeof object.boolValue !== "boolean")
+        invalidPayload();
+    else if ("intValue" in object && !/^-?[0-9]{1,20}$/.test(String(object.intValue)))
+        invalidPayload();
+    else if ("doubleValue" in object && (typeof object.doubleValue !== "number" || !Number.isFinite(object.doubleValue)))
+        invalidPayload();
+    else if ("arrayValue" in object) {
+        const arrayValue = object.arrayValue;
+        if (!arrayValue || Object.keys(arrayValue).some((key) => key !== "values") || !Array.isArray(arrayValue.values) || arrayValue.values.length > 32)
+            invalidPayload();
+        for (const item of arrayValue.values)
+            validateValue(item, depth + 1);
+    }
+}
+function validateAttributes(value) {
+    if (!Array.isArray(value) || value.length > 32)
+        invalidPayload();
+    for (const item of value) {
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            invalidPayload();
+        const attribute = item;
+        if (Object.keys(attribute).some((key) => key !== "key" && key !== "value") || !ATTRIBUTE_KEYS.has(String(attribute.key)))
+            invalidPayload();
+        validateValue(attribute.value);
+        const stringValue = attribute.value.stringValue;
+        if (typeof stringValue !== "string")
+            invalidPayload();
+        {
+            const key = String(attribute.key);
+            const text = stringValue;
+            if (key === "service.name" && text !== "larkin")
+                invalidPayload();
+            if (key === "service.version" && !/^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$/.test(text))
+                invalidPayload();
+            if (key === "service.instance.id" && !/^[0-9a-f-]{16,64}$/i.test(text))
+                invalidPayload();
+            if (["larkin.agent.id_hash", "messaging.message.id_hash"].includes(key) && !/^[0-9a-f]{24}$/.test(text))
+                invalidPayload();
+            if (key === "larkin.message.relation" && text !== "fan_in")
+                invalidPayload();
+            if (key === "larkin.observation.boundary" && !["runtime_host", "runtime_event_interval", "agent_cli", "agent_transport", "pi_rpc", "comment_cli"].includes(text))
+                invalidPayload();
+            if (key === "larkin.activity.type" && !["thinking", "text", "tool", "internal"].includes(text))
+                invalidPayload();
+            if (key === "larkin.message.source" && !["im", "document_comment"].includes(text))
+                invalidPayload();
+            if (key === "larkin.filter.reason" && !["subscription_unverified", "self_or_missing_operator", "unsupported_file_type", "duplicate"].includes(text))
+                invalidPayload();
+            if (key === "larkin.runtime.id" && text !== "pi")
+                invalidPayload();
+            if (key === "larkin.runtime.distribution" && !["builtin", "external"].includes(text))
+                invalidPayload();
+            if (key === "larkin.operation.outcome" && !["success", "error"].includes(text))
+                invalidPayload();
+            if (key === "larkin.pi.preflight.outcome" && !["accepted", "timeout", "error"].includes(text))
+                invalidPayload();
+            if (key === "larkin.pi.preflight.progress" && !["compaction", "retry"].includes(text))
+                invalidPayload();
+        }
+    }
+}
+export function validateOtlpPayload(payload) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload) || Object.keys(payload).some((key) => key !== "resourceSpans"))
+        invalidPayload();
+    const resourceSpans = payload.resourceSpans;
+    if (!Array.isArray(resourceSpans) || resourceSpans.length < 1 || resourceSpans.length > 1024)
+        invalidPayload();
+    for (const resourceSpanValue of resourceSpans) {
+        const resourceSpan = resourceSpanValue;
+        if (!resourceSpan || typeof resourceSpan !== "object" || Object.keys(resourceSpan).some((key) => key !== "resource" && key !== "scopeSpans"))
+            invalidPayload();
+        const resource = resourceSpan.resource;
+        if (!resource || Object.keys(resource).some((key) => key !== "attributes"))
+            invalidPayload();
+        validateAttributes(resource.attributes);
+        if (!Array.isArray(resourceSpan.scopeSpans) || resourceSpan.scopeSpans.length > 16)
+            invalidPayload();
+        for (const scopeSpanValue of resourceSpan.scopeSpans) {
+            const scopeSpan = scopeSpanValue;
+            if (!scopeSpan || Object.keys(scopeSpan).some((key) => key !== "scope" && key !== "spans"))
+                invalidPayload();
+            const scope = scopeSpan.scope;
+            if (!scope || Object.keys(scope).some((key) => key !== "name" && key !== "version") || typeof scope.name !== "string" || typeof scope.version !== "string")
+                invalidPayload();
+            if (!Array.isArray(scopeSpan.spans) || scopeSpan.spans.length > 4096)
+                invalidPayload();
+            for (const spanValue of scopeSpan.spans) {
+                const span = spanValue;
+                const allowed = new Set(["traceId", "spanId", "parentSpanId", "name", "kind", "startTimeUnixNano", "endTimeUnixNano", "attributes", "links", "status", "flags"]);
+                if (!span || Object.keys(span).some((key) => !allowed.has(key)) || !HEX_TRACE.test(String(span.traceId)) || !HEX_SPAN.test(String(span.spanId))
+                    || (span.parentSpanId !== undefined && !HEX_SPAN.test(String(span.parentSpanId))) || !SPAN_NAMES.has(String(span.name))
+                    || !Number.isInteger(span.kind) || Number(span.kind) < 1 || Number(span.kind) > 5
+                    || !/^[0-9]{1,24}$/.test(String(span.startTimeUnixNano)) || !/^[0-9]{1,24}$/.test(String(span.endTimeUnixNano))
+                    || BigInt(String(span.endTimeUnixNano)) < BigInt(String(span.startTimeUnixNano)))
+                    invalidPayload();
+                validateAttributes(span.attributes);
+                if (!Array.isArray(span.links) || span.links.length > 8)
+                    invalidPayload();
+                for (const linkValue of span.links) {
+                    const link = linkValue;
+                    if (!link || Object.keys(link).some((key) => !["traceId", "spanId", "traceState", "flags", "attributes"].includes(key))
+                        || !HEX_TRACE.test(String(link.traceId)) || !HEX_SPAN.test(String(link.spanId)))
+                        invalidPayload();
+                    validateAttributes(link.attributes);
+                }
+                const status = span.status;
+                if (!status || Object.keys(status).some((key) => key !== "code") || !Number.isInteger(status.code) || Number(status.code) < 0 || Number(status.code) > 2)
+                    invalidPayload();
+            }
+        }
+    }
+}
+export class TelemetrySpool {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    ensure() {
+        const parent = path.dirname(this.config.spoolDir);
+        fs.mkdirSync(parent, { recursive: true, mode: 0o700 });
+        try {
+            if (fs.lstatSync(this.config.spoolDir).isSymbolicLink())
+                throw new Error("invalid telemetry spool");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        fs.mkdirSync(this.config.spoolDir, { recursive: true, mode: 0o700 });
+        const stat = fs.lstatSync(this.config.spoolDir);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new Error("invalid telemetry spool");
+        fs.chmodSync(this.config.spoolDir, 0o700);
+    }
+    acquireLease() {
+        this.ensure();
+        const lease = path.join(this.config.spoolDir, ".queue.lock");
+        const token = crypto.randomUUID();
+        const currentStartToken = inspectProcess(process.pid).startToken;
+        const create = () => {
+            fs.mkdirSync(lease, { mode: 0o700 });
+            fs.writeFileSync(path.join(lease, "owner.json"), JSON.stringify({ version: 1, pid: process.pid, processStartToken: currentStartToken,
+                token, createdAt: Date.now() }), { mode: 0o600, flag: "wx" });
+        };
+        try {
+            create();
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            try {
+                const stat = fs.lstatSync(lease);
+                if (!stat.isDirectory() || stat.isSymbolicLink())
+                    return null;
+                let owner = null;
+                try {
+                    owner = JSON.parse(fs.readFileSync(path.join(lease, "owner.json"), "utf8"));
+                }
+                catch { /* reclaim only after timeout */ }
+                const inspected = owner && Number.isSafeInteger(Number(owner.pid)) && Number(owner.pid) > 0 ? inspectProcess(Number(owner.pid)) : { ok: false };
+                const hasStartToken = typeof owner?.processStartToken === "string" && owner.processStartToken.length > 0;
+                const sameProcess = hasStartToken && inspected.ok && inspected.startToken === owner?.processStartToken;
+                const identityMismatch = hasStartToken && inspected.ok && inspected.startToken !== owner?.processStartToken;
+                const age = Date.now() - (owner && Number.isFinite(Number(owner.createdAt)) ? Number(owner.createdAt) : stat.mtimeMs);
+                if (sameProcess || (!identityMismatch && !inspected.dead && age < 2 * 60_000))
+                    return null;
+                const stale = path.join(this.config.spoolDir, `.stale-lock-${crypto.randomUUID()}`);
+                fs.renameSync(lease, stale);
+                const moved = fs.lstatSync(stale);
+                if (!moved.isDirectory() || moved.isSymbolicLink() || moved.dev !== stat.dev || moved.ino !== stat.ino)
+                    return null;
+                fs.rmSync(stale, { recursive: true });
+                create();
+            }
+            catch {
+                return null;
+            }
+        }
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            try {
+                const ownerFile = path.join(lease, "owner.json");
+                const owner = JSON.parse(fs.readFileSync(ownerFile, "utf8"));
+                if (owner.token !== token)
+                    return;
+                fs.unlinkSync(ownerFile);
+                fs.rmdirSync(lease);
+            }
+            catch { /* isolated */ }
+        };
+    }
+    readyFiles() {
+        this.ensure();
+        return fs.readdirSync(this.config.spoolDir).filter((name) => READY.test(name)).flatMap((name) => {
+            const file = path.join(this.config.spoolDir, name);
+            try {
+                const stat = fs.lstatSync(file);
+                return stat.isFile() && !stat.isSymbolicLink() ? [{ file, size: stat.size, mtimeMs: stat.mtimeMs, device: stat.dev, inode: stat.ino }] : [];
+            }
+            catch {
+                return [];
+            }
+        }).sort((a, b) => a.mtimeMs - b.mtimeMs || a.file.localeCompare(b.file));
+    }
+    remnantFiles() {
+        this.ensure();
+        return fs.readdirSync(this.config.spoolDir).filter((name) => REMNANT.test(name)).flatMap((name) => {
+            const file = path.join(this.config.spoolDir, name);
+            try {
+                const stat = fs.lstatSync(file);
+                const directory = stat.isDirectory() && !stat.isSymbolicLink();
+                return (stat.isFile() || directory) && !stat.isSymbolicLink()
+                    ? [{ file, size: directory ? this.directoryBytes(file, stat) : stat.size, mtimeMs: stat.mtimeMs,
+                            device: stat.dev, inode: stat.ino, directory, remnant: true }] : [];
+            }
+            catch {
+                return [];
+            }
+        }).sort((a, b) => a.mtimeMs - b.mtimeMs || a.file.localeCompare(b.file));
+    }
+    directoryBytes(root, rootStat) {
+        const saturation = this.config.maxBytes + 1;
+        const seen = new Set();
+        let entries = 0;
+        const spoolRoot = fs.realpathSync(this.config.spoolDir);
+        const prefix = `${spoolRoot}${path.sep}`;
+        const visit = (directory, stat, depth) => {
+            const identity = `${stat.dev}:${stat.ino}`;
+            if (seen.has(identity))
+                return 0;
+            seen.add(identity);
+            if (depth > 8 || entries > 1024)
+                return saturation;
+            try {
+                const real = fs.realpathSync(directory);
+                if (real !== spoolRoot && !real.startsWith(prefix))
+                    return saturation;
+            }
+            catch {
+                return saturation;
+            }
+            let total = stat.size;
+            let names;
+            try {
+                names = fs.readdirSync(directory);
+            }
+            catch {
+                return saturation;
+            }
+            for (const name of names) {
+                entries += 1;
+                if (entries > 1024)
+                    return saturation;
+                const child = path.join(directory, name);
+                let childStat;
+                try {
+                    childStat = fs.lstatSync(child);
+                }
+                catch {
+                    continue;
+                }
+                if (childStat.isSymbolicLink()) {
+                    total += childStat.size;
+                    continue;
+                }
+                if (childStat.isFile())
+                    total += childStat.size;
+                else if (childStat.isDirectory())
+                    total += visit(child, childStat, depth + 1);
+            }
+            try {
+                const after = fs.lstatSync(directory);
+                if (after.isSymbolicLink() || after.dev !== stat.dev || after.ino !== stat.ino)
+                    return saturation;
+            }
+            catch {
+                return saturation;
+            }
+            return total;
+        };
+        return visit(root, rootStat, 0);
+    }
+    atomicWrite(file, bytes) {
+        this.ensure();
+        const temporary = path.join(this.config.spoolDir, `.write-${process.pid}-${crypto.randomUUID()}.tmp`);
+        let descriptor;
+        try {
+            descriptor = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+            fs.writeFileSync(descriptor, bytes);
+            fs.fsyncSync(descriptor);
+            fs.closeSync(descriptor);
+            descriptor = undefined;
+            fs.renameSync(temporary, file);
+            fs.chmodSync(file, 0o600);
+            const directory = fs.openSync(this.config.spoolDir, fs.constants.O_RDONLY);
+            try {
+                fs.fsyncSync(directory);
+            }
+            finally {
+                fs.closeSync(directory);
+            }
+        }
+        finally {
+            if (descriptor !== undefined)
+                try {
+                    fs.closeSync(descriptor);
+                }
+                catch { /* isolated */ }
+            try {
+                fs.unlinkSync(temporary);
+            }
+            catch { /* isolated */ }
+        }
+    }
+    removeVerified(entry) {
+        const quarantine = path.join(this.config.spoolDir, `.delete-${crypto.randomUUID()}.tmp`);
+        try {
+            fs.renameSync(entry.file, quarantine);
+            const stat = fs.lstatSync(quarantine);
+            if (!stat.isFile() || stat.isSymbolicLink() || stat.dev !== entry.device || stat.ino !== entry.inode) {
+                try {
+                    fs.renameSync(quarantine, entry.file);
+                }
+                catch { /* preserve replacement */ }
+                return false;
+            }
+            fs.unlinkSync(quarantine);
+            return true;
+        }
+        catch {
+            try {
+                fs.renameSync(quarantine, entry.file);
+            }
+            catch { /* isolated */ }
+            return false;
+        }
+    }
+    removeManaged(entry) {
+        if (!entry.directory)
+            return this.removeVerified(entry);
+        const quarantine = path.join(this.config.spoolDir, `.purge-${crypto.randomUUID()}.dir`);
+        try {
+            fs.renameSync(entry.file, quarantine);
+            const stat = fs.lstatSync(quarantine);
+            if (!stat.isDirectory() || stat.isSymbolicLink() || stat.dev !== entry.device || stat.ino !== entry.inode) {
+                try {
+                    fs.renameSync(quarantine, entry.file);
+                }
+                catch { /* preserve */ }
+                return false;
+            }
+            fs.rmSync(quarantine, { recursive: true });
+            return true;
+        }
+        catch {
+            try {
+                fs.renameSync(quarantine, entry.file);
+            }
+            catch { /* isolated */ }
+            return false;
+        }
+    }
+    enqueue(payload) {
+        validateOtlpPayload(payload);
+        const file = path.join(this.config.spoolDir, `span-${crypto.randomUUID()}.json`);
+        this.atomicWrite(file, Buffer.from(JSON.stringify(payload)));
+        try {
+            this.prune();
+        }
+        catch { /* telemetry cannot alter business behavior */ }
+        return file;
+    }
+    list(limit = Number.MAX_SAFE_INTEGER, quarantineCorrupt = false) {
+        const output = [];
+        let dropped = 0;
+        for (const entry of this.readyFiles().slice(0, limit)) {
+            let descriptor;
+            let invalid = false;
+            try {
+                descriptor = fs.openSync(entry.file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+                const stat = fs.fstatSync(descriptor);
+                if (!stat.isFile() || stat.dev !== entry.device || stat.ino !== entry.inode)
+                    throw new Error("telemetry spool changed");
+                const payload = JSON.parse(fs.readFileSync(descriptor, "utf8"));
+                validateOtlpPayload(payload);
+                output.push({ file: entry.file, payload, device: stat.dev, inode: stat.ino });
+            }
+            catch {
+                invalid = true;
+            }
+            finally {
+                if (descriptor !== undefined)
+                    try {
+                        fs.closeSync(descriptor);
+                    }
+                    catch { /* isolated */ }
+            }
+            if (invalid) {
+                if (!quarantineCorrupt)
+                    throw new Error("invalid telemetry spool record");
+                const quarantine = path.join(this.config.spoolDir, `.corrupt-${crypto.randomUUID()}.json`);
+                try {
+                    fs.renameSync(entry.file, quarantine);
+                    const stat = fs.lstatSync(quarantine);
+                    if (!stat.isFile() || stat.isSymbolicLink() || stat.dev !== entry.device || stat.ino !== entry.inode)
+                        throw new Error("record changed");
+                    dropped += 1;
+                }
+                catch {
+                    try {
+                        fs.renameSync(quarantine, entry.file);
+                    }
+                    catch { /* preserve */ }
+                }
+            }
+        }
+        if (dropped)
+            try {
+                this.updateDiagnostics({ droppedFiles: this.diagnostics().droppedFiles + dropped, lastErrorCategory: "corrupt_spool" });
+            }
+            catch { /* isolated */ }
+        return output;
+    }
+    acknowledge(records) {
+        const root = `${path.resolve(this.config.spoolDir)}${path.sep}`;
+        const moved = [];
+        try {
+            for (const record of records) {
+                const resolved = path.resolve(record.file);
+                const quarantine = path.join(this.config.spoolDir, `.ack-${crypto.randomUUID()}.tmp`);
+                if (!resolved.startsWith(root) || !READY.test(path.basename(resolved)))
+                    throw new Error("invalid record");
+                fs.renameSync(resolved, quarantine);
+                moved.push({ original: resolved, quarantine });
+                const stat = fs.lstatSync(quarantine);
+                if (!stat.isFile() || stat.isSymbolicLink() || stat.dev !== record.device || stat.ino !== record.inode)
+                    throw new Error("record changed");
+            }
+            for (const entry of moved)
+                fs.unlinkSync(entry.quarantine);
+            const directory = fs.openSync(this.config.spoolDir, fs.constants.O_RDONLY);
+            try {
+                fs.fsyncSync(directory);
+            }
+            finally {
+                fs.closeSync(directory);
+            }
+        }
+        catch {
+            for (const entry of moved.reverse())
+                try {
+                    fs.renameSync(entry.quarantine, entry.original);
+                }
+                catch { /* preserve without deleting */ }
+            throw new Error("telemetry acknowledgement failed");
+        }
+    }
+    diagnostics() {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(path.join(this.config.spoolDir, "diagnostics.json"), "utf8"));
+            return { droppedFiles: Number.isSafeInteger(parsed.droppedFiles) && Number(parsed.droppedFiles) >= 0 ? Number(parsed.droppedFiles) : 0,
+                cleanedRemnantFiles: Number.isSafeInteger(parsed.cleanedRemnantFiles) && Number(parsed.cleanedRemnantFiles) >= 0 ? Number(parsed.cleanedRemnantFiles) : 0,
+                droppedSpans: Number.isSafeInteger(parsed.droppedSpans) && Number(parsed.droppedSpans) >= 0 ? Number(parsed.droppedSpans) : 0,
+                lastUploadAt: typeof parsed.lastUploadAt === "string" ? parsed.lastUploadAt : null,
+                lastErrorCategory: typeof parsed.lastErrorCategory === "string" ? parsed.lastErrorCategory : null };
+        }
+        catch {
+            return emptyDiagnostics();
+        }
+    }
+    updateDiagnostics(patch) {
+        this.atomicWrite(path.join(this.config.spoolDir, "diagnostics.json"), Buffer.from(JSON.stringify({ ...this.diagnostics(), ...patch })));
+    }
+    prune(now = Date.now()) {
+        const release = this.acquireLease();
+        if (!release)
+            return;
+        try {
+            let files = [...this.readyFiles().map((entry) => ({ ...entry, directory: false, remnant: false })), ...this.remnantFiles()]
+                .sort((a, b) => a.mtimeMs - b.mtimeMs || a.file.localeCompare(b.file));
+            let dropped = 0;
+            let cleaned = 0;
+            const remove = (entry) => { if (this.removeManaged(entry)) {
+                if (entry.remnant)
+                    cleaned += 1;
+                else
+                    dropped += 1;
+            } };
+            for (const entry of files.filter((item) => now - item.mtimeMs > this.config.maxAgeMs))
+                remove(entry);
+            files = [...this.readyFiles().map((entry) => ({ ...entry, directory: false, remnant: false })), ...this.remnantFiles()]
+                .sort((a, b) => a.mtimeMs - b.mtimeMs || a.file.localeCompare(b.file));
+            let bytes = files.reduce((sum, entry) => sum + entry.size, 0);
+            while (files.length > this.config.maxFiles || bytes > this.config.maxBytes) {
+                const oldest = files.shift();
+                if (!oldest)
+                    break;
+                const before = dropped + cleaned;
+                remove(oldest);
+                if (dropped + cleaned > before)
+                    bytes -= oldest.size;
+            }
+            if (dropped || cleaned)
+                try {
+                    const diagnostic = this.diagnostics();
+                    this.updateDiagnostics({ droppedFiles: diagnostic.droppedFiles + dropped,
+                        cleanedRemnantFiles: diagnostic.cleanedRemnantFiles + cleaned });
+                }
+                catch { /* isolated */ }
+        }
+        finally {
+            release();
+        }
+    }
+    status(now = Date.now()) {
+        try {
+            const files = this.readyFiles();
+            const remnants = this.remnantFiles();
+            const diagnostic = this.diagnostics();
+            return { queuedFiles: files.length, queuedBytes: files.reduce((sum, item) => sum + item.size, 0),
+                oldestAgeMs: files[0] ? Math.max(0, now - files[0].mtimeMs) : null,
+                remnantFiles: remnants.length, remnantBytes: remnants.reduce((sum, item) => sum + item.size, 0),
+                oldestRemnantAgeMs: remnants[0] ? Math.max(0, now - remnants[0].mtimeMs) : null, ...diagnostic };
+        }
+        catch {
+            return { queuedFiles: 0, queuedBytes: 0, oldestAgeMs: null, remnantFiles: 0, remnantBytes: 0,
+                oldestRemnantAgeMs: null, ...emptyDiagnostics(), lastErrorCategory: "spool" };
+        }
+    }
+    exportBundle(destination) {
+        const release = this.acquireLease();
+        if (!release)
+            throw new Error("telemetry queue busy");
+        try {
+            const records = this.list().map(({ payload }) => { const bytes = Buffer.from(JSON.stringify(payload)); return { sha256: crypto.createHash("sha256").update(bytes).digest("hex"), payload }; });
+            const bundle = { format: "larkin-otlp-bundle", version: 1, createdAt: new Date().toISOString(), records };
+            const compressed = zlib.gzipSync(Buffer.from(JSON.stringify(bundle)), { level: 9 });
+            const descriptor = fs.openSync(destination, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+            try {
+                fs.writeFileSync(descriptor, compressed);
+                fs.fsyncSync(descriptor);
+            }
+            finally {
+                fs.closeSync(descriptor);
+            }
+            return { records: records.length, sha256: crypto.createHash("sha256").update(compressed).digest("hex") };
+        }
+        finally {
+            release();
+        }
+    }
+    importBundle(source, maxBundleBytes = 128 * 1024 * 1024) {
+        let descriptor;
+        let bytes;
+        try {
+            descriptor = fs.openSync(source, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+            const stat = fs.fstatSync(descriptor);
+            if (!stat.isFile() || stat.size > maxBundleBytes)
+                throw new Error("invalid telemetry bundle");
+            bytes = fs.readFileSync(descriptor);
+        }
+        catch {
+            throw new Error("invalid telemetry bundle");
+        }
+        finally {
+            if (descriptor !== undefined)
+                fs.closeSync(descriptor);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(zlib.gunzipSync(bytes, { maxOutputLength: maxBundleBytes }).toString("utf8"));
+        }
+        catch {
+            throw new Error("invalid telemetry bundle");
+        }
+        if (parsed.format !== "larkin-otlp-bundle" || parsed.version !== 1 || !Array.isArray(parsed.records) || parsed.records.length > 100_000)
+            throw new Error("invalid telemetry bundle");
+        const validated = parsed.records.map((record) => {
+            validateOtlpPayload(record?.payload);
+            const payloadBytes = Buffer.from(JSON.stringify(record.payload));
+            const sha256 = crypto.createHash("sha256").update(payloadBytes).digest("hex");
+            if (sha256 !== record.sha256)
+                throw new Error("invalid telemetry bundle");
+            return { sha256, payloadBytes };
+        });
+        const release = this.acquireLease();
+        if (!release)
+            throw new Error("telemetry queue busy");
+        const added = [];
+        let duplicates = 0;
+        try {
+            for (const record of validated) {
+                const destination = path.join(this.config.spoolDir, `import-${record.sha256}.json`);
+                if (fs.existsSync(destination)) {
+                    duplicates += 1;
+                    continue;
+                }
+                this.atomicWrite(destination, record.payloadBytes);
+                added.push(destination);
+            }
+        }
+        catch (error) {
+            for (const file of added)
+                try {
+                    fs.unlinkSync(file);
+                }
+                catch { /* rollback best effort */ }
+            throw error;
+        }
+        finally {
+            release();
+        }
+        try {
+            this.prune();
+        }
+        catch { /* isolated */ }
+        return { imported: added.length, duplicates };
+    }
+}