@nacre.work/api 0.0.0 → 0.2.0

package/dist/pagination.d.ts

@@ -0,0 +1,72 @@
+import { type Problem } from './errors.js';
+/**
+ * Cursor pagination, and never offset.
+ *
+ * `docs/api.md` forbids offset on two grounds and both are real. It breaks
+ * under concurrent inserts — a row added while a client pages through shifts
+ * everything after it, so the client sees an item twice or not at all. And it
+ * invites enumeration: `?offset=10000` is a question about how much exists,
+ * which on a permission-scoped collection is a question the caller has no right
+ * to ask.
+ *
+ * The cursor is a position, not an index. It carries the sort key of the last
+ * item returned, so the next page is "everything after this one" — which is
+ * stable no matter what was inserted in between, and says nothing about size.
+ *
+ * ## Opaque, and only just
+ *
+ * It is base64url of `created_at|id`, which anyone can decode, and that is
+ * fine: both values are already in the response they came from. What matters is
+ * that it is *treated* as opaque — a client that parses it and constructs its
+ * own has built a dependency on a format that is allowed to change, and the
+ * signature check below is what tells them so before it becomes their problem.
+ *
+ * It is not signed. A forged cursor selects a different page of the same
+ * caller's own collection, which they could reach by paging anyway; signing it
+ * would defend nothing and imply a guarantee that does not exist.
+ */
+export declare const MAX_LIMIT = 200;
+export declare const DEFAULT_LIMIT = 50;
+export interface Position {
+    /** The sort key of the last item on the previous page. */
+    readonly createdAt: string;
+    /** Tie-breaker, because timestamps collide under a bulk insert. */
+    readonly id: string;
+}
+export interface Page {
+    readonly limit: number;
+    readonly after: Position | undefined;
+}
+export declare function encodeCursor(position: Position): string;
+/**
+ * Read `?limit=` and `?cursor=`, or explain what is wrong with them.
+ *
+ * `?offset=` is refused rather than ignored. Ignoring it gives a client the
+ * first page over and over while they believe they are paging, which is the
+ * failure that takes an afternoon to see.
+ */
+export declare function readPage(params: URLSearchParams, instance: string, requestId: string): Page | Problem;
+/**
+ * What a paginated port returns.
+ *
+ * `items` and the cursor are separate because they are not always derived from
+ * the same row. Where a collection is filtered in application code after the
+ * database has already applied the cursor — grants are, because who may see one
+ * is decided by walking the scope tree — the cursor has to come from the last
+ * row **fetched** rather than the last one returned. Taking it from the last
+ * returned row would skip everything the filter removed after it.
+ *
+ * The consequence, which callers have to know: **a page may hold fewer than
+ * `limit` items, and an empty page does not mean the end.** `nextCursor` is the
+ * only signal that more exist.
+ */
+export interface PageResult<T> {
+    readonly items: readonly T[];
+    readonly nextCursor: string | null;
+}
+/**
+ * The common case: rows come back already filtered, so the cursor is the last
+ * one returned and a short page means the collection is exhausted.
+ */
+export declare function pageOf<T>(rows: readonly T[], page: Page | undefined, positionOf: (row: T) => Position): PageResult<T>;
+//# sourceMappingURL=pagination.d.ts.map

package/dist/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,OAAO,EAAE,MAAM,aAAa,CAAA;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,eAAO,MAAM,SAAS,MAAM,CAAA;AAC5B,eAAO,MAAM,aAAa,KAAK,CAAA;AAE/B,MAAM,WAAW,QAAQ;IACvB,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,CAAA;CACrC;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAEvD;AAoCD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,IAAI,GAAG,OAAO,CAoChB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAA;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CACnC;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,CAAC,EACtB,IAAI,EAAE,SAAS,CAAC,EAAE,EAClB,IAAI,EAAE,IAAI,GAAG,SAAS,EACtB,UAAU,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,QAAQ,GAC/B,UAAU,CAAC,CAAC,CAAC,CAIf"}

