@b4run/memory 0.8.28

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Brian Love
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/cacheplane/b4run/main/docs/brand/b4-logo-horizontal-black-on-white.png" alt="B4.run" width="180" />
+</p>
+
+# @b4run/memory
+
+Supported long-term memory storage, ranking, browsing, namespace, and reconciliation primitives. Most route authors should declare memory with `defineMemory()` and use this package when they need direct store access.
+
+**Use this when:** You need to access memory stores or ranking primitives directly instead of using only `defineMemory()`.
+
+## Install
+
+```bash
+pnpm add @b4run/memory
+```
+
+## Example
+
+```ts
+import { sqliteMemoryStore } from "@b4run/memory"
+
+const store = sqliteMemoryStore({ path: ".b4/memory.sqlite" })
+```
+
+Supported focused entry points are `@b4run/memory/browse`, `@b4run/memory/namespace`, and `@b4run/memory/reconcile`.
+
+## Runtime and stability
+
+- `@b4run/memory` is a supported node-only application surface because it includes SQLite.
+- `@b4run/memory/browse` is a supported, dependency-free edge-safe integration surface.
+- `@b4run/memory/namespace` is a supported edge-safe integration surface.
+- `@b4run/memory/reconcile` is a supported edge-safe integration surface.
+
+SQLite rows contain plaintext content, data, sources, and tags. Treat the database as sensitive application data and enforce tenant scope at the caller boundary.
+
+## Related
+
+- [Memory API reference](https://b4.run/docs/api/memory) — exact store, query, and subpath contracts.
+- [Long-term Memory](https://b4.run/docs/memory/long-term) — application configuration.
+- [Recall and Retrieval](https://b4.run/docs/memory/retrieval) and [Browse and Manage Memory](https://b4.run/docs/memory/browse) — retrieval and administration workflows.
+- [`@b4run/memory-pgvector`](https://www.npmjs.com/package/@b4run/memory-pgvector) — shared Postgres-backed vector memory.
+
+## Maturity and support
+
+B4.run is pre-1.0, and its public surface can change. All publishable B4.run packages release together as a fixed group; review the [`@b4run/memory` changelog](https://github.com/cacheplane/b4run/blob/main/packages/memory/CHANGELOG.md) and [upgrading guide](https://b4.run/docs/upgrading) before upgrading. For support, use [GitHub Discussions](https://github.com/cacheplane/b4run/discussions); report defects in [GitHub Issues](https://github.com/cacheplane/b4run/issues).
+
+## License
+
+MIT. See the [repository license](https://github.com/cacheplane/b4run/blob/main/LICENSE).

package/dist/browse-budget.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The §11 server budgets of the server-controlled-exploration design, as data, plus the
+ * comparison the bench and its test share. Deliberately NOT exported from `index.ts` or
+ * `browse.ts`: this is bench vocabulary, not part of the package's public surface.
+ */
+export type BrowseBudgetId = "windowed-fetch" | "filtered-count" | "head-refresh" | "non-default-sort" | "content-contains";
+/** Ceilings approved for SQLite at 100 000 rows; the margin covers real payload decode.
+ *  Four are grounded in a §5.5 measurement. `head-refresh` is NOT — §5.5 has no row for
+ *  it, and §11 grounds it by extrapolation ("~3-8 ms + decode"), so this bench is the
+ *  first measurement it has ever had. */
+export declare const SQLITE_BROWSE_BUDGETS_MS: Readonly<Partial<Record<BrowseBudgetId, number>>>;
+/** Postgres. §11 approves only two numbers, and BOTH are estimates — no container bench
+ *  has ever run. The other three shapes stay deliberately absent so the checker reports
+ *  them as unbudgeted rather than inventing a ceiling. */
+export declare const POSTGRES_BROWSE_BUDGETS_MS: Readonly<Partial<Record<BrowseBudgetId, number>>>;
+/** Nearest-rank p95. With 20 samples that is the 19th — no interpolation, so the number
+ *  reported is a measurement that actually happened. */
+export declare function percentileMs(samples: readonly number[], fraction: number): number;
+export interface BrowseBudgetRow {
+    readonly id: BrowseBudgetId;
+    /** null only when the shape was never measured. */
+    readonly p95Ms: number | null;
+    readonly budgetMs: number | null;
+    readonly status: "pass" | "fail" | "unbudgeted" | "unmeasured";
+}
+export interface BrowseBudgetReport {
+    readonly rows: readonly BrowseBudgetRow[];
+    readonly ok: boolean;
+}
+/**
+ * A row per measured shape, plus a row per approved ceiling nobody measured. Both holes
+ * are reported rather than skipped, for opposite reasons: a measurement with no ceiling
+ * must not be counted as approval nobody gave, and a ceiling with no measurement must not
+ * let a partial run exit clean — a `--assert` that checked one of five and returned 0
+ * would certify four budgets it never looked at. A zero-sample array is a broken run, not
+ * an absent one, so it fails.
+ */
+export declare function checkBrowseBudgets(measurements: Readonly<Partial<Record<BrowseBudgetId, readonly number[]>>>, budgets: Readonly<Partial<Record<BrowseBudgetId, number>>>): BrowseBudgetReport;
+export declare function formatBrowseBudgetReport(report: BrowseBudgetReport): string;
+//# sourceMappingURL=browse-budget.d.ts.map

package/dist/browse-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browse-budget.d.ts","sourceRoot":"","sources":["../src/browse-budget.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,cAAc,GACtB,gBAAgB,GAChB,gBAAgB,GAChB,cAAc,GACd,kBAAkB,GAClB,kBAAkB,CAAA;AAEtB;;;yCAGyC;AACzC,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC,CAMtF,CAAA;AAED;;0DAE0D;AAC1D,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC,CAGxF,CAAA;AAED;wDACwD;AACxD,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKjF;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAA;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,YAAY,GAAG,YAAY,CAAA;CAC/D;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,SAAS,eAAe,EAAE,CAAA;IACzC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC,EAC1E,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC,GACzD,kBAAkB,CAiBpB;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAQ3E"}

package/dist/browse-budget.js

@@ -0,0 +1,57 @@
+/** Ceilings approved for SQLite at 100 000 rows; the margin covers real payload decode.
+ *  Four are grounded in a §5.5 measurement. `head-refresh` is NOT — §5.5 has no row for
+ *  it, and §11 grounds it by extrapolation ("~3-8 ms + decode"), so this bench is the
+ *  first measurement it has ever had. */
+export const SQLITE_BROWSE_BUDGETS_MS = {
+    "windowed-fetch": 10,
+    "filtered-count": 25,
+    "head-refresh": 50,
+    "non-default-sort": 50,
+    "content-contains": 150,
+};
+/** Postgres. §11 approves only two numbers, and BOTH are estimates — no container bench
+ *  has ever run. The other three shapes stay deliberately absent so the checker reports
+ *  them as unbudgeted rather than inventing a ceiling. */
+export const POSTGRES_BROWSE_BUDGETS_MS = {
+    "windowed-fetch": 30,
+    "filtered-count": 100,
+};
+/** Nearest-rank p95. With 20 samples that is the 19th — no interpolation, so the number
+ *  reported is a measurement that actually happened. */
+export function percentileMs(samples, fraction) {
+    if (samples.length === 0)
+        return Number.NaN;
+    const sorted = [...samples].sort((a, b) => a - b);
+    const rank = Math.max(1, Math.ceil(fraction * sorted.length));
+    return sorted[rank - 1];
+}
+/**
+ * A row per measured shape, plus a row per approved ceiling nobody measured. Both holes
+ * are reported rather than skipped, for opposite reasons: a measurement with no ceiling
+ * must not be counted as approval nobody gave, and a ceiling with no measurement must not
+ * let a partial run exit clean — a `--assert` that checked one of five and returned 0
+ * would certify four budgets it never looked at. A zero-sample array is a broken run, not
+ * an absent one, so it fails.
+ */
+export function checkBrowseBudgets(measurements, budgets) {
+    const rows = [];
+    for (const [id, samples] of Object.entries(measurements)) {
+        const p95Ms = percentileMs(samples, 0.95);
+        const budgetMs = budgets[id] ?? null;
+        // A zero-sample p95 is NaN, and NaN loses every comparison, so the row falls to "fail".
+        const status = budgetMs === null ? "unbudgeted" : p95Ms <= budgetMs ? "pass" : "fail";
+        rows.push({ id, p95Ms, budgetMs, status });
+    }
+    for (const [id, budgetMs] of Object.entries(budgets)) {
+        if (id in measurements)
+            continue;
+        rows.push({ id, p95Ms: null, budgetMs, status: "unmeasured" });
+    }
+    return { rows, ok: rows.every((row) => row.status === "pass" || row.status === "unbudgeted") };
+}
+export function formatBrowseBudgetReport(report) {
+    return report.rows
+        .map((row) => `${row.id.padEnd(20)} p95 ${(row.p95Ms === null ? "—" : row.p95Ms.toFixed(2)).padStart(8)} ms  ` +
+        `budget ${(row.budgetMs === null ? "—" : `${row.budgetMs} ms`).padStart(8)}  ${row.status}`)
+        .join("\n");
+}

package/dist/browse-cursor.d.ts

@@ -0,0 +1,22 @@
+import type { ResolvedBrowseSort } from "./browse-order.js";
+import type { BrowseQuery, MemoryRecord } from "./types.js";
+export declare const BROWSE_CURSOR_VERSION = 1;
+export type BrowseCursorValue = string | number;
+export interface BrowseCursorPayload {
+    /** Raw stored sort-key values, one per ordered field, in order. */
+    readonly key: readonly BrowseCursorValue[];
+    readonly id: string;
+}
+/**
+ * Fingerprint of the query's DATASET IDENTITY — every field that changes which rows
+ * match or in what order, and nothing else. `limit`/`offset`/`cursor` are paging,
+ * not identity. Encoded into every cursor so a continuation can never smuggle its
+ * own query into a different request.
+ */
+export declare function browseQueryFingerprint(query: BrowseQuery): string;
+/** The raw stored values of `record` for the ordered fields, in order. */
+export declare function browseCursorKey(record: MemoryRecord, order: readonly ResolvedBrowseSort[]): readonly BrowseCursorValue[];
+export declare function encodeBrowseCursor(fingerprint: string, payload: BrowseCursorPayload): string;
+/** Decode a continuation and check it against the request's OWN parameters. */
+export declare function decodeBrowseCursor(cursor: string, fingerprint: string, order: readonly ResolvedBrowseSort[]): BrowseCursorPayload;
+//# sourceMappingURL=browse-cursor.d.ts.map

package/dist/browse-cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browse-cursor.d.ts","sourceRoot":"","sources":["../src/browse-cursor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAG3D,OAAO,KAAK,EAAgB,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAEzE,eAAO,MAAM,qBAAqB,IAAI,CAAA;AAEtC,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,CAAA;AAE/C,MAAM,WAAW,mBAAmB;IAClC,mEAAmE;IACnE,QAAQ,CAAC,GAAG,EAAE,SAAS,iBAAiB,EAAE,CAAA;IAC1C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CACpB;AAkED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAcjE;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAC7B,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,SAAS,kBAAkB,EAAE,GACnC,SAAS,iBAAiB,EAAE,CAuB9B;AAED,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAI5F;AAMD,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,SAAS,kBAAkB,EAAE,GACnC,mBAAmB,CA4BrB"}

package/dist/browse-cursor.js

@@ -0,0 +1,146 @@
+import { normalizeSetFilter } from "./browse-filter.js";
+import { resolveBrowseOrder } from "./browse-order.js";
+import { BrowseQueryError } from "./browse-validate.js";
+export const BROWSE_CURSOR_VERSION = 1;
+// btoa/atob + TextEncoder are available in Node 24 AND browsers; Buffer is not, and
+// slice 3's hook imports this module from client code.
+function toBase64Url(json) {
+    const bytes = new TextEncoder().encode(json);
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64Url(cursor) {
+    const base64 = cursor.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64 + "=".repeat((4 - (base64.length % 4)) % 4);
+    const binary = atob(padded);
+    return new TextDecoder().decode(Uint8Array.from(binary, (char) => char.charCodeAt(0)));
+}
+// FNV-1a/32 over UTF-8 bytes, the input the algorithm is defined on: the canonical string
+// carries non-ASCII namespaces and filter values, where UTF-16 code units would diverge.
+// A cursor is server-issued over localhost, so this is a mismatch DETECTOR, not a MAC —
+// and staying dependency-free keeps the module isomorphic.
+function fnv1a32(input) {
+    let hash = 0x811c9dc5;
+    for (const byte of new TextEncoder().encode(input)) {
+        hash ^= byte;
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(16).padStart(8, "0");
+}
+function canonicalFilter(filter) {
+    switch (filter.field) {
+        case "status":
+        case "kind":
+            return `${filter.field}|${filter.op}|${[...filter.values].sort().join(",")}`;
+        case "content":
+        case "namespace":
+            return `${filter.field}|${filter.op}|${filter.value}`;
+        case "confidence":
+            return filter.op === "between"
+                ? `confidence|between|${filter.min}|${filter.max}`
+                : `confidence|${filter.op}|${filter.value}`;
+        case "updatedAt":
+            return filter.op === "betweenDays"
+                ? `updatedAt|betweenDays|${filter.fromDay}|${filter.untilDay}`
+                : `updatedAt|${filter.op}|${filter.day}`;
+        default: {
+            // In-process callers are trusted past validateBrowseQuery, so an unmapped field
+            // arrives here unchecked. Borrowing another field's canonical form would hand two
+            // different datasets ONE fingerprint — the collision this whole function prevents.
+            const unmapped = filter;
+            throw new BrowseQueryError(`unknown filter field ${JSON.stringify(unmapped.field)}`);
+        }
+    }
+}
+/** A set filter is a SET, so member order is not identity. `undefined` (no filter, every
+ *  row) stays distinct from `[]` (matches nothing) — see `normalizeSetFilter`. */
+function canonicalSet(value) {
+    const values = normalizeSetFilter(value);
+    return values === undefined ? null : [...values].sort();
+}
+/**
+ * Fingerprint of the query's DATASET IDENTITY — every field that changes which rows
+ * match or in what order, and nothing else. `limit`/`offset`/`cursor` are paging,
+ * not identity. Encoded into every cursor so a continuation can never smuggle its
+ * own query into a different request.
+ */
+export function browseQueryFingerprint(query) {
+    const canonical = JSON.stringify({
+        namespace: query.namespace ?? null,
+        namespacePrefix: query.namespacePrefix ?? null,
+        status: canonicalSet(query.status),
+        kind: canonicalSet(query.kind),
+        sourceType: query.sourceType ?? null,
+        since: query.since ?? null,
+        until: query.until ?? null,
+        now: query.now ?? null,
+        filters: (query.filters ?? []).map(canonicalFilter).sort(),
+        order: resolveBrowseOrder(query.orderBy).map((entry) => `${entry.field}:${entry.dir}`),
+    });
+    return fnv1a32(canonical);
+}
+/** The raw stored values of `record` for the ordered fields, in order. */
+export function browseCursorKey(record, order) {
+    return order.map((entry) => {
+        switch (entry.field) {
+            case "updatedAt":
+                return record.updatedAt;
+            case "createdAt":
+                return record.createdAt;
+            case "confidence":
+                return record.confidence;
+            case "namespace":
+                return record.namespace;
+            case "kind":
+                return record.kind;
+            case "status":
+                return record.status;
+            default: {
+                // A stand-in value here is a key read off the WRONG column: the next page then
+                // continues from a boundary that never existed in this ordering.
+                const unmapped = entry.field;
+                throw new BrowseQueryError(`unknown sort field ${JSON.stringify(unmapped)}`);
+            }
+        }
+    });
+}
+export function encodeBrowseCursor(fingerprint, payload) {
+    return toBase64Url(JSON.stringify({ v: BROWSE_CURSOR_VERSION, fp: fingerprint, key: payload.key, id: payload.id }));
+}
+function invalid(reason) {
+    throw new BrowseQueryError(reason, "continuation-invalid");
+}
+/** Decode a continuation and check it against the request's OWN parameters. */
+export function decodeBrowseCursor(cursor, fingerprint, order) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fromBase64Url(cursor));
+    }
+    catch {
+        invalid("cursor is not decodable");
+    }
+    const decoded = parsed;
+    if (decoded?.v !== BROWSE_CURSOR_VERSION)
+        invalid("cursor version is not supported");
+    if (decoded.fp !== fingerprint)
+        invalid("cursor belongs to a different query");
+    if (!Array.isArray(decoded.key) || decoded.key.length !== order.length)
+        invalid("cursor key does not match the requested sort order");
+    // Checked against the ORDERED FIELD, not merely "some string or number": a cursor is
+    // unauthenticated, and a text value bound against a numeric column is compared across
+    // SQLite's storage classes — every number sorts below every string, so the keyset
+    // boundary silently admits every row — while Postgres rejects the ::real bind outright.
+    for (const [index, entry] of order.entries()) {
+        const value = decoded.key[index];
+        const wellTyped = entry.numeric
+            ? typeof value === "number" && Number.isFinite(value)
+            : typeof value === "string";
+        if (!wellTyped)
+            invalid(`cursor key for "${entry.field}" must be ${entry.numeric ? "a finite number" : "a string"}`);
+    }
+    if (typeof decoded.id !== "string" || decoded.id.length === 0)
+        invalid("cursor id is missing");
+    return { key: decoded.key, id: decoded.id };
+}

package/dist/browse-filter.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Normalise a `BrowseQuery` filter that accepts either one value or a set.
+ *
+ * Returns `undefined` when the caller did not filter on the field at all, and
+ * an array otherwise — including the empty array, which is a filter that
+ * matches nothing rather than an absent one. Backends must keep that
+ * distinction: `IN ()` is false, while "no clause" is true for every row.
+ *
+ * Exported so the sqlite and Postgres stores share one reading of the contract
+ * instead of each interpreting the union themselves.
+ */
+export declare function normalizeSetFilter<T extends string>(value: T | readonly T[] | undefined): readonly T[] | undefined;
+//# sourceMappingURL=browse-filter.d.ts.map

package/dist/browse-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browse-filter.d.ts","sourceRoot":"","sources":["../src/browse-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,EACjD,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC,EAAE,GAAG,SAAS,GAClC,SAAS,CAAC,EAAE,GAAG,SAAS,CAG1B"}

package/dist/browse-filter.js

@@ -0,0 +1,16 @@
+/**
+ * Normalise a `BrowseQuery` filter that accepts either one value or a set.
+ *
+ * Returns `undefined` when the caller did not filter on the field at all, and
+ * an array otherwise — including the empty array, which is a filter that
+ * matches nothing rather than an absent one. Backends must keep that
+ * distinction: `IN ()` is false, while "no clause" is true for every row.
+ *
+ * Exported so the sqlite and Postgres stores share one reading of the contract
+ * instead of each interpreting the union themselves.
+ */
+export function normalizeSetFilter(value) {
+    if (value === undefined)
+        return undefined;
+    return typeof value === "string" ? [value] : value;
+}

package/dist/browse-order.d.ts

@@ -0,0 +1,28 @@
+import type { BrowseSortEntry, BrowseSortField } from "./types.js";
+export interface ResolvedBrowseSort {
+    readonly field: BrowseSortField;
+    /** Physical column. Comes from the table below and NOWHERE else — this is the
+     *  only place a browse sort name becomes a SQL identifier. */
+    readonly column: string;
+    readonly dir: "asc" | "desc";
+    /** Postgres binds JS numbers as float8; a float4 column needs a `::real` cast on
+     *  the parameter or equality against a stored value is false. Postgres also STORES
+     *  confidence as float4, so two confidences that differ only below float4 precision
+     *  are equal at rest there and still distinct on SQLite — ordering by confidence
+     *  then falls to the id tie-break on one backend and not the other. */
+    readonly numeric: boolean;
+    /** Postgres needs COLLATE "C" here to match SQLite's BINARY order. Deliberately
+     *  FALSE for updated_at/created_at: they are uniform ASCII (so every collation
+     *  agrees) AND the (updated_at DESC, id ASC) index is uncollated — a collated
+     *  ORDER BY would stop matching it and turn the hot path into a sort. FALSE for
+     *  kind/status on unrelated grounds: they are closed lowercase-ASCII enums, so no
+     *  collation can reorder them. Nothing but TypeScript holds that — neither schema
+     *  has a CHECK — and a member outside `[a-z]+` would need this flipped to true. */
+    readonly collateC: boolean;
+}
+/** The documented reset state: newest first. `resolveBrowseOrder` hands out THIS array,
+ *  so it is frozen — the stores' `id ASC` tie-break goes into a new list, and a store
+ *  that appends in place fails loudly instead of rewriting the default process-wide. */
+export declare const DEFAULT_BROWSE_ORDER: readonly ResolvedBrowseSort[];
+export declare function resolveBrowseOrder(orderBy?: readonly BrowseSortEntry[]): readonly ResolvedBrowseSort[];
+//# sourceMappingURL=browse-order.d.ts.map

package/dist/browse-order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browse-order.d.ts","sourceRoot":"","sources":["../src/browse-order.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAElE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;IAC/B;kEAC8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,GAAG,EAAE,KAAK,GAAG,MAAM,CAAA;IAC5B;;;;2EAIuE;IACvE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB;;;;;;uFAMmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B;AAgBD;;wFAEwF;AACxF,eAAO,MAAM,oBAAoB,EAAE,SAAS,kBAAkB,EAE5D,CAAA;AAEF,wBAAgB,kBAAkB,CAChC,OAAO,CAAC,EAAE,SAAS,eAAe,EAAE,GACnC,SAAS,kBAAkB,EAAE,CAqB/B"}

package/dist/browse-order.js

@@ -0,0 +1,37 @@
+import { BrowseQueryError } from "./browse-validate.js";
+const COLUMNS = {
+    updatedAt: { column: "updated_at", numeric: false, collateC: false },
+    createdAt: { column: "created_at", numeric: false, collateC: false },
+    confidence: { column: "confidence", numeric: true, collateC: false },
+    namespace: { column: "namespace", numeric: false, collateC: true },
+    kind: { column: "kind", numeric: false, collateC: false },
+    status: { column: "status", numeric: false, collateC: false },
+};
+/** The documented reset state: newest first. `resolveBrowseOrder` hands out THIS array,
+ *  so it is frozen — the stores' `id ASC` tie-break goes into a new list, and a store
+ *  that appends in place fails loudly instead of rewriting the default process-wide. */
+export const DEFAULT_BROWSE_ORDER = Object.freeze([
+    Object.freeze({ field: "updatedAt", ...COLUMNS.updatedAt, dir: "desc" }),
+]);
+export function resolveBrowseOrder(orderBy) {
+    if (!orderBy || orderBy.length === 0)
+        return DEFAULT_BROWSE_ORDER;
+    return orderBy.map((entry) => {
+        const meta = COLUMNS[entry.field];
+        // Defence in depth: validateBrowseQuery already rejected this, but a store
+        // must never interpolate an unmapped name.
+        if (!meta)
+            throw new BrowseQueryError(`unknown sort field ${JSON.stringify(entry.field)}`);
+        // Checked HERE rather than trusted to each dialect's `dir === "desc" ? … : …`, so the
+        // whitelist is the single gate every part of an ORDER BY passes through.
+        if (entry.dir !== "asc" && entry.dir !== "desc")
+            throw new BrowseQueryError(`sort direction must be "asc" or "desc", got ${JSON.stringify(entry.dir)}`);
+        return {
+            field: entry.field,
+            column: meta.column,
+            dir: entry.dir,
+            numeric: meta.numeric,
+            collateC: meta.collateC,
+        };
+    });
+}

package/dist/browse-range.d.ts

@@ -0,0 +1,16 @@
+/** Inclusive lower bound of a UTC day, in the stored full-ISO-Z form. */
+export declare function utcDayStart(day: string): string;
+/** EXCLUSIVE upper bound of a UTC day — the next day's start. UTC has no DST, so
+ *  adding 24h is exact. */
+export declare function utcDayAfter(day: string): string;
+/**
+ * Smallest string strictly greater than every string starting with `prefix`, so a
+ * prefix match becomes the sargable range `col >= prefix AND col < succ(prefix)`.
+ * Strip trailing maximal code points, increment the last remaining one; an
+ * all-maximal prefix has no upper bound (undefined = omit the clause).
+ *
+ * Defined over CODE POINTS, which is order-equivalent to UTF-8 byte order — the
+ * order SQLite's BINARY collation and Postgres's COLLATE "C" both use.
+ */
+export declare function namespacePrefixUpperBound(prefix: string): string | undefined;
+//# sourceMappingURL=browse-range.d.ts.map

package/dist/browse-range.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browse-range.d.ts","sourceRoot":"","sources":["../src/browse-range.ts"],"names":[],"mappings":"AAkBA,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG/C;AAED;2BAC2B;AAC3B,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/C;AAMD;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAY5E"}

package/dist/browse-range.js

@@ -0,0 +1,52 @@
+import { BrowseQueryError } from "./browse-validate.js";
+const DAY_MS = 86_400_000;
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+/** Defence in depth, the same posture as browse-order: validateBrowseQuery already
+ *  rejected this, but an unchecked day becomes a bound no stored row can sit at —
+ *  a silently empty window instead of a 400. */
+function checkDay(day) {
+    if (!DAY.test(day))
+        throw new BrowseQueryError(`day must be a "YYYY-MM-DD" UTC day, got ${JSON.stringify(day)}`);
+    // Out-of-range components ROLL OVER rather than fail to parse: "2026-02-31" reads as
+    // March 3, so only a day that round-trips names the date it spells.
+    const parsed = Date.parse(`${day}T00:00:00.000Z`);
+    if (!Number.isFinite(parsed) || new Date(parsed).toISOString().slice(0, 10) !== day)
+        throw new BrowseQueryError(`day ${JSON.stringify(day)} is not a real calendar day`);
+}
+/** Inclusive lower bound of a UTC day, in the stored full-ISO-Z form. */
+export function utcDayStart(day) {
+    checkDay(day);
+    return `${day}T00:00:00.000Z`;
+}
+/** EXCLUSIVE upper bound of a UTC day — the next day's start. UTC has no DST, so
+ *  adding 24h is exact. */
+export function utcDayAfter(day) {
+    return new Date(Date.parse(utcDayStart(day)) + DAY_MS).toISOString();
+}
+const MAX_CODE_POINT = 0x10ffff;
+const SURROGATE_START = 0xd800;
+const SURROGATE_END = 0xdfff;
+/**
+ * Smallest string strictly greater than every string starting with `prefix`, so a
+ * prefix match becomes the sargable range `col >= prefix AND col < succ(prefix)`.
+ * Strip trailing maximal code points, increment the last remaining one; an
+ * all-maximal prefix has no upper bound (undefined = omit the clause).
+ *
+ * Defined over CODE POINTS, which is order-equivalent to UTF-8 byte order — the
+ * order SQLite's BINARY collation and Postgres's COLLATE "C" both use.
+ */
+export function namespacePrefixUpperBound(prefix) {
+    const points = Array.from(prefix);
+    for (let i = points.length - 1; i >= 0; i -= 1) {
+        const codePoint = points[i]?.codePointAt(0);
+        if (codePoint === undefined || codePoint >= MAX_CODE_POINT)
+            continue;
+        let next = codePoint + 1;
+        // Surrogates are not valid scalar values; skipping the block keeps the bound a
+        // legal string while staying an upper bound (nothing sorts between D7FF and E000).
+        if (next >= SURROGATE_START && next <= SURROGATE_END)
+            next = SURROGATE_END + 1;
+        return points.slice(0, i).join("") + String.fromCodePoint(next);
+    }
+    return undefined;
+}

package/dist/browse-validate.d.ts

@@ -0,0 +1,31 @@
+import type { BrowseQuery } from "./types.js";
+/** Largest `limit` the UNTRUSTED boundary accepts. Enforced only when a caller passes
+ *  `maxLimit` — in-process callers (the CLI's 10 000-row consolidation scan) are
+ *  trusted and exempt; the HTTP route is not. */
+export declare const BROWSE_MAX_LIMIT = 1000;
+/** Applied by the stores when `limit` is absent. */
+export declare const BROWSE_DEFAULT_LIMIT = 50;
+export declare const BROWSE_SORT_FIELDS: readonly ["updatedAt", "createdAt", "confidence", "namespace", "kind", "status"];
+/** Every rejection this module raises. The Inspector maps it to 400 `{error}`; the
+ *  stores let it propagate, so a bad query fails loudly instead of silently matching
+ *  zero rows. */
+export declare class BrowseQueryError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
+}
+/**
+ * The single reading of "is this browse query legal". Runs at the Inspector HTTP
+ * boundary (mapped to 400) and defensively inside every store (thrown). Pass
+ * `maxLimit` at untrusted boundaries only — see BROWSE_MAX_LIMIT.
+ *
+ * The empty set is spelled two ways and they do NOT mean the same thing. The shorthand
+ * `status: []` / `kind: []` is legal and means "match nothing" (see `BrowseQuery`), while
+ * `filters: [{ field: "status", op: "in", values: [] }]` is rejected: a filter entry exists
+ * only because a caller constructed one, so an empty value list is a construction bug
+ * rather than a narrowing. A caller translating UI state must use the shorthand to say
+ * "narrowed to nothing".
+ */
+export declare function validateBrowseQuery(query: BrowseQuery, opts?: {
+    readonly maxLimit?: number;
+}): void;
+//# sourceMappingURL=browse-validate.d.ts.map

package/dist/browse-validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browse-validate.d.ts","sourceRoot":"","sources":["../src/browse-validate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,WAAW,EAKZ,MAAM,YAAY,CAAA;AAEnB;;iDAEiD;AACjD,eAAO,MAAM,gBAAgB,OAAO,CAAA;AACpC,oDAAoD;AACpD,eAAO,MAAM,oBAAoB,KAAK,CAAA;AAYtC,eAAO,MAAM,kBAAkB,kFAOgB,CAAA;AAyD/C;;iBAEiB;AACjB,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,YAAY,OAAO,EAAE,MAAM,EAAE,IAAI,SAAkB,EAIlD;CACF;AAmHD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,IAAI,GAAE;IAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GACxC,IAAI,CA0DN"}