sealkeep 0.9.0 → 0.11.1

package/dist/src/index-store.js

@@ -0,0 +1,495 @@
+/**
+ * The segmented content index in use: the manifest and its segments become a
+ * `ContentIndex` a lookup can read, a seal appends one small segment instead
+ * of rewriting the whole vault, and a catch-up build streams archives into
+ * bounded batches instead of holding everything in memory at once.
+ *
+ * This is the integration layer over the two finished, independently tested
+ * pieces: `index-segments.ts` (one sealed segment) and `index-manifest.ts`
+ * (the list of them, and compaction). Nothing here seals or opens ciphertext
+ * directly — every crypto operation goes through those two modules.
+ *
+ * Segments mode is opt-in per vault: it is on once
+ * `<dataDir>/index/segments/manifest.json` exists with at least one segment
+ * (see `segmentsEnabled`). Until `sealkeep index migrate` runs, a vault stays
+ * on the legacy single-blob path untouched.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdir, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { canonicalPhrase } from "./mnemonic.js";
+import { appendSegment, compactSegments, mergeSegmentRows, orphanSegmentIds, planCompaction, readManifest, retireArchives, updateManifest, } from "./index-manifest.js";
+import { openSegment, removeSegment, writeSegment } from "./index-segments.js";
+import { MAX_POSTINGS_PER_TOKEN, } from "./index-segment-types.js";
+import { applyArchiveTokens, chronologicalPostings, INDEX_EXTRACTION_POLICY, loadContentIndex, normalizeContentIndex, persistContentIndex, } from "./search.js";
+import { remoteIndexStoreFor } from "./index-sync.js";
+import { publishSegments, writePublishedBlobState } from "./index-publish.js";
+import { listArchives } from "./vault.js";
+const segmentsDir = (dataDir) => join(dataDir, "index", "segments");
+const manifestFilePath = (dataDir) => join(dataDir, "index", "segments", "manifest.json");
+const coveragePath = (dataDir) => join(dataDir, "index", "coverage.json");
+/** Atomic publication that never leaves this call's temp behind on error.
+ * Mirrors the private `writeIndexFile` in src/search.ts. */
+async function writeStoreFile(target, contents) {
+    const temp = `${target}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temp, contents, { mode: 0o600 });
+        await rename(temp, target);
+    }
+    finally {
+        await rm(temp, { force: true }).catch(() => undefined);
+    }
+}
+function emptyBatchIndex(builtAt) {
+    return { version: 2, extractionPolicy: INDEX_EXTRACTION_POLICY, builtAt, archives: {}, tokens: {}, meta: {} };
+}
+/** Sorted "a", then "t", then "m" rows — the region order every segment
+ * writer requires. Declared synchronous (not `async`, despite the design
+ * doc's signature): an `async function` may only return a `Promise`, and
+ * every caller here — `writeSegment`'s `rows` parameter — accepts a plain
+ * `Iterable<SegmentRow>` directly, so there is nothing for a Promise to buy. */
+export function segmentRowsFromIndex(index) {
+    function* rows() {
+        for (const id of Object.keys(index.archives).sort()) {
+            const line = index.archives[id];
+            yield ["a", id, ...line];
+        }
+        for (const token of Object.keys(index.tokens).sort()) {
+            yield ["t", token, index.tokens[token]];
+        }
+        const meta = index.meta ?? {};
+        for (const id of Object.keys(meta).sort()) {
+            yield ["m", id, meta[id]];
+        }
+    }
+    return rows();
+}
+const newestBuiltAt = (segments) => {
+    let newest = "";
+    for (const segment of segments)
+        if (segment.builtAt > newest)
+            newest = segment.builtAt;
+    return newest || new Date().toISOString();
+};
+/**
+ * Segments mode is a one-way door for a vault: once `sealkeep index migrate`
+ * has run, it must never silently fall back to the legacy whole-blob build
+ * (and its whole-index-in-memory cost) just because `dropContentIndex`
+ * happened to empty the manifest. So this is a FILE-existence check, not a
+ * segment-count one — `dropContentIndex` deliberately leaves behind an empty
+ * manifest (see `resetSegments`) rather than removing it, precisely so this
+ * keeps answering true.
+ */
+export async function segmentsEnabled(dataDir) {
+    return stat(manifestFilePath(dataDir)).then(() => true, () => false);
+}
+/** The archive ids segments cover on this machine: the union of every
+ * segment's `archiveIds` minus tombstones — exactly what `coverage.json`
+ * holds, computed straight from the plaintext manifest. No segment body is
+ * opened and no phrase is needed. */
+export async function manifestCoverage(dataDir) {
+    const manifest = await readManifest(dataDir);
+    const tombstones = new Set(manifest.tombstones);
+    const indexed = new Set();
+    for (const segment of manifest.segments) {
+        for (const id of segment.archiveIds ?? [])
+            if (!tombstones.has(id))
+                indexed.add(id);
+    }
+    return indexed;
+}
+/** Archives another machine sealed whose rows a segment here still carries — searchable, never this machine's to prune. */
+export async function manifestRemoteCoverage(dataDir) {
+    const manifest = await readManifest(dataDir);
+    const tombstones = new Set(manifest.tombstones);
+    const remote = new Set();
+    for (const segment of manifest.segments) {
+        for (const id of segment.remoteArchiveIds ?? [])
+            if (!tombstones.has(id))
+                remote.add(id);
+    }
+    return remote;
+}
+/**
+ * `coverage.json` exactly as `saveLocal` writes it in search.ts: the unsealed
+ * sidecar `index status`, doctor, and the daemon read to answer "what is
+ * searchable" without the recovery phrase. Always re-derived from the
+ * manifest, so it can never drift from what the segments actually cover.
+ */
+export async function writeCoverageFromManifest(dataDir) {
+    // Everything searchable here, as the blob path's saveLocal writes it: this
+    // machine's own seals and the rows it carries for another machine's. What
+    // this machine may prune is answered by the manifest (manifestCoverage),
+    // never by this file.
+    const indexed = new Set([...(await manifestCoverage(dataDir)), ...(await manifestRemoteCoverage(dataDir))]);
+    await mkdir(join(dataDir, "index"), { recursive: true, mode: 0o700 });
+    await writeStoreFile(coveragePath(dataDir), JSON.stringify({
+        extractionPolicy: INDEX_EXTRACTION_POLICY,
+        builtAt: new Date().toISOString(),
+        indexed: [...indexed].sort(),
+    }, null, 2) + "\n");
+}
+/**
+ * Empties a vault's segment set back to nothing while keeping it IN segments
+ * mode (the manifest file itself survives, freshly empty) — the counterpart
+ * `dropContentIndex` needs so a drop-then-rebuild never regresses to the
+ * legacy blob, and the extraction-policy bump needs so a stale segment set
+ * can be discarded wholesale rather than patched in place (segments are
+ * immutable; there is no way to re-extract one that already exists).
+ */
+export async function resetSegments(dataDir) {
+    await mkdir(segmentsDir(dataDir), { recursive: true, mode: 0o700 });
+    return updateManifest(dataDir, async (current) => {
+        const onDisk = await listSksegIds(dataDir);
+        const ids = new Set([...current.segments.map((segment) => segment.id), ...onDisk]);
+        for (const id of ids)
+            await removeSegment(dataDir, id);
+        return { version: 1, generation: "", segments: [], tombstones: [] };
+    });
+}
+/** ids on disk under `index/segments/` with a `.skseg` body, regardless of
+ * whether the manifest still lists them. */
+async function listSksegIds(dataDir) {
+    let entries;
+    try {
+        entries = await readdir(segmentsDir(dataDir));
+    }
+    catch {
+        return [];
+    }
+    const ids = [];
+    for (const name of entries) {
+        if (!name.endsWith(".skseg"))
+            continue;
+        const id = name.slice(0, -".skseg".length);
+        if (/^[0-9a-f-]{36}$/.test(id))
+            ids.push(id);
+    }
+    return ids;
+}
+async function removeOrphanSegments(dataDir) {
+    const orphans = await orphanSegmentIds(dataDir, listSksegIds);
+    for (const id of orphans)
+        await removeSegment(dataDir, id);
+}
+/**
+ * `planCompaction` over the current manifest; when it has work, stream the
+ * merge and replace the merged segments with the single result, then bring
+ * `coverage.json` and any stray `.skseg` files left by an interrupted prior
+ * attempt back in line with the manifest.
+ */
+export async function maybeCompact(dataDir, phrase, options = {}) {
+    const manifest = await readManifest(dataDir);
+    // Seal time (appendArchiveSegment) asks for smallOnly: the "too many
+    // segments" rule can pull a hundreds-of-MB segment into a merge, which
+    // belongs to the background build lane, not a foreground seal. Disabling
+    // it here means only the cheap small-segment rule (< 8 MiB, >= 4 of them)
+    // can fire from that path.
+    const plan = planCompaction(manifest, options.smallOnly ? { maxSegments: Number.MAX_SAFE_INTEGER } : undefined);
+    if (plan.length === 0)
+        return null;
+    const planned = new Set(plan);
+    const tombstones = new Set(manifest.tombstones);
+    const mergedArchiveIds = new Set();
+    for (const segment of manifest.segments) {
+        if (!planned.has(segment.id))
+            continue;
+        for (const id of segment.archiveIds ?? [])
+            if (!tombstones.has(id))
+                mergedArchiveIds.add(id);
+    }
+    const archiveIds = [...mergedArchiveIds].sort();
+    const write = async (writeDataDir, writePhrase, input, writeOptions) => {
+        const entry = await writeSegment(writeDataDir, writePhrase, input, writeOptions);
+        return { ...entry, origin: "local", archiveIds };
+    };
+    // Two writers (a seal and the catch-up) can plan the same small segments;
+    // whichever merges second finds them gone and refuses — a benign race, not
+    // a failed seal. The next plan sees the merged set.
+    let entry;
+    try {
+        entry = await compactSegments(dataDir, phrase, plan, { open: openSegment, write, remove: removeSegment }, options);
+    }
+    catch (error) {
+        if (error?.code === "invalid_argument")
+            return null;
+        throw error;
+    }
+    await writeCoverageFromManifest(dataDir);
+    await removeOrphanSegments(dataDir);
+    return entry;
+}
+/** One archive, sealed at seal time: no whole-index rewrite, just a new
+ * one-archive segment. Also publishes it (step 2): a segment is exactly the
+ * unit a peer wants as soon as possible, not just at the next background
+ * build. A publish failure never fails the seal that produced the segment —
+ * it is already durable locally — so it is caught and named for the next
+ * successful publish (a build's, or this machine's next seal) to pick up. */
+export async function appendArchiveSegment(dataDir, phrase, record, tokensByChunk, options = {}) {
+    const index = emptyBatchIndex(new Date().toISOString());
+    applyArchiveTokens(index, record, tokensByChunk);
+    const segmentId = randomUUID();
+    const builtAt = new Date().toISOString();
+    const entry = await writeSegment(dataDir, phrase, { segmentId, builtAt, rows: segmentRowsFromIndex(index) });
+    const withArchiveIds = { ...entry, origin: "local", archiveIds: [record.id] };
+    await appendSegment(dataDir, withArchiveIds);
+    await writeCoverageFromManifest(dataDir);
+    // Seal time only ever pays for the cheap small-segment compaction; the
+    // build lane pays for the full policy (see maybeCompact and
+    // buildContentIndex's segments branch).
+    await maybeCompact(dataDir, phrase, { smallOnly: true });
+    if (options.sync !== false) {
+        try {
+            const store = await remoteIndexStoreFor(dataDir, phrase, undefined, {
+                signal: options.signal,
+                remoteIdleMs: options.remoteIdleMs,
+                maxBytesPerSecond: options.maxBytesPerSecond,
+            });
+            if (store)
+                await publishSegments(dataDir, phrase, store, { signal: options.signal });
+        }
+        catch (error) {
+            if (options.signal?.aborted)
+                throw error;
+            const reason = error instanceof Error ? error.message.split("\n")[0] : String(error);
+            process.emitWarning(`segment publish deferred: ${reason}`, "SealkeepIndexDeferred");
+        }
+    }
+    return withArchiveIds;
+}
+/** The catch-up build's per-batch equivalent: one segment for however many
+ * archives a checkpoint's worth of indexing collected. */
+export async function appendBatchSegment(dataDir, phrase, batch, options = {}) {
+    const archiveIds = Object.keys(batch.archives).sort();
+    if (archiveIds.length === 0)
+        return null;
+    const segmentId = randomUUID();
+    const builtAt = new Date().toISOString();
+    const entry = await writeSegment(dataDir, phrase, { segmentId, builtAt, rows: segmentRowsFromIndex(batch) }, options);
+    const withArchiveIds = { ...entry, origin: "local", archiveIds };
+    await appendSegment(dataDir, withArchiveIds);
+    await writeCoverageFromManifest(dataDir);
+    await maybeCompact(dataDir, phrase, options);
+    return withArchiveIds;
+}
+export async function retireArchiveIds(dataDir, archiveIds) {
+    await retireArchives(dataDir, archiveIds);
+    await writeCoverageFromManifest(dataDir);
+}
+/**
+ * Open every segment, answer `terms` from each concurrently, and merge into
+ * one `ContentIndex` a query-time caller reads exactly like the legacy blob:
+ * archives keep the richer (longer) row, meta merges field by field with the
+ * later (newest-last) segment winning except a real `summary` over scaffold
+ * and unioned `commits`/`files`, and token postings union, drop anything
+ * tombstoned, and rank chronologically before the usual per-token cap.
+ */
+export async function lookupSegments(dataDir, phrase, terms, options = {}) {
+    const manifest = await readManifest(dataDir);
+    const settled = await Promise.allSettled(manifest.segments.map((segment) => openSegment(dataDir, phrase, segment.id)));
+    const readers = [];
+    for (const result of settled)
+        if (result.status === "fulfilled")
+            readers.push(result.value);
+    try {
+        const failed = settled.find((result) => result.status === "rejected");
+        if (failed)
+            throw failed.reason;
+        const lookups = await Promise.all(readers.map((reader) => reader.lookup(terms, { prefixKeep: options.prefixKeep, signal: options.signal })));
+        const tombstones = new Set(manifest.tombstones);
+        const merged = {
+            version: 2,
+            extractionPolicy: INDEX_EXTRACTION_POLICY,
+            builtAt: newestBuiltAt(manifest.segments),
+            archives: {},
+            tokens: {},
+            meta: {},
+        };
+        const tokenUnion = {};
+        for (const lookup of lookups) {
+            for (const [id, line] of Object.entries(lookup.archives)) {
+                if (tombstones.has(id))
+                    continue;
+                const current = merged.archives[id];
+                if (!current || line.length > current.length)
+                    merged.archives[id] = line;
+            }
+            for (const [id, metaObject] of Object.entries(lookup.meta)) {
+                if (tombstones.has(id))
+                    continue;
+                const current = merged.meta[id];
+                merged.meta[id] = current ? mergeMetaFields(current, metaObject) : metaObject;
+            }
+            await options.onYield?.();
+        }
+        for (const lookup of lookups) {
+            for (const [token, postings] of Object.entries(lookup.tokens)) {
+                const bucket = (tokenUnion[token] ??= []);
+                const seen = new Set(bucket);
+                for (const posting of postings) {
+                    const archiveId = posting.split("@")[0];
+                    if (tombstones.has(archiveId) || seen.has(posting))
+                        continue;
+                    seen.add(posting);
+                    bucket.push(posting);
+                }
+            }
+        }
+        for (const [token, postings] of Object.entries(tokenUnion)) {
+            if (postings.length === 0)
+                continue;
+            const ranked = chronologicalPostings(postings, merged.meta ?? {});
+            merged.tokens[token] = ranked.length > MAX_POSTINGS_PER_TOKEN ? ranked.slice(-MAX_POSTINGS_PER_TOKEN) : ranked;
+        }
+        return merged;
+    }
+    finally {
+        await Promise.all(readers.map((reader) => reader.close().catch(() => undefined)));
+    }
+}
+// A captured tool artifact, not a real session line; a real summary always
+// beats it regardless of which segment it came from. Mirrors the same
+// pattern in search.ts (SCAFFOLD_SUMMARY) and index-manifest.ts (JUNK_SUMMARY).
+const JUNK_SUMMARY = /^\s*<(?:system-reminder|local-command-stdout|task-notification|command-name|command-message)/;
+function isJunkSummary(value) {
+    return typeof value !== "string" || JUNK_SUMMARY.test(value);
+}
+function unionArrayField(existing, incoming) {
+    if (!Array.isArray(incoming))
+        return existing;
+    if (!Array.isArray(existing))
+        return incoming;
+    const seen = new Set(existing.map((item) => JSON.stringify(item)));
+    const merged = existing.slice();
+    for (const item of incoming) {
+        const key = JSON.stringify(item);
+        if (!seen.has(key)) {
+            seen.add(key);
+            merged.push(item);
+        }
+    }
+    return merged;
+}
+/** Later segment wins field by field, except `summary` (a real line beats
+ * captured scaffolding) and the unioned `commits`/`files` arrays. */
+function mergeMetaFields(base, incoming) {
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(incoming)) {
+        if (key === "summary") {
+            const existing = merged.summary;
+            merged.summary = existing !== undefined && !isJunkSummary(existing) && isJunkSummary(value) ? existing : value;
+        }
+        else if (key === "commits" || key === "files") {
+            merged[key] = unionArrayField(merged[key], value);
+        }
+        else {
+            merged[key] = value;
+        }
+    }
+    return merged;
+}
+/**
+ * The blob for cloud publication, produced from segments without ever
+ * holding more than the streaming merge needs: `mergeSegmentRows` folds every
+ * segment into archive/token/meta rows with tombstones already applied, and
+ * `persistContentIndex` seals and pushes exactly as the legacy build does.
+ * `maxTokens` is the background child's guard — a merge that would exceed it
+ * is abandoned (nothing written) rather than produced and then rejected.
+ *
+ * The blob-fallback publish path (step 2 addendum): a store with no generic
+ * keyed storage (managed today) cannot hold segments, so this is still how
+ * such a vault reaches the cloud at all. A successful push also records
+ * `published-blob.json`, so `publishPending` knows the manifest it merged is
+ * no longer waiting, and a peer without segments support (`pullSegments`'s
+ * own blob fallback) can tell its own publication apart from one worth
+ * converting.
+ */
+export async function publishFromSegments(dataDir, phrase, options) {
+    const manifest = await readManifest(dataDir);
+    // A vault that has been dropped back to an empty (but still segments-mode)
+    // manifest has nothing to publish. persistContentIndex would happily seal
+    // and write an empty blob; that is not "nothing written".
+    if (manifest.segments.length === 0)
+        return false;
+    const tombstones = new Set(manifest.tombstones);
+    const readers = [];
+    try {
+        for (const segment of manifest.segments)
+            readers.push(await openSegment(dataDir, phrase, segment.id));
+        const index = {
+            version: 2,
+            extractionPolicy: INDEX_EXTRACTION_POLICY,
+            builtAt: newestBuiltAt(manifest.segments),
+            archives: {},
+            tokens: {},
+            meta: {},
+        };
+        let tokenRows = 0;
+        for await (const row of mergeSegmentRows(readers, tombstones, { signal: options.signal, onYield: options.onYield })) {
+            if (row[0] === "a") {
+                index.archives[row[1]] = row.slice(2);
+            }
+            else if (row[0] === "t") {
+                tokenRows += 1;
+                if (options.maxTokens !== undefined && tokenRows > options.maxTokens)
+                    return false;
+                index.tokens[row[1]] = row[2];
+            }
+            else {
+                (index.meta ??= {})[row[1]] = row[2];
+            }
+        }
+        const pushed = await persistContentIndex(dataDir, phrase, index, options.store, { signal: options.signal, onYield: options.onYield });
+        if (pushed && options.store) {
+            // Not index.builtAt, and not the local content-index.json: sealing
+            // stamps its own envelope createdAt, and persistContentIndex's own BYO
+            // convergence retry can resave the LOCAL file with a later timestamp
+            // than the one it actually pushed (it reseals again after observing
+            // the remote). Read back what the store itself now reports, so this
+            // matches exactly what a peer's pullSegments blob fallback — or this
+            // vault's own next publish — will also see from store.meta().
+            const remoteEnvelope = await options.store.meta({ signal: options.signal }).catch(() => null);
+            const builtAt = remoteEnvelope?.manifest?.createdAt ?? index.builtAt;
+            await writePublishedBlobState(dataDir, { version: 1, generation: manifest.generation, builtAt });
+        }
+        return pushed;
+    }
+    finally {
+        await Promise.all(readers.map((reader) => reader.close().catch(() => undefined)));
+    }
+}
+/**
+ * One-time move of the existing whole-index blob into a single segment. The
+ * blob files are left exactly where they are — the cloud path still reads
+ * them until the next publish, and a vault with neither blob nor manifest is
+ * simply "build one" (unchanged). Accepts a raw or already-canonical phrase,
+ * like the other public entry points in search.ts (`buildContentIndex`,
+ * `loadContentIndex`): `sealkeep index migrate` hands it the CLI's raw
+ * `--recovery-phrase` value directly.
+ */
+export async function migrateBlobToSegments(dataDir, rawPhrase) {
+    // Not `segmentsEnabled`: that is a file-existence check now (a vault stays
+    // in segments mode across a drop, even with an empty manifest). Migration
+    // itself must still be a no-op once there is real segment content, but is
+    // allowed — indeed necessary — to (re)run against an empty manifest, e.g.
+    // right after a drop.
+    if ((await readManifest(dataDir)).segments.length > 0)
+        return { migrated: false, archives: 0, tokens: 0 };
+    const phrase = canonicalPhrase(rawPhrase);
+    const index = normalizeContentIndex(await loadContentIndex(dataDir, phrase));
+    // The blob may carry rows another machine indexed (pulled from the account
+    // index). They stay searchable in the segment, but only this machine's own
+    // archives become coverage: the next build tombstones "covered but no
+    // longer here", and a teammate's session was never here to begin with.
+    const here = new Set((await listArchives(dataDir)).map((record) => record.id));
+    const allIds = Object.keys(index.archives).sort();
+    const archiveIds = allIds.filter((id) => here.has(id));
+    const remoteArchiveIds = allIds.filter((id) => !here.has(id));
+    const segmentId = randomUUID();
+    const builtAt = new Date().toISOString();
+    const entry = await writeSegment(dataDir, phrase, { segmentId, builtAt, rows: segmentRowsFromIndex(index) });
+    const withArchiveIds = { ...entry, origin: "local", archiveIds, ...(remoteArchiveIds.length ? { remoteArchiveIds } : {}) };
+    await appendSegment(dataDir, withArchiveIds);
+    await writeCoverageFromManifest(dataDir);
+    return { migrated: true, archives: allIds.length, tokens: Object.keys(index.tokens).length };
+}

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

@@ -1,5 +1,7 @@
-import type { Envelope } from "../packages/vaultline-crypto/src/index.js";
+import type { Envelope } from "../packages/sealkeep-crypto/src/index.js";
 import { type ChunkStoreClient } from "./chunk-store.js";
+import type { StorageTargetConfig } from "./types.js";
+import type { ManagedIndexCoverage, ManagedIndexHead, ManagedIndexReceipt, ManagedIndexV2PublishResult, ManagedIndexV2Snapshot, ManagedIndexV2Unsupported } from "./cloud.js";
 /**
  * The content index travels, sealed — Paul's question answered structurally.
  *
@@ -10,9 +12,9 @@ import { type ChunkStoreClient } from "./chunk-store.js";
  * whole history to rebuild its own. So the index now syncs like everything
  * else does: as ciphertext. Two small objects in the storage —
  *
- *   …/index.vlmeta     the index's ENVELOPE (tiny; carries builtAt, so
+ *   …/index.skmeta     the index's ENVELOPE (tiny; carries builtAt, so
  *                      "is theirs newer than mine" costs one small GET)
- *   …/index.vlindex    the sealed index itself
+ *   …/index.skindex    the sealed index itself
  *
  * — and the recovery phrase, which every machine of the vault holds, opens
  * them. The provider learns that an index exists and when it changed;
@@ -23,29 +25,103 @@ import { type ChunkStoreClient } from "./chunk-store.js";
  * hash it). Pro (managed): the control plane vends signed PUT/GET for a
  * per-account index slot — same signer, known lengths — via cloud.ts.
  */
+export type RemoteIndexIoOptions = {
+    signal?: AbortSignal;
+    maxBytesPerSecond?: number;
+    onProgress?: (bytes: number) => void;
+    /** Optional caller memory ceiling for the combined immutable metadata and ciphertext read. */
+    maxBytes?: number;
+};
+/**
+ * The account's per-machine segment objects (step 2): a generic keyed
+ * put/get/head/delete over the same bucket the blob uses, addressed by a key
+ * RELATIVE to this machine's or a peer's `segments/` folder — the caller
+ * (`src/index-publish.ts`) never sees the prefix/hashing that turns it into
+ * the real remote key, exactly as `meta`/`pull`/`push` hide it for the blob.
+ */
+export type RemoteIndexSegmentStore = {
+    put(key: string, body: Buffer | string, options?: RemoteIndexIoOptions): Promise<void>;
+    /** null when the object does not exist. */
+    get(key: string, options?: RemoteIndexIoOptions): Promise<Buffer | null>;
+    head(key: string, options?: RemoteIndexIoOptions): Promise<boolean>;
+    del(key: string, options?: RemoteIndexIoOptions): Promise<void>;
+};
 export type RemoteIndexStore = {
     /** The remote envelope, or null when no index was ever pushed. */
-    meta(): Promise<Envelope | null>;
-    pull(): Promise<Buffer>;
-    push(envelope: Envelope, ciphertext: Buffer): Promise<void>;
+    meta(options?: RemoteIndexIoOptions): Promise<Envelope | null>;
+    pull(options?: RemoteIndexIoOptions): Promise<Buffer>;
+    push(envelope: Envelope, ciphertext: Buffer, options?: RemoteIndexIoOptions): Promise<void>;
+    /** Large production snapshots use the committed local ciphertext directly. */
+    pushFile?(envelope: Envelope, ciphertextPath: string, options?: RemoteIndexIoOptions): Promise<void>;
+    /**
+     * Managed storage's immutable generation/CAS lane.  Its absence means the
+     * provider has no protocol that can prove a cross-machine publication.  An
+     * explicit `unsupported` result means the managed plane is too old; callers
+     * must keep source sessions rather than falling back to the legacy slot.
+     */
+    cas?: RemoteIndexCas;
+    /**
+     * Present only for a provider whose client exposes generic keyed objects —
+     * an own bucket. Managed and team stores vend a single fixed index slot,
+     * not a general key space, so they omit this; a caller with no `segments`
+     * skips publish/pull rather than guessing at a protocol that is not there.
+     */
+    segments?: RemoteIndexSegmentStore;
+};
+export type RemoteIndexCasPublishOptions = RemoteIndexIoOptions & {
+    /** Zero means there is no committed head. */
+    expectedRevision: number;
+    /** Canonical archiveRef -> entryDigest map for these exact sealed bytes. */
+    coverageJson: ManagedIndexCoverage;
+    /** Required for team stores and ignored/omitted for account stores. */
+    expectedMembershipVersion?: number;
 };
+export type RemoteIndexCasHeadResult = ManagedIndexV2Unsupported | {
+    status: "ok";
+    head: ManagedIndexHead | null;
+};
+export type RemoteIndexCasSnapshotResult = ManagedIndexV2Unsupported | {
+    status: "ok";
+    snapshot: ManagedIndexV2Snapshot | null;
+};
+export type RemoteIndexCas = {
+    head(options?: RemoteIndexIoOptions): Promise<RemoteIndexCasHeadResult>;
+    pullSnapshot(options?: RemoteIndexIoOptions): Promise<RemoteIndexCasSnapshotResult>;
+    publish(envelope: Envelope, ciphertext: Buffer, options: RemoteIndexCasPublishOptions): Promise<ManagedIndexV2PublishResult>;
+    publishFile?(envelope: Envelope, ciphertextPath: string, options: RemoteIndexCasPublishOptions): Promise<ManagedIndexV2PublishResult>;
+};
+export type { ManagedIndexCoverage, ManagedIndexHead, ManagedIndexReceipt };
+export declare const DEFAULT_INDEX_REMOTE_IDLE_MS: number;
 /** The store for an own-bucket vault, over the provider's plain object verbs. */
-export declare function byoIndexStore(dataDir: string, phrase: string, injected?: ChunkStoreClient, targetOverride?: {
-    provider: "s3" | "r2" | "b2" | "gcs" | "gdrive" | "vaultline";
-    bucket: string;
-    prefix: string;
-    region?: string;
-}): Promise<RemoteIndexStore>;
+export declare function byoIndexStore(dataDir: string, phrase: string, injected?: ChunkStoreClient, targetOverride?: StorageTargetConfig, transfer?: Pick<RemoteIndexIoOptions, "maxBytesPerSecond" | "onProgress">): Promise<RemoteIndexStore>;
 /** The store for a managed vault, through the control plane's signed index slot. */
-export declare function managedIndexStore(dataDir: string): Promise<RemoteIndexStore>;
+export declare function managedIndexStore(dataDir: string, options?: {
+    signal?: AbortSignal;
+    renewCloudToken?: boolean;
+    maxBytesPerSecond?: number;
+    onProgress?: (bytes: number) => void;
+}): Promise<RemoteIndexStore>;
+/** Managed team-space index slot. Membership authorization is enforced by the plane. */
+export declare function managedTeamIndexStore(dataDir: string, spaceKey: string, transfer?: Pick<RemoteIndexIoOptions, "maxBytesPerSecond" | "onProgress">): Promise<RemoteIndexStore>;
 /** Picks the right store for this vault, or null when there is nowhere to sync. */
-export declare function remoteIndexStoreFor(dataDir: string, phrase: string, injected?: ChunkStoreClient): Promise<RemoteIndexStore | null>;
+export declare function remoteIndexStoreFor(dataDir: string, phrase: string, injected?: ChunkStoreClient, options?: {
+    signal?: AbortSignal;
+    renewCloudToken?: boolean;
+    remoteIdleMs?: number;
+    maxBytesPerSecond?: number;
+    onProgress?: (bytes: number) => void;
+}): Promise<RemoteIndexStore | null>;
 /**
  * Pulls the remote index when it is newer than what this machine holds.
  * Freshness is the envelope's own createdAt — one tiny GET decides, and the
  * blob only moves when it would change something.
  */
-export declare function pullIndexIfNewer(dataDir: string, store: RemoteIndexStore, localBuiltAt: string | null, save: (envelope: Envelope, ciphertext: Buffer) => Promise<void>): Promise<{
+export declare function pullIndexIfNewer(dataDir: string, store: RemoteIndexStore, localBuiltAt: string | null, save: (envelope: Envelope, ciphertext: Buffer) => Promise<void>, options?: {
+    signal?: AbortSignal;
+    idleMs?: number;
+    maxBytesPerSecond?: number;
+    onProgress?: (bytes: number) => void;
+}): Promise<{
     pulled: boolean;
     remoteBuiltAt: string | null;
 }>;