@superbee/core 0.2.0-pre.3 → 0.2.0-pre.30

package/dist/remote-parsers.js

@@ -0,0 +1,181 @@
+/**
+ * The client side of the wire's heads and snapshot grammar (`docs/WIRE-PROTOCOL.md`, "Heads and
+ * snapshot"): what a heads answer must carry before its rows may be diffed as deletions, and
+ * how a snapshot body is read so that iterating it to completion is the completeness signal.
+ * {@link RemoteBackend.heads} and {@link RemoteBackend.snapshot} are thin callers over these
+ * two functions; a host that serves the same grammar through routes of its own validates the
+ * answers with the same functions rather than a second parser, since this grammar decides what
+ * a working copy deletes locally.
+ *
+ * Only `TextDecoder` and the Web Streams reader are used, so the same code runs in a browser, a
+ * Worker, and Node.
+ */
+import { headsDigest, isHeadsDigest } from "./heads-digest.js";
+import { RemoteError, malformed } from "./remote-error.js";
+/** A snapshot body that ended, or failed, before its terminator arrived with the announced count. */
+export const SNAPSHOT_TRUNCATED = "SNAPSHOT_TRUNCATED";
+/**
+ * A snapshot whose body arrived whole, with its terminator and the announced count, but whose
+ * rows digest to something other than the header announced. Not truncation: re-requesting will
+ * not necessarily repair it, since the authority contradicted itself. A consumer discards the
+ * documents' claim to the header digest either way.
+ */
+export const SNAPSHOT_DIGEST_MISMATCH = "SNAPSHOT_DIGEST_MISMATCH";
+function isDocumentHead(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const head = value;
+    return typeof head.id === "string" && typeof head.version === "string";
+}
+/**
+ * The `200` body of `GET /heads`, admitted or refused as one: a well-formed digest, a `heads`
+ * array of `{ id, version }` rows, a `count` equal to the number of rows, and rows that digest
+ * by the documented recipe to the digest served. Anything else rejects as malformed (a
+ * {@link MalformedAnswer}, code `MALFORMED_ANSWER`) rather than being trusted. The
+ * recomputation is what stops a listing that is whole by its own count but not the state its
+ * digest names (a shortened listing under the real digest) from being diffed as a mass
+ * deletion. Rows keep the order served: the recipe sorts for itself, so order does not decide
+ * admission.
+ */
+export function parseHeadsAnswer(payload) {
+    const answer = payload;
+    if (!isHeadsDigest(answer?.digest))
+        throw malformed("wire heads answered without a well-formed digest");
+    if (!Array.isArray(answer.heads) || !answer.heads.every(isDocumentHead)) {
+        throw malformed("wire heads answered without a heads array of { id, version } rows");
+    }
+    if (answer.count !== answer.heads.length) {
+        throw malformed(`wire heads count ${String(answer.count)} disagrees with its ${answer.heads.length} row(s)`);
+    }
+    const heads = answer.heads.map(({ id, version }) => ({ id, version }));
+    const recomputed = headsDigest(heads);
+    if (recomputed !== answer.digest) {
+        throw malformed(`wire heads served digest ${answer.digest}, but its ${heads.length} row(s) digest to ${recomputed}`);
+    }
+    return { digest: answer.digest, heads };
+}
+/**
+ * Split a response body into its NDJSON lines as they arrive, decoding UTF-8 across chunk
+ * boundaries. A partial trailing line at the end of the body is a cut line and is not yielded; a
+ * transport failure while reading is reported as truncation, since either way the terminator
+ * never arrived. Leaving the loop early cancels the reader so the connection is released.
+ */
+async function* ndjsonLines(body, status) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffered = "";
+    try {
+        for (;;) {
+            let chunk;
+            try {
+                chunk = await reader.read();
+            }
+            catch (cause) {
+                throw new RemoteError("snapshot body failed before its end line arrived", SNAPSHOT_TRUNCATED, status, cause);
+            }
+            buffered += decoder.decode(chunk.value, { stream: !chunk.done });
+            let start = 0;
+            for (let newline = buffered.indexOf("\n"); newline !== -1; newline = buffered.indexOf("\n", start)) {
+                yield buffered.slice(start, newline);
+                start = newline + 1;
+            }
+            buffered = buffered.slice(start);
+            if (chunk.done)
+                return;
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+    }
+}
+function parseSnapshotLine(line) {
+    let record;
+    try {
+        record = JSON.parse(line);
+    }
+    catch {
+        throw malformed("snapshot line is not JSON");
+    }
+    if (typeof record !== "object" || record === null)
+        throw malformed("snapshot line is not a JSON object");
+    return record;
+}
+function parseSnapshotHeader(line) {
+    const record = parseSnapshotLine(line);
+    if (record.kind !== "snapshot")
+        throw malformed("snapshot did not begin with its header line");
+    if (typeof record.count !== "number" || !Number.isInteger(record.count) || record.count < 0) {
+        throw malformed("snapshot header carries no document count");
+    }
+    if (!isHeadsDigest(record.digest))
+        throw malformed("snapshot header carries no well-formed digest");
+    return { count: record.count, digest: record.digest };
+}
+/**
+ * The document lines of a snapshot, ending normally only at an `end` line whose count equals
+ * both the header's announcement and the documents actually seen, and only when the digest
+ * recomputed over the received heads equals the header's. Anything else is a rejection: a body
+ * that ends first is `SNAPSHOT_TRUNCATED`; a whole body whose heads digest differently is
+ * `SNAPSHOT_DIGEST_MISMATCH`; a line the contract does not admit is malformed. The digest is the
+ * client's own check of the listing it is about to trust: a count and a terminator say the body
+ * is whole, only the recipe says it is the state the header named.
+ */
+async function* snapshotDocuments(lines, header, status) {
+    let seen = 0;
+    const received = [];
+    for await (const line of lines) {
+        const record = parseSnapshotLine(line);
+        if (record.kind === "doc") {
+            if (typeof record.id !== "string" || typeof record.version !== "string" || typeof record.body !== "string") {
+                throw malformed("snapshot doc line lacks id, version, or body");
+            }
+            if (typeof record.frontmatter !== "object" || record.frontmatter === null || Array.isArray(record.frontmatter)) {
+                throw malformed("snapshot doc line lacks a frontmatter object");
+            }
+            seen += 1;
+            if (seen > header.count)
+                throw malformed(`snapshot delivered more than the ${header.count} announced document(s)`);
+            received.push({ id: record.id, version: record.version });
+            yield { id: record.id, version: record.version, frontmatter: record.frontmatter, body: record.body };
+            continue;
+        }
+        if (record.kind === "end") {
+            if (record.count !== seen || seen !== header.count) {
+                throw new RemoteError(`snapshot end line counts ${String(record.count)} document(s), but ${seen} of ${header.count} announced arrived`, SNAPSHOT_TRUNCATED, status);
+            }
+            const recomputed = headsDigest(received);
+            if (recomputed !== header.digest) {
+                throw new RemoteError(`snapshot header announced digest ${header.digest}, but its ${seen} document(s) digest to ${recomputed}`, SNAPSHOT_DIGEST_MISMATCH, status);
+            }
+            return;
+        }
+        throw malformed(`snapshot line has unexpected kind ${JSON.stringify(record.kind)}`);
+    }
+    throw new RemoteError(`snapshot ended after ${seen} of ${header.count} document(s) without its end line`, SNAPSHOT_TRUNCATED, status);
+}
+/**
+ * Read a `GET /snapshot` body by the documented grammar. The header line is parsed before this
+ * resolves, so a body that ends before it rejects here with `SNAPSHOT_TRUNCATED` and a first
+ * line that is not the header rejects as malformed; the documents then stream through
+ * {@link RemoteSnapshot.docs}, which ends normally only for a whole body whose rows digest to
+ * the header's announcement (see {@link RemoteSnapshot}). Obtaining the response, checking its
+ * status, and re-requesting a truncated snapshot are the caller's: this function reads one body
+ * once and cancels the reader when the iteration is abandoned or fails.
+ */
+export async function readSnapshotStream(body, options = {}) {
+    const status = options.status ?? 200;
+    const lines = ndjsonLines(body, status);
+    const first = await lines.next();
+    if (first.done)
+        throw new RemoteError("snapshot ended before its header line", SNAPSHOT_TRUNCATED, status);
+    let header;
+    try {
+        header = parseSnapshotHeader(first.value);
+    }
+    catch (err) {
+        await lines.return(undefined);
+        throw err;
+    }
+    return { header, docs: snapshotDocuments(lines, header, status) };
+}
+//# sourceMappingURL=remote-parsers.js.map

