@agenthoney/analytics 0.0.0-stage → 0.14.0

package/dist/next.d.ts

@@ -0,0 +1,90 @@
+import { type Collector } from "./core/collector.js";
+import { type AgentHoneyConfig } from "./core/config.js";
+import { advertiseHeader, type TwinOptions } from "./serve/twin.js";
+/**
+ * The Next.js adapter, for `proxy.ts` (called `middleware.ts` before Next 16).
+ *
+ * ── ⚠️ Why this exists rather than "just use ./web" ──────────────────────────
+ * Because `./web` produces FALSE DATA in a Next proxy, and does it silently.
+ *
+ * A proxy runs **before the route**. It hands control onward by returning
+ * `NextResponse.next()` — a sentinel with status 200, no real content-type and
+ * no content-length. `./web` reads that sentinel and records
+ * `{ status: 200, observation: "measured" }`, so **every event claims a
+ * measured 200**, including requests the route renders as 404 or 500.
+ *
+ * ⚠️ **Our own schema already said this was wrong and refused it**:
+ * `observation: "unknown"` may not carry a status, and the Next case is the one
+ * where the `response` object is absent entirely — "we never had a chance to
+ * look". Correct behaviour, specified, enforced by a `superRefine`, and until
+ * now unreachable because no adapter emitted it. That reads as done, which is
+ * worse than reading as missing.
+ *
+ * ── What this emits ──────────────────────────────────────────────────────────
+ * Exactly what a proxy genuinely knows — method, path, host, user agent,
+ * referrer origin, campaign — and **no `response` object at all**, unless it
+ * served the twin itself, in which case it made the response and can measure it
+ * honestly.
+ *
+ * ── ⚠️ The requestId merge is DESIGNED and NOT BUILT ─────────────────────────
+ * `requestId` rides every event so a later post-response observation can be
+ * merged onto it. **Nothing performs that merge today** — measured: nothing in
+ * the worker or the database reads the field. Next offers no general
+ * post-response hook (`onRequestError` fires only on errors; `after()` still
+ * runs in the proxy, which cannot see the route's response), so the honest
+ * second observation point is a wrapper around each route handler — a second
+ * install step, easy to forget, and a half-installed product reports half its
+ * traffic.
+ *
+ * So this ships the single honest observation. That is not a degraded event: a
+ * proxy cannot see a response, and saying so precisely is the product's
+ * differentiator rather than a shortfall.
+ *
+ * ── ⚠️ `after` is an OPTION, not an import ───────────────────────────────────
+ * There is no `ctx.waitUntil` in a Next proxy; the equivalent is `after()` from
+ * `next/server`. Importing it here — even dynamically — would put a bare
+ * specifier in a package whose whole discipline is zero runtime dependencies,
+ * and a dynamic `import()` slips past `check-sdk-artifact.mjs`'s regex, which
+ * would be a gate quietly stopping working. So the customer passes it, exactly
+ * as `observe()` already takes `waitUntil`:
+ *
+ * ```ts
+ * import { after } from "next/server";
+ * import { proxy } from "@agenthoney/analytics/next";
+ *
+ * export default proxy({ after });
+ * export const config = { matcher: ["/((?!_next/static).*)"] };
+ * ```
+ *
+ * Without it the collector falls back to its own 2s timer, which a serverless
+ * deployment can freeze before it fires.
+ */
+export interface ProxyOptions extends AgentHoneyConfig {
+    /**
+     * `after` from `next/server`. Passed rather than imported — see the docblock.
+     * Omitting it is supported and costs reliability on serverless.
+     */
+    after?: (task: () => void | Promise<void>) => void;
+    /** For tests, and for a host that already has a collector. */
+    collector?: Collector;
+    /**
+     * Serve a markdown twin from the proxy.
+     *
+     * ⚠️ A proxy is a GOOD place for this, unlike the observation half: it runs
+     * before the route, so returning the twin short-circuits rendering entirely
+     * and the agent never pays for a React tree it discards. And because the
+     * proxy built that response itself, the event can honestly say `measured`.
+     */
+    twin?: TwinOptions;
+}
+/**
+ * ⚠️ Returns `undefined` to continue, rather than `NextResponse.next()`.
+ *
+ * Next treats a void return as "carry on", which means this adapter never has
+ * to import `next/server` at all. It also removes the exact sentinel that made
+ * `./web` lie here: there is no fake 200 to accidentally observe.
+ */
+export type ProxyResult = Response | undefined;
+export declare function proxy(options?: ProxyOptions): (request: Request) => Promise<ProxyResult>;
+/** Advertise a twin from a route handler, where the response actually exists. */
+export { advertiseHeader };

