@grimoire-rs/indexer 0.3.3 → 0.4.1

package/dist/ratings/config.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Forges a rating can be collected on. The same two names as CI's [`Forge`],
+ * and deliberately a separate type: an index hosted on one forge could tally
+ * on the other, and nothing here needs them to move together.
+ */
+export type RatingProviderKind = "github" | "gitlab";
+export declare const RATING_PROVIDERS: readonly RatingProviderKind[];
+/** Per-run thread-creation budget when the config names none. */
+export declare const DEFAULT_CREATE_BUDGET = 400;
+/**
+ * The `ratings` block, with every gap filled. The block being absent means
+ * ratings are off — that is the *absence* of this value, not a variant of it,
+ * so every reader gets `undefined` and has nothing to branch on twice.
+ */
+export interface RatingsConfig {
+    /** Which forge holds the threads. Required — there is no sensible default. */
+    provider: RatingProviderKind;
+    /**
+     * Where threads live: a GitHub Discussions **category** name, or a GitLab
+     * **work item type**. Required, and no default is offered — "Ratings" is a
+     * category an operator creates, while GitLab's work item types are a closed
+     * set, so a default correct on one forge would be wrong on the other.
+     */
+    container: string;
+    /**
+     * Threads created per run. Default {@link DEFAULT_CREATE_BUDGET}, which sits
+     * under GitHub's 500-per-hour content-creation cap with room for the retries
+     * a run may spend. A partial run creates *fewer threads*, never corrupt
+     * state, so the only cost of a small budget is more runs to converge.
+     */
+    createBudget: number;
+    /**
+     * Lock every thread on creation. **Default `true`**: votes still count,
+     * replies are refused.
+     *
+     * Two things at once. It is the low-moderation default — an operator gets a
+     * rating signal without also running a comment forum they have to moderate.
+     * And it independently hardens R-1 clause 1: a locked thread cannot receive
+     * the forged-marker reply that clause exists to reject, so the marker rule
+     * and the lock have to fail together before a stranger's text is counted.
+     */
+    lockThreads: boolean;
+}
+/**
+ * Validate the `ratings` block of an already-parsed config object.
+ *
+ * Absent (or `null`) ⇒ `undefined` ⇒ ratings off. Unknown keys are ignored,
+ * the same forward-compatibility rule `stats.json` itself follows.
+ */
+export declare function validateRatings(raw: unknown): RatingsConfig | undefined;
+/**
+ * Read the `ratings` block out of `index.config.json`. A missing file, or a
+ * file with no `ratings` block, means ratings are off.
+ */
+export declare function loadRatingsConfig(root: string): Promise<RatingsConfig | undefined>;
+//# sourceMappingURL=config.d.ts.map

package/dist/ratings/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/ratings/config.ts"],"names":[],"mappings":"AAiBA;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAErD,eAAO,MAAM,gBAAgB,EAAE,SAAS,kBAAkB,EAAyB,CAAC;AAEpF,iEAAiE;AACjE,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,8EAA8E;IAC9E,QAAQ,EAAE,kBAAkB,CAAC;IAC7B;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;;;OASG;IACH,WAAW,EAAE,OAAO,CAAC;CACtB;AAMD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,GAAG,SAAS,CAgCvE;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAkBxF"}

