nexus-ai-pro 2.2.0 → 2.4.0

package/dist/utils/checksums.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Checks that tell a real identifier from a number that only looks like one. Every detector of card
+ * numbers and account numbers uses them, so an order id or a millisecond timestamp is never masked as
+ * a card.
+ */
+/** Whether a card number passes the Luhn check, with 13 to 19 digits; spaces and dashes are ignored. */
+export declare function luhn(value: string): boolean;
+/** Whether an IBAN passes its mod-97 check, with 15 to 34 characters; spaces are ignored. */
+export declare function ibanChecksum(value: string): boolean;
+/** Whether a phone-like match has as many digits as a phone number can: 10 to 15. */
+export declare function phoneDigits(value: string): boolean;
+/**
+ * Whether a match reads as a phone number: 10 to 15 digits, written with a leading `+` or with
+ * separators. A bare run of digits is an id or a timestamp far more often than a phone number.
+ */
+export declare function phoneNumber(value: string): boolean;
+/**
+ * Text as a detector should read it: Unicode compatibility forms folded (full-width letters become
+ * ASCII), and the invisible characters an attacker uses to split a phrase removed, so
+ * `ｉｇｎｏｒｅ` and `ig​nore` read as `ignore`.
+ */
+export declare function normalizeForDetection(text: string): string;

package/dist/utils/checksums.js

@@ -0,0 +1,39 @@
+export function luhn(value) {
+    const digits = value.replace(/[\s-]/g, '');
+    if (!/^\d{13,19}$/.test(digits))
+        return false;
+    let sum = 0;
+    for (let index = 0; index < digits.length; index += 1) {
+        let digit = Number(digits[digits.length - 1 - index]);
+        if (index % 2 === 1) {
+            digit *= 2;
+            if (digit > 9)
+                digit -= 9;
+        }
+        sum += digit;
+    }
+    return sum % 10 === 0;
+}
+export function ibanChecksum(value) {
+    const iban = value.replace(/ /g, '').toUpperCase();
+    if (!/^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$/.test(iban))
+        return false;
+    const rearranged = `${iban.slice(4)}${iban.slice(0, 4)}`;
+    let remainder = 0;
+    for (const char of rearranged) {
+        const code = /\d/.test(char) ? char : String(char.charCodeAt(0) - 55);
+        for (const digit of code)
+            remainder = (remainder * 10 + Number(digit)) % 97;
+    }
+    return remainder === 1;
+}
+export function phoneDigits(value) {
+    const digits = value.replace(/\D/g, '').length;
+    return digits >= 10 && digits <= 15;
+}
+export function phoneNumber(value) {
+    return phoneDigits(value) && (/^\s*\+/.test(value) || /\d[\s.()-]+\d/.test(value));
+}
+export function normalizeForDetection(text) {
+    return text.normalize('NFKC').replace(/[­᠎​-‏‪-‮⁠-⁤]/g, '');
+}

package/dist/utils/ids.d.ts

@@ -1 +1,9 @@
+/**
+ * Ids and text measures from Web Crypto and plain JavaScript, so the modules that use them run on
+ * every runtime: Node.js, Deno, Bun, edge runtimes, and browsers.
+ */
+/** Random bytes as lowercase hex, two characters per byte. */
+export declare function randomHex(bytes: number): string;
 export declare function generateRequestId(): string;
+/** The bytes UTF-8 takes for a string, as `Buffer.byteLength()` counts them, without encoding it. */
+export declare function utf8Length(text: string): number;

package/dist/utils/ids.js

@@ -1,4 +1,28 @@
-import { randomBytes } from 'node:crypto';
+export function randomHex(bytes) {
+    const values = globalThis.crypto.getRandomValues(new Uint8Array(bytes));
+    let hex = '';
+    for (const value of values)
+        hex += HEX[value];
+    return hex;
+}
 export function generateRequestId() {
-    return `req_${randomBytes(12).toString('hex')}`;
+    return `req_${randomHex(12)}`;
+}
+export function utf8Length(text) {
+    let length = 0;
+    for (let index = 0; index < text.length; index += 1) {
+        const code = text.charCodeAt(index);
+        if (code < 0x80)
+            length += 1;
+        else if (code < 0x800)
+            length += 2;
+        else if (code >= 0xd800 && code <= 0xdbff && (text.charCodeAt(index + 1) & 0xfc00) === 0xdc00) {
+            length += 4;
+            index += 1;
+        }
+        else
+            length += 3;
+    }
+    return length;
 }
