@chatpanel/events 0.2.0

package/LICENSE

@@ -0,0 +1,168 @@
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+Required Notice: Copyright © 2026 ChatPanel (https://chatpanel.net)
+
+Licensor Line of Business: ChatPanel — an AI browser side-panel, its local
+bridge, and related developer tools and services (https://chatpanel.net)
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to
+distribute copies of the software.  Your license to distribute
+covers distributing the software with changes and new works
+permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright © 2026 ChatPanel (https://chatpanel.net)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any
+product that competes with the software or any product the
+licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality
+through different kinds of interfaces or for different technical
+platforms.  Applications can compete with services, libraries
+with plugins, frameworks with development tools, and so on,
+even if they're written in different programming languages
+or for different computer architectures.  Goods and services
+compete even when provided free of charge.  If you market a
+product as a practical substitute for the software or another
+product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does
+not compete, but the licensor or any of its affiliates brings
+your product into competition by providing a new version of
+the software or another product using the software, you may
+continue using versions of the software available under these
+terms beforehand to provide your competing product, but not
+any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product
+or service that the licensor or any of its affiliates has
+stopped providing, unless the licensor includes a plain-text
+line beginning with `Licensor Line of Business:` with the
+software that mentions that line of business.  For example:
+
+> Licensor Line of Business: ChatPanel — an AI browser side-panel, its local
+> bridge, and related developer tools and services (https://chatpanel.net)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of
+business developing the software or using the software
+to provide a product, the buyer can also enforce
+Noncompete for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law.  These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately.  If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+A **product** can be a good or service, or a combination
+of them.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+its affiliates.
+
+**Affiliates** means the other organizations that an
+organization has control over, is under the control of, or is
+under common control with.
+
+**Control** means ownership of substantially all the assets of
+an entity, or the power to direct its management and policies
+by vote, contract, or otherwise.  Control can be direct or
+indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

package/README.md

@@ -0,0 +1,183 @@
+# @chatpanel/events
+
+The canonical ChatPanel **event-log** and **capability** contracts. Pure, dependency-free
+ESM — the identical code runs in the extension (browser, MV3/CSP-safe), the gateway and
+the bridge, the same way [`@chatpanel/pii`](https://github.com/chatpanel/chatpanel-pii)
+does.
+
+Two contracts everything else inherits from:
+
+- **The event schema** — append-only, versioned forever, metadata only, and ordered
+  **without clocks**.
+- **The capability signature** — one call shape a rule, a schedule, the user or a model
+  all invoke identically.
+
+## Why it exists
+
+A ChatPanel run should be reconstructable: what context was assembled, which capability
+ran, in which class and on which runtime, what was redacted, and what left the device.
+That record is only trustworthy if it is *checkable*, so this package ships the
+invariants alongside the types.
+
+## Ordering without clocks
+
+```js
+import { linearize } from '@chatpanel/events'
+```
+
+> Replay orders events by topological sort over `causes`, breaking ties by `(host, seq)`
+> with hosts in lexicographic id order. **Wall time is never consulted.**
+
+Once two hosts append concurrently a timestamp is not an order — clocks skew, and two
+hosts can stamp the same millisecond. `at` is advisory and shown to humans; `(host, seq)`
+and `causes` are authority. `linearize()` is therefore a function of the event *set*, not
+of the array it was handed.
+
+## Durable facts, not streams
+
+Market ticks, live captions and DOM mutations are **not** events. They live in an
+in-memory ring buffer; only the windowed aggregate that entered a model request or
+crossed the device boundary is promoted. This is structural — there is no event type
+that would accept a per-tick item — because durably logging a caption stream is roughly
+3 MB per meeting and 5.5 GB a year.
+
+## Metadata only
+
+Events carry [`Ref`](./ref.js)s and counts, never content:
+
+```js
+makeRef({ kind: 'note', id: 'n_88', hash: 'sha256:…', range: { from: 10, to: 40 } })
+```
+
+Replay resolves a `Ref` by hash: match → exact reconstruction; absent or crypto-shredded
+→ `verified-but-unavailable`. It never silently substitutes today's version of the note.
+`privacy.redacted` carries how many of each entity type were redacted and never the
+values — a log of what was redacted must not itself contain the redacted data.
+
+## The capability signature
+
+```js
+validateCapability({
+  id: 'page.actions', version: '1.0.0', class: 'R',
+  requires: ['tab'], provides: ['page.tools'],
+  reads: ['page'], writes: ['page'],
+  egress: 'none', effects: 'non-replayable',
+  disclose: () => ({ name: 'page.actions', gist: 'Act on the current web page' }),
+  output: { schema: …, render: (v) => … },
+  invoke: async (input, ctx) => …,
+})
+```
+
+`actor` on an invocation is what makes capabilities turn-independent. `requirements`
+(`maxLatencyMs`, `deterministic`, `egress`, `maxCostUsd`) is what a router dispatches on —
+*what must be true*, not *which model* — and `canSatisfy()` **refuses** rather than
+silently exceeding a budget.
+
+Class is intrinsic (a determinism guarantee); latency is host-bound. The two are never
+fused into one table.
+
+`toModelSchema()` is an **allowlist** built from three fields, never an omit-list — so
+`invoke`, `effects`, `cost`, `writes` and `egress` cannot leak into a model request.
+
+## Stores — persistence is a host adapter
+
+```js
+const log   = createLogStore(adapter)    // append-only events
+const blobs = createBlobStore(adapter)   // content-addressed, deduped
+```
+
+The *semantics* live here; each host supplies the storage underneath — IndexedDB in the
+extension, SQLite on a gateway or daemon, a capped ring buffer colocated. An in-memory
+adapter ships for tests, colocated hosts and the replay harness.
+
+`append()` is **idempotent on event id**, so replicating to a warm tier can retry
+safely — the log-level counterpart of the idempotency keys capabilities carry. A seq that
+moves *backwards* for a host is rejected as a corrupt writer; gaps are allowed, because
+eviction must not corrupt the log. `cursor()` and `since()` are the replication pair.
+
+The two stores are separate so **crypto-shredding** works: `blobs.shred(hash)` drops the
+payload and leaves a tombstone, so "delete this meeting" can be honoured against an
+append-only log while every event that referenced it, and the causality chain, stay
+intact. Replay then reports `verified-but-unavailable`.
+
+## The registry — effects and reactive availability
+
+```js
+const reg = createRegistry({ onEvent })
+reg.register({ name: 'page-tools', requires: ['tab'], apply(ctx) {
+  ctx.effect(() => { const off = arm(); return () => off() })   // unwinds automatically
+}})
+const withdraw = reg.provide('tab', tab)   // page-tools activates
+withdraw()                                  // page-tools deactivates and unwinds
+```
+
+This is the runtime half of the capability contract: `requires`/`provides` in a
+declaration only mean something because something binds them here. Two rules carry it,
+and each prevents a specific bug class:
+
+1. **LIFO disposal** — inverses run in reverse order of registration, so each meets the
+   state its own application produced.
+2. **Dependents deactivate *before* a provider's binding is removed** — a component
+   being torn down because its provider is leaving is running teardown that frequently
+   *needs* the very capability being withdrawn (closing a pool means handing connections
+   back). Remove the binding first and that teardown reaches for something already gone.
+
+A failing component is recorded on itself, unwinds whatever it registered, and leaves
+its siblings running. A dependency cycle simply leaves its components permanently
+inactive — and unlike a schedule-dependent deadlock it is visible from the declarations
+alone, so `pending()` can report it at load time.
+
+No dependency *resolution*: this binds availability, it does not solve versions.
+
+## Invariants
+
+```js
+checkInvariants(events) // → [] when the log is sound
+```
+
+| | |
+|---|---|
+| **I1** | Model-visible input is reconstructable from the log |
+| **I2** | Every egress is recorded (`controlled: false` for delegated agents) |
+| **I3** | Non-pure invocations carry an idempotency key |
+| **I4** | Every activation has a recorded inverse |
+| **I5** | Ephemeral streams never become durable facts |
+| **I6** | Replay is deterministic |
+
+I3 is additionally structural: a non-pure `capability.invoked` without a key fails
+`validateEvent`, so it cannot enter the log at all.
+
+## The replay harness
+
+```js
+const report = replay(parseJsonl(log), { blobs })
+if (!report.ok) { console.error(formatReport(report)); process.exit(1) }
+```
+
+Run it in CI and the determinism claim stops being a comment. It reproduces order from
+`(host, seq)` and `causes`, checks I1–I6, and resolves every resident `Ref` by hash.
+
+Two outcomes are worth distinguishing, because they look similar and mean opposite
+things:
+
+- a blob that is **gone** (crypto-shredded or evicted) reports *verified-but-unavailable*
+  and **passes** — shredding is a feature, and the log still proves what was sent;
+- a source that **changed** reports *drifted* and **fails**, because the alternative is
+  replay quietly substituting today's note for the one actually sent.
+
+## Install
+
+```sh
+npm install @chatpanel/events
+```
+
+Node ≥ 20. No dependencies. `node --test tests/*.test.js`.
+
+The default `digest` and id factory use the **global** WebCrypto, which every browser has
+and which Node exposes without a flag from 19 onward — hence ≥ 20 rather than ≥ 18 (EOL
+since April 2025). Both are injectable, so a host with its own crypto never touches the
+default.
+
+## License
+
+See [LICENSE](./LICENSE).

package/adapters.js

@@ -0,0 +1,83 @@
+// Surface adapters — the plugin contract for "this app is driven better by its own data
+// format than by pointer automation".
+//
+// Excalidraw is drawn by writing scene elements, a spreadsheet is filled by addressing
+// cells, a diagram tool by inserting nodes. Each of those is the SAME shape of thing:
+// recognise a page, offer a tool, say how to use it, execute it. That was hardcoded as a
+// list inside one 1,200-line module, which meant every new app edited a shared file and
+// nothing outside the extension could offer one at all.
+//
+// As a plugin contract instead (P15): an adapter is declared, registered with the kernel,
+// and discovered. The desktop and mobile clients get the same registry; a user or a skill
+// can eventually contribute one without touching this code.
+//
+// WHAT IS SHARED IS THE CONTRACT, NOT THE ADAPTER. Recognition and selection are pure and
+// live here; the execution of any real adapter needs a platform (chrome.scripting, CDP)
+// and therefore lives in the client, injected at registration.
+
+export class AdapterError extends Error {
+  constructor(code, message) { super(message); this.name = 'AdapterError'; this.code = code; }
+}
+
+/**
+ * Declare an adapter.
+ *
+ * @param matches  (url, caps) => boolean. Given the URL and whatever capability probe the
+ *                 host performed, so an adapter can recognise a self-hosted or embedded
+ *                 instance rather than only a known hostname — the reason a hostname table
+ *                 was rejected in the first place.
+ * @param priority higher wins when two adapters match. Ties break on registration order,
+ *                 so the answer is stable rather than dependent on activation timing.
+ */
+export function defineAdapter({ id, label, matches, toolSpecs, guidance, execute, priority = 0 }) {
+  if (!id) throw new AdapterError('BAD_ADAPTER', 'adapter.id required');
+  if (typeof matches !== 'function') throw new AdapterError('BAD_ADAPTER', `adapter '${id}': matches required`);
+  if (typeof execute !== 'function') throw new AdapterError('BAD_ADAPTER', `adapter '${id}': execute required`);
+  return Object.freeze({
+    id,
+    label: label || id,
+    matches,
+    priority,
+    toolSpecs: typeof toolSpecs === 'function' ? toolSpecs : () => [],
+    guidance: typeof guidance === 'function' ? guidance : () => '',
+    execute,
+  });
+}
+
+/**
+ * The registry a host binds adapters into.
+ *
+ * Deliberately independent of the kernel: a plugin registers through the kernel and calls
+ * `add` from its activate, but a host with no kernel yet can still use this. Coupling them
+ * would make the plugin model a prerequisite for a feature rather than a way to build it.
+ */
+export function createAdapterRegistry() {
+  const adapters = [];
+  return {
+    /** Register an adapter. Returns its remover, so registration is revertible (P15). */
+    add(adapter) {
+      adapters.push(adapter);
+      return () => {
+        const i = adapters.indexOf(adapter);
+        if (i >= 0) adapters.splice(i, 1);
+      };
+    },
+
+    list: () => [...adapters],
+
+    /**
+     * The adapter for a page, or null.
+     *
+     * A matcher that throws is treated as "no match" rather than taking the page down: one
+     * badly-written adapter must not stop the others being offered, which is the same
+     * isolation rule the source registry follows.
+     */
+    for(url, caps = {}) {
+      const hits = adapters.filter((a) => {
+        try { return !!a.matches(url, caps); } catch { return false; }
+      });
+      if (!hits.length) return null;
+      return hits.sort((a, b) => b.priority - a.priority)[0];
+    },
+  };
+}

package/capability.js

@@ -0,0 +1,121 @@
+// The capability signature — one call shape a rule, a schedule, the user or a model all
+// invoke identically, through one policy path.
+//
+// `actor` is the field that makes capabilities turn-independent; it is the whole of the
+// "capabilities are not turn-shaped" principle expressed as data rather than as a
+// subsystem.
+//
+// `requirements` is what the router dispatches on: not "which model" but "what must be
+// true". {maxLatencyMs:100, deterministic:true, egress:'none'} selects class R or M on a
+// host that can realize it — or REFUSES. Silently exceeding a declared budget is the
+// failure mode this exists to prevent.
+
+import { CLASSES, EFFECTS, EGRESS, ACTOR_KINDS, SCOPE_KINDS, EventError } from './event.js';
+
+export const DATA_SCOPES = Object.freeze(['notes', 'meetings', 'chats', 'page', 'files', 'net']);
+
+const str = (v) => typeof v === 'string' && v.length > 0;
+const strs = (v, allowed = null) => Array.isArray(v) && v.every((x) => str(x) && (!allowed || allowed.includes(x)));
+
+/**
+ * Validate a capability DECLARATION — the static surface a reviewer, a user or an admin
+ * approves BEFORE the capability runs. Everything here is readable without executing
+ * anything, which is what makes load-time approval possible.
+ */
+export function validateCapability(c) {
+  if (!c || typeof c !== 'object') throw new EventError('SHAPE', 'capability must be an object');
+  if (!str(c.id)) throw new EventError('SHAPE', 'capability.id required');
+  if (!str(c.version)) throw new EventError('SHAPE', 'capability.version required');
+  if (!CLASSES.includes(c.class)) throw new EventError('SHAPE', `capability.class must be one of ${CLASSES}`);
+  if (!strs(c.requires)) throw new EventError('SHAPE', 'capability.requires must be string[]');
+  if (!strs(c.provides)) throw new EventError('SHAPE', 'capability.provides must be string[]');
+  if (!strs(c.reads, DATA_SCOPES)) throw new EventError('SHAPE', `capability.reads must be within ${DATA_SCOPES}`);
+  if (!strs(c.writes, DATA_SCOPES)) throw new EventError('SHAPE', `capability.writes must be within ${DATA_SCOPES}`);
+  if (!EGRESS.includes(c.egress)) throw new EventError('SHAPE', `capability.egress must be one of ${EGRESS}`);
+  if (!EFFECTS.includes(c.effects)) throw new EventError('SHAPE', `capability.effects must be one of ${EFFECTS}`);
+  if (typeof c.invoke !== 'function') throw new EventError('SHAPE', 'capability.invoke required');
+  if (typeof c.disclose !== 'function') throw new EventError('SHAPE', 'capability.disclose required');
+  if (!c.output || typeof c.output.render !== 'function') {
+    throw new EventError('SHAPE', 'capability.output.render required — canonical value and rendering are separate');
+  }
+  // A class-R capability that declares egress is a contradiction: R is a determinism
+  // guarantee, and a network round-trip is not deterministic.
+  if (c.class === 'R' && c.egress !== 'none') {
+    throw new EventError('CONTRADICTION', 'class R must declare egress:none');
+  }
+  return c;
+}
+
+/**
+ * Validate an INVOCATION. Enforces the one rule that is easiest to forget and worst to
+ * miss: a capability that is not `pure` cannot be invoked without an idempotency key,
+ * because a retried delegated call would otherwise perform the side effect twice.
+ */
+export function validateInvocation(inv, capability) {
+  if (!inv || typeof inv !== 'object') throw new EventError('SHAPE', 'invocation must be an object');
+  if (!str(inv.capability)) throw new EventError('SHAPE', 'invocation.capability required');
+  if (!inv.actor || !ACTOR_KINDS.includes(inv.actor.kind) || !str(inv.actor.id)) {
+    throw new EventError('SHAPE', `invocation.actor.kind must be one of ${ACTOR_KINDS}`);
+  }
+  if (!inv.scope || !SCOPE_KINDS.includes(inv.scope.kind) || !str(inv.scope.id)) {
+    throw new EventError('SHAPE', `invocation.scope.kind must be one of ${SCOPE_KINDS}`);
+  }
+  if (!Array.isArray(inv.causes)) throw new EventError('SHAPE', 'invocation.causes must be string[]');
+  const effects = capability ? capability.effects : inv.effects;
+  if (effects && effects !== 'pure' && !str(inv.idempotencyKey)) {
+    throw new EventError('IDEMPOTENCY', `invocation of a '${effects}' capability requires an idempotencyKey`);
+  }
+  return inv;
+}
+
+/**
+ * Can this capability satisfy these requirements on this host?
+ * Returns { ok, reasons[] } — REFUSING is a valid, expected outcome.
+ *
+ * `host` supplies what it can actually realize: { realizes: {R:{maxMs},M:{maxMs},...} }.
+ * Class is intrinsic (a guarantee); latency is host-bound. Never fuse the two.
+ */
+export function canSatisfy(capability, requirements = {}, host = null) {
+  const reasons = [];
+  const { maxLatencyMs, deterministic, egress, maxCostUsd } = requirements;
+
+  if (deterministic === true && !['R', 'M'].includes(capability.class)) {
+    reasons.push(`class ${capability.class} is not deterministic`);
+  }
+  if (egress === 'none' && capability.egress !== 'none') {
+    reasons.push(`capability egresses '${capability.egress}', requirement is 'none'`);
+  }
+  if (egress === 'redacted' && capability.egress === 'delegated') {
+    reasons.push('delegated egress is not controlled, requirement is redacted');
+  }
+  if (maxLatencyMs != null && host) {
+    const realized = host.realizes && host.realizes[capability.class];
+    if (!realized) reasons.push(`host cannot realize class ${capability.class}`);
+    else if (realized.maxMs > maxLatencyMs) {
+      reasons.push(`host realizes class ${capability.class} at ~${realized.maxMs}ms, requirement is ${maxLatencyMs}ms`);
+    }
+  }
+  if (maxCostUsd != null && capability.class === 'C' && maxCostUsd <= 0) {
+    reasons.push('cloud class requires a positive cost ceiling');
+  }
+  return { ok: reasons.length === 0, reasons };
+}
+
+/**
+ * The model-facing projection — an ALLOWLIST built from exactly three fields.
+ *
+ * Never an omit-list. An omit-list leaks the next field someone adds; this cannot,
+ * because `invoke`, `effects`, `cost`, `writes` and `egress` are never copied.
+ */
+export function toModelSchema(capability) {
+  return {
+    name: capability.id,
+    description: capability.disclose().gist,
+    parameters: capability.input || { type: 'object', properties: {} },
+  };
+}
+
+/** The same allowlist over a toolset — the only supported way to build a model request. */
+export function toModelSchemas(capabilities) {
+  return capabilities.map(toModelSchema);
+}

package/citations.js

@@ -0,0 +1,79 @@
+// Turn the citations a model wrote into the citations a reader can click.
+//
+// Models are told to cite as markdown links and finish with a Sources section. Large ones
+// mostly comply; small ones write bare `[1]` and stop — and a user then sees numbers that
+// reference nothing, with the URLs sitting unused in a tool result they never see. That is
+// exactly what happened on a real answer about SpaceX: five sources fetched, five bracket
+// numbers rendered, no links anywhere.
+//
+// The instinct is to write a firmer instruction. But the mapping from [1] to a URL is
+// already known EXACTLY — the tool result numbered them — so this is a substitution, not a
+// judgement, and a deterministic pass cannot fail to follow it. Prompting is the wrong tool
+// for something a rule can guarantee.
+//
+// Shared rather than client-side: any client that shows model output with sources needs
+// this, and the numbering convention belongs with the tool contract that produced it.
+
+/** `[1] [Title](https://url)` — the citation index every search result opens with. */
+const INDEX_RE = /^\[(\d+)\]\s*\[([^\]]*)\]\(([^)\s]+)\)/gm;
+
+/**
+ * Recover the numbered sources from a tool result.
+ *
+ * Parsed from the SAME text the model was shown, so the numbers can never disagree with
+ * what it read — deriving them from anywhere else would reintroduce the mismatch this
+ * exists to remove.
+ */
+export function sourcesFromToolText(text) {
+  const out = new Map();
+  for (const m of String(text || '').matchAll(INDEX_RE)) {
+    const rank = Number(m[1]);
+    if (!out.has(rank)) out.set(rank, { rank, title: m[2].trim(), url: m[3] });
+  }
+  return [...out.values()].sort((a, b) => a.rank - b.rank);
+}
+
+// A bare citation: [1] or [1, 3] or [1,3] — but NOT a markdown link `[x](url)`, NOT a
+// footnote definition at line start, and not `[]`.
+const BARE_RE = /\[(\d+(?:\s*,\s*\d+)*)\](?!\()/g;
+
+/**
+ * Rewrite bare `[n]` citations as markdown links, and append a Sources section listing
+ * exactly what was cited.
+ *
+ * Only ever ADDS links; text the model already wrote as a link is untouched, and a number
+ * with no matching source is left exactly as it is — inventing a link for `[7]` when seven
+ * sources were never returned would be fabricating a citation, which is worse than an
+ * unlinked number.
+ */
+export function linkifyCitations(answer, sources, { heading = 'Sources' } = {}) {
+  const text = String(answer ?? '');
+  const byRank = new Map((sources || []).filter((s) => s?.url).map((s) => [Number(s.rank), s]));
+  if (!text.trim() || !byRank.size) return text;
+
+  const cited = new Set();
+  // Skip fenced code: a `[1]` inside a code block is code, not a citation.
+  const parts = text.split(/(```[\s\S]*?```|`[^`\n]*`)/g);
+  const linked = parts.map((part, i) => {
+    if (i % 2 === 1) return part;                       // the captured code spans
+    return part.replace(BARE_RE, (whole, group) => {
+      const ranks = group.split(',').map((n) => Number(n.trim()));
+      if (!ranks.every((n) => byRank.has(n))) return whole;   // unknown number → leave alone
+      ranks.forEach((n) => cited.add(n));
+      return ranks.map((n) => `([${n}](${byRank.get(n).url}))`).join(' ');
+    });
+  }).join('');
+
+  if (!cited.size) return linked;
+
+  // A Sources section the model already wrote is left alone — appending a second one is a
+  // worse outcome than a slightly differently-formatted first.
+  // Match the heading however it was written — `## Sources`, `**Sources**`, or bare. The
+  // first version only matched the bare form, so a model that bolded it got a second one.
+  if (new RegExp(`(^|\\n)\\s*(?:#{1,6}\\s*|\\*\\*)?${heading}\\b`, 'i').test(linked)) return linked;
+
+  const list = [...cited].sort((a, b) => a - b)
+    .map((n) => { const s = byRank.get(n); return `${n}. [${s.title || s.url}](${s.url})`; })
+    .join('\n');
+  return `${linked.trimEnd()}\n\n**${heading}**\n${list}\n`;
+}