sealkeep 0.8.1 → 0.11.0

package/dist/src/search.d.ts

@@ -1,3 +1,10 @@
+import { x25519PrivateKeyFromRaw, type Envelope } from "../packages/sealkeep-crypto/src/index.js";
+import type { ArchiveRecord } from "./types.js";
+import type { FetchClient } from "./offload.js";
+import { type IndexPublicationCoverage } from "./index-publication-proof.js";
+import type { ManagedIndexReceipt, RemoteIndexStore } from "./index-sync.js";
+import { type SourceReference } from "./source-reader.js";
+export { backgroundCpuDelayMs } from "./background-cpu.js";
 export type SearchMode = "metadata" | "content";
 type HitBase = {
     id: string;
@@ -5,6 +12,7 @@ type HitBase = {
     path: string;
     bytes: number;
     createdAt: string;
+    project?: string | null;
 };
 export type MetadataHit = HitBase & {
     matched: "metadata";
@@ -12,6 +20,13 @@ export type MetadataHit = HitBase & {
 export type ContentHit = HitBase & {
     matched: "content";
     snippets: string[];
+    meta?: ArchiveMeta;
+    source?: SourceReference;
+    context?: {
+        source: SourceReference;
+        query: string;
+        chunkIndex?: number;
+    };
 };
 export type SearchHit = MetadataHit | ContentHit;
 /**
@@ -27,12 +42,137 @@ export type SearchHit = MetadataHit | ContentHit;
  * storage into a ranged fetch of a few chunks instead of a full restore.
  * Bare ids (v1, or legacy archives) still mean "somewhere in the archive".
  */
+/** What the index remembers ABOUT a session, beyond its words: when it ran,
+ * where it ran, which git commits landed inside that window, which files it
+ * touched. This is the layer git itself lacks — the index becomes the join
+ * table between commits (the what) and sessions (the why). */
+export type ArchiveMeta = {
+    startedAt?: string;
+    endedAt?: string;
+    /** Public archive creation time, retained as a total-order fallback when a
+     * transcript has no parseable session timestamps. */
+    archivedAt?: string;
+    cwd?: string;
+    commits?: Array<{
+        h: string;
+        s: string;
+    }>;
+    files?: string[];
+    /** Last concise agent-facing line, captured while the source still exists. */
+    summary?: string;
+    /**
+     * The non-secret record facts a fresh machine needs to move an already-sealed
+     * object without decrypting its transcript.  This lives inside the encrypted
+     * index, alongside path/project metadata, and deliberately excludes wrapped
+     * keys and provider credentials.  In particular, the delta pointer is kept:
+     * copying a delta head without its bases would create a destination that
+     * cannot restore the session.
+     */
+    archiveRecord?: ArchiveCatalogFacts;
+};
 export type ContentIndex = {
     version: 1 | 2;
+    extractionPolicy?: number;
     builtAt: string;
     archives: Record<string, string[]>;
     tokens: Record<string, string[]>;
+    meta?: Record<string, ArchiveMeta>;
+};
+export type ArchiveCatalogFacts = {
+    v: 1;
+    /** Authenticated sealed identity when the managed locator is an alias. */
+    envelopeArchiveId?: string;
+    /** Commits the entire envelope, including the raw-to-stored range map. */
+    envelopeSha256?: string;
+    /** Explicit authenticated owner-custody provenance; an alias alone grants none. */
+    teamCustody?: true;
+    createdAt: string;
+    sourceBytes: number;
+    sourceSha256: string;
+    storedBytes: number;
+    ciphertextSha256: string;
+    algorithm: string;
+    chunks: number;
+    delta?: {
+        baseArchiveId: string;
+        baseBytes: number;
+    };
+    supersedes?: {
+        archiveId: string;
+        bytes: number;
+    };
+};
+/** Facts suitable for the encrypted cross-machine catalog, never plaintext. */
+export declare function archiveCatalogFacts(record: ArchiveRecord): ArchiveCatalogFacts | null;
+/** Bump when transcript-derived text must be re-extracted, not merely merged. */
+export declare const INDEX_EXTRACTION_POLICY = 3;
+/**
+ * Remove only abandoned files from SealKeep's atomic index publications.
+ *
+ * Age alone is not enough for the sealed OWNED_INDEX_TEMP names below: a
+ * large live checkpoint can legitimately spend a long time writing, so a
+ * candidate must also be older than the corresponding committed generation.
+ * Keeping a full day of additional distance makes this safe across
+ * concurrent/manual builders and coarse filesystem timestamps. Unknown
+ * names, directories, and temps without a committed successor stay.
+ *
+ * The plaintext staging files (never sealed, so there is no "committed"
+ * counterpart to compare against) use a simpler, shorter age-only rule —
+ * see PLAINTEXT_STAGING_JSONL and SEGMENT_STAGING_*.
+ */
+export declare function cleanupStaleContentIndexTemps(dataDir: string): Promise<number>;
+export declare function writeArchiveTokenSidecar(dataDir: string, rawPhrase: string, archiveId: string, tokensByChunk: ReadonlyMap<number, ReadonlySet<string>>): Promise<string>;
+/** The archive's preserved seal-time tokens, or null when there is no usable sidecar. */
+export declare function readArchiveTokenSidecar(dataDir: string, rawPhrase: string, archiveId: string): Promise<Map<number, Set<string>> | null>;
+/**
+ * Registers one archive's chunk-tagged tokens in an in-memory index, replacing
+ * any previous entries for that id and applying the build's caps: bounded
+ * tokens per archive, two chunk tags per token. Shared by the seal-time merge
+ * and the catch-up's sidecar path so both produce the same entry.
+ */
+type IndexableRecordFacts = {
+    id: string;
+    version?: number;
+    createdAt?: string;
+    source: {
+        agent: string;
+        path: string;
+        bytes: number;
+        sha256?: string;
+        project?: string | null;
+        projectKey?: string | null;
+        projectScope?: string | null;
+    };
+    cipher?: {
+        algorithm: unknown;
+        ciphertextSha256: string;
+        storedBytes: number;
+        chunks?: number;
+    };
+    delta?: {
+        baseArchiveId: string;
+        baseBytes: number;
+    };
+    supersedes?: {
+        archiveId: string;
+        bytes: number;
+    };
 };
+export declare function applyArchiveTokens(index: ContentIndex, sealed: ArchiveRecord | IndexableRecordFacts, tokensByChunk: ReadonlyMap<number, ReadonlySet<string>>): void;
+/**
+ * Removes every project shard, without needing to know which projects exist.
+ *
+ * Called when the recipient list changes. A shard is sealed to the members a
+ * project had when it was written, so ANY change to that list makes every
+ * shard potentially stale — and the documented revocation path
+ * (`recipients remove` then `rewrap`) rebuilds neither. Leaving them was the
+ * whole defect: a revoked key kept opening a file no code ever revisited.
+ * Shards are derived data; the next `index build` writes them again.
+ */
+export declare function invalidateScopedShards(dataDir: string): Promise<void>;
+/** Cheap unsealed migration check; archive ids are already local metadata. */
+export declare function indexPublicationPending(dataDir: string): Promise<boolean>;
+export declare function contentIndexNeedsPolicyUpgrade(dataDir: string): Promise<boolean>;
 /**
  * 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
@@ -40,6 +180,20 @@ export type ContentIndex = {
  * long id simply misses content and falls to metadata search, which owns ids.
  */
 export declare function indexableToken(token: string): boolean;
+/**
+ * True only for raw historical context SealKeep itself injected or returned.
+ * The user's query and the agent's later reasoning remain new knowledge; the
+ * retrieved payload does not get indexed a second time as a new session.
+ */
+export declare function isRecalledMemoryLine(line: string): boolean;
+/** Keeps JSONL boundaries intact across archive/chunk windows. */
+export declare class RecalledMemoryFilter {
+    private carry;
+    private static readonly MAX_CARRY_CHARS;
+    private static readonly TAIL_CHARS;
+    push(text: string, final?: boolean): string;
+    finish(): string;
+}
 /**
  * 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
@@ -53,6 +207,22 @@ export declare function mergeChunkTokens(byChunk: ReadonlyMap<number, ReadonlySe
  * starves everything past the first chunk of a big archive ("retention"
  * indexed, "chunk" lost). Bounded so the phonebook stays a phonebook.
  */
+/**
+ * Collects a seal's index tokens as its plaintext streams past, one set per
+ * sealed chunk (a posting `<id>@c<n>` later quotes by ranged-reading that
+ * chunk alone), so the archive is searchable the moment the seal returns and
+ * nobody decrypts it again to index it. Filtered and budgeted at collection:
+ * junk (hex digests, base64 runs) never takes a slot, the budget scales with
+ * the archive — a flat 4000 starved everything past chunk zero of a 1.7 GB
+ * seal — and memory Sealkeep itself injected on an earlier turn is not
+ * indexed as if the person had said it. Windowed inside a chunk: a chunk is
+ * up to 64 MB, and tokenising that much in one call is what took the index
+ * build to the 4 GB heap limit. Shared by the cloud seal and the local one.
+ */
+export declare function createSealTokenCollector(totalBytes: number): {
+    onPlaintext: (chunkIndex: number, slice: Buffer) => void;
+    finish: (totalChunks: number) => Map<number, Set<string>>;
+};
 export declare function tokenCapFor(sourceBytes: number): number;
 /** Own-property-safe read: inherited names ("constructor", "toString") answer as absent. */
 export declare function tokenEntries(tokens: Record<string, string[]>, token: string): string[];
@@ -63,9 +233,13 @@ export declare function tokenEntries(tokens: Record<string, string[]>, token: st
  */
 export declare function tokenEntriesExpanded(tokens: Record<string, string[]>, term: string): string[];
 export declare function tokenize(text: string): string[];
+/** Terms search actually requires. Quoting opts out of conversational cleanup. */
+export declare function contentQueryTerms(query: string): string[];
 /** Metadata search needs no secret and never touches an archive's contents. */
 export declare function searchMetadata(dataDir: string, query: string, options?: {
     agent?: string;
+    archiveId?: string;
+    sessionId?: string;
 }): Promise<MetadataHit[]>;
 /**
  * Builds the opt-in content index.
@@ -76,6 +250,57 @@ export declare function searchMetadata(dataDir: string, query: string, options?:
  */
 export declare function buildContentIndex(dataDir: string, rawPhrase: string, options?: {
     sync?: boolean;
+    /** Cancellation belongs to the historical child that owns this build.
+     * It is propagated into remote scratch writes so a graceful stop removes
+     * its partial rather than abandoning archive-sized temporary data. */
+    signal?: AbortSignal;
+    /** Genuine archive/index work, used by the owning child process to reset
+     * its idle deadline. This is intentionally not a timer heartbeat. */
+    onActivity?: () => void;
+    onProgress?: (done: number, total: number, id: string) => void;
+    /** Dependency seam for provider/concurrency rehearsals; normal callers let
+     * Sealkeep resolve the configured remote store. */
+    /** Widened to the full `RemoteIndexStore` (rather than just meta/pull/push)
+     * so this same seam can carry a segments-capable store for segments-mode
+     * rehearsals; normal callers still let Sealkeep resolve it. */
+    remoteStore?: RemoteIndexStore | null;
+    /** Archive provider seam. Production resolves each record's stored copy;
+     * deterministic tests can supply the same bounded streaming contract. */
+    archiveClient?: FetchClient;
+    /** Scheduling seam used by the background builder and deterministic
+     * rehearsals. It does not add writers: lanes share one in-memory index and
+     * every checkpoint still passes through the same serialized promise. */
+    scheduling?: {
+        lanes?: number;
+        /** Fraction of one CPU core historical work may consume over time.
+         * Foreground/manual builds omit this; the daemon child uses 0.30. */
+        cpuTarget?: number;
+        cpuUsage?: typeof process.cpuUsage;
+        sleep?: (ms: number) => Promise<void>;
+        /** Current RSS guard for derived background work. */
+        maxRssBytes?: number;
+        rssBytes?: () => number;
+        /** Durable daemon-child generation whose private directory owns every
+         * derived index scratch file. Foreground builds omit it. */
+        scratchGeneration?: string;
+        checkpointEvery?: number;
+        checkpointAfterMs?: number;
+        checkpointLargeArchiveBytes?: number;
+        /** How long a compatibility archive may wait for the shared temporary
+         * workspace. Current chunk archives do not use that workspace at all. */
+        scratchWaitMs?: number;
+        /** Maximum time a remote index operation may make no observable progress. */
+        remoteIdleMs?: number;
+        /** Explicit background network ceiling. Foreground search omits it. */
+        backgroundTransferBytesPerSecond?: number;
+        now?: () => number;
+        /** Segments mode only, blob-fallback publish: publishFromSegments's
+         * guard against producing a cloud blob too large to hold in this
+         * build's memory. The background daemon child sets this; a foreground
+         * build omits it and always publishes. Unused when the store supports
+         * `segments` directly (publishSegments streams instead of merging). */
+        publishMaxTokens?: number;
+    };
 }): Promise<{
     archives: number;
     tokens: number;
@@ -85,6 +310,97 @@ export declare function buildContentIndex(dataDir: string, rawPhrase: string, op
     pulled: boolean;
     pushed: boolean;
 }>;
+/** Pure lookup for `sealkeep why <commit>`: which sessions carry this commit. */
+export declare function sessionsForCommit(index: ContentIndex, commitish: string): Array<{
+    id: string;
+    meta: ArchiveMeta;
+    subject: string;
+}>;
+/**
+ * Reads an index from bytes without ever holding it as ONE string.
+ *
+ * The write side learned this lesson first (see serializeIndex below), and the
+ * read side then hit the identical wall: a fully built 1,035-archive index
+ * decrypts to ~692 MB of JSON, and `.toString("utf8")` on that throws at V8's
+ * ~512 MB string ceiling — so the finished index sealed fine and could not be
+ * OPENED. Two formats live here:
+ *
+ *  - version 3 (what serializeIndex writes now): one small JSON document per
+ *    line — a meta line, then one line per archive, one per token. Parsing is
+ *    a linear walk splitting on newlines; no line is ever large.
+ *  - version 2 (what an existing vault may hold): one giant document. It is
+ *    walked byte-wise — strings tracked through their escapes, arrays through
+ *    their brackets — and each `"key":value` entry is parsed on its own.
+ */
+export declare function parseIndexBuffer(buffer: Buffer): ContentIndex;
+/**
+ * Posting lists are a result of concurrent work, not a clock. Give every
+ * dated archive an explicit chronological key and use input position only as
+ * the stable fallback for legacy entries with no metadata. Unknown entries
+ * sort before dated ones so a legacy posting cannot displace a known-current
+ * session from the newest-retention window.
+ */
+export declare function chronologicalPostings(entries: readonly string[], meta: Readonly<Record<string, ArchiveMeta>>): string[];
+/**
+ * Writes a checkpoint's plaintext JSONL without allocating a vault-sized
+ * Buffer. The allowed-id snapshot keeps coverage and ciphertext consistent
+ * even when a foreground build has several lanes finishing concurrently.
+ */
+export declare function writeContentIndexCheckpoint(path: string, index: ContentIndex, signal?: AbortSignal, onYield?: () => void | Promise<void>): Promise<ContentIndexCheckpoint["coverage"]>;
+export type ContentIndexCheckpoint = {
+    serialized: Buffer;
+    coverage: {
+        extractionPolicy: number;
+        builtAt: string;
+        indexed: string[];
+        publication: IndexPublicationCoverage;
+        effectivePostingCounts: Record<string, number>;
+        /** Where a lookup finds a token without reading the whole file; absent for in-memory snapshots. */
+        directory?: IndexDirectoryDraft;
+    };
+};
+/**
+ * Captures the sealed index bytes and their unsealed coverage description in
+ * one synchronous event-loop turn.
+ *
+ * Index builds use several lanes. A lane can finish another archive while a
+ * checkpoint is awaiting its temporary-file write. Reading `index` again
+ * after that await made coverage claim the newer archive was searchable even
+ * though the ciphertext had been serialized before it arrived. Keeping both
+ * products in this immutable checkpoint makes status describe exactly the
+ * bytes that were written, while the next checkpoint naturally includes any
+ * later archive.
+ */
+export declare function snapshotContentIndexCheckpoint(index: ContentIndex): ContentIndexCheckpoint;
+export declare function openVerifiedManagedIndex(envelope: Envelope, ciphertext: Buffer, opener: {
+    phrase: string;
+} | {
+    privateKey: ReturnType<typeof x25519PrivateKeyFromRaw>;
+}, advertisedCoverage: Readonly<Record<string, string>>): ContentIndex;
+/**
+ * Exported for the segmented index's blob fallback (src/index-publish.ts): a
+ * managed plane publishes through its CAS generation lane, so the legacy
+ * `meta`/`blob` objects it also exposes can be weeks stale. Anything asking
+ * "is there a newer account index?" must ask through here, or it reads an
+ * August envelope and concludes there is nothing to learn.
+ */
+export declare function pullRemoteIndexIfNewerVerified(dataDir: string, phrase: string, store: RemoteIndexStore, localBuiltAt: string | null, save: (envelope: Envelope, ciphertext: Buffer) => Promise<void>, options?: QueryIndexWorkOptions, reuseVerifiedAccountGeneration?: boolean): Promise<{
+    pulled: boolean;
+    remoteBuiltAt: string | null;
+}>;
+/**
+ * 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.
+ */
+export declare function persistContentIndex(dataDir: string, phrase: string, index: ContentIndex, store: RemoteIndexStore | null, options?: {
+    signal?: AbortSignal;
+    remoteIdleMs?: number;
+    maxBytesPerSecond?: number;
+    onYield?: () => void | Promise<void>;
+    scratchGeneration?: string;
+}): Promise<boolean>;
 /**
  * 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
@@ -94,13 +410,36 @@ export declare function buildContentIndex(dataDir: string, rawPhrase: string, op
  */
 export declare function indexArchiveTokens(dataDir: string, rawPhrase: string, record: {
     id: string;
+    version?: number;
+    createdAt?: string;
     source: {
         agent: string;
         path: string;
         bytes: number;
+        sha256?: string;
+        project?: string | null;
+        projectKey?: string | null;
+        projectScope?: string | null;
+    };
+    cipher?: {
+        algorithm: unknown;
+        ciphertextSha256: string;
+        storedBytes: number;
+        chunks: number;
+    };
+    delta?: {
+        baseArchiveId: string;
+        baseBytes: number;
+    };
+    supersedes?: {
+        archiveId: string;
+        bytes: number;
     };
 }, tokensByChunk: ReadonlyMap<number, ReadonlySet<string>>, options?: {
     sync?: boolean;
+    signal?: AbortSignal;
+    remoteIdleMs?: number;
+    maxBytesPerSecond?: number;
 }): Promise<{
     pushed: boolean;
 }>;
@@ -112,28 +451,244 @@ export declare function indexArchiveTokens(dataDir: string, rawPhrase: string, r
  * dropped here and simply re-indexed, which is what "incremental" owes its
  * caller anyway.
  */
-export declare function normalizeContentIndex(raw: unknown): ContentIndex;
-export declare function loadContentIndex(dataDir: string, rawPhrase: string): Promise<ContentIndex>;
+export declare function normalizeContentIndex(raw: unknown, options?: {
+    preserveCatalog?: boolean;
+}): ContentIndex;
+/** Advisory admission only: a persisted turn is never a publication receipt. */
+export declare function nextScopedPublication(dataDir: string, scopes: ReadonlyArray<{
+    key: string;
+    newestArchiveAt: string;
+    unpublishedArchiveAt?: string;
+}>, remaining: ReadonlySet<string>, signal?: AbortSignal): Promise<string | undefined>;
+export declare function refreshIndexFromRemote(dataDir: string, rawPhrase: string, options?: QueryIndexWorkOptions & {
+    renewCloudToken?: boolean;
+}): Promise<boolean>;
+export declare function loadReadableIndexes(dataDir: string, unlock: {
+    phrase: string;
+} | {
+    privateKey: string;
+}): Promise<ContentIndex>;
+/**
+ * The streaming-with-legacy-fallback core `loadContentIndex` reads its own
+ * fixed local slot through, factored out and parameterised on the envelope
+ * and ciphertext path instead: a caller decrypting somebody ELSE's sealed
+ * index (an account-index publication pulled to a temp file, never this
+ * vault's own `content-index.skindex`) gets the identical safe reader —
+ * stream first, fall back to the bounded legacy buffer parse — without
+ * pretending that file is this vault's local index (it is not cached here,
+ * and a failure is not this vault's own "rebuild your index" story).
+ */
+export declare function loadContentIndexFromFile(envelope: Envelope, ciphertextPath: string, phrase: string, options?: {
+    signal?: AbortSignal;
+    onYield?: () => void | Promise<void>;
+}): Promise<ContentIndex>;
+export declare function loadContentIndex(dataDir: string, rawPhrase: string, options?: {
+    signal?: AbortSignal;
+    onYield?: () => void | Promise<void>;
+}): Promise<ContentIndex>;
+export type QueryIndexWorkOptions = {
+    signal?: AbortSignal;
+    remoteIdleMs?: number;
+    maxBytesPerSecond?: number;
+    /**
+     * Default true: check the account's hosted index for a newer copy before
+     * answering. False answers from the local index as it is — the mode for
+     * prompt-time automatic recall, which must return in the moment before an
+     * agent's next tool call. The daemon's own sync lane keeps the local index
+     * fresh; re-pulling it inside every recall serialised the whole lane behind
+     * one network transfer, and no memory ever reached the agent in time.
+     */
+    refreshRemote?: boolean;
+    /**
+     * Bounded freshness for time-critical readers: try the hosted index for at
+     * most this many milliseconds, then answer from the local index regardless.
+     * Prompt-time automatic recall uses this — a teammate's memory pushed a
+     * moment ago still arrives when the check is quick, while a slot mid-catch-up
+     * can no longer hold every later request hostage. The caller's own signal
+     * still aborts the whole search; only the budget is absorbed.
+     */
+    refreshRemoteBudgetMs?: number;
+    /** Internal cooperative scheduling hook used only by daemon-owned work. */
+    onYield?: () => void | Promise<void>;
+    /** Reports transferred ciphertext bytes without exposing their contents. */
+    onProgress?: (bytes: number) => void;
+    /** Optional tighter checkpoint ceilings for one interactive context read. */
+    maxIndexBytes?: number;
+    maxIndexDecodedBytes?: number;
+    /** Reports every expanded index chunk, including on a decoded-cache hit. */
+    onIndexDecoded?: (bytes: number) => void;
+    /** Internal diagnostic: an actual full checkpoint decoder was started. */
+    onIndexDecodeStart?: () => void;
+    /** Source readers need immutable catalog facts, not query/session metadata. */
+    sourceFactsOnly?: boolean;
+    strictErrors?: boolean;
+};
+export type StreamedIndexInspection = {
+    extractionPolicy: number;
+    builtAt: string;
+    archiveRefs: string[];
+    coverageJson: IndexPublicationCoverage;
+    effectivePostingCounts: Record<string, number>;
+    /** Present only when query terms were requested. It contains every archive
+     * and metadata row but only token rows which that query can inspect. */
+    index?: ContentIndex;
+};
+/**
+ * Authenticates a managed CAS snapshot and recomputes its exact semantic
+ * coverage without materialising the expanded plaintext or complete token map.
+ */
+export declare function openVerifiedManagedIndexV3Streaming(envelope: Envelope, ciphertext: Buffer, opener: {
+    phrase: string;
+} | {
+    privateKey: ReturnType<typeof x25519PrivateKeyFromRaw>;
+}, advertisedCoverage: Readonly<Record<string, string>>, options?: QueryIndexWorkOptions & {
+    terms?: readonly string[];
+}): Promise<StreamedIndexInspection>;
+export declare function inspectLocalContentIndexCheckpoint(dataDir: string, rawPhrase: string, options?: QueryIndexWorkOptions): Promise<StreamedIndexInspection & {
+    envelope: Envelope;
+    ciphertextPath: string;
+}>;
+export type PublishLocalContentIndexCheckpointOptions = QueryIndexWorkOptions & {
+    /** Deterministic test seam. Production always resolves the account's managed store. */
+    store?: Pick<RemoteIndexStore, "cas">;
+};
+export type PublishedLocalContentIndexCheckpoint = {
+    status: "committed";
+    builtAt: string;
+    archiveRefs: number;
+    requirementsRecorded: number;
+    receipt: ManagedIndexReceipt;
+};
+/**
+ * Publish the already-committed local v3 checkpoint through managed immutable
+ * CAS without rebuilding it or retaining its token map.
+ *
+ * This deliberately is not a convergence writer: an upgrade process cannot
+ * merge a remote generation without constructing a new local checkpoint. It
+ * therefore accepts an empty head, or a head which is byte-for-byte this same
+ * local checkpoint, and refuses every other pre-existing head. Exact local
+ * archive requirements are durable before the first remote read/write; their
+ * receipts are installed only after `publishFile` has committed and verified
+ * both immutable objects by read-back.
+ */
+export declare function publishLocalContentIndexCheckpointToManagedCas(dataDir: string, rawPhrase: string, options?: PublishLocalContentIndexCheckpointOptions): Promise<PublishedLocalContentIndexCheckpoint>;
+/**
+ * Parses ONLY what a query needs from the sealed index buffer, streaming.
+ *
+ * Every archive and meta line is kept — a few thousand, small. Of the token
+ * lines, only those a query term hits are materialised: the exact token always,
+ * plus the first `QUERY_PREFIX_KEEP` prefix forms per term. The result is an
+ * index with a dozen token entries instead of a million, which `searchContent`
+ * then queries exactly as it would the full one — same maps, same shape.
+ */
+export declare function parseIndexForQuery(buffer: Buffer, terms: string[]): ContentIndex;
+type IndexDirectoryDraft = {
+    stride: number;
+    regions: {
+        archives: [number, number];
+        tokens: [number, number];
+        meta: [number, number];
+    };
+    entries: Array<[string, number]>;
+};
+export declare function loadContentIndexForQuery(dataDir: string, rawPhrase: string, terms: string[], options?: QueryIndexWorkOptions): Promise<ContentIndex>;
+/**
+ * An ordinary authenticated search can lend its compact source catalog to a
+ * following bounded context read. A warm hit decodes zero index bytes. Cold
+ * reads retain the caller's original encrypted/expanded ceilings; this is not
+ * permission to download or expand a larger global index for one citation.
+ */
+export declare function loadPersonalSourceFacts(dataDir: string, rawPhrase: string, options?: QueryIndexWorkOptions): Promise<ContentIndex>;
+/**
+ * Merge one remotely opened shard through a second, plaintext scope gate.
+ *
+ * Membership controls whether the object may be downloaded and its recipient
+ * wrap controls whether it may be opened. The embedded project line is checked
+ * as well: a stale or incorrectly published shard must never make a record from
+ * another project visible merely because its postings share the same object.
+ */
+export declare function mergeTeamProjectShard(target: ContentIndex, incoming: ContentIndex, project: string, spaceKey: string, origins: Map<string, string>, projectKey?: string): void;
+/** Pull and open exactly the shard belonging to the requested bound project. */
+export declare function pullBoundTeamProjectIndex(dataDir: string, phrase: string, project: string, terms: string[], projectKey?: string, options?: QueryIndexWorkOptions): Promise<{
+    index: ContentIndex;
+    spaceKey: string;
+    membershipVersion: number;
+    indexDecodedBytes: number;
+    readGuard: import("./cloud.js").TeamReadGuard;
+} | null>;
+export type ProjectMemory = {
+    id: string;
+    agent: string;
+    path: string;
+    at: string;
+    summary?: string;
+    commits?: Array<{
+        h: string;
+        s: string;
+    }>;
+    files?: string[];
+};
+/**
+ * The newest memories of one project, without a query and without expanding
+ * the token map. Used by lifecycle hooks before the user's first prompt has
+ * supplied search terms. A second machine first pulls a fresher sealed index;
+ * parsing with an empty term list retains only archive/meta lines, so even a
+ * million-token vault stays bounded.
+ */
+export declare function recentProjectMemories(dataDir: string, rawPhrase: string, project: string, limit?: number, projectKey?: string, options?: QueryIndexWorkOptions): Promise<ProjectMemory[]>;
+/**
+ * Removes the content index — all of it.
+ *
+ * This used to delete the sealed index and its envelope and leave two things
+ * behind: the unsealed coverage sidecar, and (since sharding) every project
+ * shard. The sidecar is what `index status` reads, so dropping the index left
+ * the product cheerfully reporting the archives as searchable when nothing
+ * could search them — the worst kind of wrong, because it is reassuring. The
+ * shards were worse: sealed slices of the index still readable by project
+ * members, surviving a command whose entire job is to remove the index.
+ */
 export declare function dropContentIndex(dataDir: string): Promise<void>;
 /**
  * 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 declare function searchContent(dataDir: string, query: string, rawPhrase: string, options?: {
+export declare function searchContent(dataDir: string, query: string, rawPhrase: string, options?: QueryIndexWorkOptions & {
     agent?: string;
     snippets?: boolean;
+    snippetLimit?: number;
+    quoteLocalFirst?: boolean;
+    project?: string;
+    projectKey?: string;
+    archiveId?: string;
+    sessionId?: string;
 }): Promise<SearchHit[]>;
 export declare function search(dataDir: string, query: string, options?: {
     mode?: SearchMode;
     phrase?: string;
     agent?: string;
+    project?: string;
+    projectKey?: string;
+    archiveId?: string;
+    sessionId?: string;
 }): Promise<SearchHit[]>;
 /**
- * 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.
+ * What the index covers.
+ *
+ * `total`/`indexed`/`missing` describe THIS machine's own archives, from the
+ * unsealed sidecar, so they need no phrase. That was once the whole answer,
+ * and on a team it was a confidently wrong one: a colleague's laptop holds no
+ * local record of anything the others sealed, so it reported "0 of 0 archives
+ * searchable" for an account full of history it could in fact search. An
+ * admin checking whether the team's memory was indexed got a zero that meant
+ * "I did not look", printed as though it meant "there is nothing".
+ *
+ * So when a phrase is offered, the shared index is opened and the corpus is
+ * reported too. Left null when no phrase is given or no index exists —
+ * unknown, said plainly, rather than a number that reads as none.
  */
-export declare function indexCoverage(dataDir: string): Promise<{
+export declare function indexCoverage(dataDir: string, options?: {
+    phrase?: string;
+}): Promise<{
     total: number;
     indexed: number;
     builtAt: string | null;
@@ -143,5 +698,8 @@ export declare function indexCoverage(dataDir: string): Promise<{
         path: string;
         agent: string;
     }[];
+    /** Every distinct archive the index can answer for, this machine's and other machines'. */
+    searchable: number | null;
+    /** Of those, how many this machine never sealed — the team's, pulled in as ciphertext. */
+    fromOtherMachines: number | null;
 }>;
-export {};