wiki-formant 0.28.0 → 0.29.0

package/README.md

@@ -148,7 +148,7 @@ handler: async (args, ctx) => {
 }
 ```
 
-`config.gate` is envelope-level middleware: it may withhold entries before dispatch and merge its own responses back afterwards. A payment gate has to sit there rather than in a handler, because the demand *replaces* the call and the receipt rides on the envelope.
+`config.gate` is envelope-level middleware: it may withhold entries before dispatch and merge its own responses back afterwards. A payment gate has to sit there rather than in a handler, because the demand *replaces* the call and the receipt rides on the envelope. `RpcRequest` and `toolText` are exported for a gate to build with; acuiq2's x402 gate is the one that does.
 
 ### Tool arguments and the corpus tool
 
@@ -213,6 +213,13 @@ export async function GET(request: Request) {
 }
 ```
 
+`corpusValidatorsFrom(seed, stamps)` is that pair from an aggregate: the newest of `stamps` (the epoch when every one is null), appended to `seed` for the tag. `corpusRoute(validators, build)` is the whole handler, and skips the build on a 304.
+
+```ts
+const agg = await prisma.page.aggregate({ _count: true, _max: { updatedAt: true } });
+corpusValidatorsFrom([depth, agg._count], [agg._max.updatedAt]);
+```
+
 ## Pagination and versioning
 
 `parsePagination` clamps `page ≥ 1` and `pageSize` to 1–100; `paginatedResponse` always carries `totalPages`. Reshaping that response is a breaking change to every client that pages, which is why it lives here rather than being re-typed per repo.
@@ -311,14 +318,6 @@ import Link from 'next/link';
 
 There is no `next` peer dependency here and there is not going to be one, but a rail that falls back to a bare `<a>` turns every press into a full page load — which is the whole reason a wiki has a persistent rail. So the router arrives through the door.
 
-## Payment gating
-
-`wiki-formant/x402` gates an MCP envelope on payment, for a wiki that charges for a bulk export over HTTP and would otherwise hand the same bytes over free through the equivalent MCP tool. Payment travels in-band — `params._meta["x402/payment"]` in, `result._meta["x402/payment-response"]` out — because one HTTP 402 cannot answer a batch of twenty in which one call is priced and nineteen are not.
-
-`gatePaidCalls` returns what `handleMcp` should dispatch and a `finish` that puts the answer back together. The ordering is the part worth owning once: verify before dispatch, settle only after a non-error answer, splice the challenges back into the caller's original order. A tool that raises cancels rather than settles — the caller pays for an answer, not an attempt.
-
-It imports nothing. `@x402/core`, `@x402/evm`, `@x402/extensions`, `@x402/next` and `viem` are optional peers, and the resource server arrives as a structural port instead of an import, so a wiki that never imports this subpath never resolves any of them. Which surfaces cost what, the prices and the terms text stay with the caller: those are policy, and this is the envelope surgery.
-
 ## AI crawlers
 
 Every wiki kept this roster twice — once in the proxy, keyed by user-agent, to
@@ -490,6 +489,27 @@ leafBlocks(blocks, BLOCK_SHAPE.containers);
 
 The dispatch over a repo's own block union stays in that repo; the bodies come from here. `wiki-formant/text` has a prose body for every core leaf — `statsToText`, `linkGridToText` and `pageListToText` joined the originals when two of the three wikis turned out to extract nothing from them, so their MCP `get_page` answered a hub page as nearly empty.
 