package/dist/ratings/config.js

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 The Grimoire Authors
+// The `ratings` block of `index.config.json` — the third independent reader of
+// that file, beside `config.ts` (the site) and `ci.ts` (the pipeline). One
+// loader for all three would couple the renderer, the CI generator and the
+// tally to each other's validation for the sake of one `readFile`; each stays
+// able to fail on its own block and say so in its own words.
+//
+// There is deliberately no `botIds` key here. The author allowlist is
+// `index-policy.json`'s `trustedBots[].id` and nothing else — a second copy of
+// the same ids in a second file is a consistency hazard, not a convenience.
+import fs from "node:fs/promises";
+import path from "node:path";
+import { CONFIG_FILE, SiteConfigError } from "../config.js";
+export const RATING_PROVIDERS = ["github", "gitlab"];
+/** Per-run thread-creation budget when the config names none. */
+export const DEFAULT_CREATE_BUDGET = 400;
+function fail(msg) {
+    throw new SiteConfigError(`${CONFIG_FILE}: ratings.${msg}`);
+}
+/**
+ * Validate the `ratings` block of an already-parsed config object.
+ *
+ * Absent (or `null`) ⇒ `undefined` ⇒ ratings off. Unknown keys are ignored,
+ * the same forward-compatibility rule `stats.json` itself follows.
+ */
+export function validateRatings(raw) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        throw new SiteConfigError(`${CONFIG_FILE}: ratings must be an object`);
+    }
+    const ratings = raw;
+    if (!RATING_PROVIDERS.includes(ratings.provider)) {
+        fail(`provider must be one of ${RATING_PROVIDERS.join(", ")}`);
+    }
+    if (typeof ratings.container !== "string" || ratings.container.trim() === "") {
+        fail("container must be a non-empty string - a GitHub Discussions category, or a GitLab work item type");
+    }
+    if (ratings.createBudget !== undefined) {
+        if (typeof ratings.createBudget !== "number" || !Number.isInteger(ratings.createBudget)) {
+            fail("createBudget must be a whole number");
+        }
+        if (ratings.createBudget < 0)
+            fail("createBudget must not be negative");
+    }
+    if (ratings.lockThreads !== undefined && typeof ratings.lockThreads !== "boolean") {
+        fail("lockThreads must be a boolean");
+    }
+    // Built key by key rather than spread: the returned value is the four
+    // documented keys and nothing else, so an unknown key is ignored in the
+    // strong sense — it cannot reach a consumer that happens to look for it.
+    return {
+        provider: ratings.provider,
+        container: ratings.container,
+        createBudget: ratings.createBudget ?? DEFAULT_CREATE_BUDGET,
+        lockThreads: ratings.lockThreads ?? true,
+    };
+}
+/**
+ * Read the `ratings` block out of `index.config.json`. A missing file, or a
+ * file with no `ratings` block, means ratings are off.
+ */
+export async function loadRatingsConfig(root) {
+    let text;
+    try {
+        text = await fs.readFile(path.join(root, CONFIG_FILE), "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new SiteConfigError(`${CONFIG_FILE}: ${err.message}`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new SiteConfigError(`${CONFIG_FILE}: must contain a JSON object`);
+    }
+    return validateRatings(parsed.ratings);
+}
+//# sourceMappingURL=config.js.map

package/dist/ratings/config.js.map

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

package/dist/ratings/marker.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Invariant R-1 — marker authority.
+ *
+ * A `<!-- grim-ref: <ref> -->` marker binds `ref → thread` only when all four
+ * clauses hold: it is in the body of a top-level thread (never a comment,
+ * reply or note); the author's *account id* is registered in
+ * `index-policy.json`'s `trustedBots[].id`; it is the first anchored match in
+ * that body; and the thread still lives in the configured container — the
+ * repository/project id *and* the category or work-item type, compared by
+ * immutable id, never by name. A ref bound by more than one authorized thread
+ * is a conflict and contributes nothing.
+ *
+ * Pure, and separate from the providers because the rule must be enforced
+ * identically on both forges — two copies is how one of them drifts. The
+ * providers apply it inside `listAuthored()`, so no caller can receive an
+ * unauthorized thread and forget to filter it.
+ */
+import type { TrustedBot } from "../validate/core/ownership.js";
+/** What R-1 compares against: the registered bots and the configured container. */
+export interface MarkerPolicy {
+    /**
+     * `index-policy.json`'s `trustedBots`. Read for ids only — the bare-string
+     * form and the object form without an `id` are login-only and authorize
+     * nothing here, because clause 2 has an account id and no login in hand.
+     */
+    trustedBots?: readonly TrustedBot[];
+    /** GitHub `repository.id` / GitLab `project.id`. */
+    containerId: string;
+    /** GitHub discussion category id / GitLab work-item type id. */
+    categoryId: string;
+}
+/** A forge thread as observed, before R-1 has ruled on it. */
+export interface ObservedThread {
+    /** Opaque forge node id the vote mutation targets. */
+    target: string;
+    url: string;
+    /** The forge's own upvote counter. */
+    up: number;
+    body: string;
+    /** Absent when the forge reports no author — a deleted account. */
+    authorId?: string;
+    containerId: string;
+    categoryId: string;
+    /**
+     * Replies, comments or notes. Carried so clause 1 is enforced *here* rather
+     * than by each provider remembering not to pass them: this module never
+     * reads them, and an attacker's reply is the forgery clause 1 exists for.
+     */
+    comments?: readonly {
+        body: string;
+        authorId?: string;
+    }[];
+}
+/** A thread R-1 accepted. Structurally the provider's `RatingThread`. */
+export interface AuthorizedThread {
+    ref: string;
+    target: string;
+    url: string;
+    up: number;
+}
+/** A ref claimed by more than one authorized thread. Contributes zero votes. */
+export interface RefConflict {
+    ref: string;
+    urls: string[];
+}
+export interface Resolution {
+    /** Refs bound by exactly one authorized thread. */
+    bound: Map<string, AuthorizedThread>;
+    conflicts: RefConflict[];
+}
+/**
+ * The marker line for `ref`.
+ *
+ * Defence in depth against the injection `desiredRefs` already rejects at
+ * ingest: this function composes the body that {@link parseMarkerRef} later
+ * reads back, so a `ref` carrying a newline, a space, or a `-->` would author
+ * a *second* marker line under the bot's own identity — and every R-1 clause
+ * would pass it, because they constrain who wrote the body and where the
+ * thread lives, never what is in it. A ref that does not round-trip through
+ * the marker grammar is refused here rather than published.
+ *
+ * @throws {RangeError} when `ref` cannot survive its own marker.
+ */
+export declare function buildMarker(ref: string): string;
+/**
+ * The first anchored marker in a body, by lowest byte offset — clause 3.
+ *
+ * Scanned line by line rather than with a `/m` regex: `^`/`$` alone would
+ * accept a marker sitting at column 0 inside a fenced code block, and would
+ * reject every marker in a CRLF body — which is what GitHub hands back for a
+ * discussion it stored. An unterminated fence swallows the rest of the body;
+ * that fails closed, which is the direction this rule errs in.
+ */
+export declare function parseMarkerRef(body: string): string | null;
+/** Apply R-1 to one observed thread. `null` means it binds nothing. */
+export declare function authorizeThread(thread: ObservedThread, policy: MarkerPolicy): AuthorizedThread | null;
+/**
+ * Group authorized threads by ref. A ref claimed twice is ambiguous, and
+ * silently picking one would let a second thread quietly retarget a popular
+ * artifact's votes — so it contributes zero and the operator is told to delete
+ * all but one.
+ */
+export declare function resolveConflicts(threads: readonly AuthorizedThread[]): Resolution;
+export declare function conflictWarning(conflict: RefConflict): string;
+//# sourceMappingURL=marker.d.ts.map

package/dist/ratings/marker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"marker.d.ts","sourceRoot":"","sources":["../../src/ratings/marker.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAEhE,mFAAmF;AACnF,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,WAAW,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACpC,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,sCAAsC;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3D;AAED,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACrC,SAAS,EAAE,WAAW,EAAE,CAAC;CAC1B;AAqBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQ/C;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAwB1D;AA0BD,uEAAuE;AACvE,wBAAgB,eAAe,CAC7B,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,YAAY,GACnB,gBAAgB,GAAG,IAAI,CAUzB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,GAAG,UAAU,CAgBjF;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,CAE7D"}

package/dist/ratings/marker.js

@@ -0,0 +1,141 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 The Grimoire Authors
+/**
+ * Anchored: the whole line and nothing else. Not because an unanchored pattern
+ * is exploitable while clause 2 holds — an attacker's content is never parsed
+ * as a marker source — but because an unanchored parser is a parser-
+ * differential bug waiting for the day someone relaxes clause 2.
+ */
+const MARKER_LINE = /^<!-- grim-ref: (\S+) -->$/;
+/**
+ * A fence opener or closer: the run of `` ` `` or `~` and whatever follows it.
+ *
+ * CommonMark closes a fence only with **the same character**, in a run at
+ * least as long as the opener — so a `~~~` inside a ``` block is ordinary
+ * text, not a close. A boolean toggle gets that wrong in the direction that
+ * matters: ``` then `~~~` then a marker would read the marker as unfenced and
+ * bind it.
+ */
+const FENCE = /^\s{0,3}(`{3,}|~{3,})/;
+/**
+ * The marker line for `ref`.
+ *
+ * Defence in depth against the injection `desiredRefs` already rejects at
+ * ingest: this function composes the body that {@link parseMarkerRef} later
+ * reads back, so a `ref` carrying a newline, a space, or a `-->` would author
+ * a *second* marker line under the bot's own identity — and every R-1 clause
+ * would pass it, because they constrain who wrote the body and where the
+ * thread lives, never what is in it. A ref that does not round-trip through
+ * the marker grammar is refused here rather than published.
+ *
+ * @throws {RangeError} when `ref` cannot survive its own marker.
+ */
+export function buildMarker(ref) {
+    const line = `<!-- grim-ref: ${ref} -->`;
+    if (MARKER_LINE.exec(line)?.[1] !== ref) {
+        throw new RangeError(`refusing to build a rating marker for ${JSON.stringify(ref)}: it does not round-trip through the marker grammar`);
+    }
+    return line;
+}
+/**
+ * The first anchored marker in a body, by lowest byte offset — clause 3.
+ *
+ * Scanned line by line rather than with a `/m` regex: `^`/`$` alone would
+ * accept a marker sitting at column 0 inside a fenced code block, and would
+ * reject every marker in a CRLF body — which is what GitHub hands back for a
+ * discussion it stored. An unterminated fence swallows the rest of the body;
+ * that fails closed, which is the direction this rule errs in.
+ */
+export function parseMarkerRef(body) {
+    // The open fence's delimiter run, or null outside a fence. Tracked as the
+    // run itself rather than a boolean so a different fence character, or a
+    // shorter run of the same one, cannot close it (CommonMark 4.5).
+    let open = null;
+    for (const line of body.split(/\r?\n/)) {
+        const fence = FENCE.exec(line)?.[1];
+        if (fence) {
+            if (open === null) {
+                open = fence;
+                continue;
+            }
+            if (fence[0] === open[0] && fence.length >= open.length) {
+                open = null;
+            }
+            // A non-matching run inside a fence is content, and content is never
+            // a marker source.
+            continue;
+        }
+        if (open !== null)
+            continue;
+        const ref = MARKER_LINE.exec(line)?.[1];
+        if (ref)
+            return ref;
+    }
+    return null;
+}
+/**
+ * Is this author one of the registered bots? Clause 2, keyed by account id.
+ *
+ * `findTrustedBot` cannot serve this — it is login-keyed, and R-1 has an id
+ * and no login. An entry without an `id` is skipped, never read as a wildcard;
+ * an author without an id matches nothing, so a deleted account and an
+ * unpinned entry cannot meet in the middle as `undefined === undefined`.
+ */
+function authorIsTrustedBot(bots, authorId) {
+    if (authorId === undefined)
+        return false;
+    return (bots ?? []).some(
+    // `index-policy.json` is hand-written and `id` is *typed* string but never
+    // validated at runtime, so an operator who writes `"id": 99` — which this
+    // repo's own fixtures do — used to fail `99 === "99"` on every thread,
+    // authorize nothing, and publish an empty rating set. Compare in string
+    // space so the natural thing to type works. A value that is not
+    // id-shaped still matches nothing, which is the safe direction.
+    (bot) => typeof bot !== "string" && bot.id !== undefined && String(bot.id) === authorId);
+}
+/** Apply R-1 to one observed thread. `null` means it binds nothing. */
+export function authorizeThread(thread, policy) {
+    // Clause 4, two independent equalities: a transfer moves the container id, a
+    // discussion→issue conversion moves the category. Either alone disqualifies.
+    if (thread.containerId !== policy.containerId)
+        return null;
+    if (thread.categoryId !== policy.categoryId)
+        return null;
+    if (!authorIsTrustedBot(policy.trustedBots, thread.authorId))
+        return null;
+    // Clause 1: the thread's own body. `thread.comments` is deliberately unread.
+    const ref = parseMarkerRef(thread.body);
+    if (ref === null)
+        return null;
+    return { ref, target: thread.target, url: thread.url, up: thread.up };
+}
+/**
+ * Group authorized threads by ref. A ref claimed twice is ambiguous, and
+ * silently picking one would let a second thread quietly retarget a popular
+ * artifact's votes — so it contributes zero and the operator is told to delete
+ * all but one.
+ */
+export function resolveConflicts(threads) {
+    const byRef = new Map();
+    for (const thread of threads) {
+        const group = byRef.get(thread.ref);
+        if (group)
+            group.push(thread);
+        else
+            byRef.set(thread.ref, [thread]);
+    }
+    const bound = new Map();
+    const conflicts = [];
+    for (const [ref, group] of byRef) {
+        const only = group.length === 1 ? group[0] : undefined;
+        if (only)
+            bound.set(ref, only);
+        else
+            conflicts.push({ ref, urls: group.map((thread) => thread.url) });
+    }
+    return { bound, conflicts };
+}
+export function conflictWarning(conflict) {
+    return `ratings: ref ${conflict.ref} bound by ${conflict.urls.length} threads: ${conflict.urls.join(", ")} — delete all but one`;
+}
+//# sourceMappingURL=marker.js.map

package/dist/ratings/marker.js.map

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

package/dist/ratings/paging.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Nodes per page.
+ *
+ * 50 rather than the API maximum of 100. This used to be a workaround for
+ * `request()`'s fixed 1 MiB cap — a page carries every thread's full body,
+ * including bodies this bot did not write, so a container holding long human
+ * threads overran the cap and [`graphql`] reported it as a transport failure.
+ * That was a real failure on first runs, before any bot thread existed.
+ *
+ * The cap is now per-call (`LARGE_RESPONSE_BYTES`), so the size argument for
+ * keeping this at 50 is gone. It stays at 50 anyway: raising it changes request
+ * count and cursor behaviour for every existing index, which is a separate
+ * decision from fixing the overrun.
+ */
+export declare const PAGE_SIZE = 50;
+//# sourceMappingURL=paging.d.ts.map

package/dist/ratings/paging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paging.d.ts","sourceRoot":"","sources":["../../src/ratings/paging.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,SAAS,KAAK,CAAC"}

package/dist/ratings/paging.js

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 The Grimoire Authors
+// Page size, alone in a module because of *where* it is read.
+//
+// `provider.ts` and the two implementations form a deliberate cycle: the
+// factory imports both providers, and both import the shared plumbing back.
+// `provider.ts` states the rule that makes that safe -- everything crossing the
+// cycle is a hoisted function declaration, referenced only from inside a
+// closure -- and a `const` interpolated into a module-level query string is
+// precisely the case the rule excludes.
+//
+// It was declared in `provider.ts` and read at module scope by both providers,
+// which the factory imports before it reaches the declaration. Under Node's ESM
+// that is a temporal dead zone and every `ratings` run died on import; under
+// Vitest's SSR transform the same read is a property access on a
+// not-yet-populated namespace, so it quietly yielded `undefined` and shipped
+// `first:undefined` in the query while 24 provider tests passed.
+//
+// Living here, the constant does not cross the cycle at all, so the rule holds
+// by construction instead of by remembering it.
+/**
+ * Nodes per page.
+ *
+ * 50 rather than the API maximum of 100. This used to be a workaround for
+ * `request()`'s fixed 1 MiB cap — a page carries every thread's full body,
+ * including bodies this bot did not write, so a container holding long human
+ * threads overran the cap and [`graphql`] reported it as a transport failure.
+ * That was a real failure on first runs, before any bot thread existed.
+ *
+ * The cap is now per-call (`LARGE_RESPONSE_BYTES`), so the size argument for
+ * keeping this at 50 is gone. It stays at 50 anyway: raising it changes request
+ * count and cursor behaviour for every existing index, which is a separate
+ * decision from fixing the overrun.
+ */
+export const PAGE_SIZE = 50;
+//# sourceMappingURL=paging.js.map

package/dist/ratings/paging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paging.js","sourceRoot":"","sources":["../../src/ratings/paging.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,sCAAsC;AAEtC,8DAA8D;AAC9D,EAAE;AACF,yEAAyE;AACzE,4EAA4E;AAC5E,gFAAgF;AAChF,yEAAyE;AACzE,4EAA4E;AAC5E,wCAAwC;AACxC,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,6EAA6E;AAC7E,iEAAiE;AACjE,6EAA6E;AAC7E,iEAAiE;AACjE,EAAE;AACF,+EAA+E;AAC/E,gDAAgD;AAEhD;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,CAAC"}

package/dist/ratings/provider.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The `RatingProvider` seam — one interface, two forges, one in-memory fake.
+ *
+ * Mirrors `validate/adapters/forge.ts`: an interface, per-forge closures, and a
+ * `create*` factory that picks between them. The GraphQL plumbing every
+ * provider needs lives here rather than in each of them, because the one rule
+ * that must not drift is [`graphql`]'s error branching — a 200 carrying a
+ * populated `errors` array is a hard error, and two copies of that check is how
+ * one of them turns into an empty tally.
+ */
+import { CliError, type ExitCode } from "../cli/exit.js";
+import { type AuthorizedThread } from "./marker.js";
+import type { TrustedBot } from "../validate/core/ownership.js";
+export { PAGE_SIZE } from "./paging.js";
+/**
+ * A thread the reconcile loop may tally. Declared as an alias of R-1's
+ * `AuthorizedThread` rather than a second identical interface: R-1 is what
+ * produces these, and the type should say so.
+ */
+export type RatingThread = AuthorizedThread;
+export interface RatingProviderConfig {
+    /** GraphQL endpoint, e.g. `https://api.github.com/graphql`. */
+    api: string;
+    /** Credential with write access to threads. Never logged. */
+    token: string;
+    /** GitHub `owner/repo`; GitLab full project path. */
+    project: string;
+    /** GitHub Discussions category name; GitLab work item type name. */
+    container: string;
+    /** Lock threads on creation — votes count, replies are refused. */
+    lockThreads: boolean;
+    /** `index-policy.json`'s allowlist. R-1 clause 2 reads ids out of it. */
+    trustedBots?: readonly TrustedBot[];
+}
+export interface RatingProvider {
+    /**
+     * Every thread the bot authored in the configured container, paginated to
+     * exhaustion. R-1 filtering is applied **here**, never by the caller.
+     *
+     * A secondary rate limit part-way through throws [`RateLimited`] carrying the
+     * pages already read — a truncated pass is partial, not empty, and the caller
+     * needs both facts to publish without wiping what it could not observe.
+     */
+    listAuthored(): Promise<RatingThread[]>;
+    /** Create one thread carrying the marker. The budget is the caller's job. */
+    create(ref: string): Promise<RatingThread>;
+}
+/**
+ * The forge answered, and the answer was unusable: a transport failure, a
+ * non-2xx, a body that did not parse, or a 200 carrying GraphQL `errors`.
+ *
+ * A `CliError` subclass rather than a name in `classify()`'s list, following
+ * `seed.ts`: that list exists for errors thrown by modules `main.ts` must not
+ * import, and `cli/exit.js` is already one of its static imports — so the
+ * mapping here is by type, which cannot drift out of sync with a string.
+ */
+export declare class ForgeError extends CliError {
+    constructor(message: string, code?: ExitCode);
+}
+/**
+ * A secondary rate limit. Distinguished from [`ForgeError`] because the two are
+ * handled oppositely: a forge error fails the run, a rate limit stops it early
+ * and publishes what it already got.
+ */
+export declare class RateLimited extends ForgeError {
+    /** What the forge asked us to wait, by GitHub's documented precedence. */
+    readonly retryAfterMs: number;
+    /** Threads read before the limit. Empty on the create path. */
+    readonly observed: readonly RatingThread[];
+    constructor(message: string, retryAfterMs: number, observed?: readonly RatingThread[]);
+}
+/** GitHub's documented floor when neither header says how long to wait. */
+export declare const BACKOFF_FLOOR_MS = 60000;
+/**
+ * The body every provider writes. The marker sits on its own line, which is the
+ * only position R-1's anchored parser accepts; the prose above it is for the
+ * human who lands on the thread from the catalog.
+ */
+export declare function threadBody(ref: string): string;
+export declare function field(data: unknown, key: string): unknown;
+/** `field`, chained. Every GraphQL read here is a path into an `unknown`. */
+export declare function at(data: unknown, ...keys: string[]): unknown;
+export declare function stringAt(data: unknown, ...keys: string[]): string;
+export declare function nodes(data: unknown): unknown[];
+/**
+ * One GraphQL round trip, with the branching every provider shares.
+ *
+ * Order matters and is the reason this is one function: a rate limit is
+ * classified first (it is the one failure that must not fail the run), then
+ * `errors` is checked **independently of the HTTP status and before `data` is
+ * touched** — a 200 with `errors` and a null `data` otherwise reads as
+ * "genuinely fewer votes observed", which is silent emptying arriving through
+ * the one door R-2 does not watch.
+ *
+ * @param observed Threads already read, attached to a [`RateLimited`] so a
+ *   truncated pagination pass stays partial rather than becoming empty.
+ */
+export declare function graphql(api: string, headers: Record<string, string>, query: string, variables: Record<string, unknown>, observed?: readonly RatingThread[]): Promise<Record<string, unknown>>;
+export declare function createRatingProvider(kind: "github" | "gitlab", config: RatingProviderConfig): RatingProvider;
+//# sourceMappingURL=provider.d.ts.map

package/dist/ratings/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/ratings/provider.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AAEH,OAAO,EAAE,QAAQ,EAAQ,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/D,OAAO,EAAe,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAQhE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAIxC;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,gBAAgB,CAAC;AAE5C,MAAM,WAAW,oBAAoB;IACnC,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,WAAW,EAAE,OAAO,CAAC;IACrB,yEAAyE;IACzE,WAAW,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,cAAc;IAC7B;;;;;;;OAOG;IACH,YAAY,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IACxC,6EAA6E;IAC7E,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC5C;AAED;;;;;;;;GAQG;AACH,qBAAa,UAAW,SAAQ,QAAQ;gBAC1B,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,QAA2B;CAI/D;AAED;;;;GAIG;AACH,qBAAa,WAAY,SAAQ,UAAU;IACzC,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;gBAE/B,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,GAAE,SAAS,YAAY,EAAO;CAM1F;AAED,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAGvC;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQ9C;AAED,wBAAgB,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAGzD;AAED,6EAA6E;AAC7E,wBAAgB,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAE5D;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAGjE;AAED,wBAAgB,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,EAAE,CAG9C;AAqDD;;;;;;;;;;;;GAYG;AACH,wBAAsB,OAAO,CAC3B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,QAAQ,GAAE,SAAS,YAAY,EAAO,GACrC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAmDlC;AAED,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,QAAQ,GAAG,QAAQ,EACzB,MAAM,EAAE,oBAAoB,GAC3B,cAAc,CAIhB"}