package/dist/next.js

@@ -0,0 +1,5 @@
+export { proxy } from './chunk-OH4H2B7O.js';
+export { advertiseHeader } from './chunk-L22VERBM.js';
+import './chunk-F3PRHEXB.js';
+//# sourceMappingURL=next.js.map
+//# sourceMappingURL=next.js.map

package/dist/next.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"next.js"}

package/dist/observe/client-ip.d.ts

@@ -0,0 +1,109 @@
+import type { RequestEvent } from "@agenthoney/event-schema";
+/**
+ * The end client's address, and the coarse country — the two facts this SDK is
+ * the ONLY thing positioned to supply.
+ *
+ * ── ⚠️ Why the SDK has to send it ────────────────────────────────────────────
+ * Ingest's socket peer is the customer's SERVER, not their visitor. So unlike a
+ * browser beacon, AgentHoney cannot observe a visitor's address itself, and
+ * `network.ip` is the one field whose absence quietly disables a whole tier of
+ * the product: **verification is IP work** — forward-confirmed reverse DNS, or
+ * a vendor-published range. With no address every crawler stays `CLAIMED`
+ * forever and `VERIFIED` is unreachable. Measured on live traffic 2026-09-17,
+ * before this existed: 590 stored events, 581 `UNVERIFIABLE`, 9 `CLAIMED`,
+ * **0 `VERIFIED`**, 2 country codes, and those two came from a hand-made test
+ * payload rather than from any adapter.
+ *
+ * ── ⚠️ Trust is the whole design, not a detail ───────────────────────────────
+ * `x-forwarded-for` is **client-supplied**. Anyone can send one. And a spoofed
+ * address is not merely a wrong row: `GPTBot` in the user agent plus a real
+ * OpenAI address in `x-forwarded-for` would forward-confirm and mint a
+ * **`VERIFIED` GPTBot** row in a customer's dashboard. Verification would then
+ * be a badge an attacker can award themselves, which is worse than not having
+ * one — the honesty of that pill is the product.
+ *
+ * So the default source is **platform edge headers plus what the framework
+ * already believes**, never a bare `x-forwarded-for`:
+ *
+ *   - Edge headers (`cf-connecting-ip` and friends) are written by the
+ *     proxy itself and OVERWRITE whatever the client sent -- ON that
+ *     platform. **Their PRESENCE proves nothing by itself**: a visitor
+ *     talking directly to a customer's own nginx can send a `cf-connecting-ip`
+ *     that nothing ever overwrites, because there is no Cloudflare in the
+ *     path to overwrite it. Reading these in `platform` mode is trusting that
+ *     the deployment matches the header's name, which is the whole of what
+ *     the mode name promises the customer is asserting.
+ *   - Express's `req.ip` is the customer's OWN `trust proxy` decision. We
+ *     inherit it rather than inventing a trust policy on their behalf; with no
+ *     `trust proxy` configured it is simply the socket address.
+ *   - `x-forwarded-for` is read only when a customer sets
+ *     `clientIp: "forwarded"`, and then only its RIGHTMOST hop -- see
+ *     `rightmost` below, which is what makes that opt-in safe rather than a
+ *     promise the customer has to keep. It is a statement that a trusted proxy sets
+ *     it. The option's name says what it trusts.
+ *
+ * ⚠️ **`forwarded` mode never reads a platform header.** Choosing `forwarded`
+ * is the customer saying "my own reverse proxy is what's in front of me, and
+ * it sets `x-forwarded-for` honestly" -- which is precisely the case where a
+ * platform edge is NOT terminating the connection, so a `cf-connecting-ip` on
+ * that request was written by the visitor, not overwritten by Cloudflare.
+ * Reading it anyway, as this did before 2026-09-20, let `GPTBot` plus a
+ * forged `cf-connecting-ip` reverse-DNS-confirm and mint a `VERIFIED` row on
+ * exactly the self-hosted installs Phase 69 pointed `forwarded` at. See
+ * `docs/design/accepted-risks.md` R14.
+ *
+ * ⚠️ **Country is independent of the address.** A platform that already
+ * resolved one hands it over in a header, and taking it costs nothing and
+ * discloses nothing: it is coarse by construction. So `clientIp: false` still
+ * yields geography, which is the cheapest honest version of this feature.
+ */
+/** Where an address may come from. `false` sends none, ever. */
+export type ClientIpSource = "platform" | "forwarded" | false | ((facts: IpFacts) => string | undefined);
+export interface IpFacts {
+    /** Case-insensitive header lookup. Lowercase names in, single value out. */
+    header: (name: string) => string | undefined;
+    /** The peer on the socket. Express only; a `Request` does not carry one. */
+    socketIp?: string | undefined;
+    /** Express's `req.ip` — the app's own `trust proxy` verdict. */
+    frameworkIp?: string | undefined;
+}
+/**
+ * One address, in one canonical form, or nothing.
+ *
+ * ⚠️ **`::ffff:1.2.3.4` and `1.2.3.4` are the SAME client**, and a Node socket
+ * reports the first form on a dual-stack listener while every proxy header
+ * reports the second. Left alone they hash to two different pseudonyms, so one
+ * visitor becomes two and one crawler's verification is done twice — which is
+ * exactly the kind of quiet wrongness this product cannot afford. They are
+ * folded here, once, rather than at three call sites.
+ *
+ * ⚠️ A port is stripped (`1.2.3.4:51234`, and `[::1]:8080`), because a port is
+ * per-connection: keeping it would make every request from one client a
+ * different address.
+ */
+export declare function normaliseIp(raw: string | undefined | null): string | undefined;
+export declare function resolveClientIp(facts: IpFacts, source: ClientIpSource): string | undefined;
+export declare function resolveCountry(facts: IpFacts): string | undefined;
+/**
+ * What the OPERATOR configured, which is not the same question as where this
+ * one address came from.
+ *
+ * ⚠️ It reports the SETTING, not the header that happened to answer. "platform
+ * mode, and nothing is arriving" is an install that was never finished;
+ * "off" is an answer somebody gave. Without this field a dashboard cannot tell
+ * them apart, and the only honest thing it can say to a customer who chose to
+ * send nothing is to accuse them of a broken install -- which is what the first
+ * draft of Phase 69 would have shipped.
+ */
+export declare function ipSourceName(source: ClientIpSource): "platform" | "forwarded" | "off" | "custom";
+/**
+ * The `network` block.
+ *
+ * ⚠️ **It now carries `ipSource` even when there is no address**, which is the
+ * one case that matters: a block saying "platform, and nothing arrived" is how
+ * an install that can never verify a crawler becomes visible. That is not the
+ * `{}` the old docblock refused -- an empty object says "we looked and found
+ * nothing" with no way to act on it; this says which setting produced the
+ * silence. An absent BLOCK stays the fourth state and means an older SDK.
+ */
+export declare function observeNetwork(facts: IpFacts, source: ClientIpSource): RequestEvent["network"] | undefined;