+The core leaves — `content`, `codeTabs`, `banner`, `references`, `stats`, `linkGrid`, `recentPages`, `pageList` — had the same case bodies in every wiki's text export, markdown twin, validator and new-block record. A repo's switch hands those cases over and keeps its own, so it stays exhaustive over its union:
+
+```ts
+import { coreAtomicText, coreAtomicToMarkdown, coreBlockDefaults } from 'wiki-formant/blocks';
+import { coreAtomicValidator } from 'wiki-formant/validation';
+
+switch (block.type) {
+  case 'content': case 'codeTabs': case 'banner': case 'references':
+  case 'stats': case 'linkGrid': case 'recentPages': case 'pageList':
+    return coreAtomicToMarkdown(block, { siteUrl: SITE_URL, referencesTitle: 'Sources' });
+  case 'corpusStats':
+    return block.resolvedHtml ? htmlToMarkdown(block.resolvedHtml) : '';
+}
+
+const BLOCK_DEFAULTS = { ...coreBlockDefaults({ stats }), daoTimeline: () => ({ type: 'daoTimeline', limit: 25 }) };
+const core = coreAtomicValidator({ pageId: id => /^\d{1,9}$/.test(id) });
+// validateAtomic: b => { switch (b.type) { case 'daoTimeline': …; default: return core(b); } }
+```
+
+`coreAtomicToMarkdown` joins a resolved page's site-relative `href` to `siteUrl`, because a twin is read off-site; a wiki whose lists hold its own page rows keeps those two cases. `coreAtomicValidator` caps `recentPages.limit` and `pageIds` at `MAX_BLOCK_ROWS`, a whole number of rows, because both end in a database `take:`; `blockLimit` is the same bound on the read side.
+
 `createBlockValidator` returns `blockIssues` beside the boolean validators: the same walk, reporting where each failure is.
 
 ```ts
@@ -504,7 +524,7 @@ A `codeTabs` tab's `code` is source text in every wiki here, and every view trea
 
 ## Dates
 
-`relativeTime(then, now, { style })` is `compact` (`3h`), `short` (`3h ago`) or `long` (`3 days ago`, day-grained for pages cached for hours), with `absoluteAfterDays` to hand over to the date itself. `now` is always passed in, never read, so a server render and its hydration agree. `formatDay` is always UTC: a stored day formatted in the server's zone, or the browser's, is the previous day for half the world. Both are in `wiki-formant/freshness`, with `isoDate`.
+`relativeTime(then, now, { style })` is `compact` (`3h`), `short` (`3h ago`) or `long` (`3 days ago`, day-grained for pages cached for hours), with `absoluteAfterDays` to hand over to the date itself. `now` is always passed in, never read, so a server render and its hydration agree. `formatDay` is always UTC: a stored day formatted in the server's zone, or the browser's, is the previous day for half the world. It reads `en-US` unless given a `locale`: `formatDay(day, { locale: 'en-GB', month: 'long' })` is `19 September 2026`. Both are in `wiki-formant/freshness`, with `isoDate`.
 
 ## Sanitising stored HTML
 
@@ -562,21 +582,32 @@ top of `src/analytics.ts`.
 
 ```ts
 // src/lib/track.ts
-export const sql: Sql = (query, ...values) => prisma.$queryRawUnsafe(query, ...values);
+const sql: Sql = (query, ...values) => prisma.$queryRawUnsafe(query, ...values);
+export const { trackEvent, trackMcpCall, trackSearch, viewRoute } =
+  createTracker({ sql, defer: after, siteUrl: SITE_URL });
 
 // src/app/api/view/route.ts – the whole beacon route
-export const POST = (request: Request) => collect(request, { sql, defer: after });
+export const POST = viewRoute();
 
 // the root layout, once
 <Beacon />
 ```
 
+`createTracker` records only on a Vercel production deployment unless told
+otherwise (`enabled`), because dev and previews write to production's
+database. `trackMcpCall(request, body, server?)` fits `McpServerConfig.onCall`;
+`trackSearch(headers, query, results, surface?)` takes the headers or Next's
+`headers` itself, which it reads inside the deferred write. `viewRoute({ site })`
+passes a site resolver to `collect`. The module that builds the tracker
+imports the app's database client, so a proxy reaches it through a dynamic
+`import()` inside `event.waitUntil`, never a static one.
+
 `<Beacon>` (`wiki-formant/react`) sends a view each time the path changes,
 client-side moves included, and a click on a link to another host as an
 "Outbound Link: Click" event; `track(name, props)` (`wiki-formant/dom`) sends
-any other browser event. Server code calls `recordEvent` and leaves the
-deferral to the framework, so this package keeps its zero-dependency
-guarantee:
+any other browser event. Underneath the tracker, server code calls
+`recordEvent` and leaves the deferral to the framework, so this package keeps
+its zero-dependency guarantee:
 
 ```ts
 const props = searchQueryProps({ query, results: rows.length, surface: 'wiki' });
