sealkeep 0.5.0

package/dist/src/search.js

@@ -0,0 +1,677 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { decryptArchive as openEnvelope, encryptArchive as sealEnvelope } from "../packages/vaultline-crypto/src/index.js";
+import { fail } from "./errors.js";
+import { canonicalPhrase } from "./mnemonic.js";
+import { decryptRecord, listArchives, readConfig } from "./vault.js";
+import { openChunkWindow, supportsChunkAccess } from "../packages/vaultline-crypto/src/chunk-access.js";
+import { isV2 } from "./types.js";
+const indexPath = (dataDir) => join(dataDir, "index", "content-index.vlindex");
+const envelopePath = (dataDir) => join(dataDir, "index", "content-index.json");
+const coveragePath = (dataDir) => join(dataDir, "index", "coverage.json");
+const MIN_TOKEN = 3;
+const MAX_TOKENS_PER_ARCHIVE = 4000;
+/**
+ * What deserves an index slot. Transcripts are full of hex digests, base64
+ * blobs, and minified identifiers; every one of those admitted is a real word
+ * crowded out of the cap. Queries still tokenize unfiltered — searching FOR a
+ * long id simply misses content and falls to metadata search, which owns ids.
+ */
+export function indexableToken(token) {
+    if (token.length > 24)
+        return false;
+    if (token.length >= 12 && /^[0-9a-f]+$/.test(token))
+        return false;
+    if (token.length >= 16 && /^[A-Za-z0-9+/=_-]+$/.test(token) && !/[aeiou]{1}/i.test(token.slice(0, 8)))
+        return false;
+    return true;
+}
+/**
+ * Round-robin merge of per-chunk token sets: every chunk gets a fair slice of
+ * the archive's token budget. First-chunks-win was the live finding — with a
+ * 40k budget, chunks 0–7 of a 399-chunk archive consumed everything and a
+ * word living in chunk 50 stayed unsearchable.
+ */
+export function mergeChunkTokens(byChunk, cap) {
+    const merged = new Map();
+    const iterators = [...byChunk.entries()]
+        .sort(([a], [b]) => a - b)
+        .map(([chunkIndex, tokens]) => ({ chunkIndex, iterator: tokens[Symbol.iterator]() }));
+    let admitted = 0;
+    let progressed = true;
+    while (progressed && iterators.length > 0) {
+        progressed = false;
+        for (const lane of iterators) {
+            let step = lane.iterator.next();
+            while (!step.done) {
+                const token = step.value;
+                const existing = merged.get(token);
+                if (existing) {
+                    if (existing.size < 2)
+                        existing.add(lane.chunkIndex);
+                    step = lane.iterator.next();
+                    continue; // an already-admitted token only collects a tag; keep drawing for a NEW one
+                }
+                if (admitted < cap) {
+                    merged.set(token, new Set([lane.chunkIndex]));
+                    admitted += 1;
+                    progressed = true;
+                }
+                break;
+            }
+        }
+        if (admitted >= cap)
+            break;
+    }
+    // Budget spent or lanes dry: sweep remaining occurrences so admitted tokens
+    // still collect their second tag.
+    if (admitted >= cap) {
+        for (const lane of iterators) {
+            let step = lane.iterator.next();
+            while (!step.done) {
+                const existing = merged.get(step.value);
+                if (existing && existing.size < 2)
+                    existing.add(lane.chunkIndex);
+                step = lane.iterator.next();
+            }
+        }
+    }
+    return merged;
+}
+/**
+ * The token budget grows with the archive: a 40 KB session and a 1.7 GB one
+ * do not deserve the same 4000 slots — the live drill proved the flat cap
+ * starves everything past the first chunk of a big archive ("retention"
+ * indexed, "chunk" lost). Bounded so the phonebook stays a phonebook.
+ */
+export function tokenCapFor(sourceBytes) {
+    // 72 tokens/MB, capped at 120k: a 1.7 GB transcript's real (junk-filtered)
+    // vocabulary measured ~40–100k distinct words, and a 40k budget cut the
+    // tail off — "chunk", 141 honest mentions, lost every per-chunk seat. At
+    // ~100 bytes per entry the whale archive costs ~2 MB gzipped in the index;
+    // ordinary sessions stay in the low thousands.
+    return Math.min(120_000, MAX_TOKENS_PER_ARCHIVE + Math.floor(sourceBytes / (1024 * 1024)) * 72);
+}
+/**
+ * Own-property-safe append to the tokens map. A transcript containing the
+ * word "constructor" made `tokens[token] ??= []` find — and push into —
+ * Object.prototype.constructor. Every read and write of a token entry must
+ * go through own-property checks; the token space is attacker-adjacent input.
+ */
+function pushTokenTag(tokens, token, tag) {
+    if (Object.prototype.hasOwnProperty.call(tokens, token) && Array.isArray(tokens[token]))
+        tokens[token].push(tag);
+    else
+        tokens[token] = [tag];
+}
+/** Own-property-safe read: inherited names ("constructor", "toString") answer as absent. */
+export function tokenEntries(tokens, token) {
+    return Object.prototype.hasOwnProperty.call(tokens, token) && Array.isArray(tokens[token]) ? tokens[token] : [];
+}
+/**
+ * A query term also matches indexed tokens it prefixes — "chunk" finds
+ * "chunks" and "chunkbytes", which is what a person typing it meant. Bounded
+ * fan-out; exact entries come first so precise queries stay precise.
+ */
+export function tokenEntriesExpanded(tokens, term) {
+    const exact = tokenEntries(tokens, term);
+    if (term.length < MIN_TOKEN)
+        return exact;
+    const expanded = [...exact];
+    let fanOut = 0;
+    for (const key of Object.keys(tokens)) {
+        if (key === term || !key.startsWith(term))
+            continue;
+        expanded.push(...tokenEntries(tokens, key));
+        fanOut += 1;
+        if (fanOut >= 40)
+            break;
+    }
+    return expanded;
+}
+export function tokenize(text) {
+    const out = new Set();
+    for (const raw of text.toLowerCase().split(/[^a-z0-9_.@/-]+/)) {
+        if (raw.length < MIN_TOKEN)
+            continue;
+        out.add(raw);
+        // Compounds also index by their segments: "chunk-store.ts" answers for
+        // "chunk" and "store", and a hyphenated marker longer than the storage
+        // cap is still findable through every piece of itself. Queries run the
+        // same split, so a compound query becomes an AND of its segments.
+        if (/[-._/@]/.test(raw)) {
+            for (const segment of raw.split(/[-._/@]+/)) {
+                if (segment.length >= MIN_TOKEN)
+                    out.add(segment);
+            }
+        }
+    }
+    return [...out];
+}
+function metadataHaystack(record) {
+    return `${record.id} ${record.source.agent} ${record.source.path} ${record.createdAt}`.toLowerCase();
+}
+/** Metadata search needs no secret and never touches an archive's contents. */
+export async function searchMetadata(dataDir, query, options = {}) {
+    const needle = query.trim().toLowerCase();
+    if (!needle)
+        fail("invalid_argument", "A search query is required");
+    return (await listArchives(dataDir))
+        .filter((record) => (!options.agent || record.source.agent === options.agent) && metadataHaystack(record).includes(needle))
+        .map((record) => ({ id: record.id, agent: record.source.agent, path: record.source.path, bytes: record.source.bytes, createdAt: record.createdAt, matched: "metadata" }));
+}
+/**
+ * Builds the opt-in content index.
+ *
+ * This decrypts every archive locally, so it requires the recovery phrase. The
+ * resulting index is itself encrypted with the same envelope before it touches the
+ * disk, and it is never uploaded: `sealkeep upload` only ever sends archive objects.
+ */
+export async function buildContentIndex(dataDir, rawPhrase, options = {}) {
+    const phrase = canonicalPhrase(rawPhrase);
+    await readConfig(dataDir);
+    const records = await listArchives(dataDir);
+    // Start from what already exists — the remote index when it is newer (a
+    // teammate's machine may have indexed archives this one never decrypted),
+    // the local one otherwise. Rebuilding from zero used to be the only mode,
+    // which on a second machine meant fetching and decrypting the whole
+    // history to answer one search.
+    const { remoteIndexStoreFor, pullIndexIfNewer, localIndexBuiltAt } = await import("./index-sync.js");
+    const store = options.sync === false ? null : await remoteIndexStoreFor(dataDir, phrase);
+    let pulled = false;
+    if (store) {
+        const outcome = await pullIndexIfNewer(dataDir, store, await localIndexBuiltAt(envelopePath(dataDir)), async (envelope, ciphertext) => {
+            await mkdir(join(dataDir, "index"), { recursive: true, mode: 0o700 });
+            await writeFile(indexPath(dataDir), ciphertext, { mode: 0o600 });
+            await writeFile(envelopePath(dataDir), JSON.stringify(envelope, null, 2) + "\n", { mode: 0o600 });
+        });
+        pulled = outcome.pulled;
+    }
+    let index;
+    try {
+        const existing = normalizeContentIndex(await loadContentIndex(dataDir, phrase));
+        // Merge-by-union is safe because an archive's tokens are a pure function
+        // of its content: whoever indexed it got the same answer.
+        index = { version: 2, builtAt: new Date().toISOString(), archives: existing.archives, tokens: existing.tokens };
+    }
+    catch {
+        index = { version: 2, builtAt: new Date().toISOString(), archives: {}, tokens: {} };
+    }
+    // Drop entries for archives that no longer exist, then index only what is
+    // NEW — the difference between "re-decrypt 53 archives" and "decrypt the
+    // two sealed since the last build".
+    const liveIds = new Set(records.map((record) => record.id));
+    for (const id of Object.keys(index.archives)) {
+        if (liveIds.has(id))
+            continue;
+        delete index.archives[id];
+        for (const token of Object.keys(index.tokens)) {
+            index.tokens[token] = index.tokens[token].filter((entry) => entry !== id && !entry.startsWith(`${id}@`));
+            if (index.tokens[token].length === 0)
+                delete index.tokens[token];
+        }
+    }
+    const fresh = records.filter((record) => !index.archives[record.id]);
+    let indexedNow = 0;
+    let skipped = 0;
+    for (const record of fresh) {
+        // One flaky download must not kill a 54-archive build: each archive gets
+        // two tries, then the build moves on and reports what it left for the
+        // next run. The archives entry is only written on success — a listed id
+        // with no tokens would be "indexed" yet unfindable forever.
+        try {
+            try {
+                await indexOneRecord(dataDir, index, record, phrase);
+            }
+            catch {
+                await indexOneRecord(dataDir, index, record, phrase);
+            }
+            indexedNow += 1;
+        }
+        catch {
+            skipped += 1;
+        }
+    }
+    const pushed = await persistContentIndex(dataDir, phrase, index, store);
+    return { archives: Object.keys(index.archives).length, tokens: Object.keys(index.tokens).length, builtAt: index.builtAt, indexedNow, skipped, pulled, pushed };
+}
+/** Indexes one archive into `index`, chunk-tagged when the format allows, windowed otherwise. Writes the archives entry LAST, so a failure leaves no half-indexed id. */
+async function indexOneRecord(dataDir, index, record, phrase) {
+    const cap = tokenCapFor(record.source.bytes);
+    if (isV2(record) && supportsChunkAccess(record.envelope)) {
+        const { readFile: readBlob } = await import("node:fs/promises");
+        const { materialiseArchive } = await import("./offload.js");
+        const materialised = await materialiseArchive(dataDir, record);
+        try {
+            const stored = await readBlob(materialised.path);
+            const byChunk = new Map();
+            const perChunkCap = Math.max(4000, Math.floor(cap / 4));
+            let offset = 0;
+            for (const chunk of record.envelope.chunks) {
+                const slice = stored.subarray(offset, offset + chunk.storedBytes);
+                offset += chunk.storedBytes;
+                const window = { firstIndex: chunk.index, lastIndex: chunk.index, storedOffset: 0, storedLength: chunk.storedBytes, rawStartInWindow: 0, rawLengthInWindow: chunk.rawBytes ?? 0 };
+                const raw = openChunkWindow(record.envelope, window, slice, { phrase });
+                const bucket = new Set();
+                for (const token of tokenize(raw.toString("utf8"))) {
+                    if (bucket.size >= perChunkCap)
+                        break;
+                    if (!indexableToken(token))
+                        continue;
+                    bucket.add(token);
+                }
+                byChunk.set(chunk.index, bucket);
+                raw.fill(0);
+            }
+            // Round-robin merge: every chunk gets a fair slice of the budget, so a
+            // word living only in chunk 50 is as findable as one from chunk 0.
+            for (const [token, chunkSet] of mergeChunkTokens(byChunk, cap)) {
+                for (const chunkIndex of [...chunkSet].slice(0, 2))
+                    pushTokenTag(index.tokens, token, `${record.id}@c${chunkIndex}`);
+            }
+        }
+        finally {
+            await materialised.release();
+        }
+        index.archives[record.id] = [record.source.agent, record.source.path];
+        return;
+    }
+    const { plaintext } = await decryptRecord(dataDir, record.id, phrase);
+    // Windowed, never one giant string: a legacy archive can decrypt to more
+    // than Node's ~512 MB string ceiling, and the live index build died on
+    // exactly that ("Cannot create a string longer than 0x1fffffe8"). Small
+    // overlap keeps tokens that straddle a window boundary.
+    const seen = new Set();
+    const WINDOW = 8 * 1024 * 1024;
+    const OVERLAP = 256;
+    for (let at = 0; at < plaintext.length && seen.size < cap; at += WINDOW) {
+        const slice = plaintext.subarray(Math.max(0, at - OVERLAP), Math.min(plaintext.length, at + WINDOW));
+        for (const token of tokenize(slice.toString("utf8"))) {
+            if (!indexableToken(token))
+                continue;
+            seen.add(token);
+            if (seen.size >= cap)
+                break;
+        }
+    }
+    for (const token of seen)
+        pushTokenTag(index.tokens, token, record.id);
+    plaintext.fill(0);
+    index.archives[record.id] = [record.source.agent, record.source.path];
+}
+/**
+ * Seals the index to disk atomically and pushes it to the vault's remote slot
+ * when one is reachable. Sealed local, so sealed remote: pushing costs two
+ * PUTs of ciphertext and buys every other machine of this vault a search that
+ * needs no rebuild. A token index is highly repetitive JSON and compresses hard.
+ */
+async function persistContentIndex(dataDir, phrase, index, store) {
+    const { envelope, ciphertext } = sealEnvelope(Buffer.from(JSON.stringify(index)), { recipients: [{ kind: "phrase", phrase }], compression: "gzip", adapter: { agent: "vaultline-index", version: "1" } });
+    const target = indexPath(dataDir);
+    await mkdir(join(dataDir, "index"), { recursive: true, mode: 0o700 });
+    const temp = `${target}.${randomUUID()}.tmp`;
+    await writeFile(temp, ciphertext, { mode: 0o600 });
+    await rename(temp, target);
+    await writeFile(envelopePath(dataDir), JSON.stringify(envelope, null, 2) + "\n", { mode: 0o600 });
+    // The unsealed coverage sidecar: WHICH archive ids are in the index, and
+    // nothing else. Ids are metadata the records directory already shows, so
+    // status, doctor, and the panel can answer "what is searchable and what is
+    // not" without asking for the phrase. Tokens stay sealed next door.
+    await writeFile(coveragePath(dataDir), JSON.stringify({ builtAt: index.builtAt, indexed: Object.keys(index.archives).sort() }, null, 2) + "\n", { mode: 0o600 });
+    if (!store)
+        return false;
+    try {
+        await store.push(envelope, ciphertext);
+        return true;
+    }
+    catch {
+        return false; /* an offline build is still a build; the next one pushes */
+    }
+}
+/**
+ * Seal-time indexing: the seal already held every plaintext slice in its
+ * hands, so the tokens arrive here for free — no downloading an archive back
+ * just to read what was just read. Merges one archive's chunk-tagged tokens
+ * into the index (pulling a newer remote first, exactly like a build) and
+ * persists. Failure must never fail a seal; callers treat this as advisory.
+ */
+export async function indexArchiveTokens(dataDir, rawPhrase, record, tokensByChunk, options = {}) {
+    const phrase = canonicalPhrase(rawPhrase);
+    const { remoteIndexStoreFor, pullIndexIfNewer, localIndexBuiltAt } = await import("./index-sync.js");
+    const store = options.sync === false ? null : await remoteIndexStoreFor(dataDir, phrase);
+    if (store) {
+        await pullIndexIfNewer(dataDir, store, await localIndexBuiltAt(envelopePath(dataDir)), async (envelope, ciphertext) => {
+            await mkdir(join(dataDir, "index"), { recursive: true, mode: 0o700 });
+            await writeFile(indexPath(dataDir), ciphertext, { mode: 0o600 });
+            await writeFile(envelopePath(dataDir), JSON.stringify(envelope, null, 2) + "\n", { mode: 0o600 });
+        }).catch(() => undefined);
+    }
+    let index;
+    try {
+        index = normalizeContentIndex(await loadContentIndex(dataDir, phrase));
+    }
+    catch {
+        index = { version: 2, builtAt: new Date().toISOString(), archives: {}, tokens: {} };
+    }
+    // Replace any previous entries for this archive id, then apply the same
+    // caps the build applies: bounded tokens per archive, two tags per token.
+    for (const token of Object.keys(index.tokens)) {
+        index.tokens[token] = index.tokens[token].filter((entry) => entry !== record.id && !entry.startsWith(`${record.id}@`));
+        if (index.tokens[token].length === 0)
+            delete index.tokens[token];
+    }
+    index.archives[record.id] = [record.source.agent, record.source.path];
+    const filtered = new Map();
+    for (const [chunkIndex, tokens] of tokensByChunk) {
+        const keep = new Set();
+        for (const token of tokens)
+            if (indexableToken(token))
+                keep.add(token);
+        filtered.set(chunkIndex, keep);
+    }
+    const merged = mergeChunkTokens(filtered, tokenCapFor(record.source.bytes));
+    for (const [token, chunkSet] of merged) {
+        for (const chunkIndex of [...chunkSet].slice(0, 2))
+            pushTokenTag(index.tokens, token, `${record.id}@c${chunkIndex}`);
+    }
+    index.builtAt = new Date().toISOString();
+    const pushed = await persistContentIndex(dataDir, phrase, index, store);
+    return { pushed };
+}
+/**
+ * Whatever shape an old index decrypts to, the build merges only what it can
+ * use: token entries must be arrays of archive tags, archive entries must
+ * exist. The live rebuild found a version-1 index whose token values were not
+ * arrays — `.push is not a function`, four archives in. Anything unusable is
+ * dropped here and simply re-indexed, which is what "incremental" owes its
+ * caller anyway.
+ */
+export function normalizeContentIndex(raw) {
+    const source = (typeof raw === "object" && raw !== null ? raw : {});
+    const archives = {};
+    for (const [id, value] of Object.entries(source.archives ?? {})) {
+        archives[id] = Array.isArray(value) ? value.map(String) : [];
+    }
+    const tokens = {};
+    for (const [token, value] of Object.entries(source.tokens ?? {})) {
+        if (Array.isArray(value))
+            tokens[token] = value.filter((entry) => typeof entry === "string");
+        else if (typeof value === "string")
+            tokens[token] = [value];
+        // anything else (counts, objects from the v1 experiment) is dropped
+    }
+    // An archive no surviving token points at would be listed as indexed yet
+    // unfindable forever. Unlisting it here makes the next build re-index it —
+    // the one-time cost that turns a relic index into a working one.
+    const referenced = new Set();
+    for (const entries of Object.values(tokens))
+        for (const entry of entries)
+            referenced.add(entry.split("@")[0]);
+    for (const id of Object.keys(archives))
+        if (!referenced.has(id))
+            delete archives[id];
+    return { version: 2, builtAt: typeof source.builtAt === "string" ? source.builtAt : new Date().toISOString(), archives, tokens };
+}
+export async function loadContentIndex(dataDir, rawPhrase) {
+    const phrase = canonicalPhrase(rawPhrase);
+    const envelope = await readFile(envelopePath(dataDir), "utf8").then((raw) => JSON.parse(raw)).catch(() => null);
+    const ciphertext = await readFile(indexPath(dataDir)).catch(() => null);
+    if (!envelope || !ciphertext)
+        fail("invalid_argument", "No local content index. Build one with: sealkeep index build", { dataDir });
+    try {
+        return JSON.parse(openEnvelope(envelope, ciphertext, { phrase }).toString("utf8"));
+    }
+    catch {
+        return fail("recovery_phrase_mismatch", "The content index could not be opened with this recovery phrase");
+    }
+}
+export async function dropContentIndex(dataDir) {
+    await rm(indexPath(dataDir), { force: true });
+    await rm(envelopePath(dataDir), { force: true });
+}
+/**
+ * Content search over the opt-in index. Every returned snippet is read from the
+ * archive at query time, so nothing readable is kept on disk between searches.
+ */
+export async function searchContent(dataDir, query, rawPhrase, options = {}) {
+    const phrase = canonicalPhrase(rawPhrase);
+    const terms = tokenize(query);
+    if (terms.length === 0)
+        fail("invalid_argument", "A content query needs a term of at least three characters");
+    // Terms the index could never hold (an over-long compound, a hex digest)
+    // must not be REQUIRED — their segments carry the query. They still count
+    // for snippet line matching, where the literal text exists.
+    const requiredTerms = terms.filter((term) => indexableToken(term));
+    const effectiveTerms = requiredTerms.length > 0 ? requiredTerms : terms;
+    // A teammate's machine may have pushed a newer index since this one last
+    // built — one tiny meta GET decides, and search answers from the freshest
+    // sealed index either side has produced. Tolerated failure: offline search
+    // over yesterday's index beats no search.
+    try {
+        const { remoteIndexStoreFor, pullIndexIfNewer, localIndexBuiltAt } = await import("./index-sync.js");
+        const store = await remoteIndexStoreFor(dataDir, phrase);
+        if (store) {
+            await pullIndexIfNewer(dataDir, store, await localIndexBuiltAt(envelopePath(dataDir)), async (envelope, ciphertext) => {
+                await mkdir(join(dataDir, "index"), { recursive: true, mode: 0o700 });
+                await writeFile(indexPath(dataDir), ciphertext, { mode: 0o600 });
+                await writeFile(envelopePath(dataDir), JSON.stringify(envelope, null, 2) + "\n", { mode: 0o600 });
+            });
+        }
+    }
+    catch { /* the local index still answers */ }
+    const index = await loadContentIndex(dataDir, phrase);
+    const counts = new Map();
+    const chunkTags = new Map();
+    for (const term of effectiveTerms) {
+        // One term may carry several chunk tags for the same archive; a match is
+        // still ONE term seen — counting entries instead of archives would let a
+        // single-term archive impersonate an every-term one.
+        const idsThisTerm = new Set();
+        for (const entry of tokenEntriesExpanded(index.tokens, term)) {
+            const at = entry.indexOf("@c");
+            const id = at === -1 ? entry : entry.slice(0, at);
+            idsThisTerm.add(id);
+            if (at !== -1) {
+                const tags = chunkTags.get(id) ?? new Set();
+                tags.add(Number(entry.slice(at + 2)));
+                chunkTags.set(id, tags);
+            }
+        }
+        for (const id of idsThisTerm)
+            counts.set(id, (counts.get(id) ?? 0) + 1);
+    }
+    const matches = [...counts.entries()].filter(([, hitCount]) => hitCount === effectiveTerms.length).map(([id]) => id);
+    const records = await listArchives(dataDir);
+    const hits = [];
+    for (const id of matches) {
+        // A matched id with no local record used to be dropped silently — which
+        // made a second machine of the vault blind to everything it had not
+        // archived itself, defeating the shared index entirely. The archive is
+        // self-carrying in the cloud (envelope sidecar + chunk objects), so the
+        // hit is reconstructed from there: phrase opens the sidecar, the sealed
+        // identity restores agent/path, and snippets fetch like any cold archive.
+        const record = records.find((item) => item.id === id) ?? await remoteOnlyRecord(dataDir, id, phrase);
+        if (!record || (options.agent && record.source.agent !== options.agent))
+            continue;
+        let snippets = [];
+        if (options.snippets !== false) {
+            snippets = await snippetsFor(dataDir, record, phrase, terms, chunkTags.get(id));
+        }
+        hits.push({ id: record.id, agent: record.source.agent, path: record.source.path, bytes: record.source.bytes, createdAt: record.createdAt, matched: "content", snippets });
+    }
+    return hits;
+}
+/**
+ * Reconstructs enough of an archive to search it, from the cloud alone: the
+ * managed chunk layout stores `<id>.envelope.vlmeta` beside the chunks, and
+ * that sidecar carries the envelope plus the sealed identity. Nothing is
+ * persisted — this is a read-time view for machines that never held the
+ * record. Managed accounts only; a vault with no cloud sign-in answers null
+ * and the hit stays dropped, exactly as before.
+ */
+async function remoteOnlyRecord(dataDir, id, phrase) {
+    try {
+        const { pullCiphertext, unframeObject } = await import("./cloud.js");
+        const { openIdentity } = await import("./chunk-store.js");
+        const { unwrapArchiveKey } = await import("../packages/vaultline-crypto/src/recipients.js");
+        const { ciphertext: sidecar } = await pullCiphertext(dataDir, `${id}.envelope.vlmeta`);
+        const { envelope, ciphertext: identityBlob } = unframeObject(sidecar);
+        if (!envelope)
+            return null;
+        const archiveKey = unwrapArchiveKey(envelope.wrappedKeys, envelope.suite, envelope.archiveId, { phrase });
+        let identity;
+        try {
+            identity = openIdentity(archiveKey, id, identityBlob);
+        }
+        finally {
+            archiveKey.fill(0);
+        }
+        const storedBytes = envelope.chunks.reduce((sum, chunk) => sum + chunk.storedBytes, 0);
+        return {
+            version: 2, id, createdAt: identity.createdAt,
+            source: { path: identity.sourcePath, agent: identity.agent, bytes: envelope.manifest.originalBytes ?? 0, sha256: envelope.manifest.originalSha256 ?? envelope.manifest.plaintextSha256 },
+            cipher: { algorithm: envelope.suite, ciphertextSha256: "", storedBytes, chunks: envelope.chunks.length },
+            envelope,
+            objectPath: join(dataDir, "never-materialised", `${id}.vlarchive`),
+            remote: {
+                provider: "vaultline", bucket: "vaultline-managed", objectKey: id,
+                bytes: storedBytes, checksum: "", verifiedAt: identity.createdAt,
+                layout: { kind: "chunks", chunkCount: envelope.chunks.length }
+            }
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Snippets, fetched as narrowly as the archive allows. A chunk-tagged hit on a
+ * chunk-independent archive reads ONLY the tagged chunks (padded one chunk
+ * each side, because a matching line can straddle a boundary): from the local
+ * blob when present, and through a ranged managed download when the local copy
+ * was offloaded — kilobytes over the wire against a cold 1.6 GB object.
+ * Anything else falls back to the whole-archive read it always was.
+ */
+async function snippetsFor(dataDir, record, phrase, terms, tagged) {
+    const lineMatches = (text) => text.split("\n").filter((line) => terms.every((term) => line.toLowerCase().includes(term))).slice(0, 3).map((line) => line.slice(0, 200));
+    if (tagged && tagged.size > 0 && isV2(record) && supportsChunkAccess(record.envelope)) {
+        try {
+            // Up to two SEPARATE small windows, one per tagged chunk, each padded a
+            // chunk either side. The old code built ONE window spanning from the
+            // lowest tag to the highest — tags at c3 and c350 fetched 349 chunks of
+            // a cold archive to show two snippet lines. Bounded now: ≤ 6 chunks,
+            // and a multi-term query costs the same as a single-term one.
+            const anchors = [...tagged].sort((a, b) => a - b).slice(0, 2);
+            const windows = [];
+            for (const anchor of anchors) {
+                const first = Math.max(0, anchor - 1);
+                const last = Math.min(record.envelope.chunks.length - 1, anchor + 1);
+                const previous = windows[windows.length - 1];
+                if (previous && first <= previous.last + 1)
+                    previous.last = Math.max(previous.last, last);
+                else
+                    windows.push({ first, last });
+            }
+            const { stat: statFile, readFile: readBlob } = await import("node:fs/promises");
+            const local = await statFile(record.objectPath).then((entry) => entry.isFile()).catch(() => false);
+            const found = [];
+            for (const { first, last } of windows) {
+                const window = {
+                    firstIndex: first, lastIndex: last,
+                    storedOffset: record.envelope.chunks.slice(0, first).reduce((sum, chunk) => sum + chunk.storedBytes, 0),
+                    storedLength: record.envelope.chunks.slice(first, last + 1).reduce((sum, chunk) => sum + chunk.storedBytes, 0),
+                    rawStartInWindow: 0,
+                    rawLengthInWindow: record.envelope.chunks.slice(first, last + 1).reduce((sum, chunk) => sum + (chunk.rawBytes ?? 0), 0)
+                };
+                let slice;
+                if (local) {
+                    const blob = await readBlob(record.objectPath);
+                    slice = blob.subarray(window.storedOffset, window.storedOffset + window.storedLength);
+                }
+                else if (record.remote?.provider === "vaultline" && record.remote.layout?.kind === "chunks") {
+                    // A chunk-folder copy IS the ranged read — and the window's chunks
+                    // fetch in PARALLEL, each read hash-checked by the account.
+                    const { managedChunkClient } = await import("./managed-chunks.js");
+                    const { chunkObjectName } = await import("./chunk-store.js");
+                    const managed = managedChunkClient(dataDir);
+                    const parts = await Promise.all(Array.from({ length: last - first + 1 }, (_, offsetIndex) => managed.getObject(`${record.remote.objectKey}/${chunkObjectName(first + offsetIndex)}`)));
+                    slice = Buffer.concat(parts);
+                }
+                else if (record.offloaded?.provider === "vaultline" || record.remote?.provider === "vaultline") {
+                    const { pullCiphertextRange, frameObject } = await import("./cloud.js");
+                    // A managed object is envelope-framed: the ciphertext starts after a
+                    // header whose size is knowable from the envelope in hand — frame it
+                    // over nothing and measure. Offsets in the window address the
+                    // ciphertext; the wire range must address the object.
+                    const frameHeaderBytes = frameObject(record.envelope, Buffer.alloc(0)).length;
+                    slice = await pullCiphertextRange(dataDir, record.id, frameHeaderBytes + window.storedOffset, window.storedLength);
+                }
+                else {
+                    throw new Error("no ranged path for this provider yet");
+                }
+                const raw = openChunkWindow(record.envelope, window, slice, { phrase });
+                found.push(...lineMatches(raw.toString("utf8")));
+                raw.fill(0);
+                if (found.length >= 3)
+                    break;
+            }
+            if (found.length > 0)
+                return found.slice(0, 3);
+            // A boundary case the padding did not cover — fall through to whole.
+        }
+        catch { /* ranged read unavailable — the whole path below still answers */ }
+    }
+    const { plaintext } = await decryptRecord(dataDir, record.id, phrase);
+    // Same string-ceiling discipline as the index build: scan line by line in
+    // windows, carrying the partial last line across the boundary.
+    const found = [];
+    const WINDOW = 8 * 1024 * 1024;
+    let carry = "";
+    for (let at = 0; at < plaintext.length && found.length < 3; at += WINDOW) {
+        const text = carry + plaintext.subarray(at, Math.min(plaintext.length, at + WINDOW)).toString("utf8");
+        const lines = text.split("\n");
+        carry = at + WINDOW < plaintext.length ? lines.pop() ?? "" : "";
+        for (const line of lines) {
+            if (terms.every((term) => line.toLowerCase().includes(term))) {
+                found.push(line.slice(0, 200));
+                if (found.length >= 3)
+                    break;
+            }
+        }
+    }
+    if (found.length < 3 && carry && terms.every((term) => carry.toLowerCase().includes(term)))
+        found.push(carry.slice(0, 200));
+    plaintext.fill(0);
+    return found;
+}
+export async function search(dataDir, query, options = {}) {
+    if ((options.mode ?? "metadata") === "metadata")
+        return searchMetadata(dataDir, query, options);
+    if (!options.phrase)
+        fail("recovery_phrase_missing", "Content search decrypts archives locally and needs the recovery phrase");
+    return searchContent(dataDir, query, options.phrase, options);
+}
+/**
+ * What the index covers, from the unsealed sidecar — no phrase required.
+ * "Missing" means sealed and durable yet not yet searchable, which is exactly
+ * the list `sealkeep index build` would work through.
+ */
+export async function indexCoverage(dataDir) {
+    const records = await listArchives(dataDir);
+    const coverage = await readFile(coveragePath(dataDir), "utf8")
+        .then((raw) => JSON.parse(raw))
+        .catch(() => null);
+    const indexedIds = new Set(coverage?.indexed ?? []);
+    const missing = records
+        .filter((record) => !indexedIds.has(record.id))
+        .map((record) => ({ id: record.id, path: record.source.path, agent: record.source.agent }));
+    const indexBytes = await import("node:fs/promises").then(({ stat }) => stat(indexPath(dataDir))).then((info) => info.size).catch(() => 0);
+    return {
+        total: records.length,
+        indexed: records.length - missing.length,
+        builtAt: coverage?.builtAt ?? null,
+        indexBytes,
+        missing
+    };
+}