sealkeep 0.9.0 → 0.11.0

package/dist/src/index-sync.js

@@ -1,119 +1,343 @@
-import { readFile } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import { fail } from "./errors.js";
 import { recordAudit } from "./audit.js";
 import { readConfig } from "./vault.js";
 import { uploadClientFromStore } from "./providers/index.js";
 import { folderNamingKey, storageScopeOf } from "./chunk-store.js";
 import { createHmac } from "node:crypto";
-const INDEX_SEGMENT = "vaultline-index";
+import { STORAGE_PREFIX_DEFAULT } from "./branding.js";
+import { withProgressDeadline } from "./progress-deadline.js";
+import { bufferChunks, collectChunks, fileChunks, LEGACY_BUFFER_LIMIT_BYTES } from "./byte-stream.js";
+import { paceBackgroundByteStream } from "./background-bandwidth.js";
+export const DEFAULT_INDEX_REMOTE_IDLE_MS = 2 * 60_000;
+const INDEX_SEGMENT = "sealkeep-index";
 function indexKeys(prefix, naming, namingKey) {
     const clean = prefix.replace(/^\/+|\/+$/g, "");
     const segment = naming === "hashed" && namingKey
         ? createHmac("sha256", namingKey).update("segment:vaultline-index").digest("hex").slice(0, 16)
         : INDEX_SEGMENT;
-    return { meta: `${clean}/${segment}/index.vlmeta`, blob: `${clean}/${segment}/index.vlindex` };
+    return { meta: `${clean}/${segment}/index.skmeta`, blob: `${clean}/${segment}/index.skindex` };
+}
+/**
+ * The folder the per-machine segment objects live under — a `segments/`
+ * sibling of the blob's own keys, in the exact same (hashed or readable)
+ * folder `indexKeys` derives, so the naming rule is defined in exactly one
+ * place. `src/index-publish.ts` joins a machine/segment-relative key onto it.
+ */
+function segmentKeys(prefix, naming, namingKey) {
+    const { blob } = indexKeys(prefix, naming, namingKey);
+    return { base: `${blob.slice(0, blob.lastIndexOf("/"))}/segments` };
 }
 /** The store for an own-bucket vault, over the provider's plain object verbs. */