package/dist/remote-parsers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-parsers.js","sourceRoot":"","sources":["../src/remote-parsers.ts"],"names":[],"mappings":"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"}

package/dist/remote.d.ts

@@ -1,6 +1,9 @@
 /** Browser-safe client adapter for the Superbee wire protocol. */
-export { RemoteBackend, RemoteError } from "./remote-backend.js";
-export type { FetchLike, HeadsOptions, HeadsResult, RemoteBackendOptions, RemoteSnapshot, SnapshotDocument, SnapshotHeader, WireCapabilities, } from "./remote-backend.js";
+export { RemoteBackend } from "./remote-backend.js";
+export type { FetchLike, HeadsOptions, RemoteBackendOptions, WireCapabilities } from "./remote-backend.js";
+export { RemoteError } from "./remote-error.js";
+export { SNAPSHOT_DIGEST_MISMATCH, SNAPSHOT_TRUNCATED, parseHeadsAnswer, readSnapshotStream } from "./remote-parsers.js";
+export type { HeadsResult, ReadSnapshotStreamOptions, RemoteSnapshot, SnapshotDocument, SnapshotHeader } from "./remote-parsers.js";
 export { headsDigest, isHeadsDigest, sortHeads } from "./heads-digest.js";
 export type { DocumentHead } from "./heads-digest.js";
 //# sourceMappingURL=remote.d.ts.map

