@superbee/core 0.2.0-pre.16 → 0.2.0-pre.19

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

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../src/search/source.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAEvF,qGAAqG;AACrG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;0CACsC;IACtC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC;QAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3H;AAED,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,oCAAoC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;yDACqD;IACrD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iFAAiF;IACjF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,iGAAiG;AACjG,MAAM,WAAW,sBAAsB;IACrC,wFAAwF;IACxF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,2GAA2G;IAC3G,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC;gDAC4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;gDAC4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACjD;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B;4BACwB;IACxB,QAAQ,CACN,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,sBAAsB,EAC9B,IAAI,CAAC,EAAE,YAAY,GAClB,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAClC,6FAA6F;IAC7F,IAAI,CAAC,IAAI,EAAE,SAAS;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;CACtH"}

package/dist/search/source.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=source.js.map

package/dist/search/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../../src/search/source.ts"],"names":[],"mappings":""}

package/dist/search/text.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The search text rules, one owner: normalization, tokenization, the body scanner that keeps original
+ * byte offsets, query normalization and the automatic fallback's relaxation, plus the UTF-8 helpers
+ * excerpts need. Moved unchanged from portal-webmcp 0.3.1 (`search.ts`, `text.ts`).
+ */
+export declare function utf8(value: string): Uint8Array;
+export declare function utf8ByteLength(value: string): number;
+/**
+ * Move an index forward until it starts a UTF-8 sequence. A slice that begins on
+ * a continuation byte would decode to a replacement character, so continuations
+ * are skipped rather than replaced.
+ */
+export declare function forwardBoundary(bytes: Uint8Array, index: number): number;
+/** Move an index backward until it ends a complete UTF-8 sequence. */
+export declare function backwardBoundary(bytes: Uint8Array, index: number): number;
+export declare function decodeUtf8(bytes: Uint8Array, start: number, end: number): string;
+/** Collapse every maximal whitespace run to one ASCII space and trim both ends. */
+export declare function collapseWhitespace(value: string): string;
+/** Locale-independent normalization: Unicode NFKC then `toLowerCase()`. */
+export declare function normalize(value: string): string;
+/** Tokenization into maximal Unicode letter-or-number sequences of the normalized text. */
+export declare function tokenize(value: string): string[];
+/** A field's normalized phrase is its tokens joined by one ASCII space. */
+export declare function phrase(value: string): string;
+/**
+ * Visits every body token in document order with the original UTF-8 byte range of the run that
+ * produced it (every token of one run shares its range). `visit` returns `true` to stop the scan.
+ * The in-memory index and the excerpt both read the body through this one scanner, so a match's
+ * offsets are the same wherever they are computed.
+ */
+export declare function scanBody(body: string, visit: (term: string, start: number, end: number) => boolean | void): void;
+export interface NormalizedQueryV1 {
+    readonly phrase: string;
+    readonly terms: readonly string[];
+}
+/** Duplicate query tokens collapse after their first occurrence; the phrase is the remainder. */
+export declare function normalizeQuery(query: string): NormalizedQueryV1;
+export interface RelaxedQueryV1 {
+    readonly query: NormalizedQueryV1;
+    readonly ignoredTerms: readonly string[];
+}
+/**
+ * Removes fixed conversational terms for automatic any-term fallback. If that
+ * would remove the whole query, the original normalized query stays intact.
+ */
+export declare function relaxQuery(query: NormalizedQueryV1): RelaxedQueryV1;
+//# sourceMappingURL=text.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/search/text.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAE9C;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAMD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIxE;AAED,sEAAsE;AACtE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIzE;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhF;AAED,mFAAmF;AACnF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAExD;AAMD,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,2FAA2F;AAC3F,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAEhD;AAED,2EAA2E;AAC3E,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5C;AAsBD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,GAAG,IAAI,CA0BhH;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,iGAAiG;AACjG,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAS/D;AAYD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,iBAAiB,GAAG,cAAc,CAQnE"}

package/dist/search/text.js