+const HEX = Array.from({ length: 256 }, (_, value) => value.toString(16).padStart(2, '0'));

package/dist/utils/sha256.d.ts

@@ -0,0 +1,22 @@
+/**
+ * SHA-256 that can be fed in pieces, as `createHash('sha256')` is, with the same digest. Strings are
+ * hashed as UTF-8. Synchronous, unlike Web Crypto's `digest()`, so a cache key can be computed where
+ * it is needed.
+ */
+export declare class Sha256 {
+    private readonly state;
+    private readonly block;
+    private readonly words;
+    private filled;
+    private total;
+    /** Adds data: a string, as UTF-8, or bytes. */
+    update(data: string | Uint8Array): this;
+    /** The digest as lowercase hex. The hash takes no more data afterwards. */
+    digest(): string;
+    private compress;
+}
+/**
+ * The SHA-256 digest of a string, as UTF-8, or of bytes, as lowercase hex. Native where the runtime
+ * has it, which is ten times faster on large inputs, and the same digest everywhere else.
+ */
+export declare function sha256Hex(data: string | Uint8Array): string;

package/dist/utils/sha256.js

@@ -0,0 +1,120 @@
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98,
+    0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786,
+    0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8,
+    0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+    0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819,
+    0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a,
+    0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7,
+    0xc67178f2,
+]);
+const encoder = new TextEncoder();
+export class Sha256 {
+    state = new Uint32Array([
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+    ]);
+    block = new Uint8Array(64);
+    words = new Uint32Array(64);
+    filled = 0;
+    total = 0;
+    update(data) {
+        const bytes = typeof data === 'string' ? encoder.encode(data) : data;
+        this.total += bytes.length;
+        let offset = 0;
+        if (this.filled > 0) {
+            const take = Math.min(64 - this.filled, bytes.length);
+            this.block.set(bytes.subarray(0, take), this.filled);
+            this.filled += take;
+            offset = take;
+            if (this.filled < 64)
+                return this;
+            this.compress(this.block, 0);
+            this.filled = 0;
+        }
+        for (; offset + 64 <= bytes.length; offset += 64)
+            this.compress(bytes, offset);
+        if (offset < bytes.length) {
+            this.block.set(bytes.subarray(offset), 0);
+            this.filled = bytes.length - offset;
+        }
+        return this;
+    }
+    digest() {
+        const bits = this.total * 8;
+        const padding = new Uint8Array(this.filled < 56 ? 64 - this.filled : 128 - this.filled);
+        padding[0] = 0x80;
+        const view = new DataView(padding.buffer);
+        view.setUint32(padding.length - 8, Math.floor(bits / 0x100000000));
+        view.setUint32(padding.length - 4, bits >>> 0);
+        const total = this.total;
+        this.update(padding);
+        this.total = total;
+        let hex = '';
+        for (const word of this.state)
+            hex += word.toString(16).padStart(8, '0');
+        return hex;
+    }
+    compress(bytes, offset) {
+        const w = this.words;
+        for (let index = 0; index < 16; index += 1) {
+            const at = offset + index * 4;
+            w[index] =
+                (bytes[at] << 24) |
+                    (bytes[at + 1] << 16) |
+                    (bytes[at + 2] << 8) |
+                    bytes[at + 3];
+        }
+        for (let index = 16; index < 64; index += 1) {
+            const a = w[index - 15];
+            const b = w[index - 2];
+            const s0 = ((a >>> 7) | (a << 25)) ^ ((a >>> 18) | (a << 14)) ^ (a >>> 3);
+            const s1 = ((b >>> 17) | (b << 15)) ^ ((b >>> 19) | (b << 13)) ^ (b >>> 10);
+            w[index] = (w[index - 16] + s0 + w[index - 7] + s1) | 0;
+        }
+        const h = this.state;
+        let a = h[0];
+        let b = h[1];
+        let c = h[2];
+        let d = h[3];
+        let e = h[4];
+        let f = h[5];
+        let g = h[6];
+        let k = h[7];
+        for (let index = 0; index < 64; index += 1) {
+            const s1 = ((e >>> 6) | (e << 26)) ^ ((e >>> 11) | (e << 21)) ^ ((e >>> 25) | (e << 7));
+            const choose = (e & f) ^ (~e & g);
+            const t1 = (k + s1 + choose + K[index] + w[index]) | 0;
+            const s0 = ((a >>> 2) | (a << 30)) ^ ((a >>> 13) | (a << 19)) ^ ((a >>> 22) | (a << 10));
+            const majority = (a & b) ^ (a & c) ^ (b & c);
+            const t2 = (s0 + majority) | 0;
+            k = g;
+            g = f;
+            f = e;
+            e = (d + t1) | 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) | 0;
+        }
+        h[0] = h[0] + a;
+        h[1] = h[1] + b;
+        h[2] = h[2] + c;
+        h[3] = h[3] + d;
+        h[4] = h[4] + e;
+        h[5] = h[5] + f;
+        h[6] = h[6] + g;
+        h[7] = h[7] + k;
+    }
+}
+const nativeHash = (() => {
+    try {
+        const host = globalThis.process;
+        return host?.getBuiltinModule?.('crypto')?.createHash;
+    }
+    catch {
+        return undefined;
+    }
+})();
+export function sha256Hex(data) {
+    return nativeHash ? nativeHash('sha256').update(data).digest('hex') : new Sha256().update(data).digest();
+}