@@ -613,15 +644,23 @@ No view emits a Tailwind utility any more — `ColumnsView` states its gap and a
 
 ## API
 
-Every module has a subpath — `wiki-formant/taxonomy`, `wiki-formant/mcp`, and so on.
-The emitted `.d.ts` files are the reference. There is no hand-maintained symbol list
-here, because the one that used to be here drifted from them.
-
-The package root re-exports the runtime modules that need no peer dependency and no
-client boundary, so `import … from 'wiki-formant'` stays importable from a route
-handler with nothing else installed. Everything that reaches for React, a browser
-global, tiptap or a wallet — and the tooling modules, which no route imports — is
-subpath-only.
+Every module has a subpath — `wiki-formant/taxonomy`, `wiki-formant/mcp`, and so on —
+and there is no root export: `import … from 'wiki-formant'` does not resolve. A
+barrel loads every module it names for the one symbol a route wanted, and had
+already re-exported one module twice. The emitted `.d.ts` files are the reference.
+There is no hand-maintained symbol list here, because the one that used to be here
+drifted from them.
+
+`wiki-formant/db` holds `pgPoolConfig(url)`, the options every app here hands to
+`new pg.Pool()`: ten clients on Supabase's 6543 transaction pooler, three on the
+5432 session pooler, whose fifteen-client cap a build's workers share.
+
+`rateLimit` takes `blockMs` (and a `blockKey`, default the bucket's own) for a
+caller already shown to be abusive: running dry blocks the key outright for that
+long, across every bucket that names it, rather than letting the refill trickle
+one token through at a time. `clientIp` reads `x-real-ip` first — Vercel sets it
+and overwrites any inbound copy — and the leftmost `x-forwarded-for` only where no
+`x-real-ip` was set, since a proxy that appends hands the client that slot.
 
 ## A bin
 

package/dist/analytics.d.ts

@@ -4,8 +4,6 @@ import { type HeaderReader, type RateLimitOptions } from './rate-limit.js';
  * Prisma: `(query, ...values) => prisma.$queryRawUnsafe(query, ...values)`.
  */
 export type Sql = (query: string, ...values: unknown[]) => Promise<unknown>;
-/** Long enough to compare a month with the same month a year before. */
-export declare const KEEP_DAYS = 400;
 /** iPadOS reports itself as a Mac, so its views count as a computer's. */
 export declare const deviceOf: (ua: string) => "phone" | "tablet" | "computer";
 /**
@@ -151,4 +149,56 @@ export interface SearchQueryInput {
  * keeps the prop and the query that produced it the same string.
  */
 export declare function searchQueryProps({ query, results, surface, }: SearchQueryInput): Record<string, string> | null;
+export interface TrackerOptions {
+    sql: Sql;
+    /** `after` in Next: the write runs once the response has gone. */
+    defer: (task: () => Promise<unknown>) => void;
+    /**
+     * Whether anything is recorded. Default: only on a Vercel production
+     * deployment, because dev and previews write to production's database.
+     */
+    enabled?: boolean;
+    /** Where an event with no page of its own is filed: a search with no referer. Default `/`. */
+    siteUrl?: string;
+}
+/** Headers in hand, or a reader for them run inside the deferred write: Next's `headers`. */
+export type HeaderSource = HeaderReader | (() => HeaderReader | Promise<HeaderReader>);
+export interface Tracker {
+    /**
+     * Record one event. `headers` are the request of whoever caused it, so the
+     * event joins their visitor, an agent's included; omit them for an event no
+     * visitor caused. Never rejects, and the caller defers it: `event.waitUntil`
+     * in a proxy, `after` in a route.
+     */
+    trackEvent(name: string, url: string, props: Record<string, string | number>, headers?: HeaderReader): Promise<void>;
+    /**
+     * An "MCP Call" event, deferred. The signature is `McpServerConfig.onCall`'s
+     * plus a server name, so a one-server site passes it as `onCall` as it is.
+     */
+    trackMcpCall(request: Request, body: unknown, server?: string): void;
+    /**
+     * A "Search Query" event, deferred, filed against the page the reader
+     * searched from. A function for `headers` is called inside the deferred
+     * write, and a failure there drops the event rather than the response.
+     */
+    trackSearch(headers: HeaderSource, query: string, results: number, surface?: string): void;
+    /**
+     * The beacon route: `export const POST = tracker.viewRoute()`. `site` is
+     * `collect`'s resolver, for an app that serves many sites or drops a path.
+     */
+    viewRoute(opts?: Pick<CollectOptions, 'site' | 'rateLimit'>): (request: Request) => Promise<Response>;
+}
+/**
+ * Everything an app's `track.ts` had written around the functions above: the
+ * production gate, the deferral and the three named events. Four apps carried
+ * it, two with a search signature of their own.
+ *
+ * The tracker holds `sql`, so the module that builds it imports the app's
+ * database client. A proxy must keep reaching it through a dynamic import
+ * inside `waitUntil`, never a static one, or every request the proxy sees
+ * loads Prisma:
+ *
+ *   event.waitUntil(import('@/lib/track').then(m => m.trackEvent('AI Bot Visit', url, { bot }, request.headers)));
+ */
+export declare function createTracker({ sql, defer, enabled, siteUrl, }: TrackerOptions): Tracker;
 export {};

package/dist/analytics.js

@@ -54,7 +54,7 @@
 // runs anywhere Node 20, a browser or an edge runtime does.
 import { clientIp, clientKey, rateLimit } from './rate-limit.js';
 /** Long enough to compare a month with the same month a year before. */
-export const KEEP_DAYS = 400;
+const KEEP_DAYS = 400;
 const DAY_MS = 86_400_000;
 /** A script that runs a page's JavaScript and says what it is. */
 const BOT = /bot|crawl|spider|slurp|headless|lighthouse|prerender|preview/i;
@@ -264,3 +264,47 @@ export function searchQueryProps({ query, results, surface, }) {
         ...(surface ? { surface } : {}),
     };
 }
