wiki-formant 0.13.0 → 0.16.0

package/dist/link-check.js

@@ -0,0 +1,249 @@
+// link-check.ts — the dead-link probe both wikis' sweep scripts had written.
+//
+// Node-only (fetch, AbortSignal, URL). No framework, no database: what a
+// checker does with the verdicts — which pages to walk, what counts as an
+// internal path, how to report — stays with the caller, because that is the
+// half that is genuinely per-wiki.
+//
+// EVERY GUARD BELOW WAS PAID FOR BY A FALSE POSITIVE, and the two copies had
+// each learned a different half of the lesson. One knew that npmjs.com 403s
+// scripted requests, that an expired certificate is not a dead host, and that a
+// YouTube /embed/ URL answers 200 for a deleted video. The other knew that a
+// connect refusal is usually concurrency rather than death, and that
+// serialising per hostname is what fixes it. Neither copy was behind. A sweep
+// running either one alone strips good citations for reasons the other repo had
+// already written down — which is the entire argument for this file.
+import { stripTags } from './html.js';
+const DEFAULTS = { timeoutMs: 12_000, slowTimeoutMs: 40_000 };
+/**
+ * TLS-verification failures are NOT death.
+ *
+ * A Let's Encrypt certificate on a DAO's own consultation platform — cited 20
+ * times across 7 pages — expired at 13:47 UTC, and every one of those citations
+ * started reading as `status: 0, "fetch failed"`, indistinguishable from a
+ * vanished host. Behind the interstitial the site answered 200. undici buries
+ * the reason in `err.cause`, so it is surfaced and labelled: a run that cannot
+ * tell an expired cert from a dead domain will eventually strip good citations
+ * over a lapsed renewal.
+ */
+const TLS_CODES = new Set([
+    'CERT_HAS_EXPIRED',
+    'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+    'DEPTH_ZERO_SELF_SIGNED_CERT',
+    'SELF_SIGNED_CERT_IN_CHAIN',
+    'ERR_TLS_CERT_ALTNAME_INVALID',
+]);
+/**
+ * Codes that flap. A sweep found 16 status-0 rows and 15 were one host, every
+ * one answering 200 when probed alone. Carry the code through so a caller can
+ * treat these as retryable rather than banking a death.
+ */
+export const TRANSIENT_CODES = new Set([
+    'UND_ERR_CONNECT_TIMEOUT',
+    'UND_ERR_SOCKET',
+    'UND_ERR_HEADERS_TIMEOUT',
+    'UND_ERR_BODY_TIMEOUT',
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ETIMEDOUT',
+    'EAI_AGAIN',
+    'EPIPE',
+]);
+/** A failure as a report row: the message, the code, and the TLS caveat. */
+export function describeFailure(err) {
+    const e = err;
+    if (e?.name === 'AbortError')
+        return { error: 'timeout' };
+    const code = e?.cause?.code ?? e?.code;
+    const error = code ? `${e.message} (${code})` : (e?.message ?? 'fetch failed');
+    if (code && TLS_CODES.has(code)) {
+        return {
+            error,
+            code,
+            tls: code,
+            note: 'TLS verification failed — the host may well be serving fine behind the interstitial; confirm before touching the citation',
+        };
+    }
+    return code ? { error, code } : { error };
+}
+/**
+ * The URL to probe INSTEAD, where the public page lies about its own health.
+ *
+ * npmjs.com serves 403 to scripted requests whether or not the package exists,
+ * which made every package citation a permanent false positive. The registry
+ * answers honestly.
+ */
+export function probeUrlFor(url) {
+    const npm = url.match(/^https:\/\/(?:www\.)?npmjs\.com\/package\/(.+?)\/?$/);
+    return npm ? `https://registry.npmjs.org/${npm[1]}` : url;
+}
+// ---- per-host serialisation -------------------------------------------------
+const hostQueues = new Map();
+/**
+ * Run `fn` with at most one request in flight against this hostname.
+ *
+ * ECONNREFUSED looks deterministic and is not. A delayed retry was tried first
+ * and made things worse — 269 to 277 broken, the refusals unchanged and 8 fresh
+ * timeouts on hosts that had been fine — because the problem is not timing, it
+ * is how many sockets one host is asked for at once. The global pool still runs
+ * wide across DIFFERENT hosts; any single host is probed one request at a time,
+ * exactly as a hand re-probe does it.
+ */
+export function perHost(url, fn) {
+    let host;
+    try {
+        host = new URL(url).hostname;
+    }
+    catch {
+        return fn();
+    }
+    const prev = hostQueues.get(host) ?? Promise.resolve();
+    // `.then(fn, fn)` so one rejection does not poison the rest of the queue.
+    const next = prev.then(fn, fn);
+    hostQueues.set(host, next.catch(() => undefined));
+    return next;
+}
+async function attempt(url, budgetMs) {
+    // One signal for both requests, so the budget covers the HEAD *and* the GET
+    // rather than resetting between them. `engines.node` is >= 20, so this needs
+    // no controller and no `clearTimeout` in a `finally` that could be forgotten.
+    const signal = AbortSignal.timeout(budgetMs);
+    try {
+        let res = await fetch(url, { method: 'HEAD', redirect: 'follow', signal });
+        // Some hosts reject HEAD outright; retry with GET before believing a 4xx.
+        if (res.status >= 400) {
+            res = await fetch(url, { method: 'GET', redirect: 'follow', signal });
+        }
+        return {
+            url,
+            status: res.status,
+            ok: res.status < 400,
+            contentType: (res.headers.get('content-type') || '').split(';')[0]?.trim(),
+            bytes: Number(res.headers.get('content-length') || 0),
+        };
+    }
+    catch (err) {
+        return { url, status: 0, ok: false, ...describeFailure(err) };
+    }
+}
+/**
+ * Probe one URL, honestly.
+ *
+ * A timeout is not a death and neither is a dropped connection: slow replays —
+ * web.archive.org above all, which a sweep leans on to rescue dying citations —
+ * exceed the ordinary budget and land as status 0. So a status-0 result with a
+ * transient code earns one more attempt on the longer budget before it is
+ * reported. A 404 does not: it is an answer.
+ */
+export async function probeUrl(url, opts = {}) {
+    const { timeoutMs, slowTimeoutMs } = { ...DEFAULTS, ...opts };
+    const target = probeUrlFor(url);
+    const first = await perHost(target, () => attempt(target, timeoutMs));
+    const retryable = !first.ok && first.status === 0 && (!first.code || TRANSIENT_CODES.has(first.code));
+    if (!retryable)
+        return { ...first, url };
+    const second = await perHost(target, () => attempt(target, slowTimeoutMs));
+    return { ...second, url };
+}
+// ---- YouTube ----------------------------------------------------------------
+export const YOUTUBE_EMBED = /^https?:\/\/(?:www\.)?(?:youtube-nocookie\.com|youtube\.com)\/embed\/([\w-]+)/;
+/**
+ * The same video cited as a LINK rather than an iframe. `youtu.be/<id>` 303s and
+ * `youtube.com/watch?v=<id>` 200s for deleted and private videos alike, so an
+ * anchor carrying a dead video is invisible to a status check — 55 of them went
+ * unprobed corpus-wide until one sweep resolved them and found 7 unwatchable.
+ */
+const YOUTUBE_WATCH = /^https?:\/\/(?:(?:www\.)?youtube\.com\/(?:watch\?(?:[^#]*&)?v=|shorts\/|live\/)|youtu\.be\/)([\w-]{6,})/;
+/**
+ * A YouTube `/embed/<id>` URL answers 200 for private, deleted and
+ * playback-restricted videos alike, so HEADing it can never spot a dead hero
+ * video. oEmbed can:
+ *
+ *   200 → public and embeddable | 404 → deleted | 401/403 → private or embedding off
+ */
+export async function probeYouTube(videoId, opts = {}) {
+    const { timeoutMs } = { ...DEFAULTS, ...opts };
+    const oembed = `https://www.youtube.com/oembed?url=https%3A//www.youtube.com/watch%3Fv%3D${videoId}&format=json`;
+    try {
+        const res = await fetch(oembed, {
+            method: 'GET',
+            redirect: 'follow',
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (res.status === 404)
+            return { status: 404, ok: false, reason: 'deleted' };
+        if (res.status === 401 || res.status === 403) {
+            return { status: res.status, ok: false, reason: 'restricted (private or embedding disabled)' };
+        }
+        return { status: res.status, ok: res.status < 400 };
+    }
+    catch (err) {
+        return { status: 0, ok: false, ...describeFailure(err) };
+    }
+}
+/** An external anchor, with a video treated as a video. */
+export async function probeExternal(url, opts = {}) {
+    const yt = url.match(YOUTUBE_WATCH);
+    if (yt?.[1])
+        return { url, videoId: yt[1], ...(await probeYouTube(yt[1], opts)) };
+    return probeUrl(url, opts);
+}
+// ---- unverifiable hosts -----------------------------------------------------
+/**
+ * Hosts that answer 200 with a JavaScript loader shell regardless of whether
+ * the deck / store / dataset behind the query string still exists. A status
+ * check on these is meaningless, so a caller should report them as unverifiable
+ * rather than healthy — a green row is worse than an unknown one, because
+ * nobody looks at it again.
+ */
+export function unverifiableReason(url, hosts) {
+    let host;
+    try {
+        host = new URL(url).hostname.replace(/^www\./, '');
+    }
+    catch {
+        return null;
+    }
+    for (const [h, reason] of hosts) {
+        if (host === h || host.endsWith(`.${h}`))
+            return reason;
+    }
+    return null;
+}
+// ---- extraction -------------------------------------------------------------
+const LINK_RE = /<a\s+[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi;
+const EMBED_RE = /<(iframe|img)\b[^>]*?\ssrc="([^"]*)"/gi;
+/** Every anchor in a fragment, as `{ href, text }`. */
+export function extractLinks(html) {
+    const out = [];
+    for (const m of html.matchAll(LINK_RE)) {
+        if (m[1])
+            out.push({ href: m[1], text: stripTags(m[2] ?? '') });
+    }
+    return out;
+}
+/** Every `<iframe>` and `<img>` source in a fragment. */
+export function extractEmbeds(html) {
+    const out = [];
+    for (const m of html.matchAll(EMBED_RE)) {
+        if (m[1] && m[2])
+            out.push({ kind: m[1].toLowerCase(), url: m[2] });
+    }
+    return out;
+}
+// ---- concurrency ------------------------------------------------------------
+/** `Promise.all` with a ceiling, preserving input order in the results. */
+export async function mapLimit(items, limit, fn) {
+    const results = new Array(items.length);
+    let cursor = 0;
+    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        for (;;) {
+            const i = cursor++;
+            if (i >= items.length)
+                return;
+            results[i] = await fn(items[i], i);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}

package/dist/links.d.ts

@@ -28,4 +28,3 @@ export interface NormaliseLinkOptions {
  * nested `<a>` is not handled, being invalid HTML anyway.
  */
 export declare function normaliseLinks(html: string, options?: NormaliseLinkOptions): string;
-//# sourceMappingURL=links.d.ts.map

package/dist/links.js

@@ -14,11 +14,7 @@
 // What they drifted on: only radix-wiki synthesised a label for an anchor with
 // no visible text. That is an accessibility fix, not a preference, so it is the
 // default here and caper gains it by adopting this module.
-/** Read one double-quoted attribute out of a tag's attribute string. */
-const getAttr = (attrs, name) => attrs.match(new RegExp(`\\s${name}\\s*=\\s*"([^"]*)"`, 'i'))?.[1] ?? null;
-/** Drop every occurrence of one attribute from a tag's attribute string. */
-const removeAttr = (attrs, name) => attrs.replace(new RegExp(`\\s${name}\\s*=\\s*"[^"]*"`, 'gi'), '');
-const stripTags = (s) => s.replace(/<[^>]*>/g, '').trim();
+import { getAttr, removeAttr, stripTags } from './html.js';
 /**
  * A readable label for an anchor whose text is empty, derived from its href.
  * Without one, crawlers and screen readers meet a link with nothing in it.
@@ -78,4 +74,3 @@ export function normaliseLinks(html, options = {}) {
     const self = options.selfHost ? selfHostPattern(options.selfHost) : null;
     return html.replace(ANCHOR, (_m, attrs, inner) => normaliseAnchor(attrs, inner, options, self));
 }
-//# sourceMappingURL=links.js.map

package/dist/maps.d.ts

@@ -18,4 +18,3 @@ export declare function extractCoordsFromUrl(url: string): MapCoords | null;
 export declare function toMapEmbedUrl(url: string): string | null;
 /** True for the shortener forms that only a redirect can resolve. */
 export declare const isShortMapUrl: (url: string) => boolean;
-//# sourceMappingURL=maps.d.ts.map

package/dist/maps.js

@@ -23,7 +23,8 @@ export function extractCoordsFromUrl(url) {
     if (data)
         return { lat: +data[1], lon: +data[2] };
     try {
-        const ll = new URL(url).searchParams.get('ll') ?? new URL(url).searchParams.get('sll');
+        const params = new URL(url).searchParams;
+        const ll = params.get('ll') ?? params.get('sll');
         if (ll) {
             const [lat, lon] = ll.split(',').map(Number);
             if (lat !== undefined && lon !== undefined && !isNaN(lat) && !isNaN(lon))
@@ -74,4 +75,3 @@ export function toMapEmbedUrl(url) {
 }
 /** True for the shortener forms that only a redirect can resolve. */
 export const isShortMapUrl = (url) => /maps\.app\.goo\.gl|goo\.gl\/maps/.test(url);
-//# sourceMappingURL=maps.js.map

package/dist/markdown.d.ts

@@ -1,3 +1,4 @@
+export declare function decodeEntities(s: string): string;
 /** Inline-level HTML → markdown. Applied inside cells, list items, headings. */
 export declare function inlineToMarkdown(html: string): string;
 /** One `<table>` → a GFM table. Falls back to nothing when there are no rows. */
@@ -22,4 +23,3 @@ export interface FrontmatterFields {
 export declare function frontmatter(fields: FrontmatterFields): string;
 /** A complete markdown document: frontmatter, an H1, and a body you supply. */
 export declare function markdownDocument(fields: FrontmatterFields, body: string): string;
-//# sourceMappingURL=markdown.d.ts.map

package/dist/markdown.js

@@ -9,7 +9,40 @@
 // so `blocksToMarkdown` belongs in the app. Give this module HTML and it gives
 // you markdown; give `frontmatter` the fields and it gives you the document
 // head. That is the whole portable half.
-import { decodeEntities } from './entities.js';
+import { isoDate } from './html.js';
+// ---- entity decoding --------------------------------------------------------
+//
+// Rich-text editors store typographic punctuation as named entities, so pages
+// carry raw `—` / `“` / `’` into every text export — ampersand
+// soup an agent has to read through. Numeric forms decode generically; the named
+// table covers what wiki corpora actually use (punctuation, arrows, maths,
+// accented Latin, Greek) rather than attempting the full HTML5 list.
+//
+// Lived in its own `entities.ts` with no subpath of its own, so the only way to
+// reach `decodeEntities` was the root barrel — and the README claimed it came
+// from here, which is where it now actually is.
+const NAMED_ENTITIES = {
+    amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ',
+    mdash: '—', ndash: '–', hellip: '…', middot: '·', bull: '•', sect: '§', para: '¶', dagger: '†',
+    ldquo: '“', rdquo: '”', lsquo: '‘', rsquo: '’', laquo: '«', raquo: '»',
+    larr: '←', rarr: '→', uarr: '↑', darr: '↓', harr: '↔',
+    times: '×', divide: '÷', minus: '−', plusmn: '±', ne: '≠', le: '≤', ge: '≥',
+    asymp: '≈', radic: '√', infin: '∞', sum: '∑', prod: '∏', int: '∫', deg: '°', permil: '‰',
+    sup2: '²', sup3: '³', frac12: '½', frac14: '¼', frac34: '¾',
+    euro: '€', pound: '£', yen: '¥', cent: '¢', copy: '©', reg: '®', trade: '™',
+    eacute: 'é', egrave: 'è', ecirc: 'ê', aacute: 'á', agrave: 'à', acirc: 'â', aring: 'å',
+    auml: 'ä', ouml: 'ö', uuml: 'ü', iacute: 'í', oacute: 'ó', uacute: 'ú', ntilde: 'ñ',
+    ccedil: 'ç', oslash: 'ø', szlig: 'ß', aelig: 'æ',
+    alpha: 'α', beta: 'β', gamma: 'γ', delta: 'δ', epsilon: 'ε', theta: 'θ', lambda: 'λ',
+    mu: 'μ', nu: 'ν', pi: 'π', rho: 'ρ', sigma: 'σ', tau: 'τ', phi: 'φ', omega: 'ω',
+    Delta: 'Δ', Sigma: 'Σ', Omega: 'Ω', Lambda: 'Λ', Phi: 'Φ', Pi: 'Π',
+};
+export function decodeEntities(s) {
+    return s
+        .replace(/&#x([0-9a-fA-F]{1,6});/g, (_m, hex) => String.fromCodePoint(parseInt(hex, 16)))
+        .replace(/&#(\d{1,7});/g, (_m, dec) => String.fromCodePoint(Number(dec)))
+        .replace(/&([a-zA-Z][a-zA-Z0-9]{1,9});/g, (m, name) => NAMED_ENTITIES[name] ?? m);
+}
 /** Inline-level HTML → markdown. Applied inside cells, list items, headings. */
 export function inlineToMarkdown(html) {
     return decodeEntities(html
@@ -81,7 +114,6 @@ export function htmlToMarkdown(html) {
         .replace(/\n{3,}/g, '\n\n')
         .trim();
 }
-const isoDate = (d) => (typeof d === 'string' ? d : d.toISOString()).split('T')[0];
 /** YAML frontmatter block, `---` fences included. */
 export function frontmatter(fields) {
     const esc = (s) => s.replace(/"/g, '\\"');
@@ -104,4 +136,3 @@ export function frontmatter(fields) {
 export function markdownDocument(fields, body) {
     return `${frontmatter(fields)}\n\n# ${fields.title}\n\n${body.trim()}\n`;
 }
-//# sourceMappingURL=markdown.js.map

package/dist/mcp.d.ts

@@ -42,12 +42,6 @@ export type ToolSchema = {
  * calls has no way to tell a lookup from one that reaches a payment processor.
  */
 export type ToolAnnotations = {
-    /**
-     * Human-facing label — the pre-2025-06-18 slot. `tools/list` hoists it to
-     * the top-level `title` when that is absent, so a manifest written against
-     * either revision renders the same in a client. Prefer `McpTool.title`.
-     */
-    title?: string;
     /** Does not modify anything. */
     readOnlyHint?: boolean;
     /** May destroy or overwrite state (only meaningful when not read-only). */
@@ -192,6 +186,23 @@ export type RpcRequest = {
     method: string;
     params?: unknown;
 };
+/** How many entries one JSON-RPC batch may carry. Quoted by the conformance suite. */
+export declare const DEFAULT_MAX_BATCH = 20;
+/**
+ * A tool result envelope. Exported because `x402.ts` builds the same shape when
+ * it withholds a paid call, and had grown two more copies of it doing so.
+ */
+export declare const toolText: (id: RpcRequest["id"], text: string, isError?: boolean, extra?: Record<string, unknown>) => {
+    jsonrpc: "2.0";
+    id: string | number | null;
+    result: {
+        isError?: boolean | undefined;
+        content: {
+            type: string;
+            text: string;
+        }[];
+    };
+};
 /** Everything the dispatcher needs that is not in the JSON-RPC entry itself. */
 interface Dispatch {
     protocolVersion: McpProtocolVersion;
@@ -222,4 +233,3 @@ export declare function mcpRateLimited(retryAfterSec: number, message?: string):
 /** The whole POST leg: parse, gate, track, dispatch, and answer with the right status. */
 export declare function mcpResponse(request: Request, config: McpServerConfig): Promise<Response>;
 export {};
-//# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.js

@@ -52,7 +52,8 @@ export class McpToolError extends Error {
         this.name = 'McpToolError';
     }
 }
-const DEFAULT_MAX_BATCH = 20;
+/** How many entries one JSON-RPC batch may carry. Quoted by the conformance suite. */
+export const DEFAULT_MAX_BATCH = 20;
 const quote = (list) => list.map(s => `"${s}"`).join(', ');
 function typeOf(v) {
     if (Array.isArray(v))
@@ -66,7 +67,11 @@ const rpcError = (id, code, message, data) => ({
     id,
     error: { code, message, ...(data ? { data } : {}) },
 });
-const toolText = (id, text, isError = false, extra = {}) => ({
+/**
+ * A tool result envelope. Exported because `x402.ts` builds the same shape when
+ * it withholds a paid call, and had grown two more copies of it doing so.
+ */
+export const toolText = (id, text, isError = false, extra = {}) => ({
     jsonrpc: '2.0',
     id,
     result: { content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}), ...extra },
@@ -188,11 +193,7 @@ async function handleRpc(req, config, dispatch) {
                     result: {
                         tools: config.tools.map(({ name, title, description, inputSchema, outputSchema, annotations }) => ({
                             name,
-                            // 2025-06-18 promoted `title` out of `annotations`. Hoisting
-                            // rather than requiring every manifest to be rewritten: a
-                            // client reading only the new slot showed a raw tool name for
-                            // every surface that had not moved its label yet.
-                            ...(title ?? annotations?.title ? { title: title ?? annotations.title } : {}),
+                            ...(title ? { title } : {}),
                             description,
                             inputSchema,
                             ...(outputSchema ? { outputSchema } : {}),
@@ -433,4 +434,3 @@ export async function mcpResponse(request, config) {
     }
     return Response.json(result, { headers });
 }
-//# sourceMappingURL=mcp.js.map

package/dist/pagination.d.ts

@@ -49,4 +49,22 @@ export declare function toOffset({ page, pageSize }: Pagination): {
     skip: number;
     take: number;
 };
-//# sourceMappingURL=pagination.d.ts.map
+/**
+ * The entries either side of the current one in an already-ordered list.
+ *
+ * The ordering is the caller's, deliberately — it is the one thing here that is
+ * never portable. A wiki's sequence is its section's configured sort, a
+ * knowledge base's is a taxonomy walk, and a company log's is `updatedAt` desc.
+ * What both wikis had written twice is this scan, not the sort.
+ *
+ * `null` on both sides when the page is not in the list, so a page reached by a
+ * URL its own section does not list renders no nav rather than a wrong one.
+ *
+ * No query. Both callers already hold the ordered siblings for something else —
+ * a related-pages panel, a section listing — and the two indexed lookups the
+ * neighbours used to cost were the reason one wiki dropped the control.
+ */
+export declare function adjacentPages<T>(ordered: readonly T[], isCurrent: (page: T) => boolean): {
+    prev: T | null;
+    next: T | null;
+};

package/dist/pagination.js

@@ -56,4 +56,24 @@ export function listEnvelope(pages, total, page, pageSize, emptyNote) {
 export function toOffset({ page, pageSize }) {
     return { skip: (page - 1) * pageSize, take: pageSize };
 }
-//# sourceMappingURL=pagination.js.map
+/**
+ * The entries either side of the current one in an already-ordered list.
+ *
+ * The ordering is the caller's, deliberately — it is the one thing here that is
+ * never portable. A wiki's sequence is its section's configured sort, a
+ * knowledge base's is a taxonomy walk, and a company log's is `updatedAt` desc.
+ * What both wikis had written twice is this scan, not the sort.
+ *
+ * `null` on both sides when the page is not in the list, so a page reached by a
+ * URL its own section does not list renders no nav rather than a wrong one.
+ *
+ * No query. Both callers already hold the ordered siblings for something else —
+ * a related-pages panel, a section listing — and the two indexed lookups the
+ * neighbours used to cost were the reason one wiki dropped the control.
+ */
+export function adjacentPages(ordered, isCurrent) {
+    const i = ordered.findIndex(isCurrent);
+    if (i < 0)
+        return { prev: null, next: null };
+    return { prev: ordered[i - 1] ?? null, next: ordered[i + 1] ?? null };
+}

package/dist/rate-limit.d.ts

@@ -63,4 +63,21 @@ export declare function rateLimitHeaders(result: RateLimitResult, opts: RateLimi
 export declare function withRateLimit<T extends Response>(res: T, result: RateLimitResult, opts: RateLimitOptions): T;
 /** Test seam: the bucket map is module state and outlives a single test. */
 export declare function resetRateLimits(): void;
-//# sourceMappingURL=rate-limit.d.ts.map
+/**
+ * The one MCP rate-limit number, for every surface that states one.
+ *
+ * `.well-known/mcp.json`, the OpenAPI spec, agents.md, llms.txt and the
+ * `initialize` instructions all quote this, so the endpoint enforces exactly
+ * what the documents claim. It is a cross-surface contract, which is why it
+ * lives here rather than three times over: it had already drifted to 200 on one
+ * surface with nothing recorded about why, and that is the state that makes a
+ * number impossible to change safely later — nobody can tell a considered
+ * difference from a stale one.
+ *
+ * A surface with a genuine reason to differ passes its own `RateLimitOptions`.
+ * What it must not do is restate this one.
+ */
+export declare const MCP_RATE_LIMIT_PER_MIN = 60;
+export declare const MCP_RATE_LIMIT_TEXT = "60 requests per minute per IP";
+/** The budget as `mcpResponse` takes it, so a route states it once. */
+export declare const MCP_RATE_LIMIT: RateLimitOptions;

package/dist/rate-limit.js

@@ -110,4 +110,25 @@ export function withRateLimit(res, result, opts) {
 export function resetRateLimits() {
     buckets.clear();
 }
-//# sourceMappingURL=rate-limit.js.map
+// ---- the MCP budget ---------------------------------------------------------
+/**
+ * The one MCP rate-limit number, for every surface that states one.
+ *
+ * `.well-known/mcp.json`, the OpenAPI spec, agents.md, llms.txt and the
+ * `initialize` instructions all quote this, so the endpoint enforces exactly
+ * what the documents claim. It is a cross-surface contract, which is why it
+ * lives here rather than three times over: it had already drifted to 200 on one
+ * surface with nothing recorded about why, and that is the state that makes a
+ * number impossible to change safely later — nobody can tell a considered
+ * difference from a stale one.
+ *
+ * A surface with a genuine reason to differ passes its own `RateLimitOptions`.
+ * What it must not do is restate this one.
+ */
+export const MCP_RATE_LIMIT_PER_MIN = 60;
+export const MCP_RATE_LIMIT_TEXT = `${MCP_RATE_LIMIT_PER_MIN} requests per minute per IP`;
+/** The budget as `mcpResponse` takes it, so a route states it once. */
+export const MCP_RATE_LIMIT = {
+    capacity: MCP_RATE_LIMIT_PER_MIN,
+    refillPerSec: MCP_RATE_LIMIT_PER_MIN / 60,
+};