package/dist/utils/tenant.d.ts

@@ -1,3 +1,4 @@
+import type { Principal } from '../types/principal.js';
 /**
  * The tenant id rule every scope shares. An id is letters, digits, `_`, and `-`, so it can never hold
  * the `/` a scoped name or key is built with: no tenant's prefix is a prefix of another's.
@@ -12,3 +13,13 @@ export declare class TenantIdError extends RangeError {
 export declare function assertTenantId(tenantId: string): string;
 /** @internal The prefix a tenant's names and keys carry in a shared store. */
 export declare function tenantPrefix(tenantId: string): string;
+/**
+ * Run options with the principal's tenant applied: the principal's `tenantId` becomes the run's when
+ * it has none, a run whose two tenants differ is refused, and the principal's `userId` is recorded
+ * in the run's metadata.
+ */
+export declare function withPrincipal<O extends {
+    tenantId?: string;
+    principal?: Principal;
+    metadata?: Record<string, unknown>;
+}>(runOptions: O): O;

package/dist/utils/tenant.js

@@ -14,3 +14,17 @@ export function assertTenantId(tenantId) {
 export function tenantPrefix(tenantId) {
     return `tenant/${assertTenantId(tenantId)}/`;
 }
+export function withPrincipal(runOptions) {
+    const principal = runOptions.principal;
+    if (!principal)
+        return runOptions;
+    const tenantId = principal.tenantId;
+    if (tenantId !== undefined && runOptions.tenantId !== undefined && tenantId !== runOptions.tenantId) {
+        throw new TypeError("The run's tenantId and its principal's tenant differ");
+    }
+    return {
+        ...runOptions,
+        ...(tenantId !== undefined && runOptions.tenantId === undefined ? { tenantId } : {}),
+        ...(principal.userId !== undefined ? { metadata: { ...runOptions.metadata, userId: principal.userId } } : {}),
+    };
+}

package/dist/version.d.ts

@@ -2,4 +2,4 @@
  * This package's version, recorded where provenance matters, such as on every experiment. A test
  * keeps it equal to `package.json`.
  */
-export declare const NEXUS_VERSION = "2.2.0";
+export declare const NEXUS_VERSION = "2.4.0";

package/dist/version.js

@@ -1 +1 @@
-export const NEXUS_VERSION = '2.2.0';
+export const NEXUS_VERSION = '2.4.0';

package/dist-cjs/adapter-kit/contracts.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The contract suites the adapter kit ships: what every vector store, retriever, and long-term store
+ * must do, as checks that need no test framework. Each check is named for the behavior it proves,
+ * and a capability the adapter does not declare is reported as skipped, never as a failure.
+ */
+import type { RagChunk } from '../hallucination/rag.js';
+import type { EmbeddingProvider, VectorStore } from '../hallucination/retrieval.js';
+import type { Retriever } from '../rag/retrievers.js';
+import type { Store } from '../types/store.js';
+/** One check of a contract suite. */
+export interface AdapterCheck {
+    /** What was checked, as a sentence. */
+    name: string;
+    /** Whether it held. */
+    ok: boolean;
+    /** Why it did not hold, or why it was skipped. */
+    detail?: string;
+    /** True when the adapter does not declare the capability the check needs. */
+    skipped?: boolean;
+}
+/** The passages every retrieval contract runs on, and that benchmarks reuse. */
+export declare const ADAPTER_FIXTURE_PASSAGES: readonly RagChunk[];
+/** What a vector store declares it supports, for its contract. */
+export interface VectorStoreCapabilities {
+    /** `searchVector()` with a vector computed elsewhere. Defaults to true. */
+    searchVector?: boolean;
+    /** `minScore` drops weak matches. Defaults to true. */
+    minScore?: boolean;
+    /** Metadata filters: `exact` matches values, `typed` also tells `3` from `'3'`, `none` has no filters. Defaults to `exact`. */
+    filters?: 'none' | 'exact' | 'typed';
+}
+/** Options for `runVectorStoreContract()`. */
+export interface VectorStoreContractOptions {
+    /** The embedding function the store was given, to compute a query vector for `searchVector()`. */
+    embed: EmbeddingProvider;
+    /** What the store supports. */
+    capabilities?: VectorStoreCapabilities;
+    /** Waits for writes to become searchable, for a store whose index is eventually consistent. */
+    settle?: () => Promise<void>;
+}
+/**
+ * The `VectorStore` contract: ranking, `topK`, sources and metadata round-tripped, filters,
+ * `minScore`, vector search, replacement by id, deletes, and empty writes. The store should be empty
+ * when it starts.
+ */
+export declare function runVectorStoreContract(store: VectorStore, options: VectorStoreContractOptions): Promise<AdapterCheck[]>;
+/** What a retriever declares it supports, for its contract. */
+export interface RetrieverCapabilities {
+    /** It holds its own passages, with `add()` and `delete()`: a `SparseRetriever`. Defaults to whether it has them. */
+    writes?: boolean;
+    /** Metadata filters. Defaults to true. */
+    filters?: boolean;
+}
+/** Options for `runRetrieverContract()`. */
+export interface RetrieverContractOptions {
+    /** What the retriever supports. */
+    capabilities?: RetrieverCapabilities;
+    /**
+     * Loads the fixture passages, for a retriever that does not hold its own: into the vector store
+     * behind it, say. A retriever with `add()` is loaded through that.
+     */
+    load?: (passages: RagChunk[]) => Promise<void>;
+    /** Waits for writes to become searchable. */
+    settle?: () => Promise<void>;
+}
+/**
+ * The `Retriever` contract, and the `SparseRetriever` contract when the retriever takes writes:
+ * an exact term found, ranking, `topK`, filters, replacement, deletes, and an empty query.
+ */
+export declare function runRetrieverContract(retriever: Retriever, options?: RetrieverContractOptions): Promise<AdapterCheck[]>;
+/** What a long-term store declares it supports, for its contract. */
+export interface StoreCapabilities {
+    /** `search()` lists a namespace prefix, newest first. Defaults to true. */
+    search?: boolean;
+    /** `search()` filters on value fields. Defaults to true. */
+    filters?: boolean;
+    /** `listNamespaces()`. Defaults to true. */
+    namespaces?: boolean;
+}
+/**
+ * The long-term `Store` contract: values round-trip, a replaced item keeps its creation time, a
+ * missing key reads as nothing, deletes, prefix search with filters and paging, and namespace
+ * listing. The store should be empty when it starts.
+ */
+export declare function runStoreContract(store: Store, options?: {
+    capabilities?: StoreCapabilities;
+}): Promise<AdapterCheck[]>;

package/dist-cjs/adapter-kit/contracts.js

@@ -0,0 +1,243 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADAPTER_FIXTURE_PASSAGES = void 0;
+exports.runVectorStoreContract = runVectorStoreContract;
+exports.runRetrieverContract = runRetrieverContract;
+exports.runStoreContract = runStoreContract;
+exports.ADAPTER_FIXTURE_PASSAGES = [
+    {
+        id: 'refunds#0',
+        content: 'Refunds are issued within fourteen days of a return',
+        source: 'policy.md',
+        metadata: { tenant: 'acme', page: 3 },
+    },
+    {
+        id: 'shipping#0',
+        content: 'Orders ship from the warehouse within two business days',
+        source: 'policy.md',
+        metadata: { tenant: 'acme' },
+    },
+    { id: 'refunds#1', content: 'A refund goes back to the original payment method', metadata: { tenant: 'globex' } },
+    { id: 'careers#0', content: 'We are hiring engineers in three offices' },
+];
+function fixturePassages() {
+    return exports.ADAPTER_FIXTURE_PASSAGES.map((passage) => ({
+        ...passage,
+        ...(passage.metadata ? { metadata: { ...passage.metadata } } : {}),
+    }));
+}
+class Suite {
+    checks = [];
+    async check(name, run) {
+        try {
+            const result = await run();
+            this.checks.push(result === true ? { name, ok: true } : { name, ok: false, detail: result === false ? 'did not hold' : result });
+        }
+        catch (error) {
+            this.checks.push({ name, ok: false, detail: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    skip(name, reason) {
+        this.checks.push({ name, ok: true, skipped: true, detail: reason });
+    }
+}
+async function runVectorStoreContract(store, options) {
+    const suite = new Suite();
+    const settle = options.settle ?? (async () => undefined);
+    const capabilities = options.capabilities ?? {};
+    const filters = capabilities.filters ?? 'exact';
+    await suite.check('adds passages', async () => {
+        await store.add(fixturePassages());
+        await settle();
+        return true;
+    });
+    await suite.check('ranks the closest passage first, best first, within topK', async () => {
+        const results = await store.search('how long do refunds take', { topK: 2 });
+        if (results.length !== 2)
+            return `expected 2 results for topK 2, got ${results.length}`;
+        if (results[0]?.id !== 'refunds#0')
+            return `expected refunds#0 first, got ${results[0]?.id}`;
+        return (results[0]?.score ?? 0) > (results[1]?.score ?? 0) || 'results are not ordered by score';
+    });
+    await suite.check('returns a passage source and its metadata whole', async () => {
+        const [first] = await store.search('how long do refunds take', { topK: 1 });
+        if (first?.source !== 'policy.md')
+            return `expected source policy.md, got ${first?.source}`;
+        return (JSON.stringify(first?.metadata) === JSON.stringify({ tenant: 'acme', page: 3 }) ||
+            `metadata came back as ${JSON.stringify(first?.metadata)}`);
+    });
+    if (filters === 'none')
+        suite.skip('narrows a search by metadata', 'the store declares no filters');
+    else {
+        await suite.check('narrows a search by metadata', async () => {
+            const results = await store.search('refund', { filter: { tenant: 'globex' } });
+            return ((results.length === 1 && results[0]?.id === 'refunds#1') ||
+                `got ${results.map((result) => result.id).join(', ')}`);
+        });
+    }
+    if (filters === 'typed') {
+        await suite.check('tells a number from the same digits as text in a filter', async () => {
+            const numeric = await store.search('refunds', { filter: { page: 3 }, topK: 10 });
+            const text = await store.search('refunds', { filter: { page: '3' }, topK: 10 });
+            return ((numeric.length === 1 && text.length === 0) || `number matched ${numeric.length}, text matched ${text.length}`);
+        });
+    }
+    else
+        suite.skip('tells a number from the same digits as text in a filter', 'the store declares untyped filters');
+    if (capabilities.minScore === false)
+        suite.skip('drops matches under minScore', 'the store declares no minScore');
+    else {
+        await suite.check('drops matches under minScore', async () => {
+            const results = await store.search('how long do refunds take', { minScore: 0.99 });
+            return results.length === 0 || `${results.length} results above 0.99`;
+        });
+    }
+    if (capabilities.searchVector === false)
+        suite.skip('searches by a precomputed vector', 'the store declares no searchVector');
+    else {
+        await suite.check('searches by a precomputed vector', async () => {
+            const [vector] = await options.embed(['orders ship from the warehouse']);
+            const [first] = await store.searchVector(vector, { topK: 1 });
+            return first?.id === 'shipping#0' || `expected shipping#0, got ${first?.id}`;
+        });
+    }
+    await suite.check('replaces a passage added again under its id', async () => {
+        await store.add([
+            { id: 'careers#0', content: 'Refunds for event tickets are not available', metadata: { tenant: 'acme' } },
+        ]);
+        await settle();
+        const results = await store.search('event tickets refunds', { topK: 10 });
+        const copies = results.filter((result) => result.id === 'careers#0');
+        if (copies.length !== 1)
+            return `found ${copies.length} copies`;
+        return /event tickets/.test(copies[0]?.content ?? '') || 'the old content is still there';
+    });
+    await suite.check('deletes by id, ignoring ids it does not hold', async () => {
+        await store.delete(['refunds#0', 'not-stored']);
+        await settle();
+        const results = await store.search('how long do refunds take', { topK: 10 });
+        return !results.some((result) => result.id === 'refunds#0') || 'the deleted passage is still found';
+    });
+    await suite.check('accepts empty writes', async () => {
+        await store.add([]);
+        await store.delete([]);
+        return true;
+    });
+    return suite.checks;
+}
+async function runRetrieverContract(retriever, options = {}) {
+    const suite = new Suite();
+    const settle = options.settle ?? (async () => undefined);
+    const sparse = retriever;
+    const writes = options.capabilities?.writes ?? (typeof sparse.add === 'function' && typeof sparse.delete === 'function');
+    const passages = fixturePassages();
+    await suite.check('loads the fixture passages', async () => {
+        if (writes)
+            await sparse.add?.(passages);
+        else if (options.load)
+            await options.load(passages);
+        else
+            return 'a retriever without add() needs a load() to fill what it reads from';
+        await settle();
+        return true;
+    });
+    await suite.check('finds the passage holding the query terms first', async () => {
+        const [first] = await retriever.retrieve('warehouse business days', { topK: 3 });
+        return first?.id === 'shipping#0' || `expected shipping#0, got ${first?.id}`;
+    });
+    await suite.check('returns at most topK results, best first', async () => {
+        const results = await retriever.retrieve('refund refunds return', { topK: 1 });
+        return results.length <= 1 || `${results.length} results for topK 1`;
+    });
+    if (options.capabilities?.filters === false)
+        suite.skip('narrows by metadata', 'the retriever declares no filters');
+    else {
+        await suite.check('narrows by metadata', async () => {
+            const results = await retriever.retrieve('refund', { filter: { tenant: 'globex' }, topK: 10 });
+            return ((results.every((result) => result.metadata?.tenant === 'globex') && results.length > 0) ||
+                `got ${results.map((result) => result.id).join(', ')}`);
+        });
+    }
+    if (!writes) {
+        suite.skip('replaces a passage added again under its id', 'the retriever does not take writes');
+        suite.skip('deletes by id, ignoring ids it does not hold', 'the retriever does not take writes');
+    }
+    else {
+        await suite.check('replaces a passage added again under its id', async () => {
+            await sparse.add?.([{ id: 'careers#0', content: 'Engineers relocate with a stipend' }]);
+            await settle();
+            const results = await retriever.retrieve('stipend relocate', { topK: 10 });
+            return (results.filter((result) => result.id === 'careers#0').length === 1 || 'the passage is missing or duplicated');
+        });
+        await suite.check('deletes by id, ignoring ids it does not hold', async () => {
+            await sparse.delete?.(['shipping#0', 'not-stored']);
+            await settle();
+            const results = await retriever.retrieve('warehouse business days', { topK: 10 });
+            return !results.some((result) => result.id === 'shipping#0') || 'the deleted passage is still found';
+        });
+    }
+    await suite.check('answers an empty query without failing', async () => {
+        await retriever.retrieve('', { topK: 3 });
+        return true;
+    });
+    return suite.checks;
+}
+async function runStoreContract(store, options = {}) {
+    const suite = new Suite();
+    const capabilities = options.capabilities ?? {};
+    const namespace = ['contract', 'users'];
+    await suite.check('round-trips a value', async () => {
+        await store.put(namespace, 'ann', { name: 'Ann', plan: 'pro' });
+        const item = await store.get(namespace, 'ann');
+        return (item?.value.name === 'Ann' && item.key === 'ann') || `read ${JSON.stringify(item)}`;
+    });
+    await suite.check('keeps the creation time when an item is replaced', async () => {
+        const before = await store.get(namespace, 'ann');
+        await new Promise((resolve) => setTimeout(resolve, 5));
+        await store.put(namespace, 'ann', { name: 'Ann', plan: 'team' });
+        const after = await store.get(namespace, 'ann');
+        if (after?.value.plan !== 'team')
+            return 'the replacement was not stored';
+        return after.createdAt === before?.createdAt || `createdAt moved from ${before?.createdAt} to ${after.createdAt}`;
+    });
+    await suite.check('reads a missing key as nothing', async () => (await store.get(namespace, 'nobody')) === undefined);
+    await suite.check('deletes an item', async () => {
+        await store.put(namespace, 'temp', { name: 'Temp' });
+        await store.delete(namespace, 'temp');
+        return (await store.get(namespace, 'temp')) === undefined;
+    });
+    if (capabilities.search === false)
+        suite.skip('lists a namespace prefix, with paging', 'the store declares no search');
+    else {
+        await suite.check('lists a namespace prefix, with paging', async () => {
+            await store.put([...namespace, 'archived'], 'bob', { name: 'Bob', plan: 'free' });
+            await store.put(namespace, 'cy', { name: 'Cy', plan: 'free' });
+            const all = await store.search(['contract'], { limit: 10 });
+            if (all.length !== 3)
+                return `expected 3 items under the prefix, got ${all.length}`;
+            const page = await store.search(['contract'], { limit: 2, offset: 2 });
+            return page.length === 1 || `expected 1 item on the second page, got ${page.length}`;
+        });
+    }
+    if (capabilities.search === false || capabilities.filters === false)
+        suite.skip('filters by a value field', 'the store declares no filters');
+    else {
+        await suite.check('filters by a value field', async () => {
+            const free = await store.search(['contract'], { filter: { plan: 'free' }, limit: 10 });
+            const names = free
+                .map((item) => item.value.name)
+                .sort()
+                .join(',');
+            return names === 'Bob,Cy' || `got ${names}`;
+        });
+    }
+    if (capabilities.namespaces === false)
+        suite.skip('lists namespaces under a prefix', 'the store declares no namespace listing');
+    else {
+        await suite.check('lists namespaces under a prefix', async () => {
+            const listed = (await store.listNamespaces({ prefix: ['contract'] })).map((parts) => parts.join('/')).sort();
+            return listed.join(',') === 'contract/users,contract/users/archived' || `got ${listed.join(', ')}`;
+        });
+    }
+    return suite.checks;
+}

package/dist-cjs/adapter-kit/errors.d.ts

@@ -0,0 +1,39 @@
+/**
+ * One vocabulary for adapter failures, so code above an adapter retries, alerts, and reports the same
+ * way whichever database, provider, or service the adapter talks to.
+ */
+/** What kind of failure an adapter call met. */
+export type AdapterErrorCode = 'AUTH' | 'RATE_LIMIT' | 'NOT_FOUND' | 'INVALID' | 'CONFLICT' | 'TIMEOUT' | 'UNAVAILABLE' | 'CANCELLED' | 'UNKNOWN';
+/** A failure's code, and whether another attempt could succeed. */
+export interface AdapterErrorClass {
+    /** The kind of failure. */
+    code: AdapterErrorCode;
+    /** True for a failure a retry could get past: a rate limit, a timeout, an unavailable service. */
+    retryable: boolean;
+    /** The HTTP status, when the failure carried one. */
+    status?: number;
+}
+/** A failed adapter call, normalized. The original error is its `cause`. */
+export declare class AdapterError extends Error {
+    /** The adapter that failed. */
+    readonly adapter: string;
+    /** The method that failed, such as `search`. */
+    readonly operation: string;
+    /** The kind of failure. */
+    readonly code: AdapterErrorCode;
+    /** Whether another attempt could succeed. */
+    readonly retryable: boolean;
+    /** The HTTP status, when the failure carried one. */
+    readonly status?: number;
+    constructor(
+    /** The adapter that failed. */
+    adapter: string, 
+    /** The method that failed, such as `search`. */
+    operation: string, failure: AdapterErrorClass, cause: unknown);
+}
+/**
+ * Classifies any error by what it carries: an HTTP status (`status`, `statusCode`, or
+ * `response.status`), a Node network code such as `ECONNREFUSED`, or an `AbortError` or
+ * `TimeoutError` name. An adapter's own `normalizeError` runs first and may override it.
+ */
+export declare function classifyAdapterError(error: unknown): AdapterErrorClass;