package/dist/observe/next-router.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Was this request the page's own background traffic, rather than a reader's?
+ * (Phase 130.) Read from the headers Next's client router sets, and nothing
+ * else -- the proxy never sees the answer, so these are the only facts there.
+ *
+ * - **prefetch**: `next-router-prefetch` or `next-router-segment-prefetch`.
+ *   Every `<Link>` in the viewport sends one; nobody has read anything yet.
+ * - **refresh**: an RSC request (`rsc: 1`) for the very page it was sent from.
+ *   In Next 16 `router.refresh()` goes through the same code as a navigation
+ *   (`navigateToKnownRoute`) and sends the same headers, so the one fact that
+ *   tells them apart is the `Referer`: a refresh asks for the URL it is on, a
+ *   navigation for a different one. The `_rsc` cache-buster is ignored.
+ *
+ * ⚠️ **Absence keeps the row.** No Referer (a `no-referrer` policy), a
+ * cross-origin one, or one that does not parse is `undefined` -- recorded as
+ * today. Dropping a navigation we could not tell from a refresh would erase a
+ * reader; keeping a refresh we could not tell costs one row.
+ *
+ * ⚠️ A client-side NAVIGATION is deliberately not background: it is a person
+ * moving to a new page, and the assistant card's "pages also read" counts it.
+ */
+export declare function nextBackground(request: Request): "prefetch" | "refresh" | undefined;