+/**
+ * Everything an app's `track.ts` had written around the functions above: the
+ * production gate, the deferral and the three named events. Four apps carried
+ * it, two with a search signature of their own.
+ *
+ * The tracker holds `sql`, so the module that builds it imports the app's
+ * database client. A proxy must keep reaching it through a dynamic import
+ * inside `waitUntil`, never a static one, or every request the proxy sees
+ * loads Prisma:
+ *
+ *   event.waitUntil(import('@/lib/track').then(m => m.trackEvent('AI Bot Visit', url, { bot }, request.headers)));
+ */
+export function createTracker({ sql, defer, enabled = typeof process !== 'undefined' && process.env.VERCEL_ENV === 'production', siteUrl = '/', }) {
+    const trackEvent = (name, url, props, headers) => enabled ? recordEvent(sql, { name, url, props, headers }) : Promise.resolve();
+    return {
+        trackEvent,
+        trackMcpCall(request, body, server) {
+            if (!enabled)
+                return;
+            const props = mcpCallProps(request, body, server);
+            const { url, headers } = request;
+            defer(() => trackEvent('MCP Call', url, props, headers));
+        },
+        trackSearch(source, query, results, surface) {
+            if (!enabled)
+                return;
+            const props = searchQueryProps({ query, results, surface });
+            if (!props)
+                return;
+            defer(async () => {
+                try {
+                    const headers = typeof source === 'function' ? await source() : source;
+                    await trackEvent('Search Query', headers.get('referer') || siteUrl, props, headers);
+                }
+                catch {
+                    // A context with no readable headers loses the event, never the response.
+                }
+            });
+        },
+        viewRoute(opts = {}) {
+            return async (request) => enabled ? collect(request, { sql, defer, ...opts }) : new Response(null, { status: 204 });
+        },
+    };
+}

