sealkeep 0.9.0 → 0.11.0

package/dist/src/index-background.d.ts

@@ -0,0 +1,64 @@
+export type ContentIndexBuildResult = {
+    indexedNow: number;
+    skipped: number;
+};
+export type BackgroundIndexBuild = {
+    /** Useful for diagnostics and for proving this work is not on the daemon's PID. */
+    pid: number | undefined;
+    /** Secret-free sibling; diagnostic identity, never the build owner. */
+    watchdogPid?: number;
+    /** Resolves once the child has accepted the secret and is beginning the build. */
+    started: Promise<void>;
+    result: Promise<ContentIndexBuildResult>;
+    /** Stops this exact child with bounded escalation. Its durable barrier remains
+     * if the kernel has not confirmed exit within the join window. Idempotent. */
+    stop(): Promise<void>;
+};
+/** Hard V8-heap boundary for best-effort derived work. Plaintext and index
+ * serialization are streamed, so exceeding this means the retained index is
+ * itself unreasonable; the child fails without taking the interactive daemon
+ * or the rest of the desktop down with it. */
+export declare const BACKGROUND_INDEX_MAX_OLD_SPACE_MB = 1024;
+export declare const BACKGROUND_INDEX_MAX_SEMI_SPACE_MB = 16;
+/** Checked cooperatively every 8 MiB of plaintext in addition to V8's heap
+ * boundary. This includes native buffers, decompression, and token storage. */
+export declare const BACKGROUND_INDEX_MAX_RSS_BYTES: number;
+/** Configuration and credential-store discovery only; credentials are loaded
+ * from the vault by the worker, never inherited from the daemon environment. */
+export declare function backgroundIndexWorkerEnvironment(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function backgroundIndexExecArgv(parent: readonly string[]): string[];
+/**
+ * Runs a historical content-index build outside the daemon's event loop.
+ *
+ * Index extraction is not merely asynchronous I/O: archive authentication,
+ * decompression, token scanning, index serialisation, gzip and encryption all
+ * contain long synchronous sections. A Promise around those sections still
+ * blocks heartbeat timers. A child also gives the large derived index its own
+ * heap, and lets the OS prefer interactive Codex/Claude hook processes while a
+ * backlog is being rebuilt.
+ *
+ * The recovery phrase travels only over the already-owned IPC channel. It is
+ * deliberately absent from argv and the environment, which are routinely
+ * exposed by process inspectors and service diagnostics.
+ */
+export declare function startBackgroundIndexBuild(dataDir: string, phrase: string, options: {
+    sync: boolean;
+    idleMs?: number;
+    /** Child boot gets a small floor; once it says started, idleMs governs real work. */
+    startupMs?: number;
+    stopGraceMs?: number;
+    /** Historical work defaults to one lane and 30% of one core. */
+    lanes?: number;
+    cpuTarget?: number;
+    /** Deterministic process fixture; production always uses the package child. */
+    childPath?: string;
+    /** Deterministic failure fixture; production always uses the package watchdog. */
+    watchdogPath?: string;
+    /** Supervised cleanup only after the exact worker has actually exited. */
+    onWorkerExit?: (worker: {
+        pid: number;
+        processIdentity: string;
+    }) => Promise<void>;
+    /** Exact owning daemon's current-vault upload capability; never inferred globally. */
+    signerAuthorized?: boolean;
+}): BackgroundIndexBuild;

package/dist/src/index-background.js

@@ -0,0 +1,394 @@
+import { fork } from "node:child_process";
+import { constants, setPriority } from "node:os";
+import { fileURLToPath } from "node:url";
+import { SealkeepError } from "./errors.js";
+import { backgroundDaemonCpuBudget, BACKGROUND_CPU_TOTAL_TARGET, signalOwnedBackgroundProcess, onOwnedBackgroundProcessExit, startBackgroundProcessCpuGovernor } from "./background-cpu.js";
+import { daemonProcessIdentity, registerDaemonIndexWorker } from "./daemon-lease.js";
+import { envVar } from "./env.js";
+import { backgroundWorkerErrorFromWire } from "./background-worker-error.js";
+/** Hard V8-heap boundary for best-effort derived work. Plaintext and index
+ * serialization are streamed, so exceeding this means the retained index is
+ * itself unreasonable; the child fails without taking the interactive daemon
+ * or the rest of the desktop down with it. */
+export const BACKGROUND_INDEX_MAX_OLD_SPACE_MB = 1024;
+export const BACKGROUND_INDEX_MAX_SEMI_SPACE_MB = 16;
+/** Checked cooperatively every 8 MiB of plaintext in addition to V8's heap
+ * boundary. This includes native buffers, decompression, and token storage. */
+export const BACKGROUND_INDEX_MAX_RSS_BYTES = 1536 * 1024 * 1024;
+const PROCESS_RUNTIME_ENV = ["PATH", "SystemRoot", "WINDIR", "TEMP", "TMP", "TMPDIR"];
+/** Configuration and credential-store discovery only; credentials are loaded
+ * from the vault by the worker, never inherited from the daemon environment. */
+export function backgroundIndexWorkerEnvironment(env = process.env) {
+    const result = {};
+    for (const key of [...PROCESS_RUNTIME_ENV, "HOME", "USERPROFILE", "APPDATA", "LOCALAPPDATA",
+        "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_RUNTIME_DIR", "DBUS_SESSION_BUS_ADDRESS", "LANG", "LC_ALL", "TZ"]) {
+        if (env[key] !== undefined)
+            result[key] = env[key];
+    }
+    for (const prefix of ["SEALKEEP_", "VAULTLINE_"]) {
+        for (const name of ["SECRET_BACKEND", "CLOUD_URL", "ALLOW_PRIVATE_STORAGE_ENDPOINT", "GDRIVE_CLIENT_ID", "MAX_ARCHIVE_BYTES"]) {
+            if (env[prefix + name] !== undefined)
+                result[prefix + name] = env[prefix + name];
+        }
+    }
+    return result;
+}
+export function backgroundIndexExecArgv(parent) {
+    // A parent may have --eval source, inspector authentication, or arbitrary
+    // preload arguments. Only our development TS loader must cross this boundary.
+    const loaders = [];
+    for (let index = 0; index < parent.length; index += 1) {
+        const argument = parent[index];
+        const match = /^(--import|--require|-r)(?:=(.*))?$/.exec(argument);
+        if (!match)
+            continue;
+        const value = match[2] ?? parent[++index];
+        if (value && (value === "tsx" || /[/\\]tsx[/\\]dist[/\\](?:loader\.mjs|preflight\.cjs)$/.test(value))) {
+            loaders.push(match[1], value);
+        }
+    }
+    return [
+        ...loaders,
+        `--max-old-space-size=${BACKGROUND_INDEX_MAX_OLD_SPACE_MB}`,
+        `--max-semi-space-size=${BACKGROUND_INDEX_MAX_SEMI_SPACE_MB}`,
+        // V8's default concurrent collector can add two or more CPU cores while
+        // the JavaScript lane is correctly sleeping. This child is explicitly
+        // background work; serial GC trades a little wall time for a bounded,
+        // non-interactive process footprint.
+        "--single-threaded-gc",
+    ];
+}
+/**
+ * Runs a historical content-index build outside the daemon's event loop.
+ *
+ * Index extraction is not merely asynchronous I/O: archive authentication,
+ * decompression, token scanning, index serialisation, gzip and encryption all
+ * contain long synchronous sections. A Promise around those sections still
+ * blocks heartbeat timers. A child also gives the large derived index its own
+ * heap, and lets the OS prefer interactive Codex/Claude hook processes while a
+ * backlog is being rebuilt.
+ *
+ * The recovery phrase travels only over the already-owned IPC channel. It is
+ * deliberately absent from argv and the environment, which are routinely
+ * exposed by process inspectors and service diagnostics.
+ */
+export function startBackgroundIndexBuild(dataDir, phrase, options) {
+    // Tests execute the TypeScript source through tsx; packaged installs execute
+    // dist JavaScript. Match the entry point to the module that created us.
+    const extension = import.meta.url.endsWith(".ts") ? ".ts" : ".js";
+    const childPath = options.childPath ?? fileURLToPath(new URL(`./index-build-child${extension}`, import.meta.url));
+    // Explicit per-daemon denial overrides ambient operator enablement. Direct
+    // callers retain their explicit operator setting, but never another daemon's
+    // process-local grant. The resulting capability travels only through IPC.
+    const signerAuthorized = options.signerAuthorized ?? (envVar("ENABLE_SIGNER") === "1");
+    const child = fork(childPath, [], {
+        stdio: ["ignore", "ignore", "inherit", "ipc"],
+        execArgv: backgroundIndexExecArgv(process.execArgv),
+        env: backgroundIndexWorkerEnvironment(),
+    });
+    // The daemon and lifecycle hooks are interactive control lanes; a historical
+    // rebuild is best-effort derived work. Priority adjustment is advisory and
+    // unsupported on a few hosts, where ordinary scheduler fairness still holds.
+    if (child.pid !== undefined) {
+        try {
+            setPriority(child.pid, constants.priority.PRIORITY_BELOW_NORMAL);
+        }
+        catch { /* priority is an optimisation, never a reason to lose indexing */ }
+    }
+    const cpuTarget = Math.min(1, Math.max(0.05, options.cpuTarget ?? 0.30));
+    // The in-child limiter handles ordinary parse/compression work. Its event
+    // loop cannot interrupt V8's own GC, so this owned parent also governs the
+    // whole process on POSIX. This is what makes the ceiling apply to native
+    // worker/collector CPU rather than just JavaScript checkpoints.
+    // Do not pause or send any work until the independent orphan watchdog has
+    // verified this exact worker generation and acknowledged ownership.
+    let cpuGovernor = { stop() { } };
+    const watchdogEnv = {};
+    for (const key of PROCESS_RUNTIME_ENV) {
+        if (process.env[key] !== undefined)
+            watchdogEnv[key] = process.env[key];
+    }
+    let watchdog;
+    try {
+        watchdog = fork(options.watchdogPath ?? fileURLToPath(new URL(`./index-background-watchdog${extension}`, import.meta.url)), [], {
+            stdio: ["ignore", "ignore", "inherit", "ipc"],
+            env: watchdogEnv,
+            execArgv: [...backgroundIndexExecArgv(process.execArgv).filter((arg) => !arg.startsWith("--max-old-space-size")), "--max-old-space-size=64"],
+        });
+    }
+    catch (error) {
+        // A synchronous spawn/argument failure occurs before the usual listeners
+        // exist. This exact worker has received neither work nor a pause signal.
+        child.once("error", () => { });
+        signalOwnedBackgroundProcess(child, "SIGKILL");
+        throw error;
+    }
+    let watchdogDisarmed = false;
+    let watchdogFailure;
+    let watchdogExited = false;
+    let watchdogExitTimer;
+    let watchdogClosedResolve;
+    const watchdogClosed = new Promise((resolve) => { watchdogClosedResolve = resolve; });
+    // Keep this owned child and its IPC channel referenced until it exits. A bare
+    // Promise does not keep Node alive; unref'ing here can abandon a build before
+    // daemon.close() gets the chance to terminate it and wait for the exact PID.
+    let startedResolve;
+    let startedSettled = false;
+    const started = new Promise((resolve) => { startedResolve = resolve; });
+    const markStarted = () => {
+        if (startedSettled)
+            return;
+        startedSettled = true;
+        startedResolve();
+    };
+    let resultSettled = false;
+    let resultResolve;
+    let resultReject;
+    const result = new Promise((resolve, reject) => {
+        resultResolve = resolve;
+        resultReject = reject;
+    });
+    let reportedResult;
+    let reportedError;
+    let workerIdentity;
+    let workerRegistration;
+    let closedResolve;
+    let closedSettled = false;
+    const closed = new Promise((resolve) => { closedResolve = resolve; });
+    const idleMs = Math.max(1, options.idleMs ?? 2 * 60_000);
+    // A busy machine can take longer to load Node (and the TypeScript loader in
+    // development) than a deliberately tiny test/work idle window. Treat boot
+    // and work as separate liveness phases: a child that never starts is still
+    // bounded, while a healthy child is judged by actual progress only after its
+    // first IPC acknowledgement. Production's two-minute idle window remains
+    // the startup window too; the floor matters only for shorter overrides.
+    const startupMs = Math.max(idleMs, options.startupMs ?? 10_000);
+    const stopGraceMs = Math.max(1, options.stopGraceMs ?? 2_000);
+    let timedOut = false;
+    let idleTimer;
+    let forceTimer;
+    const clearDeadlines = () => {
+        if (idleTimer)
+            clearTimeout(idleTimer);
+        if (forceTimer)
+            clearTimeout(forceTimer);
+        idleTimer = undefined;
+        forceTimer = undefined;
+    };
+    const armIdleDeadline = (windowMs = idleMs, phase = "running") => {
+        if (closedSettled || timedOut)
+            return;
+        if (idleTimer)
+            clearTimeout(idleTimer);
+        idleTimer = setTimeout(() => {
+            timedOut = true;
+            reportedError = new SealkeepError("operation_timeout", phase === "starting"
+                ? `Historical index child did not start within ${windowMs} ms`
+                : `Historical index build made no progress for ${windowMs} ms`, { operation: "historical_index", phase, idleMs: windowMs, retryable: true });
+            cpuGovernor.stop();
+            signalOwnedBackgroundProcess(child, "SIGTERM");
+            forceTimer = setTimeout(() => { if (!closedSettled)
+                signalOwnedBackgroundProcess(child, "SIGKILL"); }, stopGraceMs);
+        }, windowMs);
+    };
+    onOwnedBackgroundProcessExit(child, (code, signal) => {
+        cpuGovernor.stop();
+        clearDeadlines();
+        closedSettled = true;
+        watchdogDisarmed = true;
+        if (!watchdogExited) {
+            if (watchdog.connected)
+                watchdog.send({ type: "disarm" }, () => { });
+            watchdogExitTimer = setTimeout(() => signalOwnedBackgroundProcess(watchdog, "SIGKILL"), stopGraceMs);
+        }
+        void (async () => {
+            try {
+                const registration = await workerRegistration;
+                const cleanupErrors = [];
+                try {
+                    if (workerIdentity && child.pid !== undefined) {
+                        await options.onWorkerExit?.({ pid: child.pid, processIdentity: workerIdentity });
+                    }
+                }
+                catch (error) {
+                    cleanupErrors.push(error);
+                }
+                // A shared-lane recovery failure must not skip cleanup of this dead
+                // generation's private scratch or leave its startup barrier stranded.
+                try {
+                    await registration?.retireAfterExit();
+                }
+                catch (error) {
+                    cleanupErrors.push(error);
+                }
+                if (cleanupErrors.length)
+                    throw new AggregateError(cleanupErrors, "Historical index worker cleanup failed");
+            }
+            catch (error) {
+                reportedError = error instanceof Error ? error : new Error(String(error));
+                reportedResult = undefined;
+            }
+            closedResolve();
+            markStarted();
+            if (resultSettled)
+                return;
+            resultSettled = true;
+            if (watchdogFailure)
+                resultReject(watchdogFailure);
+            else if (governorFailure)
+                resultReject(governorFailure);
+            else if (reportedResult)
+                resultResolve(reportedResult);
+            else
+                resultReject(reportedError ?? new Error(`Historical index child exited before reporting a result (${signal ?? code ?? "unknown"})`));
+        })();
+    });
+    child.once("error", (error) => { reportedError ??= error; });
+    child.on("message", (wire) => {
+        if (!wire || typeof wire !== "object" || !("type" in wire))
+            return;
+        const message = wire;
+        if (message.type === "started" || message.type === "progress") {
+            markStarted();
+            armIdleDeadline();
+            return;
+        }
+        if (message.type === "result") {
+            markStarted();
+            if (!timedOut)
+                reportedResult = message.result;
+            return;
+        }
+        if (message.type === "error") {
+            reportedError = backgroundWorkerErrorFromWire(message.error);
+        }
+    });
+    let governorFailure;
+    const beginBuild = (scratchGeneration) => {
+        if (closedSettled || timedOut || stopInFlight)
+            return;
+        cpuGovernor = startBackgroundProcessCpuGovernor({
+            target: cpuTarget,
+            budget: backgroundDaemonCpuBudget,
+            signal: (signal) => signalOwnedBackgroundProcess(child, signal),
+            verifySignals: true,
+            onFailure: (error) => {
+                governorFailure ??= error;
+                reportedError = error;
+                reportedResult = undefined;
+                if (child.connected)
+                    child.disconnect();
+                void stop();
+            },
+        });
+        if (governorFailure)
+            return;
+        child.send({
+            type: "build", dataDir, phrase, sync: options.sync,
+            lanes: Math.max(1, Math.floor(options.lanes ?? 1)),
+            // POSIX has a parent-side hard process governor, which can pause even a
+            // synchronous GC. Let that be the one clock instead of compounding it with
+            // child sleeps. Windows has no SIGSTOP and keeps cooperative accounting.
+            cpuTarget: process.platform === "win32" ? Math.min(cpuTarget, BACKGROUND_CPU_TOTAL_TARGET / 3) : 1,
+            maxRssBytes: BACKGROUND_INDEX_MAX_RSS_BYTES,
+            scratchGeneration,
+            signerAuthorized,
+        }, (error) => {
+            if (error) {
+                reportedError ??= error;
+                void stop();
+            }
+        });
+    };
+    let stopInFlight;
+    const stop = () => {
+        if (stopInFlight)
+            return stopInFlight;
+        stopInFlight = (async () => {
+            if (closedSettled) {
+                await closed;
+                await watchdogClosed;
+                return;
+            }
+            clearDeadlines();
+            cpuGovernor.stop();
+            signalOwnedBackgroundProcess(child, "SIGTERM");
+            let force;
+            await Promise.race([
+                closed,
+                new Promise((resolve) => {
+                    force = setTimeout(() => {
+                        if (!closedSettled)
+                            signalOwnedBackgroundProcess(child, "SIGKILL");
+                        resolve();
+                    }, stopGraceMs);
+                }),
+            ]);
+            if (force)
+                clearTimeout(force);
+            // SIGKILL is asynchronous too. Give the exact PID another join window;
+            // its durable barrier still excludes replacement if the kernel stalls.
+            if (!closedSettled) {
+                let final;
+                await Promise.race([
+                    closed,
+                    new Promise((resolve) => { final = setTimeout(resolve, stopGraceMs); }),
+                ]);
+                if (final)
+                    clearTimeout(final);
+            }
+            if (closedSettled) {
+                await closed;
+                await watchdogClosed;
+            }
+        })();
+        return stopInFlight;
+    };
+    const watchdogFailed = (cause) => {
+        if (closedSettled || watchdogDisarmed)
+            return;
+        watchdogFailure ??= cause;
+        reportedError = cause;
+        reportedResult = undefined;
+        void stop();
+    };
+    watchdog.once("error", (error) => { watchdogFailed(error); });
+    watchdog.once("disconnect", () => {
+        watchdogFailed(new Error("Historical index orphan watchdog exited unexpectedly (IPC disconnected)"));
+    });
+    onOwnedBackgroundProcessExit(watchdog, (code, signal) => {
+        watchdogExited = true;
+        if (watchdogExitTimer)
+            clearTimeout(watchdogExitTimer);
+        watchdogClosedResolve();
+        watchdogFailed(new Error(`Historical index orphan watchdog exited unexpectedly (${signal ?? code ?? "unknown"})`));
+    });
+    watchdog.once("message", (wire) => {
+        if (wire && typeof wire === "object" && "type" in wire && wire.type === "armed") {
+            if (closedSettled || timedOut || stopInFlight || !workerIdentity || child.pid === undefined)
+                return;
+            workerRegistration = registerDaemonIndexWorker(dataDir, child.pid, workerIdentity);
+            void workerRegistration.then((registration) => beginBuild(registration.scratchGeneration), watchdogFailed);
+        }
+        else
+            watchdogFailed(new Error("Historical index orphan watchdog did not acknowledge ownership"));
+    });
+    // Send only after all failure listeners are installed. Neither the phrase
+    // nor the vault path ever enters the watchdog's IPC, argv or environment.
+    void (async () => {
+        if (child.pid === undefined)
+            throw new Error("Historical index child has no process identity");
+        const identity = await daemonProcessIdentity(child.pid);
+        if (closedSettled || timedOut || stopInFlight)
+            return;
+        if (identity.state !== "identified")
+            throw new Error("Historical index child process generation could not be verified");
+        workerIdentity = identity.identity;
+        watchdog.send({ type: "arm", pid: child.pid, identity: identity.identity, graceMs: stopGraceMs }, (error) => {
+            if (error)
+                watchdogFailed(error);
+        });
+    })().catch((error) => watchdogFailed(error));
+    armIdleDeadline(startupMs, "starting");
+    return { pid: child.pid, watchdogPid: watchdog.pid, started, result, stop };
+}

package/dist/src/index-build-child.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/index-build-child.js

@@ -0,0 +1,109 @@
+import { backgroundUploadBytesPerSecond, readLocalSettings } from "./machine-settings.js";
+import { createBackgroundCpuYield } from "./background-cpu.js";
+import { runBackgroundIndexWork } from "./index-background-work.js";
+import { SealkeepError } from "./errors.js";
+import { acquireDaemonSignerGrant } from "./control-plane.js";
+import { backgroundWorkerErrorToWire } from "./background-worker-error.js";
+function send(message) {
+    return new Promise((resolve) => {
+        if (!process.send || !process.connected) {
+            resolve();
+            return;
+        }
+        process.send(message, () => resolve());
+    });
+}
+let completed = false;
+const cancellation = new AbortController();
+const cancel = () => {
+    if (completed || cancellation.signal.aborted)
+        return;
+    const error = new Error("Historical index owner requested shutdown");
+    error.name = "AbortError";
+    cancellation.abort(error);
+};
+// A normal daemon stop first asks the child to abort. Chunk-independent remote
+// archives are indexed directly from their authenticated stream, so cancellation
+// closes that read without owning archive-sized scratch space. The parent's
+// existing two-second SIGKILL fallback remains the hard bound for an unresponsive
+// provider or synchronous legacy decrypt.
+process.once("SIGTERM", cancel);
+process.once("SIGINT", cancel);
+// If the daemon dies without reaching close(), the IPC pipe still tells this
+// child it has lost its sole owner. Give an active remote read one short
+// graceful window to close. The independent, never-paused sibling watchdog
+// supplies the hard orphan bound even when this event loop is SIGSTOP-paused
+// or stuck in synchronous work and cannot observe the disconnect itself.
+process.once("disconnect", () => {
+    if (completed)
+        return;
+    cancel();
+    setTimeout(() => process.exit(0), 2_000).unref();
+});
+// One IPC request, one build, one result. Keeping this child single-purpose is
+// what makes daemon cancellation exact: there is never a second queued build
+// left behind after the parent replaces or shuts down the service.
+process.once("message", async (wire) => {
+    const request = wire && typeof wire === "object" ? wire : {};
+    if (request.type !== "build" || typeof request.dataDir !== "string" || typeof request.phrase !== "string" || typeof request.sync !== "boolean"
+        || typeof request.scratchGeneration !== "string"
+        || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(request.scratchGeneration)) {
+        await send({ type: "error", error: { message: "Historical index child received an invalid build request" } });
+        completed = true;
+        if (process.connected)
+            process.disconnect();
+        return;
+    }
+    // Only an explicit capability from this exact owning daemon crosses IPC.
+    // Other live daemons in the parent's process cannot implicitly authorize us.
+    const signerGrant = request.signerAuthorized === true ? acquireDaemonSignerGrant() : undefined;
+    try {
+        await send({ type: "started" });
+        const backgroundTransferBytesPerSecond = backgroundUploadBytesPerSecond(await readLocalSettings(request.dataDir));
+        const cpuTarget = typeof request.cpuTarget === "number" ? request.cpuTarget : 0.30;
+        const maxRssBytes = typeof request.maxRssBytes === "number" ? request.maxRssBytes : 1536 * 1024 * 1024;
+        const yieldForUpgrade = createBackgroundCpuYield({
+            target: cpuTarget,
+            budget: null,
+            signal: cancellation.signal,
+        });
+        const reportProgress = () => { void send({ type: "progress" }); };
+        const result = await runBackgroundIndexWork(request.dataDir, request.phrase, {
+            sync: request.sync,
+            signal: cancellation.signal,
+            upgradeProgress: reportProgress,
+            upgradeYield: async () => {
+                if (process.memoryUsage().rss > maxRssBytes) {
+                    throw new SealkeepError("operation_timeout", `Historical index publication reached its ${Math.round(maxRssBytes / (1024 * 1024))} MiB memory safety ceiling. Sealkeep will retry later.`, { operation: "historical_index_publication", reason: "memory_ceiling", maxRssBytes, retryable: true });
+                }
+                await yieldForUpgrade();
+                reportProgress();
+            },
+            scheduling: {
+                lanes: Number.isInteger(request.lanes) ? request.lanes : 1,
+                cpuTarget: typeof request.cpuTarget === "number" ? request.cpuTarget : 0.30,
+                maxRssBytes,
+                backgroundTransferBytesPerSecond,
+                scratchGeneration: request.scratchGeneration,
+                // Segments mode only: this background child cannot hold a merged
+                // index above this many tokens, so publishFromSegments abandons
+                // publication (pushed: false) rather than producing one and failing.
+                publishMaxTokens: 400_000,
+            },
+            onActivity: () => { void send({ type: "progress" }); },
+            onProgress: () => { void send({ type: "progress" }); },
+        });
+        await send({ type: "result", result });
+    }
+    catch (cause) {
+        await send({ type: "error", error: backgroundWorkerErrorToWire(cause) });
+    }
+    finally {
+        signerGrant?.release();
+        // Closing the IPC handle lets the otherwise listener-free child exit on
+        // its own; no secret or build worker remains resident after completion.
+        completed = true;
+        if (process.connected)
+            process.disconnect();
+    }
+});

package/dist/src/index-manifest.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The segment manifest — the list of immutable sealed segments that make up
+ * the content index — and the compaction that keeps that list short.
+ *
+ * Sealed segments never change, so the index over them need not be rewritten
+ * either: appending memory means appending a segment, removing an archive
+ * means tombstoning it, and staying fast means occasionally streaming a few
+ * small segments into one bigger immutable one. The manifest itself is the
+ * only thing ever rewritten, and every rewrite is temp-write + rename under a
+ * lock, so two processes can never interleave a read-modify-write.
+ */
+import { type SegmentEntry, type SegmentManifest, type SegmentReader, type SegmentRow, type SegmentWriter } from "./index-segment-types.js";
+export declare function readManifest(dataDir: string): Promise<SegmentManifest>;
+/** Read-modify-write under the manifest lock. Every successful write gets a
+ * fresh `generation`, whether or not `mutate` actually changed anything. */
+export declare function updateManifest(dataDir: string, mutate: (current: SegmentManifest) => SegmentManifest | Promise<SegmentManifest>): Promise<SegmentManifest>;
+export declare function appendSegment(dataDir: string, entry: SegmentEntry): Promise<SegmentManifest>;
+export declare function retireArchives(dataDir: string, archiveIds: readonly string[]): Promise<SegmentManifest>;
+/**
+ * Ids to merge, or `[]`. A "remote" segment (the whole account index pulled
+ * from the cloud) is never a candidate: it never merges with a locally-built
+ * one, and it does not count toward the segment-count trigger either.
+ */
+export declare function planCompaction(manifest: SegmentManifest, options?: {
+    maxSegments?: number;
+    maxSmallBytes?: number;
+}): string[];
+/**
+ * The compaction merge on its own: the union/cap/tombstone/summary rules that
+ * turn several sealed segments' rows into one segment's worth, streamed so no
+ * more than one batch of archive or token rows is held at once.
+ *
+ * `readers` must be given oldest first (manifest order) — every "later wins"
+ * rule below is defined relative to that order. Meta rows are the one
+ * exception to streaming: a segment holds only a few hundred bytes of
+ * metadata per archive, so the whole merged map is kept in memory (also
+ * needed to rank token postings by `archivedAt`) and emitted last.
+ */
+export declare function mergeSegmentRows(readers: readonly SegmentReader[], tombstones: ReadonlySet<string>, options?: {
+    signal?: AbortSignal;
+    onYield?: () => void | Promise<void>;
+}): AsyncGenerator<SegmentRow>;
+export declare function compactSegments(dataDir: string, phrase: string, segmentIds: readonly string[], tools: {
+    open: (dataDir: string, phrase: string, segmentId: string) => Promise<SegmentReader>;
+    write: SegmentWriter;
+    remove: (dataDir: string, segmentId: string) => Promise<void>;
+}, options?: {
+    signal?: AbortSignal;
+    onYield?: () => void | Promise<void>;
+}): Promise<SegmentEntry>;
+/** Segment ids present on disk that the manifest does not list. */
+export declare function orphanSegmentIds(dataDir: string, listed: (dataDir: string) => Promise<string[]>): Promise<string[]>;