package/dist/observe/redact.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Decide whether a path segment looks like a secret, and redact it by default.
+ *
+ * ── Why this is ON by default, when `redactPatterns` already exists ──────────
+ * Because opt-in is what failed. `redactPatterns`, `routeTemplate` and
+ * `isInternal` are all well designed and all opt-in, and an independent install
+ * attempt (`docs/design/install-findings-2026-09-16.md`) found that the install
+ * guide mentioned **none of the three**. The site in question puts single-use
+ * capability tokens in its PATHS -- `/reveal/<token>`, `/join/<code>` -- so an
+ * agent following the guide exactly would have POSTed live credential material
+ * to our event store.
+ *
+ * The guide now has a step about it, and a step an agent can skip is a step an
+ * agent will skip. **The failure mode of skipping it must be a redacted path,
+ * not a leaked one.**
+ *
+ * ── ⚠️ The hard part is not the regex ────────────────────────────────────────
+ * A high-entropy segment is INDISTINGUISHABLE from a capability token by shape:
+ *
+ *   cmu4psgny0003s397tb2t5gx6   cuid    -- our own site ids look exactly like this
+ *   7f3a9c2b1d4e6f8a            hex     -- a build hash, or a reset token
+ *   a1b2c3d4-...-e5f6           uuid    -- a public resource id, or a ticket
+ *
+ * So entropy cannot decide, and any default is wrong in one direction. The
+ * decision, written down rather than left in the code: **be wrong in the
+ * direction of redaction.** A redacted path costs an operator route detail,
+ * recoverable by setting `redactHighEntropyPaths: false`. A leaked token is
+ * recoverable by nothing -- it is already in somebody else's database.
+ *
+ * ── ⚠️ What it deliberately does NOT touch ───────────────────────────────────
+ * - **Anything with a file extension.** `/assets/app.4f3b2a.css` is an asset
+ *   path, and mangling it would destroy the format analysis that is half this
+ *   product.
+ * - **Template placeholders.** A customer whose `routeTemplate` produced
+ *   `/users/:id` has told us that segment is a dimension, not a secret.
+ * - **Slugs.** `why-markdown-twins-matter-for-agents` is long and mixed and
+ *   entirely public. Word structure is what separates it from a token, so word
+ *   structure is what is tested -- not length, which would redact every blog.
+ *
+ * ⚠️ **It is a backstop, not a policy.** Only the customer knows which of their
+ * paths are secret; a short token (`/j/aB3xK9`) is under the length floor and
+ * will not be caught. The guide's step remains the real fix, and says so.
+ */
+export declare function looksLikeSecret(segment: string): boolean;
+export declare const REDACTED = "[redacted]";
+export interface RedactionResult {
+    path: string;
+    /** True when at least one segment was replaced, by any rule. */
+    redacted: boolean;
+}
+/**
+ * Apply the customer's patterns and, unless disabled, the default detector.
+ *
+ * ⚠️ Custom patterns run FIRST and independently. A customer who wrote a
+ * pattern gets it applied whether or not the default is on, and turning the
+ * default off never turns theirs off with it.
+ */
+export declare function redactPath(path: string, patterns: readonly RegExp[], useDefault: boolean): RedactionResult;