package/dist/blocks.d.ts

@@ -147,3 +147,142 @@ export declare function statsToMarkdown(items: readonly StatItem[]): string;
 export declare function linkGridToMarkdown(groups: readonly LinkGridGroup[], intro?: string | null): string;
 /** A flat bullet list of links — resolved page lists, feed items, link rails. */
 export declare function linkList(items: readonly LinkGridLink[]): string;
+/**
+ * The core leaves as the helpers below read them: the shape every wiki here
+ * stores, built from the leaf types above. `P` is what a resolved page list
+ * carries, because radix-wiki's lists hold its own page rows and the other two
+ * hold `ResolvedPageRef`s.
+ *
+ * Structural on purpose. A repo's own switch narrows its block to one of these
+ * cases and hands it over — `case 'stats': case 'linkGrid': … return
+ * coreAtomicText(block)` — so the switch stays exhaustive over the repo's union
+ * and the case bodies stop being written three times.
+ */
+export type CoreAtomicBlock<P = ResolvedPageRef> = {
+    type: 'content';
+    text: string;
+} | {
+    type: 'codeTabs';
+    tabs: readonly CodeTab[];
+} | {
+    type: 'banner';
+    variant: string;
+    text?: string | null;
+} | {
+    type: 'references';
+    title?: string | null;
+    items: readonly ReferenceItem[];
+} | {
+    type: 'stats';
+    items: readonly StatItem[];
+} | {
+    type: 'linkGrid';
+    intro?: string | null;
+    groups: readonly LinkGridGroup[];
+} | {
+    type: 'recentPages' | 'pageList';
+    resolvedPages?: readonly P[] | null;
+};
+/**
+ * One core leaf as prose, for the LLM and MCP exports. A page list reads only
+ * after the server has resolved it; unresolved, it extracts to nothing.
+ */
+export declare function coreAtomicText(block: CoreAtomicBlock<{
+    title: string;
+}>): string;
+export interface CoreMarkdownOptions {
+    /**
+     * The origin a resolved page's site-relative `href` is joined to. A twin is
+     * read off-site, where a bare `/wiki/…` resolves to nothing.
+     */
+    siteUrl: string;
+    /** A references block's heading when it stores none. Default `References`. */
+    referencesTitle?: string;
+}
+/** One core leaf as markdown, for a page's `.md` twin. */
+export declare function coreAtomicToMarkdown(block: CoreAtomicBlock, opts: CoreMarkdownOptions): string;
+export interface CoreBlockDefaultsOptions {
+    /** Ids for the nested rows a new block starts with. Default `crypto.randomUUID`. */
+    newId?: () => string;
+    /** A new references block's title. Default `References`. */
+    referencesTitle?: string;
+    /** A new code-tabs block's tabs, each empty. Default Rust and TypeScript. */
+    codeTabs?: ReadonlyArray<{
+        label: string;
+        language: string;
+    }>;
+    /** A new stats block's three placeholder cards. */
+    stats?: ReadonlyArray<{
+        value: string;
+        label: string;
+    }>;
+}
+/** What inserting each core type makes, without its `id`. */
+export interface CoreBlockDefaults {
+    content: () => {
+        type: 'content';
+        text: string;
+    };
+    recentPages: () => {
+        type: 'recentPages';
+        limit: number;
+    };
+    pageList: () => {
+        type: 'pageList';
+        pageIds: string[];
+    };
+    columns: () => {
+        type: 'columns';
+        columns: {
+            id: string;
+            blocks: never[];
+        }[];
+        gap: 'md';
+        align: 'start';
+    };
+    infobox: () => {
+        type: 'infobox';
+        blocks: never[];
+    };
+    codeTabs: () => {
+        type: 'codeTabs';
+        tabs: {
+            label: string;
+            language: string;
+            code: string;
+        }[];
+    };
+    stats: () => {
+        type: 'stats';
+        items: {
+            id: string;
+            value: string;
+            label: string;
+        }[];
+        columns: 3;
+    };
+    linkGrid: () => {
+        type: 'linkGrid';
+        groups: {
+            id: string;
+            heading: string;
+            links: never[];
+        }[];
+    };
+    references: () => {
+        type: 'references';
+        title: string;
+        items: never[];
+    };
+    banner: () => {
+        type: 'banner';
+        variant: 'stub';
+    };
+}
+/**
+ * The new-block factories for the core types, which all three wikis had typed
+ * out identically but for a few labels. Spread into a repo's own record beside
+ * its native types, so that record stays keyed by the repo's union:
+ * `{ ...coreBlockDefaults({ stats }), daoTimeline: () => … }`.
+ */
+export declare function coreBlockDefaults(opts?: CoreBlockDefaultsOptions): CoreBlockDefaults;