package/dist/pagination.js

@@ -0,0 +1,110 @@
+import { badRequest } from './errors.js';
+/**
+ * Cursor pagination, and never offset.
+ *
+ * `docs/api.md` forbids offset on two grounds and both are real. It breaks
+ * under concurrent inserts — a row added while a client pages through shifts
+ * everything after it, so the client sees an item twice or not at all. And it
+ * invites enumeration: `?offset=10000` is a question about how much exists,
+ * which on a permission-scoped collection is a question the caller has no right
+ * to ask.
+ *
+ * The cursor is a position, not an index. It carries the sort key of the last
+ * item returned, so the next page is "everything after this one" — which is
+ * stable no matter what was inserted in between, and says nothing about size.
+ *
+ * ## Opaque, and only just
+ *
+ * It is base64url of `created_at|id`, which anyone can decode, and that is
+ * fine: both values are already in the response they came from. What matters is
+ * that it is *treated* as opaque — a client that parses it and constructs its
+ * own has built a dependency on a format that is allowed to change, and the
+ * signature check below is what tells them so before it becomes their problem.
+ *
+ * It is not signed. A forged cursor selects a different page of the same
+ * caller's own collection, which they could reach by paging anyway; signing it
+ * would defend nothing and imply a guarantee that does not exist.
+ */
+export const MAX_LIMIT = 200;
+export const DEFAULT_LIMIT = 50;
+export function encodeCursor(position) {
+    return Buffer.from(`${position.createdAt}|${position.id}`, 'utf8').toString('base64url');
+}
+function decodeCursor(cursor) {
+    let decoded;
+    try {
+        decoded = Buffer.from(cursor, 'base64url').toString('utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const at = decoded.lastIndexOf('|');
+    if (at === -1)
+        return undefined;
+    const createdAt = decoded.slice(0, at);
+    const id = decoded.slice(at + 1);
+    // A cursor that does not carry a timestamp and an identifier is not one this
+    // API issued, whatever it decodes to.
+    //
+    // A uuid **or** a run of digits: every paged collection here is keyed by uuid
+    // except `audit_events`, whose primary key is a bigserial — an audit log is
+    // append-only and strictly ordered, and a sequence says so in a way a random
+    // uuid does not.
+    //
+    // Widening the format does not weaken anything, and it is worth saying why
+    // rather than leaving the next reader to work it out. The cursor is not a
+    // security boundary: it is not signed, it is decodable by anyone, and a
+    // forged one selects a different page of the caller's *own* collection —
+    // which they could reach by paging. What this check is for is telling a
+    // client that built its own cursor that it has taken a dependency on a format
+    // allowed to change, before that becomes their problem.
+    if (Number.isNaN(Date.parse(createdAt)))
+        return undefined;
+    if (!/^[0-9a-f-]{36}$/i.test(id) && !/^\d{1,19}$/.test(id))
+        return undefined;
+    return { createdAt, id };
+}
+/**
+ * Read `?limit=` and `?cursor=`, or explain what is wrong with them.
+ *
+ * `?offset=` is refused rather than ignored. Ignoring it gives a client the
+ * first page over and over while they believe they are paging, which is the
+ * failure that takes an afternoon to see.
+ */
+export function readPage(params, instance, requestId) {
+    if (params.has('offset')) {
+        return badRequest(instance, requestId, "'offset' is not supported. Use '?cursor=' — offset paging skips and repeats rows " +
+            'when the collection changes underneath it.');
+    }
+    let limit = DEFAULT_LIMIT;
+    const raw = params.get('limit');
+    if (raw !== null) {
+        const value = Number(raw);
+        if (!Number.isInteger(value) || value < 1 || value > MAX_LIMIT) {
+            return badRequest(instance, requestId, `'limit' must be an integer between 1 and ${MAX_LIMIT}.`);
+        }
+        limit = value;
+    }
+    let after;
+    const cursor = params.get('cursor');
+    if (cursor !== null && cursor !== '') {
+        const position = decodeCursor(cursor);
+        if (position === undefined) {
+            return badRequest(instance, requestId, "'cursor' is not one this API issued. Cursors are opaque — pass back the " +
+                '`next_cursor` from the previous page rather than constructing one.');
+        }
+        after = position;
+    }
+    return { limit, after };
+}
+/**
+ * The common case: rows come back already filtered, so the cursor is the last
+ * one returned and a short page means the collection is exhausted.
+ */
+export function pageOf(rows, page, positionOf) {
+    if (page === undefined || rows.length < page.limit)
+        return { items: rows, nextCursor: null };
+    const last = rows[rows.length - 1];
+    return { items: rows, nextCursor: last === undefined ? null : encodeCursor(positionOf(last)) };
+}
+//# sourceMappingURL=pagination.js.map

package/dist/pagination.js.map

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

package/dist/rerank.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Cross-encoder reranking.
+ *
+ * `docs/architecture.md` has specified this since the beginning — "a
+ * cross-encoder rerank of the top 50 down to top-k. Reranking buys more quality
+ * than any amount of chunking tuning and is on by default" — and the search
+ * path has never called one.
+ *
+ * ## Why this is not the post-filter invariant I2 forbids
+ *
+ * It looks like it. I2 says `top_k` is passed through uncorrected and that
+ * asking for more and trimming is forbidden; this asks for fifty and returns
+ * ten. The difference is what the trim decides.
+ *
+ * The forbidden pattern trims on **permission**: fetch k results, drop the ones
+ * the caller may not see, return what is left. That returns fewer than k
+ * permitted results — the caller's last page silently shrinks, and how much it
+ * shrinks by is a measurement of what exists but is invisible to them. It also
+ * costs more, because the index ranked documents it then threw away.
+ *
+ * This trims on **relevance**, over a set that is already entirely permitted.
+ * The ACL filter runs inside the index traversal exactly as before, so all
+ * fifty candidates are ones this caller may read; reordering them and keeping
+ * ten changes which permitted results are returned, never how many. The test
+ * that separates the two: **can the number of results ever be smaller than the
+ * number of permitted matches, up to k?** For a post-filter, yes. Here, no.
+ *
+ * That is the whole justification, and it is worth stating in the code rather
+ * than in a commit message, because the next person to read the search path
+ * will see an over-fetch and reach for the rule.
+ *
+ * ## Failing closed, which is the other way round from the rate limiter
+ *
+ * If the reranker is unreachable the search still answers, in fusion order,
+ * with a metric recording that it degraded. This is not a contradiction of
+ * invariant 3: reranking decides *ordering*, and every candidate in the list
+ * was already permitted before the reranker saw it. Refusing the search would
+ * make an optional quality component into a hard dependency of the product's
+ * central operation.
+ *
+ * What it must never do is fail *quietly* — an operator who turned reranking on
+ * is entitled to know it is not running, so degradation is a counter and a log
+ * line rather than a silent fallback.
+ */
+export interface Reranker {
+    /**
+     * Score each text against the query. One score per input, **in input order**.
+     *
+     * Returning scores rather than a sorted list is deliberate: the caller holds
+     * the hits, and a reordered list of texts cannot be matched back to them
+     * without an index that a wrong implementation would get to choose.
+     */
+    rank(query: string, texts: readonly string[]): Promise<readonly number[]>;
+}
+/**
+ * Text Embeddings Inference's `/rerank`, which is what the `full` and
+ * `airgapped` Compose profiles run.
+ *
+ * The response is `[{index, score}, …]` sorted by score, so the index is the
+ * only thing tying a score back to its input. Trusting the order instead would
+ * attach the wrong score to the wrong chunk and be invisible in every test that
+ * does not check ranking against known-relevant text.
+ */
+export declare class HttpReranker implements Reranker {
+    private readonly endpoint;
+    private readonly timeoutMs;
+    constructor(endpoint: string, timeoutMs?: number);
+    rank(query: string, texts: readonly string[]): Promise<readonly number[]>;
+}
+/**
+ * The reranker a configuration asks for, or none.
+ *
+ * One factory rather than the same three lines in the API process and in the
+ * MCP one. They share a search service and must not disagree about whether
+ * results are reranked — two surfaces over one index answering in different
+ * orders is the kind of difference nobody reports as a bug and everybody
+ * notices.
+ *
+ * `loadConfig` already refuses the contradictory case (enabled with no
+ * endpoint) at startup, so there is nothing to validate here.
+ */
+export declare function rerankerFor(config: {
+    readonly rerankerEnabled: boolean;
+    readonly rerankerEndpoint: string | undefined;
+}): Reranker | undefined;
+/**
+ * Reorder hits by a reranker's scores and keep the best `topK`.
+ *
+ * Separate from the transport so the ordering rule can be tested without a
+ * model server — the rule being the part that is easy to get subtly wrong.
+ *
+ * The sort is stable in the sense that matters: ties keep the fusion order they
+ * arrived in, because `Array.prototype.sort` is stable and the comparator
+ * answers 0 for equal scores. A cross-encoder returning identical scores for
+ * two chunks is saying it cannot separate them, and falling back to the index's
+ * own ranking is a better answer than an arbitrary one.
+ */
+export declare function applyRanking<T>(items: readonly T[], scores: readonly number[], topK: number): T[];
+//# sourceMappingURL=rerank.d.ts.map

package/dist/rerank.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rerank.d.ts","sourceRoot":"","sources":["../src/rerank.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,MAAM,WAAW,QAAQ;IACvB;;;;;;OAMG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAA;CAC1E;AAED;;;;;;;;GAQG;AACH,qBAAa,YAAa,YAAW,QAAQ;IAEzC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBADT,QAAQ,EAAE,MAAM,EAChB,SAAS,SAAO;IAG7B,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC;CA0ChF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE;IAClC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAA;IACjC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAA;CAC9C,GAAG,QAAQ,GAAG,SAAS,CAGvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,EAAE,CASjG"}

package/dist/rerank.js

@@ -0,0 +1,138 @@
+/**
+ * Cross-encoder reranking.
+ *
+ * `docs/architecture.md` has specified this since the beginning — "a
+ * cross-encoder rerank of the top 50 down to top-k. Reranking buys more quality
+ * than any amount of chunking tuning and is on by default" — and the search
+ * path has never called one.
+ *
+ * ## Why this is not the post-filter invariant I2 forbids
+ *
+ * It looks like it. I2 says `top_k` is passed through uncorrected and that
+ * asking for more and trimming is forbidden; this asks for fifty and returns
+ * ten. The difference is what the trim decides.
+ *
+ * The forbidden pattern trims on **permission**: fetch k results, drop the ones
+ * the caller may not see, return what is left. That returns fewer than k
+ * permitted results — the caller's last page silently shrinks, and how much it
+ * shrinks by is a measurement of what exists but is invisible to them. It also
+ * costs more, because the index ranked documents it then threw away.
+ *
+ * This trims on **relevance**, over a set that is already entirely permitted.
+ * The ACL filter runs inside the index traversal exactly as before, so all
+ * fifty candidates are ones this caller may read; reordering them and keeping
+ * ten changes which permitted results are returned, never how many. The test
+ * that separates the two: **can the number of results ever be smaller than the
+ * number of permitted matches, up to k?** For a post-filter, yes. Here, no.
+ *
+ * That is the whole justification, and it is worth stating in the code rather
+ * than in a commit message, because the next person to read the search path
+ * will see an over-fetch and reach for the rule.
+ *
+ * ## Failing closed, which is the other way round from the rate limiter
+ *
+ * If the reranker is unreachable the search still answers, in fusion order,
+ * with a metric recording that it degraded. This is not a contradiction of
+ * invariant 3: reranking decides *ordering*, and every candidate in the list
+ * was already permitted before the reranker saw it. Refusing the search would
+ * make an optional quality component into a hard dependency of the product's
+ * central operation.
+ *
+ * What it must never do is fail *quietly* — an operator who turned reranking on
+ * is entitled to know it is not running, so degradation is a counter and a log
+ * line rather than a silent fallback.
+ */
+/**
+ * Text Embeddings Inference's `/rerank`, which is what the `full` and
+ * `airgapped` Compose profiles run.
+ *
+ * The response is `[{index, score}, …]` sorted by score, so the index is the
+ * only thing tying a score back to its input. Trusting the order instead would
+ * attach the wrong score to the wrong chunk and be invisible in every test that
+ * does not check ranking against known-relevant text.
+ */
+export class HttpReranker {
+    endpoint;
+    timeoutMs;
+    constructor(endpoint, timeoutMs = 3000) {
+        this.endpoint = endpoint;
+        this.timeoutMs = timeoutMs;
+    }
+    async rank(query, texts) {
+        if (texts.length === 0)
+            return [];
+        // A search that would otherwise have answered must not hang because a model
+        // server is wedged; the caller treats a timeout as a degradation.
+        const abort = AbortSignal.timeout(this.timeoutMs);
+        const response = await fetch(new URL('/rerank', this.endpoint), {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ query, texts: [...texts], raw_scores: false }),
+            signal: abort,
+        });
+        if (!response.ok)
+            throw new Error(`the reranker answered ${response.status}`);
+        const body = (await response.json());
+        if (!Array.isArray(body))
+            throw new Error('the reranker did not answer with a list');
+        const scores = new Array(texts.length).fill(Number.NEGATIVE_INFINITY);
+        let seen = 0;
+        for (const entry of body) {
+            const { index, score } = entry;
+            if (typeof index !== 'number' || typeof score !== 'number') {
+                throw new Error('a reranker result carried no index and score');
+            }
+            if (index < 0 || index >= texts.length) {
+                throw new Error(`the reranker scored index ${index} for ${texts.length} inputs`);
+            }
+            scores[index] = score;
+            seen++;
+        }
+        if (seen !== texts.length) {
+            // A short answer would leave some chunks at -Infinity and sink them to the
+            // bottom, which is a silent quality loss rather than a visible failure.
+            throw new Error(`the reranker scored ${seen} of ${texts.length} inputs`);
+        }
+        return scores;
+    }
+}
+/**
+ * The reranker a configuration asks for, or none.
+ *
+ * One factory rather than the same three lines in the API process and in the
+ * MCP one. They share a search service and must not disagree about whether
+ * results are reranked — two surfaces over one index answering in different
+ * orders is the kind of difference nobody reports as a bug and everybody
+ * notices.
+ *
+ * `loadConfig` already refuses the contradictory case (enabled with no
+ * endpoint) at startup, so there is nothing to validate here.
+ */
+export function rerankerFor(config) {
+    if (!config.rerankerEnabled || config.rerankerEndpoint === undefined)
+        return undefined;
+    return new HttpReranker(config.rerankerEndpoint);
+}
+/**
+ * Reorder hits by a reranker's scores and keep the best `topK`.
+ *
+ * Separate from the transport so the ordering rule can be tested without a
+ * model server — the rule being the part that is easy to get subtly wrong.
+ *
+ * The sort is stable in the sense that matters: ties keep the fusion order they
+ * arrived in, because `Array.prototype.sort` is stable and the comparator
+ * answers 0 for equal scores. A cross-encoder returning identical scores for
+ * two chunks is saying it cannot separate them, and falling back to the index's
+ * own ranking is a better answer than an arbitrary one.
+ */
+export function applyRanking(items, scores, topK) {
+    if (scores.length !== items.length) {
+        throw new Error(`the reranker returned ${scores.length} scores for ${items.length} items`);
+    }
+    return items
+        .map((item, i) => ({ item, score: scores[i] }))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, topK)
+        .map((s) => s.item);
+}
+//# sourceMappingURL=rerank.js.map

package/dist/rerank.js.map

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