package/dist/observe/request.d.ts

@@ -0,0 +1,75 @@
+import { type RequestEvent } from "@agenthoney/event-schema";
+import type { ResolvedConfig } from "../core/config.js";
+/**
+ * Turn a request into the fields the wire event carries -- and, just as
+ * importantly, leave everything else behind.
+ *
+ * ── This module IS the privacy promise ───────────────────────────────────────
+ * `docs/design/collected-fields.md` lists what we take. This is the only place
+ * that decides. Every value here is read from a named header or a named,
+ * allowlisted query parameter; there is no path that copies "the rest" of
+ * anything, which is why a cookie or a bearer token cannot arrive by accident.
+ *
+ * A reviewer should be able to read this file and check the published list
+ * against it line by line.
+ */
+/** The only query parameters ever read. Everything else is discarded. */
+export declare const CAMPAIGN_PARAMS: readonly ["utm_source", "utm_medium", "utm_campaign", "utm_content"];
+export interface ObservedRequest {
+    method: string;
+    path: string;
+    route?: string;
+    host?: string;
+    protocol?: "http" | "https";
+    userAgent?: string;
+    referrerOrigin?: string;
+    campaign?: RequestEvent["campaign"];
+    clickIdType?: RequestEvent["clickIdType"];
+    internal?: boolean;
+    /**
+     * ⚠️ Set when any segment of the path or route was replaced, by a customer
+     * pattern or by the default detector. **Visible, never silent** -- an
+     * operator staring at `/reveal/[redacted]` needs to know it was us, not a
+     * bug in their router, and needs to be able to find the setting.
+     */
+    pathRedacted?: boolean;
+}
+/**
+ * Normalise a path: no query, no fragment, no repeated slashes, bounded length.
+ *
+ * ⚠️ The query string is dropped HERE, before anything else looks at it.
+ * Allowlisted campaign values are read separately from the parsed URL. There is
+ * deliberately no code path in which a raw query string is carried forward and
+ * filtered later -- a filter can be wrong; an absence cannot.
+ */
+export declare function normalisePath(rawPath: string, redactPatterns?: readonly RegExp[]): string;
+/** Scheme and host only. The page someone came from is never collected. */
+export declare function referrerOrigin(referer: string | null | undefined): string | undefined;
+/**
+ * The hostname the CLIENT asked for, which is not always the one the server
+ * thinks it is.
+ *
+ * ⚠️ **Measured 2026-09-17 on a self-hosted Next 16 standalone server**: the
+ * proxy receives a `request.url` of `http://0.0.0.0:3013/…`, so reading
+ * `url.host` recorded **`0.0.0.0:3013`** as the host of every request to
+ * `app.agenthoney.ai`. The site's own dashboard could not tell you which
+ * hostname its traffic arrived on. A managed platform rewrites the URL for you,
+ * which is why the same code looked correct on Vercel and on Express.
+ *
+ * ⚠️ It is a CLAIM, like every header — but it is the same claim the customer's
+ * own router already dispatched on, so recording it adds no trust that their
+ * application had not already extended. `x-forwarded-host` first: a proxy that
+ * rewrites `Host` to an internal name sets it precisely to preserve the
+ * original.
+ */
+export declare function observedHost(header: (name: string) => string | undefined, fallback?: string | undefined): string | undefined;
+export interface RequestFacts {
+    method: string;
+    /** Path AND query, as it arrived. Never stored; parsed here and discarded. */
+    url: string;
+    host?: string | undefined;
+    protocol?: "http" | "https" | undefined;
+    userAgent?: string | undefined;
+    referer?: string | undefined;
+}
+export declare function observeRequest(facts: RequestFacts, config: ResolvedConfig): ObservedRequest;

package/dist/observe/response.d.ts