package/dist/remote.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remote.d.ts","sourceRoot":"","sources":["../src/remote.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAElE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACjE,YAAY,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC1E,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"remote.d.ts","sourceRoot":"","sources":["../src/remote.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAElE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC3G,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzH,YAAY,EAAE,WAAW,EAAE,yBAAyB,EAAE,cAAc,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACpI,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC1E,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/remote.js

@@ -1,4 +1,8 @@
 /** Browser-safe client adapter for the Superbee wire protocol. */
-export { RemoteBackend, RemoteError } from "./remote-backend.js";
+export { RemoteBackend } from "./remote-backend.js";
+export { RemoteError } from "./remote-error.js";
+// The heads and snapshot grammar's reference validators, for a host that serves the same grammar
+// through routes of its own; `RemoteBackend.heads` and `RemoteBackend.snapshot` call these.
+export { SNAPSHOT_DIGEST_MISMATCH, SNAPSHOT_TRUNCATED, parseHeadsAnswer, readSnapshotStream } from "./remote-parsers.js";
 export { headsDigest, isHeadsDigest, sortHeads } from "./heads-digest.js";
 //# sourceMappingURL=remote.js.map

package/dist/remote.js.map

@@ -1 +1 @@
-{"version":3,"file":"remote.js","sourceRoot":"","sources":["../src/remote.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAElE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAWjE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"remote.js","sourceRoot":"","sources":["../src/remote.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAElE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,iGAAiG;AACjG,4FAA4F;AAC5F,OAAO,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzH,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/search/backend-source.d.ts

@@ -0,0 +1,6 @@
+import type { StorageBackend } from "../types.js";
+import { type MemorySearchSourceOptionsV1, type MemorySearchSourceV1 } from "./memory-source.js";
+/** Read a complete backend corpus in bounded batches. Failed reads refuse the whole search;
+ * the cursor key describes the versions actually read, including unsent working-copy edits. */
+export declare function searchSourceFromBackend(backend: StorageBackend, options?: Omit<MemorySearchSourceOptionsV1, "key">): Promise<MemorySearchSourceV1>;
+//# sourceMappingURL=backend-source.d.ts.map

package/dist/search/backend-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-source.d.ts","sourceRoot":"","sources":["../../src/search/backend-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,EAA0C,KAAK,2BAA2B,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAKzI;+FAC+F;AAC/F,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,cAAc,EACvB,OAAO,GAAE,IAAI,CAAC,2BAA2B,EAAE,KAAK,CAAM,GACrD,OAAO,CAAC,oBAAoB,CAAC,CAqB/B"}

package/dist/search/backend-source.js

@@ -0,0 +1,33 @@
+import { headsDigest } from "../heads-digest.js";
+import { memorySearchSource, memorySearchBounds } from "./memory-source.js";
+import { SearchLimitError, stopIfAsked } from "./errors.js";
+import { documentSourceBytes } from "./row-text.js";
+/** Read a complete backend corpus in bounded batches. Failed reads refuse the whole search;
+ * the cursor key describes the versions actually read, including unsent working-copy edits. */
+export async function searchSourceFromBackend(backend, options = {}) {
+    const { maxDocuments, maxSourceBytes } = memorySearchBounds(options);
+    stopIfAsked(options.stop);
+    const ids = await backend.list();
+    if (ids.length > maxDocuments.max)
+        throw new SearchLimitError(maxDocuments.name, maxDocuments.max, ids.length);
+    const documents = [];
+    let sourceBytes = 0;
+    for (let start = 0; start < ids.length; start += 128) {
+        stopIfAsked(options.stop);
+        const batch = ids.slice(start, start + 128);
+        const results = await backend.readMany(batch);
+        if (results.length !== batch.length)
+            throw new TypeError("Search backend returned an incomplete batch.");
+        for (const [index, { doc, version }] of results.entries()) {
+            if (doc.id !== batch[index])
+                throw new TypeError("Search backend returned a different document identity.");
+            const document = { ...doc, version };
+            sourceBytes += documentSourceBytes(document);
+            if (sourceBytes > maxSourceBytes.max)
+                throw new SearchLimitError(maxSourceBytes.name, maxSourceBytes.max, sourceBytes);
+            documents.push(document);
+        }
+    }
+    return memorySearchSource(documents, { ...options, key: headsDigest(documents) });
+}
+//# sourceMappingURL=backend-source.js.map

package/dist/search/backend-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-source.js","sourceRoot":"","sources":["../../src/search/backend-source.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAA+D,MAAM,oBAAoB,CAAC;AACzI,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAGpD;+FAC+F;AAC/F,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,OAAuB,EACvB,UAAoD,EAAE;IAEtD,MAAM,EAAE,YAAY,EAAE,cAAc,EAAE,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACrE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC;IACjC,IAAI,GAAG,CAAC,MAAM,GAAG,YAAY,CAAC,GAAG;QAAE,MAAM,IAAI,gBAAgB,CAAC,YAAY,CAAC,IAAI,EAAE,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC/G,MAAM,SAAS,GAAuB,EAAE,CAAC;IACzC,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,IAAI,GAAG,EAAE,CAAC;QACrD,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC1B,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,GAAG,CAAC,CAAC;QAC5C,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC9C,IAAI,OAAO,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM;YAAE,MAAM,IAAI,SAAS,CAAC,8CAA8C,CAAC,CAAC;QACzG,KAAK,MAAM,CAAC,KAAK,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;YAC1D,IAAI,GAAG,CAAC,EAAE,KAAK,KAAK,CAAC,KAAK,CAAC;gBAAE,MAAM,IAAI,SAAS,CAAC,wDAAwD,CAAC,CAAC;YAC3G,MAAM,QAAQ,GAAG,EAAE,GAAG,GAAG,EAAE,OAAO,EAAE,CAAC;YACrC,WAAW,IAAI,mBAAmB,CAAC,QAAQ,CAAC,CAAC;YAC7C,IAAI,WAAW,GAAG,cAAc,CAAC,GAAG;gBAAE,MAAM,IAAI,gBAAgB,CAAC,cAAc,CAAC,IAAI,EAAE,cAAc,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;YACvH,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IACD,OAAO,kBAAkB,CAAC,SAAS,EAAE,EAAE,GAAG,OAAO,EAAE,GAAG,EAAE,WAAW,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;AACpF,CAAC"}

package/dist/search/contract.d.ts

@@ -0,0 +1,151 @@
+/**
+ * The `documents.search.v1` contract: its constants, request and result types, and the frontmatter
+ * fields a search reads. Ranking and index limits are portal-webmcp 0.3.1's (algorithm
+ * `portal-webmcp-search/v1`, a long document indexed whole up to 65,536 body terms); the request
+ * limits are this contract's.
+ */
+export declare const SEARCH_OPERATION_ID = "documents.search.v1";
+/** The ranking algorithm, shared with portal-webmcp 0.3.1's `superbee_search_documents`. */
+export declare const SEARCH_ALGORITHM = "portal-webmcp-search/v1";
+/** Bumped whenever normalize, tokenize or searchRowText change what a document contributes to an
+ * index; the row-text golden (`test/fixtures/search-row-text-v<revision>.json`) pins it. */
+export declare const SEARCH_TEXT_REVISION = 1;
+/** Largest answer, as JSON. A page of long hits can exceed it before 50 hits: the page then ends
+ * early with a cursor at the cut. */
+export declare const SEARCH_MAX_OUTPUT_BYTES: number;
+export declare const SEARCH_LIMITS: Readonly<{
+    /** Largest query, UTF-8 bytes. */
+    readonly maxQueryBytes: 1024;
+    /** Distinct normalized query terms. */
+    readonly maxQueryTerms: 16;
+    readonly defaultRows: 10;
+    readonly maxRows: 50;
+    /** Excerpt length, UTF-8 bytes. */
+    readonly excerptBytes: 512;
+    /** Largest exact `type` or `tag` filter, UTF-8 bytes (the kernel query's filter bound). */
+    readonly maxFilterBytes: 256;
+    /** Largest id `prefix` filter, UTF-8 bytes (a document id's bound). */
+    readonly maxPrefixBytes: 512;
+    /** Largest cursor, UTF-8 bytes. */
+    readonly maxCursorBytes: 2048;
+    /** Values per facet, most frequent first. */
+    readonly maxFacetValues: 50;
+    readonly maxIndexDocuments: 20000;
+    readonly maxIndexSourceBytes: 67108864;
+    /** portal-webmcp's V1 value: a long document is indexed whole, never truncated; one over it is
+     * left out of the index and counted as skipped. */
+    readonly maxTermsPerDocument: 65536;
+    /** The default and ceiling of `searchDocuments`' `maxEvidenceInstances`: the most capped term
+     * instances a request's terms may hold across a corpus before it is refused as too broad. */
+    readonly maxEvidenceInstances: 400000;
+}>;
+/** Body occurrences of one distinct query term that can still add score. */
+export declare const BODY_OCCURRENCE_CAP = 20;
+/** Bytes an excerpt may reach behind its first body match before the match starts. */
+export declare const EXCERPT_LEAD_BYTES = 256;
+/** Documents processed between cancellation checks. */
+export declare const SIGNAL_INTERVAL = 128;
+export declare const SEARCH_MATCHES: readonly ["auto", "all", "any"];
+export type SearchMatchV1 = (typeof SEARCH_MATCHES)[number];
+export type SearchMatchModeV1 = "all" | "any";
+export declare const SEARCH_FACETS: readonly ["type", "tags"];
+export type SearchFacetV1 = (typeof SEARCH_FACETS)[number];
+export declare const SEARCH_MATCH_FIELDS: readonly ["title", "type", "tag", "description", "id", "body"];
+export type SearchMatchFieldV1 = (typeof SEARCH_MATCH_FIELDS)[number];
+export declare const SEARCH_GUIDANCE: Readonly<{
+    all: "No document contains every query term. Retry with match \"any\", fewer terms, or different exact filters.";
+    any: "No document contains any searchable query term. Try domain-specific keywords or remove exact type and tag filters.";
+    /** The refusal of a request whose terms occur too often to rank (`maxEvidenceInstances`). */
+    broad: "The query's terms occur too often in this corpus to rank. Retry with fewer or more specific terms.";
+}>;
+/** One document of a search corpus: a read model row, or a working copy's head and body. */
+export interface SearchDocumentV1 {
+    readonly id: string;
+    readonly version: string;
+    readonly frontmatter: Readonly<Record<string, unknown>>;
+    readonly body: string;
+}
+/** Cancellation for a long build or ranking: a signal, a host check that throws, or both. */
+export interface SearchStopV1 {
+    readonly signal?: AbortSignal;
+    /** Called every SIGNAL_INTERVAL documents; throws to stop (for example a deadline). */
+    readonly check?: () => void;
+}
+/** The exact filters a source applies before it answers evidence. */
+export interface SearchFiltersV1 {
+    readonly type?: string;
+    readonly tag?: string;
+    /** Leading characters of the document id. */
+    readonly prefix?: string;
+}
+export interface SearchRequestV1 {
+    /** Free text, at most 1 KiB and 16 distinct terms after normalization. */
+    readonly query: string;
+    /** `auto` (default): every term, then any term without conversational words when nothing matched. */
+    readonly match?: SearchMatchV1;
+    /** Exact frontmatter `type`. */
+    readonly type?: string;
+    /** Exact declared tag. */
+    readonly tag?: string;
+    /** Leading characters of the document id, at most 512 bytes. */
+    readonly prefix?: string;
+    /** Hits per page, 1 to 50; default 10. */
+    readonly limit?: number;
+    /** A previous answer's `nextCursor`, for the same corpus, query, match and filters. */
+    readonly cursor?: string;
+    /** Value counts over every hit (not only this page), most frequent first, at most 50 each. */
+    readonly facets?: readonly SearchFacetV1[];
+}
+export interface SearchHitV1 {
+    readonly id: string;
+    readonly version: string;
+    readonly title?: string;
+    readonly type?: string;
+    readonly tags: readonly string[];
+    readonly score: number;
+    readonly matchedTerms: readonly {
+        readonly term: string;
+        readonly fields: readonly SearchMatchFieldV1[];
+    }[];
+    /** At most SEARCH_LIMITS.excerptBytes UTF-8 bytes: the body around the first match, else the description. */
+    readonly excerpt: string;
+}
+export interface SearchFacetValueV1 {
+    readonly value: string;
+    readonly count: number;
+}
+export interface SearchResultV1 {
+    readonly hits: readonly SearchHitV1[];
+    readonly query: {
+        readonly requestedMatch: SearchMatchV1;
+        readonly effectiveMatch: SearchMatchModeV1;
+        readonly fallbackUsed: boolean;
+        /** The terms matched: normalized, deduplicated, and without ignoredTerms after a fallback. */
+        readonly terms: readonly string[];
+        /** Conversational terms the fallback left out; absent when none were. */
+        readonly ignoredTerms?: readonly string[];
+    };
+    /** Hits across every page. */
+    readonly total: number;
+    readonly facets?: {
+        readonly type?: readonly SearchFacetValueV1[];
+        readonly tags?: readonly SearchFacetValueV1[];
+    };
+    readonly nextCursor?: string;
+    /** What was searched: every document, those indexed (reindexPending included), those the index
+     * cannot hold, and indexed rows awaiting re-derivation. */
+    readonly corpus: {
+        readonly documents: number;
+        readonly indexed: number;
+        readonly skipped: number;
+        readonly reindexPending: number;
+    };
+    /** Fixed advice when nothing matched. */
+    readonly guidance?: string;
+}
+export declare function documentTitle(document: SearchDocumentV1): string | undefined;
+export declare function documentType(document: SearchDocumentV1): string | undefined;
+export declare function documentDescription(document: SearchDocumentV1): string | undefined;
+/** Declared string tags only; a non-array or non-string member contributes nothing. */
+export declare function documentTags(document: SearchDocumentV1): readonly string[];
+//# sourceMappingURL=contract.d.ts.map

package/dist/search/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/search/contract.ts"],"names":[],"mappings":"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"}

package/dist/search/contract.js

@@ -0,0 +1,78 @@
+/**
+ * The `documents.search.v1` contract: its constants, request and result types, and the frontmatter
+ * fields a search reads. Ranking and index limits are portal-webmcp 0.3.1's (algorithm
+ * `portal-webmcp-search/v1`, a long document indexed whole up to 65,536 body terms); the request
+ * limits are this contract's.
+ */
+export const SEARCH_OPERATION_ID = "documents.search.v1";
+/** The ranking algorithm, shared with portal-webmcp 0.3.1's `superbee_search_documents`. */
+export const SEARCH_ALGORITHM = "portal-webmcp-search/v1";
+/** Bumped whenever normalize, tokenize or searchRowText change what a document contributes to an
+ * index; the row-text golden (`test/fixtures/search-row-text-v<revision>.json`) pins it. */
+export const SEARCH_TEXT_REVISION = 1;
+/** Largest answer, as JSON. A page of long hits can exceed it before 50 hits: the page then ends
+ * early with a cursor at the cut. */
+export const SEARCH_MAX_OUTPUT_BYTES = 64 * 1024;
+export const SEARCH_LIMITS = Object.freeze({
+    /** Largest query, UTF-8 bytes. */
+    maxQueryBytes: 1_024,
+    /** Distinct normalized query terms. */
+    maxQueryTerms: 16,
+    defaultRows: 10,
+    maxRows: 50,
+    /** Excerpt length, UTF-8 bytes. */
+    excerptBytes: 512,
+    /** Largest exact `type` or `tag` filter, UTF-8 bytes (the kernel query's filter bound). */
+    maxFilterBytes: 256,
+    /** Largest id `prefix` filter, UTF-8 bytes (a document id's bound). */
+    maxPrefixBytes: 512,
+    /** Largest cursor, UTF-8 bytes. */
+    maxCursorBytes: 2_048,
+    /** Values per facet, most frequent first. */
+    maxFacetValues: 50,
+    // Index limits, enforced while an in-memory index is built.
+    maxIndexDocuments: 20_000,
+    maxIndexSourceBytes: 67_108_864,
+    /** portal-webmcp's V1 value: a long document is indexed whole, never truncated; one over it is
+     * left out of the index and counted as skipped. */
+    maxTermsPerDocument: 65_536,
+    /** The default and ceiling of `searchDocuments`' `maxEvidenceInstances`: the most capped term
+     * instances a request's terms may hold across a corpus before it is refused as too broad. */
+    maxEvidenceInstances: 400_000,
+});
+/** Body occurrences of one distinct query term that can still add score. */
+export const BODY_OCCURRENCE_CAP = 20;
+/** Bytes an excerpt may reach behind its first body match before the match starts. */
+export const EXCERPT_LEAD_BYTES = 256;
+/** Documents processed between cancellation checks. */
+export const SIGNAL_INTERVAL = 128;
+export const SEARCH_MATCHES = Object.freeze(["auto", "all", "any"]);
+export const SEARCH_FACETS = Object.freeze(["type", "tags"]);
+export const SEARCH_MATCH_FIELDS = Object.freeze(["title", "type", "tag", "description", "id", "body"]);
+export const SEARCH_GUIDANCE = Object.freeze({
+    all: 'No document contains every query term. Retry with match "any", fewer terms, or different exact filters.',
+    any: "No document contains any searchable query term. Try domain-specific keywords or remove exact type and tag filters.",
+    /** The refusal of a request whose terms occur too often to rank (`maxEvidenceInstances`). */
+    broad: "The query's terms occur too often in this corpus to rank. Retry with fewer or more specific terms.",
+});
+// The one place that decides which frontmatter members become searchable or displayable fields;
+// nothing here reinterprets Markdown or adds Kind semantics.
+function stringMember(frontmatter, key) {
+    const value = frontmatter[key];
+    return typeof value === "string" ? value : undefined;
+}
+export function documentTitle(document) {
+    return stringMember(document.frontmatter, "title");
+}
+export function documentType(document) {
+    return stringMember(document.frontmatter, "type");
+}
+export function documentDescription(document) {
+    return stringMember(document.frontmatter, "description");
+}
+/** Declared string tags only; a non-array or non-string member contributes nothing. */
+export function documentTags(document) {
+    const value = document.frontmatter["tags"];
+    return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+}
+//# sourceMappingURL=contract.js.map

package/dist/search/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/search/contract.ts"],"names":[],"mappings":"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"}

package/dist/search/errors.d.ts

@@ -0,0 +1,30 @@
+/** The corpus exceeds an index limit or a host's configured bound. A kernel answers
+ * `result_too_large`. */
+export declare class SearchLimitError extends Error {
+    readonly limit: string;
+    readonly max: number;
+    readonly actual: number;
+    constructor(limit: string, max: number, actual: number, message?: string);
+}
+/** The request's terms hold more than `maxEvidenceInstances` capped instances. Still a
+ * `SearchLimitError` (`result_too_large`), but the corpus is searchable: the message is
+ * SEARCH_GUIDANCE.broad, to retry with fewer or more specific terms. */
+export declare class SearchBroadQueryError extends SearchLimitError {
+    constructor(max: number, actual: number);
+}
+export type SearchInputReason = "request" | "query" | "empty-query" | "too-many-query-terms" | "match" | "filter" | "limit" | "facets" | "cursor";
+/** The request is outside the contract. A kernel answers `invalid_input`. */
+export declare class SearchInputError extends Error {
+    readonly reason: SearchInputReason;
+    constructor(reason: SearchInputReason);
+}
+/** A cancelled index build or ranking rejects; it never returns a partial answer. */
+export declare class SearchAbortError extends Error {
+    constructor();
+}
+/** Throws as a stop asks: a signal already aborted, or a host check that throws. */
+export declare function stopIfAsked(stop: {
+    readonly signal?: AbortSignal;
+    readonly check?: () => void;
+} | undefined): void;
+//# sourceMappingURL=errors.d.ts.map

package/dist/search/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/search/errors.ts"],"names":[],"mappings":"AAKA;yBACyB;AACzB,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,SAAkD;CAOlH;AAED;;wEAEwE;AACxE,qBAAa,qBAAsB,SAAQ,gBAAgB;gBAC7C,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAIxC;AAED,MAAM,MAAM,iBAAiB,GACzB,SAAS,GACT,OAAO,GACP,aAAa,GACb,sBAAsB,GACtB,OAAO,GACP,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,QAAQ,CAAC;AAEb,6EAA6E;AAC7E,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;gBAEvB,MAAM,EAAE,iBAAiB;CAKtC;AAED,qFAAqF;AACrF,qBAAa,gBAAiB,SAAQ,KAAK;;CAK1C;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAA;CAAE,GAAG,SAAS,GAAG,IAAI,CAGlH"}

package/dist/search/errors.js

@@ -0,0 +1,50 @@
+// The ways a search refuses: a corpus over an index limit (or a host's configured bound), a request
+// whose terms occur too often to rank, a request outside the contract, and a cancellation. Messages
+// are fixed text; none repeats the caller's input.
+import { SEARCH_GUIDANCE } from "./contract.js";
+/** The corpus exceeds an index limit or a host's configured bound. A kernel answers
+ * `result_too_large`. */
+export class SearchLimitError extends Error {
+    limit;
+    max;
+    actual;
+    constructor(limit, max, actual, message = `The search corpus exceeds its ${limit} limit.`) {
+        super(message);
+        this.name = "SearchLimitError";
+        this.limit = limit;
+        this.max = max;
+        this.actual = actual;
+    }
+}
+/** The request's terms hold more than `maxEvidenceInstances` capped instances. Still a
+ * `SearchLimitError` (`result_too_large`), but the corpus is searchable: the message is
+ * SEARCH_GUIDANCE.broad, to retry with fewer or more specific terms. */
+export class SearchBroadQueryError extends SearchLimitError {
+    constructor(max, actual) {
+        super("maxEvidenceInstances", max, actual, SEARCH_GUIDANCE.broad);
+        this.name = "SearchBroadQueryError";
+    }
+}
+/** The request is outside the contract. A kernel answers `invalid_input`. */
+export class SearchInputError extends Error {
+    reason;
+    constructor(reason) {
+        super(`The search request is invalid (${reason}).`);
+        this.name = "SearchInputError";
+        this.reason = reason;
+    }
+}
+/** A cancelled index build or ranking rejects; it never returns a partial answer. */
+export class SearchAbortError extends Error {
+    constructor() {
+        super("The search was cancelled.");
+        this.name = "AbortError";
+    }
+}
+/** Throws as a stop asks: a signal already aborted, or a host check that throws. */
+export function stopIfAsked(stop) {
+    if (stop?.signal?.aborted)
+        throw new SearchAbortError();
+    stop?.check?.();
+}
+//# sourceMappingURL=errors.js.map

package/dist/search/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/search/errors.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,oGAAoG;AACpG,mDAAmD;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD;yBACyB;AACzB,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,KAAK,CAAS;IACd,GAAG,CAAS;IACZ,MAAM,CAAS;IAExB,YAAY,KAAa,EAAE,GAAW,EAAE,MAAc,EAAE,OAAO,GAAG,iCAAiC,KAAK,SAAS;QAC/G,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;wEAEwE;AACxE,MAAM,OAAO,qBAAsB,SAAQ,gBAAgB;IACzD,YAAY,GAAW,EAAE,MAAc;QACrC,KAAK,CAAC,sBAAsB,EAAE,GAAG,EAAE,MAAM,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC;QAClE,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAaD,6EAA6E;AAC7E,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,MAAM,CAAoB;IAEnC,YAAY,MAAyB;QACnC,KAAK,CAAC,kCAAkC,MAAM,IAAI,CAAC,CAAC;QACpD,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,qFAAqF;AACrF,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzC;QACE,KAAK,CAAC,2BAA2B,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAED,oFAAoF;AACpF,MAAM,UAAU,WAAW,CAAC,IAAgF;IAC1G,IAAI,IAAI,EAAE,MAAM,EAAE,OAAO;QAAE,MAAM,IAAI,gBAAgB,EAAE,CAAC;IACxD,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;AAClB,CAAC"}

package/dist/search/identity.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Canonical JSON for identity digests, cursor bodies, and byte measurement.
+ * Keys sort by UTF-16 code unit, `undefined` members are dropped, and anything
+ * outside plain JSON is rejected so a digest can never depend on host ordering.
+ */
+export declare function canonicalJson(value: unknown): string;
+/** Locale-independent UTF-16 code-unit ordering; canonical order never uses host collation. */
+export declare function codeUnitCompare(a: string, b: string): number;
+export declare function base64UrlEncode(bytes: Uint8Array): string;
+/** Strict unpadded base64url decoding; any stray character rejects the input. */
+export declare function base64UrlDecode(value: string): Uint8Array | undefined;
+//# sourceMappingURL=identity.d.ts.map

package/dist/search/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/search/identity.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAIpD;AAwBD,+FAA+F;AAC/F,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5D;AAID,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAazD;AAED,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAwBrE"}