package/dist/blocks.js

@@ -12,6 +12,7 @@
 // keeps this file free of any one repo's type union.
 import { htmlToMarkdown, inlineToMarkdown } from './markdown.js';
 import { relativeTime } from './freshness.js';
+import { BANNER_LABELS, bannerToText, codeTabsToText, linkGridToText, pageListToText, referencesToText, statsToText, stripHtml, } from './text.js';
 export function pageRef(page, now, style = 'long') {
     return {
         title: page.title,
@@ -194,3 +195,70 @@ export function linkGridToMarkdown(groups, intro) {
 export function linkList(items) {
     return items.map(l => `- [${l.label}](${l.href})`).join('\n');
 }
+const bannerLabel = (variant) => BANNER_LABELS[variant] ?? variant;
+/**
+ * One core leaf as prose, for the LLM and MCP exports. A page list reads only
+ * after the server has resolved it; unresolved, it extracts to nothing.
+ */
+export function coreAtomicText(block) {
+    switch (block.type) {
+        case 'content': return stripHtml(block.text);
+        case 'codeTabs': return codeTabsToText(block.tabs);
+        case 'banner': return bannerToText(bannerLabel(block.variant), block.text);
+        case 'references': return referencesToText(block.items);
+        case 'stats': return statsToText(block.items);
+        case 'linkGrid': return linkGridToText(block.groups, block.intro);
+        case 'recentPages':
+        case 'pageList': return pageListToText(block.resolvedPages ?? []);
+    }
+}
+/** One core leaf as markdown, for a page's `.md` twin. */
+export function coreAtomicToMarkdown(block, opts) {
+    switch (block.type) {
+        case 'content': return htmlToMarkdown(block.text);
+        case 'codeTabs': return codeTabsToMarkdown(block.tabs);
+        case 'banner': return bannerToMarkdown(bannerLabel(block.variant), block.text);
+        case 'references': return referencesToMarkdown(block.items, block.title || opts.referencesTitle || 'References');
+        case 'stats': return statsToMarkdown(block.items);
+        case 'linkGrid': return linkGridToMarkdown(block.groups, block.intro);
+        case 'recentPages':
+        case 'pageList':
+            return linkList((block.resolvedPages ?? []).map(p => ({
+                label: p.title,
+                href: p.href.startsWith('/') ? `${opts.siteUrl}${p.href}` : p.href,
+            })));
+    }
+}
+/**
+ * The new-block factories for the core types, which all three wikis had typed
+ * out identically but for a few labels. Spread into a repo's own record beside
+ * its native types, so that record stays keyed by the repo's union:
+ * `{ ...coreBlockDefaults({ stats }), daoTimeline: () => … }`.
+ */
+export function coreBlockDefaults(opts = {}) {
+    const { newId = () => crypto.randomUUID(), referencesTitle = 'References', codeTabs = [
+        { label: 'Rust', language: 'rust' },
+        { label: 'TypeScript', language: 'typescript' },
+    ], stats = [
+        { value: '100+', label: 'Customers' },
+        { value: '$1M', label: 'Revenue' },
+        { value: '99%', label: 'Uptime' },
+    ], } = opts;
+    return {
+        content: () => ({ type: 'content', text: '' }),
+        recentPages: () => ({ type: 'recentPages', limit: 5 }),
+        pageList: () => ({ type: 'pageList', pageIds: [] }),
+        columns: () => ({
+            type: 'columns',
+            columns: [{ id: newId(), blocks: [] }, { id: newId(), blocks: [] }],
+            gap: 'md',
+            align: 'start',
+        }),
+        infobox: () => ({ type: 'infobox', blocks: [] }),
+        codeTabs: () => ({ type: 'codeTabs', tabs: codeTabs.map(t => ({ ...t, code: '' })) }),
+        stats: () => ({ type: 'stats', items: stats.map(s => ({ id: newId(), ...s })), columns: 3 }),
+        linkGrid: () => ({ type: 'linkGrid', groups: [{ id: newId(), heading: 'Group', links: [] }] }),
+        references: () => ({ type: 'references', title: referencesTitle, items: [] }),
+        banner: () => ({ type: 'banner', variant: 'stub' }),
+    };
+}

package/dist/db.d.ts

@@ -0,0 +1,21 @@
+/** The options `new pg.Pool()` takes, for the fields set here. */
+export interface PgPoolConfig {
+    connectionString: string | undefined;
+    max: number;
+    idleTimeoutMillis: number;
+    connectionTimeoutMillis: number;
+}
+/**
+ * Pool options sized by which Supabase pooler the URL names, because the
+ * ceiling belongs to the pooler and not to the app. Port 6543 is the
+ * TRANSACTION pooler, which exists to hold many short-lived clients; anything
+ * else is treated as the SESSION pooler on 5432, capped at 15 clients per
+ * project and shared with a build's workers, so three each is what fits.
+ *
+ * `pg` reports an exhausted pool as "timeout exceeded when trying to connect",
+ * which reads as a network fault and is not one: connecting takes well under a
+ * second, while an acquire queued behind busy clients waits the full
+ * `connectionTimeoutMillis`. `max: 1` was serial, and three everywhere rendered
+ * a page that fans out more than three queries in thirty seconds.
+ */
+export declare function pgPoolConfig(url: string | undefined): PgPoolConfig;

package/dist/db.js

@@ -0,0 +1,27 @@
+// db.ts — the pool settings every app here hands to `pg`.
+//
+// Four Prisma client modules carried the same block, comment and all. It is a
+// value, not a client: the app still owns `new pg.Pool(...)`, the adapter and
+// the globalThis cache, so this imports nothing.
+/**
+ * Pool options sized by which Supabase pooler the URL names, because the
+ * ceiling belongs to the pooler and not to the app. Port 6543 is the
+ * TRANSACTION pooler, which exists to hold many short-lived clients; anything
+ * else is treated as the SESSION pooler on 5432, capped at 15 clients per
+ * project and shared with a build's workers, so three each is what fits.
+ *
+ * `pg` reports an exhausted pool as "timeout exceeded when trying to connect",
+ * which reads as a network fault and is not one: connecting takes well under a
+ * second, while an acquire queued behind busy clients waits the full
+ * `connectionTimeoutMillis`. `max: 1` was serial, and three everywhere rendered
+ * a page that fans out more than three queries in thirty seconds.
+ */
+export function pgPoolConfig(url) {
+    return {
+        connectionString: url,
+        max: (url ?? '').includes(':6543') ? 10 : 3,
+        idleTimeoutMillis: 20_000,
+        // The acquire timeout, despite the message it fails with.
+        connectionTimeoutMillis: 30_000,
+    };
+}

package/dist/feed.d.ts

@@ -53,7 +53,6 @@ export interface FeedChannel {
  * exist to prevent. An empty feed has no build date rather than a fictional one.
  */
 export declare function renderFeed(channel: FeedChannel, items: readonly FeedItem[]): string;
-export declare const FEED_HEADERS: Record<string, string>;
 /**
  * The feed as a response, with the validators a poller revalidates against.
  *

package/dist/feed.js

@@ -89,7 +89,7 @@ export function renderFeed(channel, items) {
     ].join('\n');
 }
 const lastBuild = (channel, items) => channel.lastBuild ?? items.reduce((max, item) => (!max || item.date > max ? item.date : max), null);
-export const FEED_HEADERS = {
+const FEED_HEADERS = {
     'Content-Type': 'application/rss+xml; charset=utf-8',
     'Cache-Control': 'public, s-maxage=3600, stale-while-revalidate=86400',
 };

package/dist/freshness.d.ts

@@ -39,8 +39,13 @@ type When = Date | string | number;
  * timestamp formatted in the server's zone, or the browser's, lands on the
  * previous day for half the world, and the server and the hydrating client
  * disagree about which day it is.
+ *
+ * `locale` defaults to `en-US`; `{ locale: 'en-GB', month: 'long' }` reads
+ * `19 September 2026`.
  */
-export declare function formatDay(date: When, options?: Intl.DateTimeFormatOptions): string;
+export declare function formatDay(date: When, options?: Intl.DateTimeFormatOptions & {
+    locale?: string;
+}): string;
 /**
  * - `compact`: `now`, `2m`, `3h`, `5d`, `2mo`, `1y` — for dense rows.
  * - `short`: `just now`, `2m ago` … `1y ago`.

package/dist/freshness.js

@@ -60,14 +60,18 @@ const toMs = (d) => (typeof d === 'number' ? d : d instanceof Date ? d.getTime()
  * timestamp formatted in the server's zone, or the browser's, lands on the
  * previous day for half the world, and the server and the hydrating client
  * disagree about which day it is.
+ *
+ * `locale` defaults to `en-US`; `{ locale: 'en-GB', month: 'long' }` reads
+ * `19 September 2026`.
  */
-export function formatDay(date, options) {
-    return new Date(toMs(date)).toLocaleDateString('en-US', {
+export function formatDay(date, options = {}) {
+    const { locale = 'en-US', ...format } = options;
+    return new Date(toMs(date)).toLocaleDateString(locale, {
         year: 'numeric',
         month: 'short',
         day: 'numeric',
         timeZone: 'UTC',
-        ...options,
+        ...format,
     });
 }
 const plural = (n, unit) => `${n} ${unit}${n === 1 ? '' : 's'} ago`;

package/dist/http.d.ts

@@ -123,6 +123,16 @@ export interface CorpusValidators {
     etag: string;
     lastModified: string;
 }
+/**
+ * The validators for an aggregate: the ETag seeded from `seed` (the depth or
+ * scope, then the row count) with the newest stamp appended, and that stamp as
+ * Last-Modified. A corpus with no rows, or stamps all null, dates from the
+ * epoch, so an empty corpus still revalidates rather than throwing.
+ *
+ * Every wiki here wrote this after its `aggregate` call: newest of the `_max`
+ * columns, `?? new Date(0)`, then the same two lines.
+ */
+export declare function corpusValidatorsFrom(seed: ReadonlyArray<string | number | null | undefined>, stamps: ReadonlyArray<Date | null | undefined>): CorpusValidators;
 /**
  * A GET handler serving `build()` under corpus validators — or a 304 instead.
  *

package/dist/http.js

@@ -191,6 +191,19 @@ export function pageLine(opts) {
     const stamp = opts.updated ? isoDate(opts.updated) : '';
     return `- [${opts.title}](${opts.url})${excerpt}${stamp ? ` _(updated ${stamp})_` : ''}`;
 }
+/**
+ * The validators for an aggregate: the ETag seeded from `seed` (the depth or
+ * scope, then the row count) with the newest stamp appended, and that stamp as
+ * Last-Modified. A corpus with no rows, or stamps all null, dates from the
+ * epoch, so an empty corpus still revalidates rather than throwing.
+ *
+ * Every wiki here wrote this after its `aggregate` call: newest of the `_max`
+ * columns, `?? new Date(0)`, then the same two lines.
+ */
+export function corpusValidatorsFrom(seed, stamps) {
+    const newest = stamps.reduce((max, d) => (d instanceof Date && d.getTime() > max.getTime() ? d : max), new Date(0));
+    return { etag: corpusEtag([...seed, newest]), lastModified: newest.toUTCString() };
+}
 /**
  * A GET handler serving `build()` under corpus validators — or a 304 instead.
  *