@@ -0,0 +1,24 @@
+import type { RequestEvent } from "@agenthoney/event-schema";
+/**
+ * Response facts, read from headers that already exist.
+ *
+ * ⚠️ **Nothing here ever touches the body.** A response is a single-read
+ * stream: to learn what it contained you would have to wrap `write`/`end` and
+ * buffer it, which adds latency, adds memory proportional to the page, and can
+ * corrupt what the customer sends if the encoding or backpressure handling is
+ * wrong. `contentLength` is therefore read from the header and is simply absent
+ * for a chunked or streamed response -- the dashboard shows "not measured",
+ * which is honest and free.
+ */
+export interface ResponseFacts {
+    status?: number | undefined;
+    contentType?: string | null | undefined;
+    contentLength?: string | number | null | undefined;
+    latencyMs?: number | undefined;
+    observation: RequestEvent extends {
+        response?: infer R;
+    } ? R extends {
+        observation: infer O;
+    } ? O : never : never;
+}
+export declare function observeResponse(facts: ResponseFacts): NonNullable<RequestEvent["response"]>;

package/dist/runtime.d.ts

@@ -0,0 +1,27 @@
+/**
+ * ⚠️ The SDK's own name and version, in ONE place.
+ *
+ * They were declared separately in `web.ts` and `express.ts`, and adding a
+ * third adapter would have made three copies of a version string that must
+ * match `package.json` -- a list nothing checks, written down three times.
+ * `runtime.test.ts` asserts the version against the manifest.
+ */
+export declare const SDK_NAME = "@agenthoney/analytics";
+export declare const SDK_VERSION = "0.14.0";
+/**
+ * Identify the runtime, for the `sdk.runtime` field.
+ *
+ * Kept deliberately dumb and total: it must never throw at import time, on any
+ * runtime, because that would take the host application down before it serves
+ * a request. Every branch is guarded and there is a final fallback.
+ */
+export declare function runtimeName(): string;
+/**
+ * A unique event id.
+ *
+ * `crypto.randomUUID()` where available -- it is in every supported runtime and
+ * costs no dependency. The fallback exists so an exotic runtime degrades to a
+ * slightly weaker id rather than to a crash; a collision costs one deduplicated
+ * event, a throw costs the customer a 500.
+ */
+export declare function newEventId(): string;

package/dist/serve/accept.d.ts

@@ -0,0 +1,7 @@
+export interface MediaRange {
+    type: string;
+    q: number;
+}
+export declare function parseAccept(header: string | null | undefined): MediaRange[];
+export declare const MARKDOWN_TYPES: readonly ["text/markdown", "text/x-markdown"];
+export declare function prefersMarkdown(header: string | null | undefined): boolean;

package/dist/serve/discovery.d.ts

@@ -0,0 +1,56 @@
+import type { TwinResolver } from "./twin.js";
+/**
+ * The three files that let an agent find a site's content without crawling it
+ * blindly: `/llms.txt`, `/llms-full.txt` and `/install.md`.
+ *
+ * ── Why generate them rather than let customers write them ───────────────────
+ * A hand-written index is wrong the first time a page is added, and an index
+ * that lists pages which no longer exist is worse than none -- an agent spends
+ * its budget on 404s and concludes the site is broken. These are derived from
+ * the same manifest that serves the twins, so they cannot disagree with what is
+ * actually servable.
+ *
+ * `llms.txt` is the convention proposed by Answer.AI in 2024: a markdown index
+ * of a site's high-value content. `llms-full.txt` is the same set with the
+ * bodies inline, for an agent that would rather make one request than a hundred.
+ */
+export interface TwinEntry {
+    /** The page path, e.g. `/docs/intro`. */
+    path: string;
+    /** One line. This is what an agent reads when deciding whether to fetch. */
+    summary?: string;
+    title?: string;
+}
+export interface DiscoveryOptions {
+    siteName: string;
+    /** One or two sentences. Appears under the heading in `llms.txt`. */
+    description?: string;
+    origin?: string;
+    entries: readonly TwinEntry[];
+}
+/** The index: every page, one line each. */
+export declare function renderLlmsTxt(options: DiscoveryOptions): string;
+/** The bulk file: one request instead of a hundred. */
+export declare function renderLlmsFullTxt(options: DiscoveryOptions, resolve: TwinResolver): Promise<string>;
+/**
+ * ⚠️ **The guide's own version, and it is the PACKAGE's version.**
+ *
+ * The dashboard's prompt links a versioned URL so an agent is told to read the
+ * guide that matches the code it is about to install, rather than whatever is
+ * at `/install.md` at the moment it happens to fetch.
+ *
+ * Read from `package.json` rather than written here, because a version written
+ * in two places is a version that disagrees with itself.
+ */
+export declare const INSTALL_GUIDE_VERSION: string;
+/**
+ * The install guide, written for an AI coding agent rather than a person.
+ *
+ * ⚠️ This is the install path for a product whose users install things by
+ * asking a model. It is deliberately imperative, names the exact failure modes,
+ * and tells the agent to STOP rather than guess at a missing value -- because an
+ * agent that guesses a credential writes a broken config that looks finished.
+ */
+export declare function renderInstallMd(options?: {
+    packageName?: string;
+}): string;