@@ -0,0 +1,148 @@
+/**
+ * The search text rules, one owner: normalization, tokenization, the body scanner that keeps original
+ * byte offsets, query normalization and the automatic fallback's relaxation, plus the UTF-8 helpers
+ * excerpts need. Moved unchanged from portal-webmcp 0.3.1 (`search.ts`, `text.ts`).
+ */
+const encoder = new TextEncoder();
+const decoder = new TextDecoder("utf-8", { fatal: false, ignoreBOM: false });
+export function utf8(value) {
+    return encoder.encode(value);
+}
+export function utf8ByteLength(value) {
+    return encoder.encode(value).byteLength;
+}
+function continuation(byte) {
+    return byte !== undefined && (byte & 0b1100_0000) === 0b1000_0000;
+}
+/**
+ * Move an index forward until it starts a UTF-8 sequence. A slice that begins on
+ * a continuation byte would decode to a replacement character, so continuations
+ * are skipped rather than replaced.
+ */
+export function forwardBoundary(bytes, index) {
+    let cursor = Math.max(0, Math.min(index, bytes.byteLength));
+    while (cursor < bytes.byteLength && continuation(bytes[cursor]))
+        cursor += 1;
+    return cursor;
+}
+/** Move an index backward until it ends a complete UTF-8 sequence. */
+export function backwardBoundary(bytes, index) {
+    let cursor = Math.max(0, Math.min(index, bytes.byteLength));
+    while (cursor > 0 && continuation(bytes[cursor]))
+        cursor -= 1;
+    return cursor;
+}
+export function decodeUtf8(bytes, start, end) {
+    return decoder.decode(bytes.subarray(start, end));
+}
+/** Collapse every maximal whitespace run to one ASCII space and trim both ends. */
+export function collapseWhitespace(value) {
+    return value.replace(/\s+/gu, " ").trim();
+}
+const TOKEN = /[\p{L}\p{N}]+/gu;
+const LETTER_OR_NUMBER = /[\p{L}\p{N}]/u;
+const MARK = /\p{M}/u;
+/** Locale-independent normalization: Unicode NFKC then `toLowerCase()`. */
+export function normalize(value) {
+    return value.normalize("NFKC").toLowerCase();
+}
+/** Tokenization into maximal Unicode letter-or-number sequences of the normalized text. */
+export function tokenize(value) {
+    return [...normalize(value).matchAll(TOKEN)].map((match) => match[0]);
+}
+/** A field's normalized phrase is its tokens joined by one ASCII space. */
+export function phrase(value) {
+    return tokenize(value).join(" ");
+}
+/**
+ * Whether an original character can belong to a token run.
+ *
+ * Body tokens must keep original byte offsets, so the body is segmented before
+ * normalization rather than after. A character joins a run when it is a letter
+ * or number, a combining mark (so a decomposed sequence composes inside its own
+ * run), or a compatibility character whose NFKC form contains a letter or
+ * number. NFKC never composes across a character outside that set, so run-wise
+ * tokenization yields the same terms as tokenizing the whole normalized field.
+ */
+const runMembership = new Map();
+function inTokenRun(character) {
+    const cached = runMembership.get(character);
+    if (cached !== undefined)
+        return cached;
+    const member = LETTER_OR_NUMBER.test(character) || MARK.test(character) || LETTER_OR_NUMBER.test(character.normalize("NFKC"));
+    runMembership.set(character, member);
+    return member;
+}
+/**
+ * Visits every body token in document order with the original UTF-8 byte range of the run that
+ * produced it (every token of one run shares its range). `visit` returns `true` to stop the scan.
+ * The in-memory index and the excerpt both read the body through this one scanner, so a match's
+ * offsets are the same wherever they are computed.
+ */
+export function scanBody(body, visit) {
+    let byteOffset = 0;
+    let runStart = 0;
+    let run = "";
+    let stopped = false;
+    const flush = () => {
+        if (run.length === 0)
+            return;
+        for (const match of normalize(run).matchAll(TOKEN)) {
+            if (visit(match[0], runStart, byteOffset) === true) {
+                stopped = true;
+                break;
+            }
+        }
+        run = "";
+    };
+    for (const character of body) {
+        if (inTokenRun(character)) {
+            if (run.length === 0)
+                runStart = byteOffset;
+            run += character;
+        }
+        else {
+            flush();
+            if (stopped)
+                return;
+        }
+        byteOffset += utf8(character).byteLength;
+    }
+    flush();
+}
+/** Duplicate query tokens collapse after their first occurrence; the phrase is the remainder. */
+export function normalizeQuery(query) {
+    const terms = [];
+    const seen = new Set();
+    for (const token of tokenize(query)) {
+        if (seen.has(token))
+            continue;
+        seen.add(token);
+        terms.push(token);
+    }
+    return { phrase: terms.join(" "), terms: Object.freeze(terms) };
+}
+// Fixed package text, deliberately not locale-sensitive. These words carry
+// little retrieval signal in ordinary English questions. They are removed only
+// by the automatic fallback, never by explicit `all` or `any` matching.
+// prettier-ignore
+const CONVERSATIONAL_TERMS = new Set([
+    "a", "an", "and", "are", "as", "at", "be", "by", "can", "did", "do", "does",
+    "for", "from", "how", "in", "is", "it", "of", "on", "or", "should", "that", "the",
+    "this", "to", "was", "what", "when", "where", "which", "who", "why", "will", "with",
+]);
+/**
+ * Removes fixed conversational terms for automatic any-term fallback. If that
+ * would remove the whole query, the original normalized query stays intact.
+ */
+export function relaxQuery(query) {
+    const terms = query.terms.filter((term) => !CONVERSATIONAL_TERMS.has(term));
+    if (terms.length === 0)
+        return { query, ignoredTerms: Object.freeze([]) };
+    const kept = new Set(terms);
+    return {
+        query: { phrase: terms.join(" "), terms: Object.freeze(terms) },
+        ignoredTerms: Object.freeze(query.terms.filter((term) => !kept.has(term))),
+    };
+}
+//# sourceMappingURL=text.js.map