-export async function byoIndexStore(dataDir, phrase, injected, targetOverride) {
+export async function byoIndexStore(dataDir, phrase, injected, targetOverride, transfer = {}) {
     const config = await readConfig(dataDir);
     const remoteStorage = targetOverride ?? config.remoteStorage ?? fail("storage_not_configured", "No remote target configured, so the index has nowhere to sync");
     if (remoteStorage.provider === "vaultline")
         fail("invalid_argument", "Managed vaults sync their index through the control plane, not the object store");
-    const raw = injected ?? (await uploadClientFromStore(dataDir, config.vaultId, remoteStorage));
+    if (!remoteStorage.bucket)
+        fail("storage_not_configured", "The index target has no bucket configured");
+    const providerConfig = {
+        provider: remoteStorage.provider,
+        bucket: remoteStorage.bucket,
+        prefix: remoteStorage.prefix ?? STORAGE_PREFIX_DEFAULT,
+        ...(remoteStorage.region ? { region: remoteStorage.region } : {}),
+    };
+    let raw = injected;
+    if (!raw) {
+        const identity = targetOverride ?? { id: "primary", ...providerConfig };
+        const { credentialConfigIdForTarget, endpointOverridesForResolvedTarget } = await import("./storage-targets.js");
+        const credentialId = await credentialConfigIdForTarget(dataDir, identity);
+        if (!credentialId)
+            fail("signer_not_configured", `Storage target "${identity.id}" is not connected on this machine, so its index cannot sync.`);
+        raw = await uploadClientFromStore(dataDir, credentialId, providerConfig, await endpointOverridesForResolvedTarget(dataDir, identity));
+    }
     if (typeof raw.putObject !== "function" || typeof raw.getObject !== "function" || typeof raw.headObject !== "function") {
         fail("invalid_argument", `The ${remoteStorage.provider} client cannot sync the index`);
     }
     const naming = config.remoteNaming ?? "hashed";
-    const keys = indexKeys(remoteStorage.prefix, naming, naming === "hashed" ? folderNamingKey(phrase, storageScopeOf(remoteStorage)) : null);
+    const namingKey = naming === "hashed" ? folderNamingKey(phrase, storageScopeOf(providerConfig)) : null;
+    const keys = indexKeys(providerConfig.prefix, naming, namingKey);
+    const segBase = segmentKeys(providerConfig.prefix, naming, namingKey).base;
+    const configuredRate = transfer.maxBytesPerSecond;
+    const configuredProgress = transfer.onProgress;
+    const get = async (key, options) => {
+        if (typeof raw.getObjectStream !== "function") {
+            const body = await raw.getObject(key, { signal: options.signal });
+            (options.onProgress ?? configuredProgress)?.(body.length);
+            return body;
+        }
+        const source = await raw.getObjectStream(key, { signal: options.signal });
+        const rate = options.maxBytesPerSecond ?? configuredRate;
+        return collectChunks(rate ? paceBackgroundByteStream(dataDir, source, rate, {
+            signal: options.signal,
+            onProgress: options.onProgress ?? configuredProgress,
+        }) : source, Number.MAX_SAFE_INTEGER);
+    };
+    const put = async (key, body, options) => {
+        const bytes = typeof body === "string" ? (await stat(body)).size : body.length;
+        const source = typeof body === "string" ? fileChunks(body, { signal: options.signal }) : bufferChunks(body);
+        if (typeof raw.uploadStream === "function") {
+            const rate = options.maxBytesPerSecond ?? configuredRate;
+            await raw.uploadStream(key, rate ? paceBackgroundByteStream(dataDir, source, rate, { signal: options.signal }) : source, { signal: options.signal, bytes });
+            return;
+        }
+        if (typeof body === "string" && bytes > LEGACY_BUFFER_LIMIT_BYTES) {
+            fail("provider_unsupported", `The ${remoteStorage.provider} client cannot stream this ${bytes}-byte index. Update the storage client before retrying.`);
+        }
+        const buffered = typeof body === "string" ? await readFile(body) : body;
+        await raw.putObject(key, buffered, { signal: options.signal });
+    };
+    const pushPair = async (envelope, ciphertext, options) => {
+        await put(keys.blob, ciphertext, options);
+        await put(keys.meta, Buffer.from(JSON.stringify(envelope), "utf8"), options);
+    };
     return {
-        meta: async () => {
-            const head = await raw.headObject(keys.meta);
+        meta: async (options = {}) => {
+            const head = await raw.headObject(keys.meta, { signal: options.signal });
             if (!head.exists)
                 return null;
-            return JSON.parse((await raw.getObject(keys.meta)).toString("utf8"));
+            return JSON.parse((await get(keys.meta, options)).toString("utf8"));
+        },
+        pull: (options = {}) => get(keys.blob, options),
+        push: (envelope, ciphertext, options = {}) => pushPair(envelope, ciphertext, options),
+        pushFile: (envelope, ciphertextPath, options = {}) => pushPair(envelope, ciphertextPath, options),
+        // Reuses the exact `put`/`get` closures above: same rate limiting, same
+        // uploadStream-when-available path for a segment's `.skseg` body, same
+        // legacy-buffer-size guard. Only the key namespace (relative to `segBase`
+        // instead of `keys.*`) differs from the blob's single slot.
+        segments: {
+            put: (key, body, options = {}) => put(`${segBase}/${key}`, body, options),
+            get: async (key, options = {}) => {
+                const fullKey = `${segBase}/${key}`;
+                const head = await raw.headObject(fullKey, { signal: options.signal });
+                if (!head.exists)
+                    return null;
+                return get(fullKey, options);
+            },
+            head: async (key, options = {}) => (await raw.headObject(`${segBase}/${key}`, { signal: options.signal })).exists,
+            del: async (key) => { await raw.deleteObject(`${segBase}/${key}`); },
         },
-        pull: () => raw.getObject(keys.blob),
-        push: async (envelope, ciphertext) => {
-            // Blob first, envelope second: a reader that sees the new envelope can
-            // always fetch the blob it describes; the reverse order has a window
-            // where the meta promises an index the bucket does not hold yet.
-            await raw.putObject(keys.blob, ciphertext);
-            await raw.putObject(keys.meta, Buffer.from(JSON.stringify(envelope), "utf8"));
-        }
     };
 }
 /** The store for a managed vault, through the control plane's signed index slot. */
-export async function managedIndexStore(dataDir) {
+export async function managedIndexStore(dataDir, options = {}) {
+    const configuredRate = options.maxBytesPerSecond;
     const cloud = await import("./cloud.js");
     if (typeof cloud.pullIndexObject !== "function" || typeof cloud.pushIndexObject !== "function") {
         fail("invalid_argument", "This build's control plane client cannot sync the index yet");
     }
     return {
-        meta: async () => {
-            const body = await cloud.pullIndexObject(dataDir, "meta");
+        meta: async (readOptions = {}) => {
+            const body = await cloud.pullIndexObject(dataDir, "meta", undefined, {
+                signal: readOptions.signal ?? options.signal,
+                renewToken: options.renewCloudToken !== false,
+                maxBytesPerSecond: readOptions.maxBytesPerSecond ?? configuredRate,
+                onProgress: readOptions.onProgress ?? options.onProgress,
+            });
             return body ? JSON.parse(body.toString("utf8")) : null;
         },
-        pull: async () => {
-            const body = await cloud.pullIndexObject(dataDir, "blob");
+        pull: async (readOptions = {}) => {
+            const body = await cloud.pullIndexObject(dataDir, "blob", undefined, {
+                signal: readOptions.signal ?? options.signal,
+                renewToken: options.renewCloudToken !== false,
+                maxBytesPerSecond: readOptions.maxBytesPerSecond ?? configuredRate,
+                onProgress: readOptions.onProgress ?? options.onProgress,
+            });
             if (!body)
                 fail("archive_not_found", "No index has been pushed to managed storage yet");
             return body;
         },
-        push: async (envelope, ciphertext) => {
-            await cloud.pushIndexObject(dataDir, "blob", ciphertext);
-            await cloud.pushIndexObject(dataDir, "meta", Buffer.from(JSON.stringify(envelope), "utf8"));
-        }
+        push: async (envelope, ciphertext, writeOptions = {}) => {
+            const io = { signal: writeOptions.signal ?? options.signal, maxBytesPerSecond: writeOptions.maxBytesPerSecond ?? configuredRate };
+            await cloud.pushIndexObject(dataDir, "blob", ciphertext, undefined, io);
+            await cloud.pushIndexObject(dataDir, "meta", Buffer.from(JSON.stringify(envelope), "utf8"), undefined, io);
+        },
+        pushFile: async (envelope, ciphertextPath, writeOptions = {}) => {
+            if (typeof cloud.pushIndexFile !== "function")
+                fail("provider_unsupported", "This build cannot stream a large managed search index");
+            const io = { signal: writeOptions.signal ?? options.signal, maxBytesPerSecond: writeOptions.maxBytesPerSecond ?? configuredRate };
+            await cloud.pushIndexFile(dataDir, "blob", ciphertextPath, undefined, io);
+            await cloud.pushIndexObject(dataDir, "meta", Buffer.from(JSON.stringify(envelope), "utf8"), undefined, io);
+        },
+        cas: {
+            head: (readOptions = {}) => cloud.headIndexGenerationV2(dataDir, undefined, {
+                signal: readOptions.signal ?? options.signal,
+                renewToken: options.renewCloudToken !== false,
+            }),
+            pullSnapshot: (readOptions = {}) => cloud.pullIndexGenerationV2(dataDir, undefined, {
+                signal: readOptions.signal ?? options.signal,
+                renewToken: options.renewCloudToken !== false,
+                maxBytesPerSecond: readOptions.maxBytesPerSecond ?? configuredRate,
+                onProgress: readOptions.onProgress ?? options.onProgress,
+                maxBytes: readOptions.maxBytes,
+            }),
+            publish: (envelope, ciphertext, writeOptions) => cloud.publishIndexGenerationV2(dataDir, {
+                envelope,
+                ciphertext,
+                expectedRevision: writeOptions.expectedRevision,
+                coverageJson: writeOptions.coverageJson,
+            }, undefined, {
+                signal: writeOptions.signal ?? options.signal,
+                maxBytesPerSecond: writeOptions.maxBytesPerSecond ?? configuredRate,
+                onProgress: writeOptions.onProgress ?? options.onProgress,
+            }),
+            publishFile: (envelope, ciphertextPath, writeOptions) => cloud.publishIndexGenerationV2(dataDir, {
+                envelope,
+                ciphertext: { path: ciphertextPath },
+                expectedRevision: writeOptions.expectedRevision,
+                coverageJson: writeOptions.coverageJson,
+            }, undefined, {
+                signal: writeOptions.signal ?? options.signal,
+                maxBytesPerSecond: writeOptions.maxBytesPerSecond ?? configuredRate,
+                onProgress: writeOptions.onProgress ?? options.onProgress,
+            }),
+        },
+    };
+}
+/** Managed team-space index slot. Membership authorization is enforced by the plane. */
+export async function managedTeamIndexStore(dataDir, spaceKey, transfer = {}) {
+    const cloud = await import("./cloud.js");
+    const configuredRate = transfer.maxBytesPerSecond;
+    return {
+        meta: async (options = {}) => {
+            const body = await cloud.pullTeamIndexObject(dataDir, spaceKey, "meta", undefined, {
+                ...options,
+                maxBytesPerSecond: options.maxBytesPerSecond ?? configuredRate,
+                onProgress: options.onProgress ?? transfer.onProgress,
+            });
+            return body ? JSON.parse(body.toString("utf8")) : null;
+        },
+        pull: async (options = {}) => {
+            const body = await cloud.pullTeamIndexObject(dataDir, spaceKey, "blob", undefined, {
+                ...options,
+                maxBytesPerSecond: options.maxBytesPerSecond ?? configuredRate,
+                onProgress: options.onProgress ?? transfer.onProgress,
+            });
+            if (!body)
+                fail("archive_not_found", "No team index has been pushed to managed storage yet");
+            return body;
+        },
+        push: async (envelope, ciphertext, options = {}) => {
+            const io = { ...options, maxBytesPerSecond: options.maxBytesPerSecond ?? configuredRate };
+            await cloud.pushTeamIndexObject(dataDir, spaceKey, "blob", ciphertext, undefined, io);
+            await cloud.pushTeamIndexObject(dataDir, spaceKey, "meta", Buffer.from(JSON.stringify(envelope), "utf8"), undefined, io);
+        },
+        cas: {
+            head: (options = {}) => cloud.headTeamIndexGenerationV2(dataDir, spaceKey, undefined, {
+                signal: options.signal,
+            }),
+            pullSnapshot: (options = {}) => cloud.pullTeamIndexGenerationV2(dataDir, spaceKey, undefined, {
+                signal: options.signal,
+                maxBytesPerSecond: options.maxBytesPerSecond ?? configuredRate,
+                onProgress: options.onProgress ?? transfer.onProgress,
+                maxBytes: options.maxBytes,
+            }),
+            publish: (envelope, ciphertext, options) => cloud.publishTeamIndexGenerationV2(dataDir, spaceKey, {
+                envelope,
+                ciphertext,
+                expectedRevision: options.expectedRevision,
+                coverageJson: options.coverageJson,
+                expectedMembershipVersion: options.expectedMembershipVersion
+                    ?? fail("invalid_argument", "A team index publication requires a membership version"),
+            }, undefined, {
+                signal: options.signal,
+                maxBytesPerSecond: options.maxBytesPerSecond ?? configuredRate,
+                onProgress: options.onProgress ?? transfer.onProgress,
+            }),
+            publishFile: (envelope, ciphertextPath, options) => cloud.publishTeamIndexGenerationV2(dataDir, spaceKey, {
+                envelope,
+                ciphertext: { path: ciphertextPath },
+                expectedRevision: options.expectedRevision,
+                coverageJson: options.coverageJson,
+                expectedMembershipVersion: options.expectedMembershipVersion
+                    ?? fail("invalid_argument", "A team index publication requires a membership version"),
+            }, undefined, {
+                signal: options.signal,
+                maxBytesPerSecond: options.maxBytesPerSecond ?? configuredRate,
+                onProgress: options.onProgress ?? transfer.onProgress,
+            }),
+        },
     };
 }
 /** Picks the right store for this vault, or null when there is nowhere to sync. */
-export async function remoteIndexStoreFor(dataDir, phrase, injected) {
+export async function remoteIndexStoreFor(dataDir, phrase, injected, options = {}) {
     const config = await readConfig(dataDir);
-    // Multi-target vaults keep ONE phonebook, on the most durable target:
-    // managed when present, else the first bucket that can hold objects.
-    if (config.storageTargets && config.storageTargets.length > 0) {
-        const managed = config.storageTargets.find((target) => target.provider === "vaultline");
-        if (managed) {
-            try {
-                return await managedIndexStore(dataDir);
-            }
-            catch {
-                return null;
-            }
+    const idleMs = options.remoteIdleMs ?? DEFAULT_INDEX_REMOTE_IDLE_MS;
+    // Keep ONE phonebook on the most durable account target: managed when
+    // present, otherwise the first connected object-store target. Resolve the
+    // cloud-backed list rather than looking only at config.json so a newly
+    // enrolled machine does not silently miss account routing metadata.
+    const { resolveTargets, targetConnectedOnThisMachine } = await import("./storage-targets.js");
+    const targets = await withProgressDeadline("Resolving search-index storage", idleMs, options.signal, (signal) => resolveTargets(dataDir, { ...options, signal }));
+    const managed = targets.find((target) => target.provider === "vaultline");
+    if (managed) {
+        try {
+            return await managedIndexStore(dataDir, options);
         }
-        const byo = config.storageTargets.find((target) => target.provider !== "gdrive");
-        if (!byo)
+        catch (error) {
+            if (options.signal?.aborted)
+                throw options.signal.reason ?? error;
             return null;
+        }
+    }
+    const byoTargets = targets
+        .filter((target) => target.provider !== "gdrive")
+        .sort((a, b) => (a.priority ?? 50) - (b.priority ?? 50));
+    for (const byo of byoTargets) {
+        if (!injected && !await targetConnectedOnThisMachine(dataDir, byo, {
+            renewCloudToken: options.renewCloudToken,
+            signal: options.signal,
+        }))
+            continue;
         try {
-            return await byoIndexStore(dataDir, phrase, injected, { provider: byo.provider, bucket: byo.bucket ?? "", prefix: byo.prefix ?? "vaultline", ...(byo.region ? { region: byo.region } : {}) });
+            return await byoIndexStore(dataDir, phrase, injected, byo, {
+                maxBytesPerSecond: options.maxBytesPerSecond,
+                onProgress: options.onProgress,
+            });
         }
-        catch {
-            return null;
+        catch (error) {
+            if (options.signal?.aborted)
+                throw options.signal.reason ?? error; /* try the next connected bucket */
         }
     }
+    if (targets.length > 0)
+        return null;
     if (!config.remoteStorage) {
         // An enrolled managed vault has a cloud token and no remoteStorage entry —
         // same rule as storedCopiesMode. Without the token there is nowhere to sync.
         try {
             const { cloudToken } = await import("./cloud.js");
-            await cloudToken(dataDir);
-            return await managedIndexStore(dataDir);
+            await withProgressDeadline("Checking the Sealkeep account for index storage", idleMs, options.signal, (signal) => cloudToken(dataDir, undefined, {
+                renew: options.renewCloudToken !== false,
+                signal,
+            }));
+            return await managedIndexStore(dataDir, options);
         }
-        catch {
+        catch (error) {
+            if (options.signal?.aborted)
+                throw options.signal.reason ?? error;
             return null;
         }
     }
     if (config.remoteStorage.provider === "vaultline") {
         try {
-            return await managedIndexStore(dataDir);
+            return await managedIndexStore(dataDir, options);
         }
-        catch {
+        catch (error) {
+            if (options.signal?.aborted)
+                throw options.signal.reason ?? error;
             return null;
         }
     }
     try {
-        return await byoIndexStore(dataDir, phrase, injected);
+        return await byoIndexStore(dataDir, phrase, injected, undefined, {
+            maxBytesPerSecond: options.maxBytesPerSecond,
+            onProgress: options.onProgress,
+        });
     }
-    catch {
+    catch (error) {
+        if (options.signal?.aborted)
+            throw options.signal.reason ?? error;
         return null;
     }
 }
@@ -122,15 +346,24 @@ export async function remoteIndexStoreFor(dataDir, phrase, injected) {
  * Freshness is the envelope's own createdAt — one tiny GET decides, and the
  * blob only moves when it would change something.
  */
-export async function pullIndexIfNewer(dataDir, store, localBuiltAt, save) {
-    const envelope = await store.meta();
+export async function pullIndexIfNewer(dataDir, store, localBuiltAt, save, options = {}) {
+    const idleMs = options.idleMs ?? DEFAULT_INDEX_REMOTE_IDLE_MS;
+    const envelope = await withProgressDeadline("Reading remote index metadata", idleMs, options.signal, (signal) => store.meta({
+        signal,
+        maxBytesPerSecond: options.maxBytesPerSecond,
+        onProgress: options.onProgress,
+    }));
     if (!envelope)
         return { pulled: false, remoteBuiltAt: null };
     const remoteBuiltAt = envelope.manifest?.createdAt ?? null;
     if (!remoteBuiltAt || (localBuiltAt && Date.parse(remoteBuiltAt) <= Date.parse(localBuiltAt))) {
         return { pulled: false, remoteBuiltAt };
     }
-    const ciphertext = await store.pull();
+    const ciphertext = await withProgressDeadline("Pulling the remote search index", idleMs, options.signal, (signal) => store.pull({
+        signal,
+        maxBytesPerSecond: options.maxBytesPerSecond,
+        onProgress: options.onProgress,
+    }));
     await save(envelope, ciphertext);
     await recordAudit(dataDir, "archive.restore", "allowed", { indexPulled: true, remoteBuiltAt }).catch(() => undefined);
     return { pulled: true, remoteBuiltAt };

package/dist/src/index-upgrade-publication.d.ts

@@ -0,0 +1,30 @@
+import { readIndexPublicationState } from "./index-publication-state.js";
+import { type RemoteIndexStore } from "./index-sync.js";
+import { publishLocalContentIndexCheckpointToManagedCas, type PublishLocalContentIndexCheckpointOptions, type PublishedLocalContentIndexCheckpoint } from "./search.js";
+export declare const legacyIndexPublicationMarkerPath: (dataDir: string) => string;
+export type LegacyIndexPublicationOutcome = {
+    status: "not-needed";
+} | {
+    status: "published";
+    publication: PublishedLocalContentIndexCheckpoint;
+};
+type UpgradePublicationDependencies = {
+    readPublicationState: typeof readIndexPublicationState;
+    resolveInitialStore(dataDir: string, phrase: string, options: PublishLocalContentIndexCheckpointOptions): Promise<RemoteIndexStore | null>;
+    resolveRetryStore(dataDir: string, options: PublishLocalContentIndexCheckpointOptions): Promise<RemoteIndexStore>;
+    publish: typeof publishLocalContentIndexCheckpointToManagedCas;
+};
+/**
+ * One-time upgrade bridge for a complete local v3 checkpoint which predates
+ * immutable managed index receipts.
+ *
+ * It runs only in the daemon-owned index child. A first attempt starts only
+ * when the receipt ledger is absent and the selected account index store has
+ * managed CAS. Once started, its marker makes every later daemon attempt retry
+ * this exact fail-closed bridge. The bridge never overwrites a different
+ * remote head; that one case exits to the ordinary authenticated merge/CAS
+ * builder. The marker is otherwise removed only after exact managed read-back
+ * has installed durable per-archive receipts.
+ */
+export declare function publishLegacyLocalIndexCheckpointIfNeeded(dataDir: string, phrase: string, options?: PublishLocalContentIndexCheckpointOptions, dependencies?: Partial<UpgradePublicationDependencies>): Promise<LegacyIndexPublicationOutcome>;
+export {};

package/dist/src/index-upgrade-publication.js

@@ -0,0 +1,179 @@
+import { randomUUID } from "node:crypto";
+import { link, mkdir, open, readFile, rm, stat, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { fail, isSealkeepError } from "./errors.js";
+import { readIndexPublicationState } from "./index-publication-state.js";
+import { managedIndexStore, remoteIndexStoreFor } from "./index-sync.js";
+import { publishLocalContentIndexCheckpointToManagedCas, } from "./search.js";
+const MARKER_VERSION = 1;
+export const legacyIndexPublicationMarkerPath = (dataDir) => join(dataDir, "index", "managed-checkpoint-upgrade.v1.json");
+const defaultDependencies = {
+    readPublicationState: readIndexPublicationState,
+    resolveInitialStore: (dataDir, phrase, options) => remoteIndexStoreFor(dataDir, phrase, undefined, {
+        signal: options.signal,
+        remoteIdleMs: options.remoteIdleMs,
+        maxBytesPerSecond: options.maxBytesPerSecond,
+        onProgress: options.onProgress,
+    }),
+    resolveRetryStore: (dataDir, options) => managedIndexStore(dataDir, {
+        signal: options.signal,
+        maxBytesPerSecond: options.maxBytesPerSecond,
+        onProgress: options.onProgress,
+    }),
+    publish: publishLocalContentIndexCheckpointToManagedCas,
+};
+function errorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        ? String(error.code)
+        : undefined;
+}
+async function checkpointPairExists(dataDir) {
+    const [ciphertext, envelope] = await Promise.all([
+        stat(join(dataDir, "index", "content-index.skindex")).catch(() => null),
+        stat(join(dataDir, "index", "content-index.json")).catch(() => null),
+    ]);
+    return Boolean(ciphertext?.isFile() && envelope?.isFile());
+}
+async function readMarker(dataDir) {
+    let raw;
+    try {
+        raw = await readFile(legacyIndexPublicationMarkerPath(dataDir), "utf8");
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return false;
+        throw error;
+    }
+    try {
+        const marker = JSON.parse(raw);
+        if (marker.version !== MARKER_VERSION || Object.keys(marker).length !== 1)
+            throw new Error("invalid marker");
+    }
+    catch {
+        return fail("ciphertext_integrity_failed", "The managed search-index upgrade marker is damaged; source sessions remain protected until it is repaired.");
+    }
+    return true;
+}
+async function syncDirectory(path) {
+    let handle;
+    try {
+        handle = await open(path, "r");
+        await handle.sync();
+    }
+    catch (error) {
+        // Windows cannot open directories for fsync. The marker inode itself is
+        // still synced before publication, which is Node's strongest primitive
+        // there; POSIX must durably publish the directory entry as well.
+        if (process.platform !== "win32")
+            throw error;
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+async function removeMarker(dataDir) {
+    try {
+        await unlink(legacyIndexPublicationMarkerPath(dataDir));
+        await syncDirectory(join(dataDir, "index"));
+    }
+    catch (error) {
+        if (errorCode(error) !== "ENOENT")
+            throw error;
+    }
+}
+/**
+ * Durably marks a legacy publication attempt before its first managed write.
+ *
+ * The marker survives an outage or service upgrade, so a failed bridge is
+ * retried as the same conservative operation rather than falling through to a
+ * memory-heavy convergence rebuild on the next process. A hard-link publish
+ * makes the small state atomic without replacing another live worker's
+ * marker.
+ */
+async function markPending(dataDir) {
+    const directory = join(dataDir, "index");
+    const marker = legacyIndexPublicationMarkerPath(dataDir);
+    const temporary = join(directory, `.managed-checkpoint-upgrade.${randomUUID()}.tmp`);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    let handle;
+    try {
+        handle = await open(temporary, "wx", 0o600);
+        await handle.writeFile(`${JSON.stringify({ version: MARKER_VERSION })}\n`, "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        try {
+            await link(temporary, marker);
+        }
+        catch (error) {
+            if (errorCode(error) !== "EEXIST")
+                throw error;
+        }
+        await syncDirectory(directory);
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+        await rm(temporary, { force: true }).catch(() => undefined);
+    }
+}
+/**
+ * One-time upgrade bridge for a complete local v3 checkpoint which predates
+ * immutable managed index receipts.
+ *
+ * It runs only in the daemon-owned index child. A first attempt starts only
+ * when the receipt ledger is absent and the selected account index store has
+ * managed CAS. Once started, its marker makes every later daemon attempt retry
+ * this exact fail-closed bridge. The bridge never overwrites a different
+ * remote head; that one case exits to the ordinary authenticated merge/CAS
+ * builder. The marker is otherwise removed only after exact managed read-back
+ * has installed durable per-archive receipts.
+ */
+export async function publishLegacyLocalIndexCheckpointIfNeeded(dataDir, phrase, options = {}, dependencies = {}) {
+    const deps = { ...defaultDependencies, ...dependencies };
+    const pending = await readMarker(dataDir);
+    if (!await checkpointPairExists(dataDir)) {
+        if (pending)
+            await removeMarker(dataDir);
+        return { status: "not-needed" };
+    }
+    let store;
+    if (pending) {
+        // Once an attempt has begun, an offline control plane is a retryable
+        // publication failure. It must not silently become a full local rebuild.
+        store = await deps.resolveRetryStore(dataDir, options);
+    }
+    else {
+        const state = await deps.readPublicationState(dataDir);
+        if (state.status !== "missing")
+            return { status: "not-needed" };
+        store = await deps.resolveInitialStore(dataDir, phrase, options);
+        if (!store?.cas || typeof store.cas.publishFile !== "function")
+            return { status: "not-needed" };
+        await markPending(dataDir);
+    }
+    if (!store?.cas || typeof store.cas.publishFile !== "function") {
+        return fail("provider_unsupported", "The managed search-index publication lane is unavailable; source sessions remain protected and Sealkeep will retry.");
+    }
+    let publication;
+    try {
+        publication = await deps.publish(dataDir, phrase, { ...options, store });
+    }
+    catch (error) {
+        const normalBuildRequired = isSealkeepError(error) && ((error.code === "lease_expired" && error.details.reason === "index_head_different")
+            || (error.code === "provider_unsupported" && error.details.reason === "legacy_index_format"));
+        if (normalBuildRequired) {
+            // The bridge itself never replaces a different checkpoint. Hand this
+            // case back to the ordinary builder, which authenticates and merges the
+            // remote generation before publishing a new union with CAS. The same
+            // builder upgrades an authenticated pre-v3 monolith. Keeping the marker
+            // for either case would retry an immutable input forever.
+            await removeMarker(dataDir);
+            return { status: "not-needed" };
+        }
+        throw error;
+    }
+    // Receipt installation is complete when publish resolves. Removing the
+    // marker afterwards cannot make a failed/partial network write authoritative.
+    await removeMarker(dataDir);
+    return { status: "published", publication };
+}

package/dist/src/integration-manager.d.ts

@@ -0,0 +1,32 @@
+export type IntegrationManagerChildReceipt = {
+    kind: string;
+    executable: string;
+    args: string[];
+};
+/** Marker understood by the daemon bootstrap and the standalone manager. */
+export declare const INTEGRATION_MANAGER_GENERATION_ENV = "SEALKEEP_SERVICE_MANAGER_GENERATION";
+export declare const INTEGRATION_MANAGER_GENERATION = "darwin-app-policy-v1";
+/**
+ * The durable service manager's exact child command.
+ *
+ * A launchd job registered by an older Sealkeep release can retain its cached
+ * ProcessType=Background policy even after the plist is corrected. Starting
+ * the daemon through taskpolicy's application profile escapes that inherited
+ * job policy before Node evaluates the CLI; every helper the daemon later
+ * starts inherits the corrected policy too. Other platforms keep their byte-
+ * for-byte command because their native service definitions reload normally.
+ */
+export declare function integrationManagerChildInvocation(receipt: IntegrationManagerChildReceipt, target?: NodeJS.Platform): {
+    executable: string;
+    args: string[];
+};
+/**
+ * Source copied outside the npm package when the background service is
+ * installed. npm 7+ deliberately runs no uninstall lifecycle scripts, so a
+ * package cannot clean hooks or services from inside code npm just removed.
+ * This tiny disclosed supervisor survives long enough to notice that the
+ * package target stayed absent beyond an upgrade grace period, remove only the
+ * integration paths named in its receipt, write a tombstone, then remove
+ * itself. Vaults, encrypted archives, outboxes, and keychain items are kept.
+ */
+export declare const INTEGRATION_MANAGER_SOURCE: string;