package/dist/serve/hosted.d.ts

@@ -0,0 +1,135 @@
+import type { Twin } from "./twin.js";
+/**
+ * Twins the customer never wrote: resolved from what their own visitors agreed
+ * a page says.
+ *
+ * ── ⚠️ Why this REFRESHES rather than fetches ────────────────────────────────
+ * `TwinOptions.resolve` runs inside the customer's request path, and this SDK's
+ * first rule is that **nothing awaits the network there**. A resolver that
+ * fetched per request would add our latency -- and our availability -- to every
+ * page of their site, which is precisely the trade this product refuses to make
+ * anywhere else.
+ *
+ * So the whole published set is pulled into memory and `resolve` is a `Map`
+ * lookup, with the network happening in the background. ⚠️ **One measured
+ * exception**, below: a COLD process awaits its first load, because answering
+ * "no twin" on a fresh isolate sent 2 of 8 live `text/markdown` requests an
+ * HTML page instead.
+ *
+ * ── ⚠️ Demand-driven, with no timer and no I/O at construction ───────────────
+ * The first version created this with `setInterval` and fired a refresh from
+ * the constructor. **Both are forbidden in a Cloudflare Worker**: I/O in the
+ * global scope throws, and a timer does not survive an isolate being evicted.
+ * It would have failed on the first runtime it was built for -- agenthoney.ai
+ * is a Worker -- and it would have failed at deploy, not in a test.
+ *
+ * So refreshing is something the HOST asks for: `refreshIfStale()` is cheap to
+ * call on every request and does nothing until the data is older than
+ * `refreshMs`. A Worker passes it to `ctx.waitUntil`; a Node server can call it
+ * per request or on its own interval.
+ *
+ * ── ⚠️ The cold await was DELIBERATE; where it leaked to was not ─────────────
+ * A cold `resolve` awaits, and `hosted.test.ts` carries the measurement that
+ * made it so. What nobody noticed is which requests reach `resolve`: until
+ * Phase 49, `./express`'s ADVERTISE branch called it on **every passing GET**
+ * and deferred `next()` until it settled, and `./web` awaited it after the
+ * handler had already built the response. So an exception argued for a client
+ * asking for markdown was being paid by a human loading HTML -- the one thing
+ * this SDK is built not to do -- on the one deployment that uses this module.
+ *
+ * Two rules now, and `lookup` exists so a caller can obey them:
+ *
+ *   1. **`lookup` is synchronous and never touches the network.** Anything
+ *      running on a request that did NOT ask for markdown -- advertising, above
+ *      all -- uses it, and a cold process simply advertises nothing.
+ *   2. **`resolve` may await on a cold process, and is now BOUNDED.** It is for
+ *      requests that asked for markdown by `.md` suffix or `Accept`, where the
+ *      alternative is never serving a twin on a serverless isolate at all. The
+ *      bound is `coldTimeoutMs`; past it the answer is "no twin" and the
+ *      customer's own handler runs. It had no bound before, which meant a
+ *      hanging ingest held a customer's request for as long as it liked.
+ *
+ * ── ⚠️ Every failure resolves to "no twin" ───────────────────────────────────
+ * Before the first refresh completes, during an outage, after a 500: `resolve`
+ * returns undefined and the customer's own HTML is served unchanged. A twin
+ * that is missing is a page that works normally; there is no failure here that
+ * degrades to anything worse.
+ */
+export interface HostedTwinsOptions {
+    /** The SERVER key. This corpus is not public and a browser never reads it. */
+    serverKey: string;
+    /** Defaults to the SDK's configured ingest origin. */
+    ingestUrl?: string;
+    /**
+     * How stale the set may get. ⚠️ A page wins consensus over DAYS, so there is
+     * nothing to gain from a tight interval and a shared database to protect.
+     */
+    refreshMs?: number;
+    /**
+     * The ceiling on the one await this module is allowed (see rule 2 above).
+     *
+     * ⚠️ **A default, not a measurement.** Nobody has measured p99 of a corpus
+     * pull from a serverless region yet, and this number lands on somebody's page
+     * load. Phase 49 records that measuring it is outstanding; until then it is
+     * short enough that the worst case is a page that renders normally.
+     */
+    coldTimeoutMs?: number;
+    /**
+     * How long a failed refresh stops the next one being attempted.
+     *
+     * ⚠️ **The breaker the telemetry half has had since the beginning, and this
+     * half did not.** `refreshIfStale()` runs on every request, and a failure
+     * does not move `fetchedAt` -- so for the whole of an ingest outage, every
+     * request through the customer's server started another refresh the moment
+     * the last one failed. `breaker.ts` says exactly why that is the customer's
+     * problem and not ours: a fleet of their servers paying a DNS lookup, a
+     * connect and a timeout, continuously, because OUR endpoint is down.
+     *
+     * A held-back refresh is free: the corpus already in memory keeps serving.
+     */
+    failureBackoffMs?: number;
+    /**
+     * The ceiling on a single refresh's network call.
+     *
+     * ⚠️ Nothing awaits this on a request, so this bound is not about latency --
+     * it is about a HANGING ingest. Without it a stalled connection kept
+     * `inFlight` set for as long as the runtime's own socket timeout (undici:
+     * five minutes), and `refreshIfStale()` returns that same promise, so the
+     * corpus stopped refreshing entirely for the duration.
+     */
+    refreshTimeoutMs?: number;
+    /** Injected for tests. */
+    now?: () => number;
+    /** Injected for tests. */
+    fetchImpl?: typeof fetch;
+}
+export interface HostedTwins {
+    /**
+     * One twin, straight from ingest, for a COLD process.
+     *
+     * ⚠️ **A single row, never the corpus.** The bulk refresh can be megabytes
+     * and an isolate that will serve one request must not pay for it on that
+     * request. Bounded by the caller; fails to `undefined`, never throws.
+     */
+    fetchOne: (path: string) => Promise<Twin | undefined>;
+    /**
+     * ⚠️ **Synchronous, and it never starts a fetch.** For every caller that runs
+     * on a request which has not asked for markdown. A cold process answers
+     * `undefined`, which is the truth: this isolate does not know of a twin.
+     */
+    lookup: (path: string) => Twin | undefined;
+    resolve: (path: string) => Twin | undefined | Promise<Twin | undefined>;
+    /** Refresh unconditionally. Mostly for tests and for a deliberate warm-up. */
+    refresh: () => Promise<void>;
+    /**
+     * Refresh only if the set is older than `refreshMs`, and never more than one
+     * at a time.
+     *
+     * ⚠️ Safe to call on every request: it is a clock comparison in the common
+     * case. Hand it to `ctx.waitUntil` on a Worker so the refresh outlives the
+     * response without delaying it.
+     */
+    refreshIfStale: () => Promise<void>;
+    readonly size: number;
+}
+export declare function hostedTwins(options: HostedTwinsOptions): HostedTwins;