package/dist/search/text.js.map

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

package/dist/source-engine/guard.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The guarded transport a profile sees. It checks every URL and every redirect hop against the
+ * run's host set (the profile's hosts within the connector's credential hosts and keyless domains)
+ * and the address rule, reads and follows robots.txt for keyless hosts, applies the method rule and
+ * the header allowlist, follows redirects itself with the guard re-run per hop, counts the request
+ * budget, honours the deadline and maps statuses to outcomes. Any refusal or error status stops
+ * the run: the call throws and the stop is recorded here, so a profile cannot swallow it.
+ */
+import { type Connector } from "../connectors.js";
+import { type FetchIdentity } from "./robots.js";
+import type { ProfileTransport, RequestRules, SourceBudget, SourceOutcome, SourceRequestRow, StatusRules, Transport } from "./types.js";
+export declare const DEFAULT_SOURCE_BUDGET: Readonly<SourceBudget>;
+/**
+ * The engine's status sets. 503 is not deferred: it ends `provider_unavailable` with a retry and
+ * any `retry_after`; a declaration's `errors` rows pass their own sets.
+ */
+export declare const DEFAULT_STATUS_RULES: Readonly<StatusRules>;
+/** Why a run stopped. */
+export interface Stop {
+    outcome: SourceOutcome;
+    reason?: string;
+    detail?: string;
+    status?: number;
+    retry: boolean;
+    retry_after?: string;
+}
+/** Thrown through a profile when the run stops. */
+export declare class SourceStop extends Error {
+    readonly stop: Stop;
+    constructor(stop: Stop);
+}
+export interface HostSet {
+    /** Every host a request may reach. */
+    allowed: ReadonlySet<string>;
+    /** Hosts a transport may send the credential to. */
+    credential: ReadonlySet<string>;
+    /** Keyless hosts: the robots.txt gate applies. */
+    keyless: ReadonlySet<string>;
+}
+/**
+ * The run's host set: the profile's hosts, each of which must be a credential host of the auth
+ * kind or a declared keyless domain. A host outside both is returned as undeclared.
+ */
+export declare function sourceHostSet(connector: Pick<Connector, "auth" | "domains">, hosts: readonly string[]): {
+    ok: true;
+    hosts: HostSet;
+} | {
+    ok: false;
+    undeclared: string[];
+};
+export interface GuardContext {
+    hosts: HostSet;
+    transport: Transport;
+    identity: FetchIdentity;
+    budget: SourceBudget;
+    rules: RequestRules;
+    statuses: StatusRules;
+    now: () => Date;
+    /**
+     * Whether a request may be conditional. A complete observation must read the whole listing, so
+     * it sends no validator and a not-modified answer stops it.
+     */
+    conditional: boolean;
+    signal?: AbortSignal;
+    /** Each request's own timeout. */
+    requestTimeoutMs?: number;
+}
+export interface GuardedTransport {
+    transport: ProfileTransport;
+    /** Every request, sent or refused, in order. */
+    requests: SourceRequestRow[];
+    /** The first stop, if any. */
+    stopped(): Stop | undefined;
+    /** Requests left in the run. */
+    remaining(): number;
+    /** End the run: every later request throws, from a reference the profile kept or not. */
+    close(): void;
+}
+/** `promise`, or a rejection once `signal` aborts; the abandoned promise's later failure is ignored. */
+export declare function raceAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T>;
+export declare function guardTransport(ctx: GuardContext): GuardedTransport;
+//# sourceMappingURL=guard.d.ts.map

package/dist/source-engine/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/source-engine/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAEnE,OAAO,EAA8C,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAC7F,OAAO,KAAK,EAIV,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,SAAS,EAEV,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,YAAY,CAOvD,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,WAAW,CAIrD,CAAC;AAmBH,yBAAyB;AACzB,MAAM,WAAW,IAAI;IACnB,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,mDAAmD;AACnD,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;gBACR,IAAI,EAAE,IAAI;CAKvB;AAED,MAAM,WAAW,OAAO;IACtB,sCAAsC;IACtC,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC7B,oDAAoD;IACpD,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAChC,kDAAkD;IAClD,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAc1K;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,SAAS,CAAC;IACrB,QAAQ,EAAE,aAAa,CAAC;IACxB,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,WAAW,CAAC;IACtB,GAAG,EAAE,MAAM,IAAI,CAAC;IAChB;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,kCAAkC;IAClC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,gBAAgB,CAAC;IAC5B,gDAAgD;IAChD,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,8BAA8B;IAC9B,OAAO,IAAI,IAAI,GAAG,SAAS,CAAC;IAC5B,gCAAgC;IAChC,SAAS,IAAI,MAAM,CAAC;IACpB,yFAAyF;IACzF,KAAK,IAAI,IAAI,CAAC;CACf;AAeD,wGAAwG;AACxG,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,CAa7F;AAoBD,wBAAgB,cAAc,CAAC,GAAG,EAAE,YAAY,GAAG,gBAAgB,CA2NlE"}