sealkeep 0.5.0

package/dist/src/search.d.ts

@@ -0,0 +1,147 @@
+export type SearchMode = "metadata" | "content";
+type HitBase = {
+    id: string;
+    agent: string;
+    path: string;
+    bytes: number;
+    createdAt: string;
+};
+export type MetadataHit = HitBase & {
+    matched: "metadata";
+};
+export type ContentHit = HitBase & {
+    matched: "content";
+    snippets: string[];
+};
+export type SearchHit = MetadataHit | ContentHit;
+/**
+ * The on-disk content index.
+ *
+ * It stores only lowercased tokens mapped to archive ids: no transcript text, no
+ * line contents. Snippets are produced at query time by decrypting the matching
+ * archive, which already requires the recovery phrase.
+ */
+/**
+ * v2 entries may read "archiveId@c3": the token was seen inside chunk 3 of a
+ * chunk-independent archive. That one tag is what turns a search over cold
+ * 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".
+ */
+export type ContentIndex = {
+    version: 1 | 2;
+    builtAt: string;
+    archives: Record<string, string[]>;
+    tokens: Record<string, string[]>;
+};
+/**
+ * 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 declare function indexableToken(token: string): boolean;
+/**
+ * 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 declare function mergeChunkTokens(byChunk: ReadonlyMap<number, ReadonlySet<string>>, cap: number): Map<string, Set<number>>;
+/**
+ * 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 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[];
+/**
+ * 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 declare function tokenEntriesExpanded(tokens: Record<string, string[]>, term: string): string[];
+export declare function tokenize(text: 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;
+}): Promise<MetadataHit[]>;
+/**
+ * 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 declare function buildContentIndex(dataDir: string, rawPhrase: string, options?: {
+    sync?: boolean;
+}): Promise<{
+    archives: number;
+    tokens: number;
+    builtAt: string;
+    indexedNow: number;
+    skipped: number;
+    pulled: boolean;
+    pushed: 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
+ * 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 declare function indexArchiveTokens(dataDir: string, rawPhrase: string, record: {
+    id: string;
+    source: {
+        agent: string;
+        path: string;
+        bytes: number;
+    };
+}, tokensByChunk: ReadonlyMap<number, ReadonlySet<string>>, options?: {
+    sync?: boolean;
+}): Promise<{
+    pushed: boolean;
+}>;
+/**
+ * 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 declare function normalizeContentIndex(raw: unknown): ContentIndex;
+export declare function loadContentIndex(dataDir: string, rawPhrase: string): Promise<ContentIndex>;
+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?: {
+    agent?: string;
+    snippets?: boolean;
+}): Promise<SearchHit[]>;
+export declare function search(dataDir: string, query: string, options?: {
+    mode?: SearchMode;
+    phrase?: string;
+    agent?: 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.
+ */
+export declare function indexCoverage(dataDir: string): Promise<{
+    total: number;
+    indexed: number;
+    builtAt: string | null;
+    indexBytes: number;
+    missing: {
+        id: string;
+        path: string;
+        agent: string;
+    }[];
+}>;
+export {};