@murumets-ee/content-api 0.0.0-preview-20261014110621

package/dist/index.d.mts

@@ -0,0 +1,2321 @@
+import { Entity } from "@murumets-ee/entity";
+import { PermissionChecker, RouteContext } from "@murumets-ee/core";
+import { z } from "zod";
+import { RateLimitStore } from "@murumets-ee/core/limits";
+
+//#region src/cache-tags.d.ts
+/**
+ * Cache-tag emission — the header only, never a purge protocol (D055, plan/api
+ * PR 11, resolves F73).
+ *
+ * **What this is for.** R05 surveyed how headless CMSes invalidate a CDN and
+ * found one convergent pattern: stamp each cached response with tags naming the
+ * documents that composed it, then purge by tag on write. R05 also recorded the
+ * asymmetry that makes the two halves separable — **emitting the header costs
+ * nothing at request time and needs no purge infrastructure to be useful, while
+ * deferring it means a later migration touches every cached response.** This
+ * module is the emission half. The purge half stays out for the reason phase 10
+ * gave and SD006 left standing: `resolveQueryField` records a cache dependency
+ * only under `renderContext === 'production-build'`, so a request-path purge
+ * would have no dependency graph to consult.
+ *
+ * **Emitting a tag nobody purges on changes nothing about S6.** Until a
+ * consumer wires purge-on-write, TTL expiry is still the entire reconciliation
+ * mechanism between a shared cache and S6. What ships here is the thing that
+ * makes that wiring possible later without a response-format change.
+ *
+ * # The format (D055)
+ *
+ * Two kinds, both namespaced, told apart by SEGMENT COUNT:
+ *
+ * | Kind | Shape | Means |
+ * |---|---|---|
+ * | Document | `lumi:<entity>:<id>` | this row's CONTENT is in the body |
+ * | Collection | `lumi:<entity>` | this response depends on WHICH rows exist |
+ *
+ * **Both kinds are needed and a document tag alone is a silent failure.** A
+ * per-document tag cannot invalidate a list when a BRAND-NEW row is created,
+ * because no cached response ever carried that row's tag. Drupal answers this
+ * with a first-class `node_list` tag; Vercel documents `cacheTag('products',
+ * 'product-${id}')` as the recommended hierarchy; Stellate names the failure
+ * verbatim. See R16.
+ *
+ * **Segment count rather than a suffix**, because Drupal's `node_list` shape
+ * would collide with an entity genuinely named `article_list` — a legal entity
+ * name here.
+ *
+ * **The `lumi:` prefix is not decoration.** The named consumer is an
+ * application, not a CDN: `plan/frontend-delivery`'s Astro BFF reads these and
+ * hands them to `Astro.cache.set({ tags })`, which merges them into ONE flat
+ * tag space alongside the app's own tags and Astro's `astro-path:` tags. Four
+ * bytes makes a collision structurally impossible.
+ *
+ * # The disclosure invariant — why raw ids are defensible here
+ *
+ * Akamai ships a knob to hide its tag header from clients, because "cache tags
+ * can include back-end information, or at least allow a malicious user to
+ * decipher back-end information from them". That is a real argument and it is
+ * answered structurally rather than waved away:
+ *
+ * > **Every id a tag names is already visible to that same caller, in that same
+ * > response, or was supplied by that caller in the request.**
+ *
+ * Row ids are in the body (`data.id`); resolved reference and media ids are in
+ * the body (`row[field].id`); `_chrome`'s document id and `_alternates`' id came
+ * from the caller's own query string; `_menu`'s handle is in the URL. The header
+ * therefore discloses nothing the body does not — asserted in the tests, not
+ * assumed. {@link CacheTagsConfig.enabled} exists anyway for an operator who
+ * wants no ids in a header regardless; the invariant is why the DEFAULT can be
+ * on, not a reason to skip the switch.
+ *
+ * # Bounds
+ *
+ * Emitted to the STRICT INTERSECTION of every CDN surveyed in R16, always,
+ * whichever one is actually configured — so switching vendors can never
+ * invalidate tags already emitted. THREE caps, and the third is not implied by
+ * the other two (128 × 128 plus separators overshoots every vendor's header
+ * limit — see {@link MAX_CACHE_TAG_HEADER_BYTES}):
+ *
+ * 1. {@link MAX_CACHE_TAG_LENGTH} characters per tag — Akamai's, the tightest.
+ * 2. {@link MAX_CACHE_TAGS_PER_RESPONSE} tags — Akamai's and Vercel's.
+ * 3. {@link MAX_CACHE_TAG_HEADER_BYTES} bytes for the assembled field, so the
+ *    whole response-header block stays inside a default proxy buffer.
+ *
+ * Plus the charset: no spaces, no commas, printable ASCII from an allowlist.
+ *
+ * A tag that fails the charset or the length cap is **DROPPED, never truncated
+ * and never escaped**: a malformed tag is one a purge silently misses, which is
+ * strictly worse than a tag that was never there. A tag that does not fit the
+ * count or byte budget is dropped from the TAIL, so what survives is always the
+ * first N added — which is what makes insertion order a degradation strategy
+ * rather than an accident.
+ */
+/**
+ * The namespace every tag this package emits begins with.
+ *
+ * Lowercase and fixed. Cloudflare matches tags case-INSENSITIVELY while Akamai
+ * matches case-sensitively, so a namespace whose case varied would mean
+ * different things on two CDNs.
+ */
+declare const CACHE_TAG_NAMESPACE = "lumi";
+/**
+ * Akamai's documented per-tag ceiling — "If your tag is longer than 128
+ * characters, the associated content won't be purged" — and the tightest of the
+ * four surveyed (Fastly 1024 bytes, Cloudflare 1024 chars, Vercel 256).
+ */
+declare const MAX_CACHE_TAG_LENGTH = 128;
+/**
+ * Akamai's documented per-object ceiling ("The maximum number of tags per
+ * cached object is 128. Any additional tags are ignored"), which Vercel matches
+ * exactly.
+ */
+declare const MAX_CACHE_TAGS_PER_RESPONSE = 128;
+/**
+ * The ceiling on the emitted header FIELD — `name: value` — in bytes. A THIRD
+ * bound, which the count and length caps do not imply.
+ *
+ * 128 tags of 128 characters plus 127 separators is 16,511 bytes, which is 127
+ * PAST Fastly's documented 16,384-byte header cap — where the documented
+ * behaviour is to ignore "the key currently being parsed and all keys following
+ * it", i.e. exactly the silent purge-miss this module refuses everywhere else.
+ * Two caps that each looked safe multiplied into one that was not.
+ *
+ * **Why 3072, and why the first draft's 8192 was the wrong number for the very
+ * reasons it cited.** That draft justified 8192 as "Akamai's documented overall
+ * maximum response-header size" and as fitting "the 8k `proxy_buffer_size` a
+ * default nginx will forward". Both numbers govern the WHOLE header block, not
+ * one field — so capping a single field AT the block maximum guarantees the
+ * block is exceeded whenever the cap binds. And nginx's default is documented
+ * as "equal to one memory page… 4K or 8K depending on the platform", which is
+ * 4096 on x86-64 Linux, and that one buffer must hold the entire block.
+ *
+ * So the budget is sized against a **4096-byte block**, leaving roughly a
+ * kilobyte for the status line, `Content-Type`, `Cache-Control`, `Vary`, up to
+ * four `Access-Control-*` headers and whatever the runtime adds. An intermediary
+ * that refuses an oversized header turns a 200 into a 502 — an availability
+ * failure caused by a caching hint, on a public surface, by default, which is
+ * the direction CLAUDE.md's "availability is a security property" rules out.
+ *
+ * **It binds before the 128-tag cap on a large page, deliberately.** At ~49
+ * bytes per tag (`lumi:article:` plus a uuid) this admits roughly 60 documents.
+ * A default `?limit=20` page fits with room to spare; a caller who asks for the
+ * `?limit=100` maximum will see tags dropped and logged. That is the right
+ * trade because the degradation is SAFE: the collection tag is added first and
+ * covers every row on the page, so a purge still invalidates the response — it
+ * is precision that is lost, not correctness. Vercel's documented advice for
+ * exactly this situation is to carry a coarser tag rather than enumerate.
+ */
+declare const MAX_CACHE_TAG_HEADER_BYTES = 3072;
+/**
+ * The entity name media tags are emitted under.
+ *
+ * `content-api` is a leaf and never imports `@murumets-ee/media`, so the media
+ * entity's name is not structurally available here. `media` is not a guess: it
+ * is the permission RESOURCE this package already names in `media.ts`, whose
+ * resolver "THROWS when the caller's role lacks `media:view`". The tag
+ * namespace follows the permission resource, which is the name a purge caller
+ * would reach for.
+ */
+declare const MEDIA_TAG_ENTITY = "media";
+/**
+ * What fills the SITE slot of a tag for a row that belongs to no site — a
+ * shared entity (media) on an app serving several sites (plan `multisite`
+ * D008): `lumi:_:media:<id>`.
+ *
+ * A slot rather than an omission, for the reason {@link CACHE_TAG_CHARSET}
+ * gives: the two tag kinds are told apart by SEGMENT COUNT. Were shared rows
+ * to skip the site segment, a shared DOCUMENT tag (`lumi:media:<id>`) and a
+ * site COLLECTION tag (`lumi:kulli:page`) would both have three segments. With
+ * the slot always present, a multi-site deployment's document tags have four
+ * and its collection tags three.
+ *
+ * `_` cannot be a site: a handle starts with a letter.
+ */
+declare const SHARED_SITE_TAG_SEGMENT = "_";
+/**
+ * Host configuration for cache-tag emission. Every field is optional; omitting
+ * the whole object emits `Cache-Tag`, comma-separated.
+ */
+interface CacheTagsConfig {
+  /**
+   * Emit the header at all. Defaults to `true`.
+   *
+   * Default-on is free for the reason D010 already established — no
+   * `content-api` consumer is live, so there is nothing deployed to surprise —
+   * and it is the point of R05's asymmetry argument: a header nobody reads yet
+   * still costs nothing, while adding it later is a contract change across
+   * every cached response.
+   *
+   * Set `false` for a deployment that does not want document ids in a response
+   * header regardless of the disclosure invariant. See the module docblock.
+   */
+  enabled?: boolean;
+  /**
+   * The header name. Defaults to `Cache-Tag`.
+   *
+   * `Cache-Tag` is Cloudflare's native name, is accepted bare by Netlify, and
+   * is trivially parseable by the BFF that is the actual named consumer. A
+   * Fastly deployment sets `Surrogate-Key` and `separator: ' '`; an Akamai one
+   * sets `Edge-Cache-Tag`.
+   *
+   * Emitting SEVERAL vendor headers at once is deliberately not offered: R16
+   * could find no product anywhere doing it, and it multiplies the disclosure
+   * surface for a hedge nobody needs.
+   */
+  header?: string;
+  /**
+   * What joins the tags. Defaults to `,`.
+   *
+   * Cloudflare and Akamai are comma-separated; Fastly is SPACE-separated. Only
+   * these two are accepted, because they are the only two any surveyed vendor
+   * parses — a third would produce one giant unparseable key rather than an
+   * error.
+   */
+  separator?: ',' | ' ';
+}
+//#endregion
+//#region src/resolution-budget.d.ts
+/**
+ * The per-document resolution budget (plan/api phase 05).
+ *
+ * Rendering ONE document can trigger four independent kinds of backend work:
+ * `query()`-field resolutions, link resolutions, media resolutions and entity-
+ * reference projections. Every one of them scales with the document's own
+ * content — which an EDITOR controls, not an operator — and all four compete
+ * for the same connection pool.
+ *
+ * **One budget, spanning all four. Not four caps.** A per-kind cap lets a
+ * single document sum four separate ceilings into one much larger pool draw,
+ * which is the same "it's only N today" defence CLAUDE.md's No-Unbounded-Fan-Out
+ * section refuses. The kinds are recorded so a DROP can be attributed; they are
+ * never separately bounded.
+ *
+ * **This is the COUNT half of the rule.** The concurrency half is
+ * `@murumets-ee/core`'s `runBounded`, which caps how many of the granted
+ * resolutions are in flight at once. Both are needed: a bound on peak
+ * concurrency still lets an unbounded list through, just more slowly, and a
+ * bound on count still lets a bounded list arrive as one burst.
+ *
+ * **Nothing here is silent.** Whatever the ceiling refuses is counted per kind
+ * and reported by {@link ResolutionBudget.dropSummary}, which the handler logs.
+ * CLAUDE.md is explicit that silent truncation reads as "covered everything" —
+ * and phase 05's failure semantics make an unresolved target INDISTINGUISHABLE
+ * from a deleted, unpublished or unviewable one ON THE WIRE, deliberately, so
+ * an editor asking "why is my related-article link gone?" can only ever be
+ * answered from the operator-facing log. That makes this log load-bearing
+ * rather than nice-to-have.
+ */
+/**
+ * The kinds of per-document resolution work this budget spans.
+ *
+ * The union is DERIVED from the array, not declared beside it. Declared
+ * separately, a fifth member added to the union but forgotten in the array
+ * would still be accepted by `claim` and counted in `drops`, then silently
+ * omitted from `dropSummary` — the exact silent truncation this module exists
+ * to prevent, and the compiler would not have caught it, because a shorter
+ * `readonly ResolutionKind[]` is a perfectly valid value of that type.
+ */
+declare const RESOLUTION_KINDS: readonly ["reference", "populate", "media", "block"];
+type ResolutionKind = (typeof RESOLUTION_KINDS)[number];
+/**
+ * Absolute ceiling on the total resolutions ONE document may trigger, across
+ * every kind. A host may lower it (see
+ * `ContentApiConfig.maxResolutionsPerDocument`); nothing can raise it.
+ *
+ * 200 is calibrated against the shape of the work rather than against a
+ * measurement. Be precise about that shape, because an authoritative-sounding
+ * cost model that is wrong is worse than none:
+ *
+ *  - A unit is at most one row in a BATCHED, keyed read — N references to the
+ *    same entity cost one query, not N.
+ *  - A REFERENCE unit additionally costs one routing-seam lookup, which in this
+ *    repo is a single-row `toolkit_paths` read per resolved row. So the
+ *    worst-case query count is roughly 2× the granted unit count, not 1×.
+ *  - `runBounded` holds peak concurrency at a small constant, so those lookups
+ *    arrive paced rather than as one burst.
+ *  - Every read on this path is on the read-only pool, which carries a
+ *    `statement_timeout` (PR 2) — including the storage lookup behind media,
+ *    which is why `StorageClient` keeps a separate read-only table client.
+ *
+ * A document needing more than 200 resolved targets to render is not a page, it
+ * is an export — and the honest answer for one is a truncated render plus an
+ * operator log, not an unbounded pool draw from an unauthenticated caller.
+ */
+declare const MAX_RESOLUTIONS_PER_DOCUMENT = 200;
+/**
+ * A claim-based counter. Callers ask for `n` units BEFORE doing the work and
+ * receive how many they may actually do.
+ *
+ * Claim-before, never report-after: a budget checked afterwards has already
+ * paid for the overrun, which is a check that cannot fail in the direction it
+ * is supposed to.
+ */
+interface ResolutionBudget {
+  /**
+   * Claim up to `n` units for `kind`. Returns how many were GRANTED — `0`
+   * through `n`. Anything short of `n` is recorded as a drop for that kind.
+   *
+   * A non-positive or non-integer `n` grants 0 and records nothing; callers
+   * derive `n` from array lengths, so a defensive floor here beats a
+   * `Math.max` at every call site.
+   */
+  claim(kind: ResolutionKind, n: number): number;
+  /** Units still available. */
+  readonly remaining: number;
+  /** Units granted so far, across every kind. */
+  readonly granted: number;
+  /** True when anything at all was refused — the log trigger. */
+  readonly hasDrops: boolean;
+  /**
+   * Per-kind refused counts, for the operator log. Only kinds that actually
+   * lost something appear, so a log line names what was cut rather than
+   * printing four zeroes.
+   */
+  dropSummary(): Partial<Record<ResolutionKind, number>>;
+  /** The ceiling this budget was built with — published in `_schema` (D008). */
+  readonly ceiling: number;
+}
+//#endregion
+//#region src/blocks.d.ts
+/**
+ * One ref a resolver was asked for and could not deliver.
+ *
+ * **This channel is the whole reason in-place media resolution is safe here**
+ * (D019, R022 §3). When a resolved value REPLACES a stored ref, "I tried and
+ * failed" has nowhere left to go — every surveyed CMS that resolves in place
+ * either goes silent (Sanity, Strapi), overloads `null` and documents it as a
+ * hazard (Directus: "you must treat `null` as both a value and an indication of
+ * restricted permissions"), or ships a type that is wrong in one of the two
+ * states (Payload). Contentful is the only one that escapes it, and it escapes
+ * by adding a SECOND, independent channel. This is that channel.
+ *
+ * `ref` is the media id for `kind: 'media'` and the `linkValueKey` for
+ * `kind: 'link'`. Neither discloses anything new: both are values the consumer
+ * already holds, because they came out of the stored tree it is being served.
+ */
+interface UnresolvedBlockRef {
+  readonly kind: 'media' | 'link';
+  readonly ref: string;
+  /**
+   * `'unresolvable'` — the target does not exist, is unpublished for this
+   * caller, is trashed, or is not public. ONE bucket, several causes,
+   * deliberately: phase 05's failure semantics do not let an anonymous consumer
+   * learn which.
+   *
+   * `'budget'` — this response ran out of resolution budget before reaching it.
+   * A fact about the RESPONSE, not about the target, so naming it separately
+   * discloses nothing and is the difference between "retry later" and "stop
+   * asking".
+   */
+  readonly reason: 'unresolvable' | 'budget';
+}
+/**
+ * A `blockTree` field, resolved — the format `plan/frontend-delivery` D019
+ * settled after `plan/api` closed with findings 069 and 075 still open.
+ *
+ * **The envelope's PRESENCE is the marker** (F075 requirement 3). A stored tree
+ * is an array; a resolved one is this object. `Array.isArray(value)` tells them
+ * apart without inspecting contents, which is what stops "resolution is not
+ * wired on this deployment" from looking like valid data. `resolved` versions
+ * the format so later additions (`queries`, when something can render them) are
+ * additive rather than breaking.
+ *
+ * **Nothing emits an empty envelope, with ONE named exception.** With no
+ * provider wired the stored tree crosses unchanged — see
+ * {@link resolveBlockTrees}. That is deliberate and it is Storyblok's
+ * documented wart avoided: its responses carry `rels: []` even when resolution
+ * was never requested, so empty-because-nothing-to-resolve is indistinguishable
+ * from empty-because-not-asked.
+ *
+ * The exception is D010's third state: a provider that failed AND then failed
+ * its I/O-free retry is served {@link EMPTY_RESOLVED_BLOCK_TREE}, loudly
+ * logged. That is narrow by construction — by the time it is reached the
+ * provider has failed a pure in-memory walk, so it is broken rather than
+ * unlucky — and it does not reintroduce Storyblok's ambiguity, because the
+ * ambiguity there was between "not asked" and "nothing found". This envelope
+ * means neither: it means "asked twice, answered neither time", and the
+ * operator log says so in those words.
+ *
+ * **Links are a keyed sidecar; media is replaced in place. The split is not
+ * arbitrary — it is what each side of the contract already agreed on.**
+ *
+ * A `LinkValue` is an opaque pointer with no href field at all, and every
+ * renderer already looks its href up by `linkValueKey` (`ResolvedLinksContext`,
+ * `resolveLinkHref(link, resolved)`, `RichTextRenderer`'s `resolvedLinks`
+ * prop). `blocks`' own `editor-state` route already serialises exactly this
+ * `Record<string, string | null>` for its wire. Writing the href INTO the link
+ * would also fight the security path: `asLinkValue` returns "a fresh, minimal
+ * `LinkValue` (extraneous keys dropped)" and is the richtext sanitiser's
+ * normaliser, so the href would be stripped by the code whose job is stripping.
+ *
+ * A media ref is NOT an opaque pointer: it is a whole `MediaRef` carrying a url
+ * denormalised at write time, which every render reads directly as
+ * `image.url`. That url has to be overwritten regardless — it is minted by
+ * `StorageClient.getUrl`, which returns a SIGNED url for any non-public file,
+ * and freezing one into content puts a bearer capability on a cacheable
+ * anonymous response. So the sidecar's headline advantage ("the stored tree
+ * crosses byte-identical") is not on offer for media, while its cost — every
+ * render in every project stops reading `image.url` and consults a lookup —
+ * very much is.
+ */
+/**
+ * One row a resolved block tree DEPENDS ON — named so a cache holding this
+ * response can be evicted when that row changes.
+ *
+ * `entity` is `'media'` for an image the tree embeds, and the target's entity
+ * name for an internal link. That is deliberately the SAME shape
+ * `CacheTagSink.addDocument(entity, id)` takes, because the point of the field
+ * is that neither consumer has to walk the tree again to learn what is in it.
+ *
+ * 🔒 **RESOLVED ROWS ONLY.** A ref appears here only if the provider actually
+ * resolved it, which means it passed that provider's publish + permission gate.
+ * An unpublished link target is reported through `unresolved` (which carries a
+ * `linkValueKey`, a value the consumer already holds) and NEVER here — listing
+ * it would disclose the id of a document this caller may not see. The same
+ * rule `ResolveBlocks`' docblock puts on hrefs, applied to identity.
+ *
+ * There is no cap on the array. Both consumers of it are already bounded — the
+ * `Cache-Tag` header by `MAX_CACHE_TAGS_PER_RESPONSE`, a frontend's own tag set
+ * by its own cap — and it is bounded upstream anyway by the resolution budget
+ * the provider claimed against.
+ */
+interface BlockTreeRef {
+  readonly entity: string;
+  readonly id: string;
+}
+interface ResolvedBlockTree {
+  /** Format marker and version. Its presence means resolution RAN. */
+  readonly resolved: 1;
+  /**
+   * The block tree, with each media ref replaced by a `MediaProjection` — or
+   * by `null` when it did not resolve.
+   *
+   * **Replaced, never merged.** Falling back to the stored url for an id that
+   * failed would preserve the leak exactly, because "did not resolve" and "is
+   * not public" are the same branch in the shipped resolver. `null` is already
+   * what every render treats as "no image".
+   */
+  readonly blocks: readonly unknown[];
+  /**
+   * `linkValueKey → href`. `null` means "no usable link" and the renderer emits
+   * the text without an `<a>` — the contract `resolveLinkHref` already has.
+   */
+  readonly links: Readonly<Record<string, string | null>>;
+  /**
+   * What could not be resolved. **Omitted entirely when nothing failed**, so
+   * its presence is itself information (Contentful's rule for `errors[]`).
+   */
+  readonly unresolved?: readonly UnresolvedBlockRef[];
+  /**
+   * The rows this tree resolved against — see {@link BlockTreeRef}. **Omitted
+   * when the tree references nothing**, matching `unresolved`.
+   *
+   * WHY IT EXISTS. Until this field, a resolved block tree was opaque to every
+   * cache: `_schema` published `blockTreeContents` as an `uncovered`
+   * dependency, meaning re-publishing an image did not evict the pages
+   * embedding it — they served the old one until their TTL expired. The
+   * resolver already knew every id (it had just looked each one up); the
+   * information simply had nowhere to go. It goes here, and BOTH consumers read
+   * the one field rather than each re-walking the tree: `content-api` mints its
+   * own `Cache-Tag` entries from it, and a frontend mints whatever its own
+   * purge vocabulary is.
+   *
+   * `resolved: 1` versions the format precisely so an addition like this is
+   * additive; a consumer that does not read `refs` is unaffected.
+   */
+  readonly refs?: readonly BlockTreeRef[];
+  /**
+   * Collection block id → the rows it resolved to (editor PR53, D001's dynamic
+   * half). **Omitted when the tree holds no collection**, matching `unresolved`
+   * and `refs`.
+   *
+   * A keyed SIDECAR, for the reason `links` is one: a render reads rows by the
+   * block's id (`CollectionRowsContext`), and writing them into the block's
+   * props would put resolved, per-reader data into a value that otherwise
+   * crosses as the author stored it. Each row carries only the slots the app
+   * mapped — never the row — and exists because it passed the SAME whitelist ∧
+   * `view` gate as any other read on this API ({@link ResolveBlocksOptions}).
+   * Row ids are listed in `refs`; the entity is tagged as a collection
+   * dependency by `resolveBlockTrees`.
+   */
+  readonly collections?: Readonly<Record<string, ResolvedCollection>>;
+  /**
+   * What this document's live-bound Price fields resolved to (block-library
+   * PR03 + F012) — structural mirror of `@murumets-ee/blocks`' `LiveValues`,
+   * minus `asked` (canvas-merge bookkeeping with no reader on a one-shot
+   * render). **Omitted when the site registers no live sources at all** —
+   * matching `unresolved`/`refs`/`collections`'s own rule, and letting the
+   * `Price` primitive tell "this deployment wires no live values" (absent)
+   * from "wired, but this source doesn't exist" (`sources` present and
+   * missing the key) exactly the way the canvas already does.
+   *
+   * `sources` is load-bearing on the SITE, not just the canvas: the `Price`
+   * primitive checks `live.sources[declaredSource]` before it will draw
+   * ANYTHING for a bound price (`rich-field-primitives-media.tsx`), so a
+   * `live` sidecar carrying only `values` would make every live price on a
+   * delivered page render as nothing.
+   */
+  readonly live?: ResolvedLiveValues;
+  /**
+   * The site's currency (ISO 4217), from `blocksPlugin({ currency })`
+   * (block-library F012). Independent of `live` — a plain, typed-in Price
+   * needs it to show a currency symbol regardless of whether this tree binds
+   * any live price — so it is present whenever the site configures one,
+   * **never omitted on the "nothing to resolve" test** `unresolved`/`refs`
+   * follow, because there is always something to say: draw it plain, or draw
+   * it in this currency.
+   */
+  readonly currency?: string;
+  /**
+   * The row this tree is drawn for, projected through its entity's detail
+   * declaration (block-library PR16) — `blocksPlugin({ details })`. A price, a
+   * list of facts, an HTML body the server has already sanitised (with its
+   * headings), a third-party viewer's allow-listed reference, and the text
+   * that stands in for the row's title and summary. Absent unless the app
+   * declares a detail for the entity and the row has a value for a declared
+   * part. Only DECLARED columns are projected — never the row.
+   */
+  readonly detail?: ResolvedDetail;
+  /**
+   * Block type → the data a plugin's provider resolved for it
+   * (davatoidud-toolkit PR04, `blocks.dataProviders`). Structural mirror of
+   * `@murumets-ee/content`'s field; each value is validated by the block that
+   * draws it, on the consumer's side of the process boundary.
+   */
+  readonly blockData?: Readonly<Record<string, unknown>>;
+}
+/** One labelled value of a row's detail — structural mirror of a collection row's meta line. */
+interface ResolvedDetailFact {
+  readonly key: string;
+  readonly label: string;
+  readonly value: string | number;
+  readonly format?: 'price';
+}
+/** See {@link ResolvedBlockTree.detail}. Structural mirror of `@murumets-ee/blocks`' `DocumentDetail`. */
+interface ResolvedDetail {
+  readonly title?: string;
+  readonly text?: string;
+  readonly price?: {
+    readonly amount: number;
+    readonly compareAt?: number;
+    readonly unit?: string;
+  };
+  readonly facts?: readonly ResolvedDetailFact[];
+  readonly body?: {
+    readonly html: string;
+    readonly headings: readonly {
+      readonly id: string;
+      readonly text: string;
+      readonly level: 2 | 3;
+    }[];
+  };
+  readonly embed?: {
+    readonly provider: string;
+    readonly reference: string;
+  };
+  /** The trail from the site's top to this page: ancestors (with a path), then the page itself. */
+  readonly breadcrumbs?: readonly {
+    readonly label: string;
+    readonly href?: string;
+  }[];
+}
+/**
+ * One live source's PUBLIC metadata — structural mirror of
+ * `@murumets-ee/blocks`' `LiveSourceMeta`.
+ */
+interface ResolvedLiveSourceMeta {
+  readonly label: string;
+  readonly labelKey?: string;
+  /** The library fields the site granted this source, as `'<block>.<field>'`. */
+  readonly fields?: readonly string[];
+  /** What the source's values are — absent means `'price'` (block-library PR18, PR21). */
+  readonly kind?: 'price' | 'text' | 'list' | 'facts';
+  /** A `'facts'` source's values, words already in the page's locale (block-library PR21). */
+  readonly facts?: readonly ResolvedLiveFact[];
+}
+/** One fact a `'facts'` source declares — structural mirror of `@murumets-ee/blocks`' `LiveFact`. */
+interface ResolvedLiveFact {
+  readonly name: string;
+  readonly label: string;
+  readonly format: 'price' | 'number' | 'text';
+  readonly unit?: string;
+}
+/** One resolved live value — structural mirror of `@murumets-ee/blocks`' `LiveValue`. */
+interface ResolvedLiveValue {
+  /**
+   * Optional to MIRROR `@murumets-ee/blocks`' own `LiveValue` exactly (itself
+   * `Pick<PriceValue, 'amount'|'compareAt'|'unit'>`), not because the wire
+   * ever actually carries one without it: `readLiveAnswer` already drops any
+   * answer with no amount before it reaches `LiveValues.values` at all. A
+   * narrower (`amount: number`) type here would make the mirror a lie
+   * `tsc` catches the moment a consumer assigns a real `LiveValues` to it.
+   */
+  readonly amount?: number;
+  readonly compareAt?: number;
+  readonly unit?: string;
+  /**
+   * A live TEXT (block-library PR18) — one line of plain text a render draws
+   * inside authored text. Text only: a consumer escapes it like any text and
+   * never puts it in markup, a URL or an attribute.
+   */
+  readonly text?: string;
+  /** A live LIST (block-library PR18) — a few lines of plain text. */
+  readonly items?: readonly string[];
+  /**
+   * Live FACTS (block-library PR21) — named numbers or one-line texts. Values
+   * only: a consumer draws them as text, never as markup, a URL or an attribute.
+   */
+  readonly facts?: Readonly<Record<string, number | string>>;
+}
+/** What a document's live-bound Price fields resolved to. See {@link ResolvedBlockTree.live}. */
+interface ResolvedLiveValues {
+  readonly sources: Readonly<Record<string, ResolvedLiveSourceMeta>>;
+  readonly values: Readonly<Record<string, Readonly<Record<string, ResolvedLiveValue>>>>;
+}
+/** One resolved collection block — the structural mirror of `@murumets-ee/blocks`' `CollectionResult`. */
+interface ResolvedCollection {
+  readonly status: 'ok' | 'unset' | 'unavailable' | 'over-budget' | 'needs-document';
+  readonly entity: string | null;
+  readonly rows: readonly ResolvedCollectionRow[];
+  /** A PAGED collection's position (davatoidud-toolkit PR03) — absent otherwise. */
+  readonly page?: {
+    readonly number: number;
+    readonly hasNext: boolean;
+  } | undefined;
+}
+/** One row, projected onto a card's slots — never the entity row itself. */
+interface ResolvedCollectionRow {
+  readonly id: string;
+  readonly title: string | null;
+  readonly text: string | null;
+  readonly image: {
+    readonly url: string;
+    readonly alt: string | null;
+    readonly width: number | null;
+    readonly height: number | null;
+  } | null;
+  readonly href: string | null;
+}
+/**
+ * Host-injected block-tree resolver.
+ *
+ * Receives the STORED tree and returns the {@link ResolvedBlockTree} that
+ * should cross the wire in its place. Called once per `blockTree` field per
+ * row, and once per `_chrome` region.
+ *
+ * **SECURITY (CLAUDE.md #1).** Every read the provider performs must be
+ * PUBLISHED-only and must honour the caller's permissions — a `query()` field
+ * resolved through an `AdminClient` would surface drafts on the anonymous
+ * surface, and an internal link resolved without a publish filter would leak an
+ * unpublished document's URL. `content-api` cannot enforce either (the resolver
+ * is injected), so the WIRING must guarantee both — the same posture, for the
+ * same reason, as `ContentApiResolution.resolvePath`.
+ *
+ * `budget` is the response's ONE resolution budget. Claim BEFORE doing work,
+ * and resolve only what was granted; whatever is refused is reported by the
+ * handler's existing drop log.
+ */
+type ResolveBlocks = (blocks: unknown, opts: ResolveBlocksOptions) => Promise<ResolvedBlockTree>;
+/** What a {@link ResolveBlocks} provider is called with. */
+interface ResolveBlocksOptions {
+  locale?: string | undefined;
+  budget: ResolutionBudget;
+  entity: string;
+  field: string;
+  /**
+   * May THIS caller read rows of `entityName`? The whitelist ∧ `view` gate the
+   * handler applies to every entity read, handed to the provider so a
+   * COLLECTION block (editor PR53) cannot list an entity this API withholds.
+   *
+   * Optional, and absence means NO: a provider that is not told who may read
+   * what must resolve no collection rows at all, rather than guess.
+   */
+  canReadEntity?: ((entityName: string) => boolean) | undefined;
+  /**
+   * Take one slot from THIS response's collection allowance
+   * ({@link MAX_COLLECTIONS_PER_RESPONSE}). Absent means NO, like
+   * `canReadEntity`: a provider not told how many collections the response may
+   * resolve resolves none.
+   */
+  claimCollection?: (() => boolean) | undefined;
+  /**
+   * Set when the field is a CODED TEMPLATE — `field.blockTree({ template })`
+   * (editor D017) — and names the template's root block.
+   *
+   * A templated document has no stored tree: its layout is rebuilt from the
+   * block registry on every load, and its content lives in entity COLUMNS the
+   * template's blocks BIND. So the provider is handed the template name instead
+   * of a tree, builds the tree itself (this package cannot — it has no idea
+   * what a block looks like), and serves it as the envelope's `blocks`.
+   *
+   * Absent for an ordinary tree, and the provider then resolves `blocks` as it
+   * always has.
+   */
+  template?: string | undefined;
+  /**
+   * The row this document's BOUND blocks read (frontend-delivery F109) — handed
+   * over for every tree, and always when {@link template} is set.
+   *
+   * A bound rich-text column's link marks live HERE, not in any tree, so the
+   * envelope's `links` sidecar never carried them — an internal link in a
+   * recipe's body rendered as plain text. The provider resolves the links in
+   * exactly the columns the template binds, in the SAME call and against the
+   * SAME budget as the tree's own, so a document costs one batch per linked
+   * entity type however many columns carry links — never one request per link.
+   *
+   * Read-only: the provider must not write to it. The row is the response being
+   * built, and its columns cross the wire as the handler already projected them.
+   */
+  boundValues?: Readonly<Record<string, unknown>> | undefined;
+  /**
+   * The tree is a STORED DETAIL TEMPLATE drawn for `boundValues` (block-library
+   * D009), not that row's own document. The provider must then project the
+   * row's detail and NOTHING else of it: in particular it must not walk the
+   * row's columns for links on the say-so of a bound block in the tree, since
+   * the tree is editor-authored and the row is not the editor's to expose.
+   *
+   * ⚠️ A contract the provider has to honour: this package cannot enforce it.
+   * `@murumets-ee/content`'s resolver does; a host-supplied one must too.
+   */
+  rowIsForeign?: boolean | undefined;
+  /**
+   * The page a PAGED collection in this tree shows (davatoidud-toolkit PR03) —
+   * the request's `?page=`, already validated (`singleParamsSchema`). Absent
+   * for page 1, and on every list read: a page number belongs to ONE document.
+   */
+  page?: number | undefined;
+}
+/**
+ * Is `value` a {@link ResolvedBlockTree}?
+ *
+ * A structural check on a host-injected return value, not a cast. It checks the
+ * marker, the tree and the sidecar — and deliberately does NOT walk `blocks`
+ * (that is the document's own content, of unbounded size, and validating it
+ * here would duplicate the consumer-side validator that already exists for the
+ * unresolved case).
+ *
+ * **The sidecar's VALUES are checked, and the unbounded-content argument above
+ * does not excuse skipping them.** `links` is bounded by the link count the
+ * provider already claimed against the budget, so walking it costs what the
+ * response has already paid for. Without this a provider returning a nested
+ * object or a number where an href belongs passes the guard and the value is
+ * serialised straight onto the wire. The Astro decoder defends itself with its
+ * own check, so this is defence in depth rather than a live hole — but it is
+ * the one field this package can cheaply own, and owning it here means a
+ * consumer that is NOT ours inherits the guarantee too.
+ *
+ * The same argument covers `unresolved`, which is bounded by the same claim.
+ *
+ * TYPE only, deliberately — not scheme policy. A host may legitimately emit any
+ * scheme its own consumers accept, and `sanitizeHref` at the consumer's process
+ * boundary is where that decision belongs. Two places deciding it is how they
+ * come to disagree.
+ */
+declare function isResolvedBlockTree(value: unknown): value is ResolvedBlockTree;
+//#endregion
+//#region src/consent.d.ts
+/**
+ * `GET /_consent` and `POST /_consent` — a site's consent settings, and the
+ * record of one visitor's choice (the second write this read-only API accepts,
+ * beside form submissions).
+ *
+ * A visitor answers the consent banner on the site's own front; the front
+ * forwards the choice here with its site key, and sets the signed cookie this
+ * answer carries on its OWN origin. So both routes answer only a caller
+ * carrying a verified site key — the site comes from that KEY and nothing
+ * else, never from a query parameter or the body — and a caller without one
+ * gets the same 404 as a route that does not exist. A browser never reaches
+ * them directly. (The same rule as the form routes, `forms.ts`.)
+ *
+ * What this module owns is the HTTP edge: the key requirement, the locale, the
+ * body cap, parsing, and turning the provider's verdict into a response. Every
+ * decision about CONSENT — which categories exist, whether a choice is
+ * well-formed, the policy version, storage, signing the cookie — is the
+ * injected `consent` provider's (`@murumets-ee/consent/server`), because this
+ * package is a leaf and does not import it.
+ *
+ * Every response here is `no-store`: a recorded choice is one visitor's, and
+ * the settings feed is memoised by the front rather than by a shared cache
+ * (tagging and purging it belongs to a later change). Nothing from a posted
+ * body is logged.
+ */
+/** The decision as the provider built it. Passed through to the caller untouched. */
+interface ContentApiConsentState {
+  readonly categories: Readonly<Record<string, boolean>>;
+  readonly policyVersion: number;
+  readonly decidedAt: string;
+  readonly source: string;
+}
+/** The signed cookie the FRONT sets on its own origin (the provider signs; the front never holds the secret). */
+interface ContentApiConsentCookie {
+  readonly name: string;
+  readonly value: string;
+  /** Seconds. */
+  readonly maxAge: number;
+}
+/** The provider's verdict on one posted choice. */
+type ContentApiConsentRecordResult = {
+  readonly kind: 'recorded';
+  readonly state: ContentApiConsentState;
+  readonly cookie: ContentApiConsentCookie;
+} | {
+  readonly kind: 'invalid';
+} | {
+  readonly kind: 'unavailable';
+};
+/**
+ * The consent provider. Omit it and both routes are 404 (opt-in,
+ * deny-by-default). Wire `createConsentContentApi` from
+ * `@murumets-ee/consent/server`.
+ */
+interface ContentApiConsent {
+  /** The site's public consent config for one locale, as a JSON object; `null` = this site has none. */
+  getConfig(input: {
+    site: string;
+    locale: string;
+  }): Promise<Readonly<Record<string, unknown>> | null>;
+  record(input: {
+    site: string;
+    body: unknown;
+  }): Promise<ContentApiConsentRecordResult>;
+}
+/**
+ * Largest consent body accepted. A choice is a handful of category flags and a
+ * version number; this is generous room for that and far short of anything
+ * worth parsing for a flood.
+ */
+declare const MAX_CONSENT_BODY_BYTES: number;
+//#endregion
+//#region src/detail-template.d.ts
+/**
+ * The key the resolved template crosses under. Underscore-led so it cannot be
+ * mistaken for a column, and stable: a frontend lists it beside its own body
+ * block fields.
+ */
+declare const DETAIL_TEMPLATE_FIELD = "_template";
+/**
+ * The detail-template provider. Injected, not imported, so this package stays a
+ * leaf — `@murumets-ee/content`'s `createDetailTemplateProvider` is the
+ * reference implementation, and its header states what each method may reach.
+ */
+interface ContentApiDetailTemplates {
+  /** The entity templates are stored in — named on the response's cache tags. */
+  readonly entity: string;
+  /**
+   * The PUBLISHED template for rows of `entity` at `locale`, or `null`.
+   * Implementations must apply the publish filter themselves: this package
+   * serves whatever comes back.
+   */
+  readTemplate(opts: {
+    entity: string;
+    locale: string;
+  }): Promise<{
+    readonly id: string;
+    readonly blocks: unknown[];
+  } | null>;
+  /**
+   * The row's public name and summary. Only string `title` and `description`
+   * are read from the answer; anything else it returns is dropped here.
+   */
+  publicRow(opts: {
+    entity: string;
+    row: Readonly<Record<string, unknown>>;
+    locale: string;
+  }): Promise<Record<string, unknown>>;
+}
+//#endregion
+//#region src/forms.d.ts
+/**
+ * `/_forms/:id/token` and `POST /_forms/:id/submissions` — one of the two
+ * places this read-only API accepts a write (forms plan D003; the other is
+ * `POST /_consent`, `consent.ts`).
+ *
+ * A form on a site is posted by the VISITOR to the site's own front (same
+ * origin, works without JavaScript); the front forwards it here with its site
+ * key and the visitor's address. So both routes answer only a caller carrying a
+ * verified site key — the site comes from that key and nothing else — and a
+ * caller without one gets the same 404 as a route that does not exist. A
+ * browser never reaches them directly.
+ *
+ * What this module owns is the HTTP edge: the key requirement, the body cap,
+ * parsing, the visitor address, and turning the provider's verdict into a
+ * response. Every decision about the FORM — which form, spam, validation,
+ * rate limits, the extra check, storage — is the injected `forms` provider's
+ * (`@murumets-ee/forms/server`), because this package is a leaf (D032).
+ *
+ * Every response here is `no-store`: a token is minted for one visitor's
+ * ask, and a submission's answer is about one post (C5 — nothing from a
+ * submission in a cache).
+ */
+/** What a rendered form needs: a fresh token, its trap's name, its extra check. */
+interface ContentApiFormTicket {
+  readonly token: string;
+  readonly honeypot: string;
+  readonly challenge: {
+    readonly provider: 'turnstile' | 'recaptcha';
+    readonly siteKey: string;
+  } | null;
+}
+/**
+ * The provider's verdict on one post. `accepted` is ALSO the answer to spam —
+ * a bot is told it succeeded (forms D004) — so this module cannot tell the two
+ * apart, and the response it builds is the same bytes for both.
+ */
+type ContentApiFormSubmitResult = {
+  readonly kind: 'accepted';
+} | {
+  readonly kind: 'invalid';
+  readonly fields: Readonly<Record<string, string>>;
+} | {
+  readonly kind: 'rate_limited';
+  readonly retryAfterSeconds: number;
+} | {
+  readonly kind: 'challenge_failed';
+} | {
+  readonly kind: 'unavailable';
+} | {
+  readonly kind: 'not_found';
+};
+/**
+ * The forms provider. Omit it and both routes are 404 (opt-in,
+ * deny-by-default). Wire `createFormsContentApi(getToolkitApp)` from
+ * `@murumets-ee/forms/server`.
+ */
+interface ContentApiForms {
+  issueToken(input: {
+    site: string;
+    formId: string;
+    purpose: 'render' | 'visitor';
+    visitorAddress: string | null;
+  }): Promise<ContentApiFormTicket | null | 'rate_limited'>;
+  submit(input: {
+    site: string;
+    formId: string;
+    body: unknown;
+    visitorAddress: string | null;
+  }): Promise<ContentApiFormSubmitResult>;
+}
+/**
+ * Largest submission body accepted. A form has at most 100 fields and its
+ * longest answer is 5,000 characters; this is room for a long message and a
+ * CAPTCHA token, and well short of anything worth parsing for a flood.
+ */
+declare const MAX_FORM_BODY_BYTES: number;
+//#endregion
+//#region src/limits.d.ts
+interface ContentApiLimits {
+  /**
+   * Max requests IN FLIGHT at once, per instance. NOT a connection ceiling —
+   * see the module docblock. Default {@link DEFAULT_MAX_CONCURRENT_REQUESTS}.
+   */
+  maxConcurrentRequests?: number;
+  /**
+   * Max requests queued waiting for a slot before the guard sheds 503, per
+   * instance. Default {@link DEFAULT_MAX_QUEUED_REQUESTS}.
+   */
+  maxQueuedRequests?: number;
+  /** Per-request wall clock in ms. Default {@link DEFAULT_REQUEST_TIMEOUT_MS}. */
+  requestTimeoutMs?: number;
+  /**
+   * Fairness budget applied to UNCREDENTIALED traffic, PER INSTANCE.
+   *
+   * Only consumed when a distinguishing key exists — which for anonymous
+   * traffic means {@link getClientIp} is wired. Without it the fairness limit is
+   * skipped entirely rather than collapsed onto one shared bucket (F011).
+   */
+  anonymousTokensPerInstance?: number;
+  /**
+   * Interval for every fairness budget on this surface, in ms. Default 60_000.
+   */
+  intervalMs?: number;
+  /**
+   * Ceiling on any credential's own budget, PER INSTANCE. A credential
+   * presenting a larger `rateBudgetPerInstance` is clamped to this. C5: the
+   * ceiling moves by operator action, never by request parameter.
+   */
+  maxBudgetPerInstance?: number;
+  /**
+   * How the host extracts a trustworthy client IP — the SECOND fairness key,
+   * used when no server-verified principal identity exists.
+   *
+   * Deliberately optional and deliberately host-supplied: only the deployment
+   * knows whether it sits behind a proxy it trusts, and a package-side default
+   * would either trust a forgeable header or invent a constant. Returning
+   * `undefined` (or omitting this) means anonymous traffic has NO distinguishing
+   * key, so the fairness limit is SKIPPED for it. That is the correct outcome,
+   * not a degraded one.
+   */
+  getClientIp?: (req: Request) => string | undefined;
+  /**
+   * The fairness counter's backing store (D028 part 3). Defaults to an
+   * in-memory, per-instance one. Supply a shared implementation only if a global
+   * quota is genuinely needed; see the module docblock.
+   */
+  store?: RateLimitStore;
+}
+//#endregion
+//#region src/media.d.ts
+/**
+ * One generated image file — a `srcset` candidate. `width`/`height` are the
+ * file's own, never the ladder rung that was requested (images D003).
+ */
+interface MediaSource {
+  url: string;
+  width: number;
+  height: number;
+}
+/**
+ * One media item as it reaches the wire.
+ *
+ * Structurally identical to `@murumets-ee/media`'s `PublicMediaProjection`; the
+ * app that wires the two is where TypeScript checks they agree, exactly as for
+ * `ContentApiResolution` and `ContentApiMenus`.
+ */
+interface MediaProjection {
+  id: string;
+  /** A PUBLIC url. Never signed — see {@link ContentApiConfig.resolveMedia}. */
+  url: string;
+  mimeType: string | null;
+  width: number | null;
+  height: number | null;
+  /** Translatable on the Media entity — this projection is locale-dependent. */
+  alt: string | null;
+  /** Translatable on the Media entity — this projection is locale-dependent. */
+  title: string | null;
+  /** Variant urls by image-style name, inlined as data (D008: a client derives nothing). */
+  variants: Record<string, string>;
+  /**
+   * Every generated file by SHAPE name (`natural` = the photograph's own ratio),
+   * ascending by width, each with the width and height the FILE actually has —
+   * what a `srcset` is built from (images D007, lumi-cms#1160). A shape the
+   * photograph has no files for yet is absent. Bounded by configuration, like
+   * `variants`.
+   */
+  sources: Record<string, MediaSource[]>;
+  /**
+   * The AVIF copy of `sources`, by the same shape names (images PR12), for a
+   * `<picture><source type="image/avif">`. ABSENT — never `{}` — when there is
+   * none: AVIF is off (the default) or the catch-up has not reached the
+   * photograph, so a site that has not turned it on sends what it did before.
+   * A shape is listed only when its AVIF files have exactly the widths of its
+   * `sources` list. Never an AVIF file in `sources` itself.
+   */
+  avifSources?: Record<string, MediaSource[]>;
+  /**
+   * Where the subject is, as `{ x, y }` fractions of the image (images D002).
+   * ALWAYS present — `{ x: 0.5, y: 0.5 }` for a row that has none — so no
+   * consumer branches on its absence (D010). A shaped slot crops around it; the
+   * `object-position` it needs depends on the slot's own ratio, so it is
+   * computed at render and never published here (`@murumets-ee/media/crop`).
+   */
+  focalPoint: {
+    x: number;
+    y: number;
+  };
+  /**
+   * The blurred preview a render draws while the photograph loads — a
+   * `data:image/webp` or `data:image/png` base64 URL of a tiny image of it, or
+   * `null` when there is none (images PR11). Validated by the provider before
+   * it gets here; a consumer that writes it into a `style` validates again
+   * (`@murumets-ee/blocks` does).
+   */
+  blurDataUrl: string | null;
+}
+/**
+ * Host-injected media resolver. Ids that do not exist, are unpublished for this
+ * caller, or whose file is not public must be ABSENT from the returned map —
+ * one absence, several causes, per phase 05's failure semantics.
+ */
+type ResolveMedia = (ids: readonly string[], opts?: {
+  locale?: string | undefined;
+}) => Promise<Map<string, MediaProjection>>;
+//#endregion
+//#region src/references.d.ts
+/**
+ * What a reference resolves to by default.
+ *
+ * `title` and `href` are nullable INDEPENDENTLY of the projection itself: the
+ * target resolved (so `id`/`entityType` are real), but the entity may have no
+ * usable title field, or may not be routable, in which case there is no href to
+ * give. That is a different outcome from "the target did not resolve", which is
+ * an absent projection — see {@link projectReferences}.
+ */
+interface ReferenceProjection {
+  id: string;
+  entityType: string;
+  title: string | null;
+  href: string | null;
+}
+/**
+ * Host-injected routing seam — a STRUCTURAL mirror of
+ * `@murumets-ee/blocks`' `ResolveEntityHref`. Redeclared rather than imported
+ * for exactly the reason spelled out on `ContentResolveResult`: `content-api`
+ * is a leaf and `blocks` depends back on it, so the edge is a build cycle. The
+ * app wires ONE implementation into both.
+ *
+ * **This one does not need a publish filter, and that is a property rather than
+ * an oversight.** It is only ever asked about ids that already came back from a
+ * published-only `QueryClient` read, so an unpublished target never reaches it.
+ * The same seam wired into `resolveLinks` — which resolves arbitrary
+ * editor-authored link targets — DOES need one, because nothing upstream of it
+ * has proven the target visible.
+ */
+type ResolveEntityHref = (target: {
+  entity: string;
+  id: string;
+  locale?: string;
+}) => string | null | Promise<string | null>;
+//#endregion
+//#region src/response.d.ts
+/**
+ * Response helpers — JSON envelope builders.
+ */
+/**
+ * The COMPLETE machine-readable error-code set this API can emit.
+ *
+ * Declared ONCE, here, beside the only function that can produce one: the
+ * compiler refuses a code that isn't in this tuple, and `GET /_schema` publishes
+ * the tuple verbatim. So a new code cannot be introduced without landing in both
+ * the type system and the contract in the same edit — there is no second,
+ * hand-kept list to forget (the drift shape D031 makes a hard requirement, and
+ * the mechanism behind the SDK that drifted 4.5 months undetected).
+ *
+ * `code` is machine contract; `message` is not, and is free to be specific.
+ */
+declare const ERROR_CODES: readonly ["NOT_FOUND", "VALIDATION_ERROR", "INTERNAL_ERROR", "RATE_LIMITED", "SERVICE_OVERLOADED", "FORM_INVALID", "CHALLENGE_FAILED", "PAYLOAD_TOO_LARGE"];
+/** One of {@link ERROR_CODES}. */
+type ContentApiErrorCode = (typeof ERROR_CODES)[number];
+//#endregion
+//#region src/search.d.ts
+/** Results returned when the caller sends no `?limit=`. */
+declare const DEFAULT_SEARCH_RESULTS = 20;
+/** Most results one search returns — in total, and per type. A 400 above it, never a clamp. */
+declare const MAX_SEARCH_RESULTS = 50;
+/** One search result, as it crosses the wire. */
+interface SearchHit {
+  /** The entity type — a name a frontend may map to its own words. */
+  type: string;
+  /** The type's English singular label — the fallback for a frontend with no words of its own. */
+  typeLabel: string;
+  id: string;
+  title: string;
+  summary: string | null;
+  image: MediaProjection | null;
+  /** Locale-relative canonical path, or `null` when the document has none. */
+  path: string | null;
+}
+/**
+ * The header a site's own frontend forwards its VISITOR's address on.
+ *
+ * Honoured ONLY from a caller whose credential is bound to a site — the site
+ * key a frontend holds server-side. That is what makes it more than obscurity
+ * (`core/limits/client-ip.ts` rule 7): the guarantee that "nobody reaches this
+ * without passing through what writes it" is not a deploy-topology claim here,
+ * it is the credential. An anonymous caller sending it is ignored.
+ */
+declare const VISITOR_ADDRESS_HEADER = "x-lumi-visitor-address";
+/** Tuning for {@link SearchRateLimiter}. Every field optional. */
+interface ContentApiSearchConfig {
+  /** Searches one visitor may run per window, PER INSTANCE. Default 30. */
+  searchesPerVisitorPerInstance?: number;
+  /** The window, in ms. Default 60 000. */
+  intervalMs?: number;
+  /** The counter's store. Defaults to an in-memory, per-instance one. */
+  store?: RateLimitStore;
+  /**
+   * The client address of an ANONYMOUS caller — a browser fetching `_search`
+   * itself, or a site that sends no key. Overrides `limits.getClientIp` for
+   * the search budget only, so a mount can bound searches per address without
+   * also turning on the surface-wide fairness limit. Use the toolkit's one
+   * derivation (`proxyClientIp` from `@murumets-ee/search/admin`, or
+   * `createClientIpResolver` from `@murumets-ee/core/limits`).
+   */
+  getClientIp?: (req: Request) => string | undefined;
+}
+//#endregion
+//#region src/types.d.ts
+/** CORS configuration — deny-by-default, explicit origin allowlist. */
+interface CorsConfig {
+  /** Allowed origins. Each matched exactly — no regex, no wildcards. */
+  allowedOrigins: string[];
+  /** Preflight cache max age (seconds). Default: 3600 */
+  maxAge?: number;
+}
+/** Per-entity cache override. */
+interface EntityCacheConfig {
+  /**
+   * This entity's total staleness window, in seconds — see
+   * {@link CacheConfig.maxStaleSeconds}. Overrides the surface default.
+   */
+  maxStaleSeconds?: number;
+  /** Whether this entity is cacheable. Default: true. Set false → no-store. */
+  cacheable?: boolean;
+}
+/** Global cache configuration. */
+interface CacheConfig {
+  /**
+   * The TOTAL staleness window, in seconds: the worst case between a publish
+   * and a visitor seeing it, with a shared cache in front. Default 360.
+   *
+   * **ONE number, because the sum is the number that is true (D036).** This
+   * field replaced a pair — `defaultMaxAge` (60) and
+   * `defaultStaleWhileRevalidate` (300) — whose real window was their SUM, and
+   * nothing in the names, the type, the JSDoc or the emitted header said so. An
+   * operator who set `defaultMaxAge: 10` believing they had bought a ten-second
+   * window had bought 310, because the other field was untouched at its default.
+   * Neither live mount passed a `cache` config at all, so 360 was what every
+   * deployment in this repo served, chosen by nobody (F032).
+   *
+   * The `max-age` / `stale-while-revalidate` split is now a package-owned
+   * derivation the operator does not tune, so **the sum of what is emitted
+   * always equals what was declared** — there is no way to write this
+   * configuration that expresses a window the deployment does not honour. Same
+   * move D028 made renaming a rate budget `perInstance`: prefer the shape that
+   * cannot be wrong over the check that has to be right.
+   *
+   * `stale-while-revalidate` extends freshness ADDITIVELY beyond `max-age` (RFC
+   * 5861 §3, whose own worked example is `max-age=600, stale-while-revalidate=600`
+   * → "up to 20 minutes"). R15 verified this rather than assuming it.
+   *
+   * **S6 is an ORIGIN invariant.** The origin serves a published edit on the very
+   * next request; any shared cache converts that into "visible within this
+   * window". An operator who needs S6 verbatim sets this to `0` and gets
+   * `no-store` out of the same field — no second knob, no code change, no
+   * per-entity opt-out to remember.
+   */
+  maxStaleSeconds?: number;
+  /** Per-entity overrides, keyed by entity name. */
+  entities?: Record<string, EntityCacheConfig>;
+  /**
+   * Cache-tag emission (D055, PR 11) — the header only, never a purge protocol.
+   *
+   * Every STORABLE response carries tags naming what composed it:
+   * `lumi:<entity>:<id>` for a row whose content is in the body, and
+   * `lumi:<entity>` for a response that depends on WHICH rows exist. A consumer
+   * purges by tag on write; nothing in this repo does yet, so **TTL expiry
+   * ({@link maxStaleSeconds}) remains the entire reconciliation mechanism with
+   * S6 until one does.** What this buys today is that wiring it later needs no
+   * response-format change (R05's asymmetry).
+   *
+   * Omit for the default: emit, under `Cache-Tag`, comma-separated. See
+   * `cache-tags.ts` for the format, its bounds and the disclosure invariant
+   * that makes raw ids defensible on a public header.
+   */
+  tags?: CacheTagsConfig;
+}
+/**
+ * Routing resolution result — a STRUCTURAL mirror of `@murumets-ee/content`'s
+ * `ResolveResult`. Redeclared locally (like the wire-format envelopes above) so
+ * `content-api` stays a ZERO-`@murumets-ee/content` leaf: a static dep on
+ * `@murumets-ee/content` is IMPOSSIBLE here — `content` transitively depends
+ * back on `content-api` (`content → blocks → content-api/query-params`), so
+ * the edge forms a hard `turbo` build cycle. The resolution functions are
+ * therefore INJECTED by the app (which already depends on `content`), never
+ * imported — mirroring the entity-package leaf rule
+ * (CLAUDE.md: "receives everything cross-package via constructor parameters").
+ */
+type ContentResolveResult = {
+  kind: 'document';
+  entityType: string;
+  id: string;
+} | {
+  kind: 'redirect';
+  to: string;
+  status: 301 | 302;
+} | {
+  kind: 'none';
+};
+/** One enumerated canonical path — structural mirror of `content`'s `PathEntry`. */
+interface ContentPathEntry {
+  /** Locale-relative canonical path (leading '/', no trailing '/'). */
+  path: string;
+  /** The routable entity type name. */
+  entityType: string;
+  /** The DOCUMENT id (entity primary key). Also the opaque `_paths` cursor token. */
+  id: string;
+  /** Last-modified timestamp (sitemap `<lastmod>` etc.). */
+  updatedAt: Date;
+}
+/**
+ * Injected routing-resolution providers (routing PR07). Supplied by the APP when
+ * it wants `content-api` to serve `GET /_resolve`, `/_paths`, `/_alternates`;
+ * omit and those three endpoints stay 404 (opt-in, deny-by-default). The app
+ * wires these from `@murumets-ee/content/resolve` — e.g.
+ * `resolvePath(path, locale, buildResolveDeps(getApp()))` — because it can depend
+ * on `@murumets-ee/content` where this leaf package cannot (see
+ * {@link ContentResolveResult} for the cycle rationale).
+ *
+ * **SECURITY (CLAUDE.md #1).** `resolvePath` MUST be the PUBLISHED-only resolver
+ * — NEVER a draft/preview resolver that skips publish checks, which would expose
+ * unpublished documents by URL. This package cannot enforce the choice (it never
+ * imports the resolution core — DI), so the WIRING must guarantee it.
+ */
+interface ContentApiResolution {
+  /** Resolve `(path, locale)` → document / redirect / none. PUBLISHED-only. */
+  resolvePath: (path: string, locale: string) => Promise<ContentResolveResult>;
+  /**
+   * Stream ONE entity type's PUBLISHED canonical paths for `locale`, keyset-
+   * resumable. `afterDocumentId` is a {@link ContentPathEntry.id} (a DOCUMENT
+   * id) — the stream resumes strictly AFTER it. Named distinctly from content's
+   * own `EnumeratePathsOptions.afterId` (a `toolkit_paths` ROW PK, a DIFFERENT
+   * UUID domain) so the required translation is glaring at the provider's own
+   * call site — the provider owns mapping this document id onto that row-PK
+   * keyset, once per page, never per row.
+   */
+  enumeratePaths: (opts: {
+    locale: string;
+    entityType: string;
+    afterDocumentId?: string;
+  }) => AsyncIterable<ContentPathEntry>;
+  /** Published per-locale canonical URLs for a document (the hreflang set). */
+  getAlternates: (entityType: string, id: string) => Promise<Array<{
+    locale: string;
+    path: string;
+  }>>;
+}
+/**
+ * One resolved menu item — a STRUCTURAL mirror of `@murumets-ee/menus`'
+ * `ResolvedMenuItem`. Redeclared rather than imported for exactly the reason
+ * spelled out on {@link ContentResolveResult}: `content-api` is a leaf, and the
+ * resolver is INJECTED by the app (which can depend on `@murumets-ee/menus`)
+ * rather than imported here.
+ *
+ * The resolver has already applied every filter (unpublished / deleted targets
+ * dropped, per-locale visibility, empty headers pruned, depth clamped), so this
+ * is a render-ready projection — there is nothing left for the handler to gate
+ * per item, and deliberately no `entityType` on the wire.
+ */
+interface ContentApiResolvedMenuItem {
+  id: string;
+  kind: 'link' | 'header';
+  /** Already resolved for the requested locale (override, else live title). */
+  label: string;
+  /** Canonical path (+ `#anchor`), external target verbatim, or `null` for headers. */
+  href: string | null;
+  newTab: boolean;
+  isActive: boolean;
+  inActiveTrail: boolean;
+  children: ContentApiResolvedMenuItem[];
+}
+/** A resolved menu — structural mirror of `@murumets-ee/menus`' `ResolvedMenu`. */
+interface ContentApiResolvedMenu {
+  handle: string;
+  items: ContentApiResolvedMenuItem[];
+}
+/**
+ * Injected menu provider (routing PR09). Supplied by the APP when it wants
+ * `content-api` to serve `GET /_menu`; omit and that endpoint stays 404 (opt-in
+ * — deny-by-default). The app wires this from `@murumets-ee/menus/resolve` —
+ * e.g. `getMenu(handle, opts, buildMenuResolveDeps(getApp()))`.
+ *
+ * **SECURITY (CLAUDE.md #1).** {@link ContentApiMenus.handles} IS the gate, and
+ * it is the ONLY one: a handle not on the list 404s before `getMenu` is ever
+ * called, and a listed handle is served to any caller the CORS/auth layer let
+ * through — there is no per-entity `view` check, because a resolved menu item
+ * carries no entity identity to check against (see
+ * {@link ContentApiResolvedMenuItem}). Listing a handle here is therefore an
+ * explicit "this navigation is public" decision, structurally the same opt-in
+ * as putting an entity in {@link ContentApiConfig.entities}.
+ *
+ * **What a listed handle exposes — read this before listing one.** The TITLES +
+ * canonical paths of any PUBLISHED, ROUTABLE document the menu's items resolve
+ * to, REGARDLESS of whether that document's entity type appears in
+ * {@link ContentApiConfig.entities}. The per-entity whitelist governs the
+ * `/:entity` routes; it does NOT govern `_menu`'s title resolution, which reads
+ * live titles from the app's routable-entity registry. So an app whose routable
+ * set is broader than its content-api whitelist should be aware that `_menu` can
+ * surface titles from types every other endpoint 404s. Note this is strictly
+ * more than a public sitemap enumerates — a sitemap carries `loc` + `lastmod`,
+ * never titles. Unpublished, trashed and unroutable targets are still dropped by
+ * the resolver, and per-locale-hidden items never appear. Do not list a handle
+ * whose labels or linked titles are themselves sensitive. (Narrowing this
+ * structurally — a per-handle `requires` permission — is recorded as a deferred
+ * option in plan/routing's F041; today the handle list is the whole gate.)
+ *
+ * `getMenu` MUST be the published-only resolver — it must never be wired to a
+ * draft/preview variant, which would leak unpublished documents by URL. This
+ * package cannot enforce that (it never imports the resolver — DI), so the
+ * WIRING must guarantee it.
+ *
+ * **`getMenu`'s inputs are `(handle, { locale, currentPath })` and nothing
+ * principal-derived — keep it that way.** Because the body cannot vary per
+ * caller, `_menu` answers every caller with the SAME cacheable headers, which is
+ * what stops the header shape from advertising that a credential verified on an
+ * endpoint with no permission gate. A provider that started varying its output
+ * by caller would silently break that; see `handleMenu`'s JSDoc for what must
+ * change first if it ever does.
+ */
+interface ContentApiMenus {
+  /**
+   * Menu handles this instance serves. Deny-by-default — an unlisted handle
+   * 404s before {@link ContentApiMenus.getMenu} is called.
+   */
+  handles: readonly string[];
+  /** Resolve one menu for a locale. `null` → unknown or unpublished menu. */
+  getMenu: (handle: string, opts: {
+    locale: string;
+    currentPath?: string;
+  }) => Promise<ContentApiResolvedMenu | null>;
+}
+/**
+ * One composed chrome region.
+ *
+ * `blocks` is `BlockInstance[]` — the same block shape a page's own `layout`
+ * tree reaches the wire as, so a consumer needs ONE renderer rather than two.
+ * It is typed `unknown[]` here for the leaf reason that governs this whole
+ * file: `content-api` cannot import `@murumets-ee/blocks` (blocks depends back
+ * on it, so the edge is a build cycle).
+ *
+ * **The provider MUST have stripped the composition's scope tags** (D027).
+ * `composeChromeRegion` tags every top-level block with `scope`, `scopeDocId`
+ * and `scopeBlockId` because `applyOverrides` REQUIRES the tagging as a
+ * precondition — hand it an untagged document and it returns the blocks
+ * unchanged with no error and zero overrides applied. So the pipeline is tag →
+ * apply → strip, and the strip happens in the provider, through the existing
+ * `stripScopeTags` rather than a second implementation.
+ *
+ * This is not a data leak and should not be described as one: `scopeBlockId` is
+ * the block's own id, `scopeDocId` the chrome row id, `scope` the literal
+ * `'site'`. The cost is to the CONTRACT — three fields `_schema` cannot
+ * describe, and `scopeBlockId` is the key `_overrides` is written under, so
+ * serialising it hands a consumer the override map's key space immediately
+ * after D011 banned the map.
+ */
+interface ContentApiChromeRegion {
+  /** Composed, override-applied, scope-tag-stripped block instances. */
+  blocks: unknown[];
+  /**
+   * Does this document's chrome differ from the site default?
+   *
+   * Rides along because it already exists and already answers the one question
+   * a consumer has that the blocks themselves do not. It is a boolean about
+   * LAYOUT, not editorial vocabulary, so it does not reopen D011.
+   */
+  overridden: boolean;
+  /**
+   * The three {@link ResolvedBlockTree} fields, MERGED in rather than nested,
+   * and present only when a `resolveBlocks` provider ran over this region.
+   *
+   * Merged so that a chrome region and a document's own `blockTree` field are
+   * read by ONE consumer-side decoder — `frontend-delivery` D019's answer to
+   * `plan/api` finding 075 requirement 5 ("`_chrome` and document layout should
+   * use one format, not two"). Nesting would have made `blocks` stop being an
+   * array on the resolved path, which is a second shape for the same idea.
+   *
+   * Absent — not empty — when nothing resolved them, for the same reason
+   * {@link ResolvedBlockTree} is not emitted empty: an unconditional empty
+   * container cannot be told apart from "resolution never ran".
+   *
+   * ⚠️ **One case emits `resolved: 1` with an EMPTY `blocks`** — editor D010's
+   * third state, where a provider failed and then failed its I/O-free retry, so
+   * the region is blanked rather than served as stored. A consumer that treats
+   * an empty region as "the page deliberately hid this" must check `resolved`
+   * to tell the two apart: a genuinely hidden region never carries it, because
+   * `resolveRegion` returns before calling the provider when a region has no
+   * blocks to walk. It is the only discriminator available, and it exists only
+   * here — a document's own `blockTree` field has no equivalent, because an
+   * empty stored tree IS handed to the provider and comes back as an envelope.
+   *
+   * Be precise about what it rests on. The argument above is airtight for a
+   * genuinely HIDDEN region. It does not bind a wired provider that answers a
+   * NON-empty region with an empty `blocks` array: `isResolvedBlockTree` only
+   * requires an array, so that passes, and the rebuilt region is byte-identical
+   * to a blanked one. The shipped resolver never does it (it returns the array
+   * it walked), and a provider that deletes a region's content is broken in a
+   * way "blanked" describes fairly — but a consumer reading this should know
+   * the discriminator is a convention the provider keeps, not a structure the
+   * server enforces.
+   */
+  resolved?: ResolvedBlockTree['resolved'];
+  links?: ResolvedBlockTree['links'];
+  unresolved?: ResolvedBlockTree['unresolved'];
+  /**
+   * The rows this region's blocks resolved against — see
+   * {@link ResolvedBlockTree.refs}.
+   *
+   * 🔴 It is here because leaving it out made the CHROME half of block-tag
+   * coverage dead code, silently. `resolveRegion` rebuilds the region field by
+   * field rather than spreading the envelope, so a field this type does not
+   * name is a field the wire does not carry — and the case that matters most is
+   * exactly a chrome one: a LOGO, which every page renders and which no tag
+   * named. Nothing failed; the frontend's ref loop simply had an empty array to
+   * iterate, forever.
+   */
+  refs?: ResolvedBlockTree['refs'];
+  /**
+   * The rows this region's COLLECTION blocks resolved to — see
+   * {@link ResolvedBlockTree.collections} (editor PR53). Named here for the
+   * reason `refs` is: a field this type omits is a field `resolveRegion` drops,
+   * and a collection in a footer would otherwise resolve, cost its reads, and
+   * reach the frontend as nothing.
+   */
+  collections?: ResolvedBlockTree['collections'];
+  /**
+   * What this region's live-bound Price fields resolved to, and the site's
+   * currency — see {@link ResolvedBlockTree.live} / {@link
+   * ResolvedBlockTree.currency} (block-library F012). Named here for the same
+   * reason `refs`/`collections` are: a field this type omits is a field
+   * `resolveRegion` drops, and a header's live-bound price (a site header can
+   * carry one as readily as a page body) would otherwise resolve, cost its
+   * read, and reach the frontend as nothing.
+   */
+  live?: ResolvedBlockTree['live'];
+  currency?: ResolvedBlockTree['currency'];
+}
+/**
+ * The named regions. Each key IS a chrome document's `placement` value — the
+ * same string, so the provider maps one to the other by identity rather than
+ * through a lookup table, and a reader of either can predict the other.
+ *
+ * That is what stops them drifting, and it replaces a three-way mirror (these
+ * keys, the legacy layout entity's four columns, and `SiteLayoutSnapshot`'s
+ * four arrays in the since-deleted multi-scope composer) that required a reader
+ * to keep three lists in their head.
+ *
+ * 🔴 **This is a WIRE BREAK as of PR30.** Two more keys — a before-content and
+ * an after-content region — were part of this shape and are gone. Nothing could
+ * ever fill them — no document form, no editor, no writer outside one test
+ * fixture — and both customer sites left them empty. A consumer built against
+ * the four-key shape must drop them: `apps/front-astro` THROWS on a region key
+ * it asked for and did not get (`src/lib/content-api.ts`), so a stale front
+ * against a new server fails every page render rather than degrading.
+ *
+ * **`null` and `[]` are DIFFERENT ANSWERS and must not be conflated.** `null`
+ * means "no chrome document — render your own fallback"; an empty `blocks`
+ * array means "the page hid everything — render nothing at all". Collapsing
+ * both to `[]` would silently turn an unseeded CMS into a site that renders a
+ * default header it was told to suppress.
+ */
+interface ContentApiChromeRegions {
+  header: ContentApiChromeRegion | null;
+  footer: ContentApiChromeRegion | null;
+}
+/**
+ * Injected site-chrome provider (plan/api phase 07). When present the handler
+ * serves `GET /_chrome`; omit and it stays 404 — opt-in, deny-by-default, the
+ * same shape as {@link ContentApiResolution} and {@link ContentApiMenus}.
+ *
+ * **Chrome is a PROJECTION, not an entity (D026).** Overrides are per-PAGE:
+ * `_overrides` lives on the page and is applied to the CHROME document, so "the
+ * chrome for this document" is a function of (chrome row, requesting document,
+ * locale) — the same stored row yields different bytes depending on who asks.
+ * Serving it at `/v1/site_chrome` would either hand back an uncomposed row
+ * (which D011 forbids) or grow the entity route a document parameter, making
+ * one route two things.
+ *
+ * **SECURITY (CLAUDE.md #1).** Two gates, both operator actions, both
+ * deny-by-default, and they are DIFFERENT decisions:
+ *  1. Injecting this provider makes the endpoint MOUNTABLE.
+ *  2. Granting `view` on {@link ContentApiChrome.entity} to the requesting role
+ *     makes it READABLE. The handler runs `checker(role, entity, 'view')` and
+ *     404s otherwise — never 403 (D006).
+ *
+ * Note the entity's own `access` map is NOT the gate. Entity-level `access` is
+ * advisory (#616, D020), and the roles table is what `buildPermissionChecker`
+ * reads — so an operator who lowers `viewRole` and stops there gets 404s with
+ * no explanation. Grant `site_chrome:view` in the Permission Matrix.
+ *
+ * Since PR30 that is also the ONLY grant this endpoint needs. It used to be
+ * three: a coarse gate on a standalone layout entity plus a `view` on each
+ * document a region actually read from, so granting the coarse one alone
+ * produced a response with an absent header — indistinguishable from a site
+ * with no chrome. The gate and the source are now the same entity.
+ *
+ * `getChrome` MUST read through the published-only, locale-merging client path
+ * — never a bespoke reader that special-cases the region columns. Two
+ * implementations of "what does a missing translation mean" is how the answer
+ * comes to differ in two places.
+ */
+interface ContentApiChrome {
+  /**
+   * The entity backing chrome (`'site_chrome'`). Its `view` permission IS the
+   * read gate — see the security note above. Declared rather than assumed so
+   * this package can run the same one firewall it runs everywhere else.
+   */
+  entity: string;
+  /**
+   * Compose the chrome for a locale, optionally overridden by one document.
+   *
+   * `null` means NO CHROME DOCUMENT EXISTS — the handler renders every region
+   * as `null`, which a consumer reads as "fall back to your own chrome". It
+   * does NOT mean "empty".
+   *
+   * `document` is absent whenever the caller named none, OR named one that does
+   * not exist / is outside the whitelist / is not viewable / is unpublished for
+   * this principal. All four collapse to the site default plus a debug log —
+   * that is what stops the parameter becoming a cheap existence oracle over
+   * document ids.
+   *
+   * `budget` is the response's ONE resolution budget. Chrome's blocks are not a
+   * fifth kind of work and do not get a ceiling of their own: they compete for
+   * the same connection pool as the document's own references, media and links.
+   */
+  getChrome: (opts: {
+    locale: string;
+    document?: {
+      entityType: string;
+      id: string;
+    };
+    budget: ResolutionBudget;
+  }) => Promise<ContentApiChromeRegions | null>;
+}
+/**
+ * The caller behind a request — an IDENTITY plus the role that governs what it
+ * may reach. Returned by {@link ContentApiConfig.authenticate}.
+ *
+ * **Why this is not just a role (D016).** The handler runs every read inside a
+ * `RequestContext` whose `user` flows into `QueryClient`'s `contextResolver`,
+ * and from there into `resolveAuthContext` on every `findMany`/`findById`/
+ * `count`. Until this type existed the hook could only resolve a role, so the
+ * handler hardcoded `user: { id: 'public' }` for EVERY caller: two
+ * authenticated principals were indistinguishable from each other and from
+ * anonymous, and nothing keyed on identity — per-principal scoping,
+ * owner-scoped rows, `tokenId` audit threading — could function at all.
+ *
+ * **`role` is what authorizes; `id` is what identifies.** Every gate on this
+ * surface is `checker(role, entity, 'view')` — the id is never consulted for
+ * access decisions here, and adding one must not change that: authorization
+ * belongs to the one shared firewall, not to a second per-identity rule.
+ *
+ * **Resolving this is the HOST's job, and it is a trust boundary.** This
+ * package never parses a credential; it calls the hook and believes the answer.
+ * The hook must therefore verify the credential itself (signature/hash,
+ * expiry, revocation) and return `null` — never a partially-trusted principal —
+ * whenever verification fails.
+ */
+interface ContentApiPrincipal {
+  /**
+   * The role every permission check runs against. Required: a principal with
+   * no role can reach nothing, which is a refusal, and a refusal is spelled
+   * `null`.
+   */
+  role: string;
+  /**
+   * Stable identity of the caller — a user id, or a service principal's id.
+   *
+   * OPTIONAL, and its absence is deliberately fail-closed: a hook that resolves
+   * a role but no identity yields the ANONYMOUS identity rather than a
+   * synthesised one, so anything keyed on `user.id` sees "not this principal"
+   * instead of a plausible-looking guess. That is also what keeps the
+   * pre-existing `{ role }`-only hook shape compiling and behaving unchanged.
+   *
+   * Must be the id of the principal the credential BELONGS to. A service
+   * integration presents its own service-principal id, never the id of whoever
+   * happened to mint its token — otherwise the token outlives its owner's
+   * account and every action it takes is attributed to a person who did not
+   * take it.
+   */
+  id?: string;
+  /** Display name, if the host resolved one. Never used for authorization. */
+  name?: string;
+  /** Email, if the host resolved one. Never used for authorization. */
+  email?: string;
+  /**
+   * This credential's own fairness budget: requests per window, PER INSTANCE.
+   *
+   * **The budget is a property of the CREDENTIAL, not of the surface (D029).**
+   * D001 fixes a page at ~4 requests and D016 puts authenticated access in the
+   * first `/v1/` release, so this plan's primary consumer is a FAN-IN POINT: one
+   * credentialed SSR frontend serving an entire public website, where every
+   * visitor becomes ~4 requests attributed to a SINGLE principal. A limit sane
+   * for a human poking at the API throttles that frontend into uselessness at a
+   * few dozen page views a minute; a limit sized for the frontend constrains
+   * nobody. There is no value that is both — so the number travels with the
+   * credential and is set when the credential is ISSUED.
+   *
+   * Clamped server-side to `ContentApiLimits.maxBudgetPerInstance` (C5): the
+   * ceiling moves by operator action, never by a request parameter, and a
+   * credential cannot raise its own.
+   *
+   * Omitted → the surface's uncredentialed default applies. Note this is the
+   * budget only; whether a fairness limit is applied AT ALL still depends on a
+   * distinguishing key existing (D025) — for a credentialed caller it does,
+   * because `id` is server-verified.
+   */
+  rateBudgetPerInstance?: number;
+  /**
+   * The ONE site this credential reads (plan `multisite` D008) — a site
+   * handle. Every endpoint then answers for that site only: its documents,
+   * paths, menus and chrome, its origins for CORS, its segment in cache tags.
+   *
+   * **This is the only way a request gets a site on an app serving several**
+   * (short of an ambient `runInSite` or the opt-in
+   * {@link ContentApiConfig.siteForHost}). There is no `site` query parameter
+   * and there will not be one — it is refused with a 400 on every route.
+   *
+   * The hook must take it from the VERIFIED credential (where it was written
+   * at mint), never from the request. `@murumets-ee/auth`'s
+   * `createContentApiAuthenticator` does. A value that is not a handle
+   * collapses the whole principal to anonymous.
+   *
+   * A site-bound frontend key should be returned as `{ role: publicRole, site }`
+   * with NO `id`: it then reads what an anonymous visitor of that site reads.
+   * Its responses are cacheable by the HOLDER of the key only — they are sent
+   * `Cache-Control: private` (and `Vary` on the declared
+   * {@link ContentApiConfig.credentialHeaders}), so a cache shared between two
+   * sites never stores them. Do not expect CDN hits in front of this API for
+   * site-keyed traffic; the site's own frontend is where they are cached.
+   */
+  site?: string;
+}
+/** The body of `GET /_site` — see {@link ContentApiConfig.site}. */
+interface ContentApiSite {
+  /** The site's handle — stable, the key everything per-site is filed under. */
+  handle: string;
+  /** Display name. */
+  name: string;
+  /** Locale codes this site serves. Never empty. */
+  locales: string[];
+  /** The locale an unprefixed / unlocalised request reads. One of `locales`. */
+  defaultLocale: string;
+  /** How locales appear in URLs: `prefix-all`, `no-prefix-default` or `cookie`. */
+  routingStrategy: string;
+  /** The site's public origins (`URL.origin` strings). */
+  origins: string[];
+}
+/**
+ * Host-supplied i18n answer for `GET /_site` (plan `multisite` D007). Injected
+ * (not imported) so this stays a leaf package: the enabled-locale registry and
+ * the single-site install's i18n setting live in `@murumets-ee/content`, which
+ * wires this from `resolveSiteI18n`.
+ */
+interface ContentApiSiteProvider {
+  /**
+   * The locales `site` serves, its default and its URL strategy. Called with
+   * the handle the HANDLER resolved — never a caller-supplied one.
+   */
+  getI18n: (site: string) => Promise<{
+    locales: readonly string[];
+    defaultLocale: string;
+    routingStrategy: string;
+  }>;
+}
+/** Content API handler configuration. */
+interface ContentApiConfig {
+  /** Entity whitelist — ONLY these entities are queryable. Deny-by-default. */
+  entities: Entity[];
+  /**
+   * Permission checker — REQUIRED. Same pattern as admin API handler.
+   * Called lazily on first request, result cached with 30s TTL.
+   * Checks: `checker(role, entityName, 'view')` → boolean.
+   *
+   * To force a reload after a role change, call
+   * `handler.invalidatePermissionCache()` from your role-management code path.
+   */
+  loadPermissions: () => Promise<PermissionChecker>;
+  /**
+   * Optional auth. Resolves the calling {@link ContentApiPrincipal}, or `null`
+   * for anonymous. Absent hook, `null`, or a THROWN error all resolve to the
+   * anonymous principal on `publicRole` — failure is never partial trust.
+   *
+   * Enables preview mode (e.g. bearer token → editor sees more entities) and,
+   * because the principal carries an identity, anything that must vary per
+   * caller rather than merely per role.
+   *
+   * **A principal that carries an `id`, OR a role other than `publicRole`,
+   * forces `Cache-Control: no-store` on every entity route** so a shared CDN
+   * cannot serve one principal's response to a subsequent anonymous visitor.
+   * The two conditions are INDEPENDENT — either alone is enough — which is the
+   * part a role-keyed rule gets wrong: `{ id, role: publicRole }`, a logged-in
+   * visitor granted no extra role, is a legal principal whose `user.id` reaches
+   * every read. That is what makes a principal-varying body safe to emit at all.
+   *
+   * The converse is the exact boundary, and it is deliberate: a return of
+   * `{ role: publicRole }` with NO `id` has asserted neither an identity nor an
+   * extra grant, so nothing about the response can vary per caller and it stays
+   * publicly cacheable. Returning that shape is not a way to opt a caller into
+   * `no-store`.
+   *
+   * **Setting this makes {@link ContentApiConfig.credentialHeaders} load-bearing.**
+   * A shared cache has to know which request headers select between those two
+   * bodies, and only the host knows which ones this hook reads. Leaving them
+   * undeclared forces `no-store` on every entity response rather than storing
+   * one under an unknown key.
+   *
+   * `GET /_menu` is the one exception, and deliberately so: its resolver takes
+   * nothing principal-derived, so its body cannot vary per caller and it stays
+   * cacheable for everyone. Applying the split there would have leaked
+   * credential validity through the header shape on an endpoint with no
+   * permission gate. See `handleMenu`'s JSDoc.
+   *
+   * **Denial is not this hook's job.** A credential that verifies but whose
+   * role lacks `view` on the target is refused by the ENTITY firewall as a 404,
+   * byte-identical to the refusal a caller who presented nothing receives
+   * (D006) — so a credential can never become an oracle for which entities
+   * exist. Stated exactly, because the property is narrower than "every
+   * response": byte-identity holds for the REFUSALS on the entity routes and on
+   * `_resolve`/`_paths`/`_alternates`, which share one 404 carrying a CONSTANT
+   * `Cache-Control: no-store` and a per-request `x-request-id`. Neither weakens
+   * the property, and the distinction is worth stating because both look like
+   * they might. The directive is the same string for every caller, so it cannot
+   * signal whether a credential verified. The correlation id varies per
+   * REQUEST, not per principal — two refusals from the same caller differ in it
+   * too — so it carries no information about who asked, and it is either the
+   * caller's own value or random. `_menu` is never refused on a permission and answers every
+   * caller alike, headers included. `_schema` is never refused either; it
+   * publishes the ROLE-FILTERED view — identical to the anonymous one for a
+   * role holding no `view`, deliberately larger for a role that holds some —
+   * always under `no-store`. Return `null` for "I could not verify this
+   * caller"; do not attempt to express "verified but unauthorized".
+   */
+  authenticate?: (req: Request) => Promise<ContentApiPrincipal | null>;
+  /**
+   * The request headers {@link ContentApiConfig.authenticate} READS — i.e. the
+   * ones a shared cache must key on to tell one caller's stored response from
+   * another's. Emitted verbatim in `Vary` beside `Origin`.
+   *
+   * ```ts
+   * authenticate: async (req) => verify(req.headers.get('X-Preview-Token')),
+   * credentialHeaders: ['X-Preview-Token'],
+   * ```
+   *
+   * **Declared, because it cannot be inferred.** The hook is host-supplied and
+   * may read any header; this package parses no credential and never sees which
+   * one mattered. Hardcoding a guess (`Cookie, Authorization`) is wrong in both
+   * directions: a host reading `X-Preview-Token` gets a public response stored
+   * with nothing keyed on it, so the next request carrying only that header
+   * matches the stored variant and **`authenticate` is never called** — the CDN
+   * answers instead. (Fail-safe in disclosure terms — the PUBLIC body is what
+   * gets replayed — but "the edge silently ignores your credential" is not a
+   * property to leave to chance.)
+   *
+   * **Omitting it when `authenticate` IS set forces `Cache-Control: no-store`
+   * on every entity response.** Deliberately fail-closed: a credential can
+   * arrive, nothing says what selects it, so there is no correct variant key —
+   * and an unkeyed cacheable response is exactly the replay above. Declare the
+   * headers to get caching back.
+   *
+   * Setting it with NO `authenticate` hook throws at construction: nothing reads
+   * a credential, so the only effect would be to fragment the cache.
+   *
+   * **The trade-off you are choosing.** `Vary` values are honoured unevenly by
+   * real CDNs. Cloudflare honours only `Accept-Encoding` and will not serve a
+   * cached variant for anything else; Fastly/Varnish key on the RAW header, so
+   * `'Cookie'` collapses the hit rate for every visitor carrying an analytics or
+   * consent cookie. If your hook can read a dedicated header instead of `Cookie`
+   * — a bearer `Authorization`, or a purpose-made `X-…` — the public surface
+   * stays far more cacheable. A deployment with no `authenticate` hook declares
+   * nothing here and keeps a clean `Vary: Origin`.
+   *
+   * Each entry must be a non-empty HTTP field-name token; `*` is refused (it
+   * means "never reuse", which is `no-store` spelled obscurely). Matching is
+   * case-insensitive, per HTTP.
+   */
+  credentialHeaders?: readonly string[];
+  /**
+   * Role for unauthenticated requests. Default: `'public'`.
+   * Must have explicit 'view' permission per entity to see anything.
+   *
+   * Must be a NON-EMPTY string — `''` throws at construction. It is not a
+   * tighter default: an empty role reaches the read path as `groups: []`, which
+   * `resolveAuthContext` refuses, so the whole public surface would answer 500.
+   * Omit the option rather than passing a possibly-unset environment variable.
+   */
+  publicRole?: string;
+  /** Default content locale for translation merging. */
+  defaultLocale?: string;
+  /** CORS configuration. Required when serving cross-origin. */
+  cors?: CorsConfig;
+  /**
+   * Cache-Control header configuration. Applied to ANONYMOUS-caller responses
+   * only — a resolved principal short-circuits to `no-store` and ignores this
+   * entirely. `GET /_menu` is the exception: its body is principal-invariant, so
+   * it applies for every caller (under the reserved `_menu` key).
+   */
+  cache?: CacheConfig;
+  /**
+   * Max pagination limit. Default: 100. Hard-capped at 100.
+   *
+   * Configurable DOWNWARD only. A `?limit=` above the effective ceiling is a
+   * 400 `VALIDATION_ERROR`, never a silent clamp (D007).
+   */
+  maxLimit?: number;
+  /**
+   * Max pagination offset. Default: 1000. Hard-capped at 1000.
+   *
+   * Configurable DOWNWARD only, exactly like {@link maxLimit}. A `?offset=`
+   * above the effective ceiling is a 400 `VALIDATION_ERROR` naming `?cursor=`
+   * as the supported deep-paging path — never a silent clamp, which would
+   * leave a deep-paging client re-reading the same page forever (D007).
+   *
+   * Bounds a full traversal of the MATCHING set per request: the read path
+   * issues a plain SQL `OFFSET`, so the work is `O(min(offset, matching rows))`
+   * — cheap on a small collection, real on a large one, from a caller who is
+   * unauthenticated by default.
+   */
+  maxOffset?: number;
+  /**
+   * Ceiling on the total resolutions ONE response may trigger, spanning
+   * reference projections, `?populate=` expansions, media and block-tree
+   * resolution (plan/api phase 05).
+   *
+   * Default and hard cap: `MAX_RESOLUTIONS_PER_DOCUMENT` (200). Configurable
+   * DOWNWARD only, like {@link maxLimit} / {@link maxOffset}.
+   *
+   * **ONE budget, not one per kind.** All four kinds of work scale with the
+   * DOCUMENT's own content — which an editor controls, not an operator — and
+   * all four draw on the same connection pool. Four separate ceilings would let
+   * a single document sum them into a much larger draw, which is the "it's only
+   * N today" defence CLAUDE.md's No-Unbounded-Fan-Out section refuses.
+   *
+   * **Exceeding it is not an error.** The response renders with the excess
+   * targets unresolved — indistinguishable on the wire from deleted or
+   * unviewable ones, per phase 05's failure semantics — and the drop is logged
+   * at `warn` with a per-kind breakdown. That log is the ONLY place the
+   * distinction survives, which is what makes it load-bearing rather than
+   * diagnostic.
+   *
+   * `0` is accepted and coherent: "resolve nothing on this deployment". A
+   * negative or non-integer value throws at construction.
+   */
+  maxResolutionsPerDocument?: number;
+  /**
+   * Host-injected routing seam: an entity id → its current canonical href.
+   *
+   * Supplies the `href` on every reference projection (D013). Omit and
+   * references still resolve — they just carry `href: null`, so a consumer gets
+   * a label it cannot link.
+   *
+   * **Wire the SAME implementation you give `resolveLinks`.** D013's reason for
+   * routing both through one seam is that a reference and a link to the same
+   * document must produce the same URL BY CONSTRUCTION, rather than by two
+   * implementations agreeing. In this repo that implementation reads the
+   * materialized `toolkit_paths` index (`getCanonicalPath`), so a href survives
+   * slug and parent renames.
+   *
+   * **This seam needs no publish filter, and that is a property rather than an
+   * omission.** It is only ever called with ids that already came back from a
+   * published-only `QueryClient` read, so an unpublished target never reaches
+   * it. The same seam wired into `resolveLinks` resolves arbitrary
+   * editor-authored targets and DOES need one.
+   *
+   * A throw is caught and degrades that one reference to `href: null` — a
+   * broken routing lookup must not 500 every page carrying a reference.
+   */
+  resolveEntityHref?: ResolveEntityHref;
+  /**
+   * Host-injected media resolver: media ids → {@link MediaProjection}s
+   * (plan/api phase 06, D021).
+   *
+   * A `media()` field stores a bare uuid, and no endpoint anywhere in the
+   * toolkit accepts one — so without this, CMS images cannot be rendered by a
+   * database-less frontend at all. Wire
+   * `createPublicMediaResolver()` from `@murumets-ee/media/public`; injected
+   * rather than imported because `content-api` is a leaf.
+   *
+   * **SECURITY (CLAUDE.md #1) — the provider MUST NEVER return a signed URL.**
+   * A signed URL is a bearer capability: it grants access to whoever holds it,
+   * for its lifetime, regardless of who they are. Public-role responses on this
+   * surface are deliberately cacheable (`public, max-age=60,
+   * stale-while-revalidate=300`), so one embedded in a response is stored by any
+   * shared CDN and replayed verbatim to every later anonymous visitor. The cache
+   * would be behaving correctly; the payload was wrong.
+   *
+   * That is why the shipped resolver ASKS storage for a public url
+   * (`getPublicUrls`) rather than asking for "a url" and inspecting what came
+   * back — the second shape produces a signed URL on the happy path and leans
+   * on a later check to suppress it. Storage also defaults files to `private`,
+   * so the safe behaviour has to be the one that happens when nobody configures
+   * anything. If you write your own provider, preserve that property; this
+   * package cannot enforce it.
+   *
+   * **The read must be PUBLISHED-only** — a `QueryClient` read, never an
+   * `AdminClient` one, for the same reason `ContentApiResolution.resolvePath`
+   * must be the published resolver.
+   *
+   * **OPERATOR NOTE — this needs a THIRD grant, and it is easy to miss.**
+   * Reading through `QueryClient` runs the entity firewall, so the requesting
+   * role needs `media:view` — even though `Media` is deliberately NOT in
+   * {@link ContentApiConfig.entities} (serving it as a plain entity would
+   * expose `fileKey`, which is exactly what this projection avoids). Without
+   * the grant the read throws, every media field on the site resolves to
+   * `null`, and the response cannot say why. Grant `media:view` to the public
+   * role alongside whatever content entities you exposed; the handler logs the
+   * failure at `warn` so it is greppable.
+   *
+   * Ids that do not exist, are unpublished for this caller, or whose file is
+   * not public must be ABSENT from the returned map. The handler turns absence
+   * into `null`, indistinguishable from every other unresolvable target.
+   *
+   * **Omitting this does not fall back to the stored uuid.** Every media field
+   * resolves to `null` instead. A uuid is not a weaker answer here, it is an
+   * unusable one, and letting the wire TYPE vary per deployment is exactly the
+   * unfalsifiable claim `_schema` exists to prevent.
+   */
+  resolveMedia?: ResolveMedia;
+  /**
+   * Host-injected `blockTree()` resolver (plan/api phase 05).
+   *
+   * A block tree embeds internal links, `query()` fields and media refs — the
+   * three resolution paths `@murumets-ee/blocks` already implements
+   * server-side. This is the seam that runs them on the REQUEST path, under the
+   * response's ONE resolution budget, which is handed to the provider so its
+   * claims land in the same counter (and the same drop log) as the reference
+   * and media passes.
+   *
+   * **SECURITY (CLAUDE.md #1).** Every read the provider performs must be
+   * PUBLISHED-only and permission-honouring: a `query()` field resolved through
+   * an `AdminClient` would surface drafts anonymously, and an internal link
+   * resolved without a publish filter would leak an unpublished document's URL.
+   * This package cannot enforce either — the resolver is injected — so the
+   * WIRING must guarantee both, exactly as for
+   * {@link ContentApiResolution.resolvePath}.
+   *
+   * **Omitting it leaves the stored tree UNCHANGED**, which is the opposite of
+   * {@link resolveMedia}'s behaviour and deliberately so: a media uuid is
+   * unusable to any consumer, while a block tree is the document's actual
+   * content and renders perfectly well with its links unresolved — that is what
+   * the in-process renderers already emit as plain text. Nulling it would
+   * delete the page to avoid an unresolved href.
+   */
+  resolveBlocks?: ResolveBlocks;
+  /**
+   * Routing resolution providers (routing PR07). When present, the handler
+   * serves `GET /_resolve`, `/_paths`, `/_alternates`; omit and those endpoints
+   * stay 404 (opt-in — deny-by-default). Injected (not imported) so this stays a
+   * leaf package — see {@link ContentApiResolution}.
+   */
+  resolution?: ContentApiResolution;
+  /**
+   * Menu provider (routing PR09). When present, the handler serves
+   * `GET /_menu`; omit and it stays 404 (opt-in — deny-by-default). Injected
+   * (not imported) so this stays a leaf package — see {@link ContentApiMenus},
+   * which also documents why its `handles` allowlist is the endpoint's ONLY
+   * gate.
+   */
+  menus?: ContentApiMenus;
+  /**
+   * Form submissions (forms plan D003/D004). When present, the handler serves
+   * `GET /_forms/:id/token` and `POST /_forms/:id/submissions` — to a caller
+   * whose site KEY names the site, and nobody else; omit and both stay 404
+   * (opt-in — deny-by-default). Injected (not imported) so this stays a leaf
+   * package — wire `createFormsContentApi` from `@murumets-ee/forms/server`.
+   */
+  forms?: ContentApiForms;
+  /**
+   * Visitor consent. When present, the handler serves `GET /_consent` (the
+   * site's public consent config for one locale) and `POST /_consent` (records
+   * one visitor's choice and answers with the signed cookie the front sets on
+   * its own origin) — to a caller whose site KEY names the site, and nobody
+   * else; omit and both stay 404 (opt-in — deny-by-default). Injected (not
+   * imported) so this stays a leaf package — wire `createConsentContentApi`
+   * from `@murumets-ee/consent/server`.
+   */
+  consent?: ContentApiConsent;
+  /**
+   * Site-chrome provider (plan/api phase 07). When present, the handler serves
+   * `GET /_chrome`; omit and it stays 404 (opt-in — deny-by-default). Injected
+   * (not imported) so this stays a leaf package — see {@link ContentApiChrome},
+   * which documents the TWO independent gates and why the entity's own `access`
+   * map is not one of them.
+   */
+  chrome?: ContentApiChrome;
+  /**
+   * i18n resolver for `GET /_site` (plan `multisite` D007). Optional: without
+   * it the endpoint answers from the site's registry row and this mount's
+   * `defaultLocale`. See {@link ContentApiSiteProvider}.
+   */
+  site?: ContentApiSiteProvider;
+  /**
+   * OPT-IN: the site an ANONYMOUS request reads, by the `Host` it was sent to
+   * (plan `multisite` D008) — for a frontend that fetches from the browser and
+   * so cannot hold a key. Keys are host names (`kulli.ee`, with a port if the
+   * API is reached on one), values are site handles.
+   *
+   * Omitted — the default — a request with no site-bound credential has no
+   * site on an app serving several, and every site-bound read answers 404.
+   *
+   * **Listing a host here publishes that site to anyone who can send that
+   * `Host`.** That is the same audience its frontend already serves; it is not
+   * a way to keep a site private. A credential's site always wins over it, and
+   * the mapped site is still checked against the registry (a disabled site is
+   * not served). A value that is not a site handle throws at construction.
+   */
+  siteForHost?: Readonly<Record<string, string>>;
+  /**
+   * Detail-template provider (block-library D009). An entity that declares
+   * `frontend: { drawnBy: 'template' }` is served by `GET /:entity/:id` only,
+   * NARROWED to its id plus what this provider projects, with the entity type's
+   * published template resolved against the row under `_template`.
+   *
+   * Omit it and such a row crosses as `{ id }` — deny by default, never the
+   * row's columns. Injected (not imported) so this stays a leaf package; see
+   * {@link ContentApiDetailTemplates}.
+   */
+  detailTemplates?: ContentApiDetailTemplates;
+  /**
+   * The MONITORING seam — attach an error tracker or a metrics counter here.
+   *
+   * **It is not a logging seam, and wiring it as one is the mistake it used to
+   * invite.** The handler already logs every error it produces, with the `err`
+   * object, so pino's serializer emits a stack. Both production mounts used to
+   * re-log the same event from here with strictly less information, because
+   * nothing said what else the hook was for. It exists because
+   * `@murumets-ee/logging`'s root logger deliberately ships NO pino transports
+   * (they use worker threads that break webpack/turbopack), so a host has no
+   * in-band way to attach Sentry / OTel / a counter to the log stream. This
+   * hook is that route, and it is the only one.
+   *
+   * Fires for EVERY error response, not just 500 — a 400/404 rate is the point,
+   * and the 404s especially: denial and absence are the same response (D006),
+   * so without this an operator has no signal that a consumer is being refused
+   * at all.
+   *
+   * Fire-and-forget: the handler does not await it, and a hook that throws or
+   * rejects is contained rather than allowed to turn a 404 into a 500.
+   *
+   * **Keep it non-blocking and bounded.** It runs once per error response, so
+   * an integration doing synchronous per-call I/O has put an unbounded fan-out
+   * on the error path — exactly the shape CLAUDE.md forbids, and much cheaper
+   * to state here than to discover under load.
+   */
+  onError?: (err: ContentApiErrorReport) => void | Promise<void>;
+  /**
+   * TUNING for the availability guard (D025). Optional in full.
+   *
+   * **Its absence does not disable anything.** The survival half — the
+   * concurrency semaphore, its bounded wait queue, and the per-request wall
+   * clock — is keyless by construction and always on, precisely so no host can
+   * lose it by omission. This field only moves numbers that already have
+   * defaults, plus supplies the one thing the package genuinely cannot know:
+   * {@link ContentApiLimits.getClientIp}, without which anonymous traffic has no
+   * distinguishing key and the FAIRNESS half is skipped rather than collapsed
+   * onto one shared bucket.
+   */
+  limits?: ContentApiLimits;
+  /**
+   * TUNING for the visitor search's per-visitor budget (`GET /_search`,
+   * davatoidud-toolkit D001). Optional in full — the limit is on by default.
+   *
+   * Which types a site searches is NOT here: it is the site's own
+   * `searchTypes` (the Sites page), so a mount serving several sites cannot
+   * give one site another's choice.
+   */
+  search?: ContentApiSearchConfig;
+}
+/**
+ * What the monitoring seam receives: DERIVED FACTS ONLY.
+ *
+ * Never the raw error, never the `Request`, never a credential — and note the
+ * absence of `message`, which this payload used to carry straight from a caught
+ * exception. A driver-level message can contain query fragments and values, so
+ * the log stream is more sensitive than the response (D034); a monitoring
+ * payload LEAVES THE PROCESS, and the operator's log is where the detail
+ * belongs.
+ */
+interface ContentApiErrorReport {
+  /** HTTP status of the response that was sent. */
+  status: number;
+  /** The machine-readable code from the error envelope — one of `ERROR_CODES`. */
+  code: ContentApiErrorCode;
+  /** Request pathname. */
+  path: string;
+  /** The RESOLVED entity name, when the request got far enough to name one. */
+  entity?: string;
+  /** Correlation id — the same value echoed to the caller and bound to the logs (D032). */
+  requestId: string;
+  /** The resolved principal's id, when the request got far enough to resolve one. */
+  principalId?: string;
+}
+/**
+ * The cache-tag contract (D055) — see {@link SchemaResponse.cacheTags}.
+ *
+ * Every value here is DERIVED from the same resolved configuration the emitter
+ * uses, never restated: a published grammar that disagrees with the emitted one
+ * would be an unfalsifiable claim, which is exactly what `_schema` exists to
+ * prevent.
+ */
+interface SchemaCacheTags {
+  /** The response header carrying the tags — e.g. `Cache-Tag`. */
+  header: string;
+  /** What joins tags inside that header — `,` or a single space. */
+  separator: string;
+  /**
+   * Template for a tag naming ONE row whose content is in the body.
+   * `{entity}` and `{id}` are the substitutions.
+   */
+  document: string;
+  /**
+   * Template for a tag naming the SET of an entity's rows — emitted on every
+   * read except the one addressed by primary key.
+   *
+   * **SEND THIS ON EVERY WRITE TO THE ENTITY, not only on create and delete.**
+   * An earlier draft of this sentence said create/delete, on the reasoning that
+   * only those change which rows exist. That is wrong for any filtered or
+   * sorted list: publishing a draft is an UPDATE, and the row it updates was by
+   * definition not on the cached `?filter[status]=published` page, so its
+   * document tag was never on that response either. The safe rule is one rule —
+   * a write to entity `E` purges `lumi:E` and `lumi:E:<id>` together.
+   */
+  collection: string;
+  /**
+   * What fills `{site}` for a row that belongs to NO site — a shared entity
+   * such as media — on an app serving several sites (plan `multisite` D008);
+   * `null` on a single-site install, whose templates have no `{site}` at all.
+   *
+   * A row of a site-bound entity carries the handle of the site the response
+   * was served for. So a write to a bound row purges that site's tags only,
+   * and a write to a shared row purges ONE tag that every site's responses
+   * carry.
+   */
+  sharedSite: string | null;
+  /** Per-tag character ceiling; a longer tag is dropped, never truncated. */
+  maxTagLength: number;
+  /**
+   * Per-response tag ceiling. Beyond it tags are dropped from the TAIL and the
+   * drop is logged — so a response at the ceiling may name fewer documents than
+   * it actually composed.
+   */
+  maxTagsPerResponse: number;
+  /**
+   * Ceiling on the assembled header in bytes — a THIRD bound, which the other
+   * two do not imply (128 × 128 plus separators overshoots it). Tags are
+   * dropped from the tail to stay inside it.
+   */
+  maxHeaderBytes: number;
+  /**
+   * What the tags on a response are guaranteed NOT to cover, so a consumer can
+   * size its own TTL for the gap rather than assume completeness (D055 §8).
+   *
+   * - `menuTargets` — a resolved menu item carries no entity identity, so
+   *   `_menu` names only the menu itself; a linked page's rename is invisible.
+   * - `crossEntityPathChanges` — `_resolve` and `_alternates` tag the entity
+   *   that answered. A document of a DIFFERENT entity taking over a path is not
+   *   covered, because there is no tag on the response that names it.
+   * - `mediaVariantStyles` — a `MediaProjection.variants` map is keyed by image
+   *   STYLE name, and the variant url embeds both that name and the style's
+   *   output format (`deriveVariantKey(fileKey, styleName, format)`). Image
+   *   styles are operator data in the settings DB, editable at runtime through
+   *   the admin UI, and renaming one or changing its format writes NO media
+   *   row — so `lumi:media:<id>` is never purged and a cached `variants` map
+   *   keeps keys and urls that no longer exist. See #852.
+   * - `outOfBandPathChanges` — a document's canonical path lives in the
+   *   `toolkit_paths` index, not on its row, and three writers move it without
+   *   touching the row: the ancestor-rename cascade, `paths:rebuild`, and a
+   *   `frontend.path` pattern change. All three go through `applyCanonicalPath`
+   *   against a `TableClient`, and only `AdminClient` emits a write event — so
+   *   a `ReferenceProjection.href` can go stale with nothing on the response
+   *   naming the cause. The ancestor cascade is ordinary editorial activity,
+   *   not a deploy, which is what puts this in the same class as `menuTargets`.
+   *   See #852.
+   *
+   * `blockTreeContents` USED to be here and no longer is. It was structural at
+   * the time — the block provider returned an opaque `unknown` — and stopped
+   * being so once `ResolvedBlockTree` gained a `refs` list (`BlockTreeRef`,
+   * exported from this package's root): every media id and link target a tree
+   * resolved is now named on the response. Removing an entry NARROWS what a
+   * consumer must widen its TTL for, so it is a behaviour improvement rather
+   * than a breaking change to the grammar.
+   *
+   * 🔴 **Two things "covered" does NOT mean, stated because a consumer sizes a
+   * TTL against this list and neither is visible from it.**
+   *
+   * 1. Block refs are subject to the SAME per-response ceiling as every other
+   *    tag ({@link SchemaCacheTags.maxTagsPerResponse}), and on a LIST read
+   *    they are added last — after the collection tag and one document tag per
+   *    item. A `?limit=100` page of documents that each embed an image spends
+   *    the budget before the refs are reached, so in practice a full list names
+   *    few of them or none. Drops are logged server-side; nothing on the wire
+   *    distinguishes "named everything" from "named what fitted".
+   * 2. The tags name what the provider actually RESOLVED, and several classes
+   *    are deliberately not resolved and therefore not named — a value that
+   *    looks like a media ref but carries an unrecognised key or a mistyped
+   *    optional (left alone, with its stored url), a subtree below the
+   *    resolver's media walk bound, a link below its link walk bound, and
+   *    anything the response's resolution budget refused.
+   *
+   *    🔴 One of those is worth calling out, because the two indexes now
+   *    DISAGREE about it. The entity-side reference index deliberately matches
+   *    a media ref whose optional field is mistyped — under-matching there
+   *    deletes a live asset — while this resolver deliberately declines it,
+   *    because over-matching HERE replaces a project's own prop with `null`.
+   *    Both are right for their own failure direction, and the consequence is
+   *    real: such an asset is delete-protected and its page is not tagged with
+   *    it, so re-publishing that image evicts nothing.
+   */
+  uncovered: readonly ('menuTargets' | 'crossEntityPathChanges' | 'mediaVariantStyles' | 'outOfBandPathChanges')[];
+}
+//#endregion
+//#region src/handler.d.ts
+/**
+ * The API version this instance mounts. Every route is served under it and
+ * ONLY under it — `/v1/article`, `/v1/_schema`. There is no unprefixed mount,
+ * no deprecation marker, no `Link` successor header (D010): no consumer
+ * predates the prefix, so there is nothing to transition.
+ *
+ * **What `v1` means.** Adding an endpoint, an entity, an error code, a `meta`
+ * field, or an OPTIONAL query parameter is additive and stays inside v1.
+ * CHANGING or REMOVING any of them — a field's type, an endpoint's shape, a
+ * default, a previously-optional param becoming required — is a v2. `GET
+ * /v1/_schema` publishes the version this instance mounts, so a client can
+ * assert against it rather than infer it from the URL it happened to be given.
+ *
+ * The version is consumed by the HANDLER, not by the mount. The app mounts one
+ * catch-all whose only job is to hand over an ordered array of path segments,
+ * so a consuming app needs no edit at all, and the package that owns the
+ * contract is the one that enforces and introspects it — rather than whichever
+ * framework the app happens to route with.
+ */
+declare const API_VERSION = "v1";
+declare function createContentApiHandler(config: ContentApiConfig): {
+  GET: (req: Request, ctx: RouteContext) => Promise<Response>;
+  /**
+   * The two write routes: `POST /_forms/:id/submissions` (forms D003) and
+   * `POST /_consent` — a 404 for every other path, and for each of those too
+   * unless its provider (`forms` / `consent`) is wired. A post goes through
+   * the SAME dispatch as a read: the survival guard, the site from the key,
+   * the fairness limit and the request context.
+   */
+  POST: (req: Request, ctx: RouteContext) => Promise<Response>;
+  OPTIONS: (req: Request) => Promise<Response>;
+  /**
+   * Invalidate the cached permission checker. Call this from the
+   * role-management code path (after a role is created/edited/deleted)
+   * so the next request re-runs `loadPermissions()` instead of waiting
+   * up to 30 seconds for the TTL to expire.
+   */
+  invalidatePermissionCache: () => void;
+};
+//#endregion
+export { API_VERSION, type BlockTreeRef, CACHE_TAG_NAMESPACE, type CacheTagsConfig, type ContentApiChrome, type ContentApiChromeRegion, type ContentApiChromeRegions, type ContentApiConfig, type ContentApiConsent, type ContentApiConsentCookie, type ContentApiConsentRecordResult, type ContentApiConsentState, type ContentApiDetailTemplates, type ContentApiErrorCode, type ContentApiErrorReport, type ContentApiFormSubmitResult, type ContentApiFormTicket, type ContentApiForms, type ContentApiMenus, type ContentApiPrincipal, type ContentApiResolution, type ContentApiResolvedMenu, type ContentApiResolvedMenuItem, type ContentApiSearchConfig, type ContentApiSite, type ContentApiSiteProvider, type ContentPathEntry, type ContentResolveResult, DEFAULT_SEARCH_RESULTS, DETAIL_TEMPLATE_FIELD, ERROR_CODES, MAX_CACHE_TAGS_PER_RESPONSE, MAX_CACHE_TAG_HEADER_BYTES, MAX_CACHE_TAG_LENGTH, MAX_CONSENT_BODY_BYTES, MAX_FORM_BODY_BYTES, MAX_RESOLUTIONS_PER_DOCUMENT, MAX_SEARCH_RESULTS, MEDIA_TAG_ENTITY, type MediaProjection, type MediaSource, type ReferenceProjection, type ResolutionBudget, type ResolutionKind, type ResolveBlocks, type ResolveEntityHref, type ResolveMedia, type ResolvedBlockTree, SHARED_SITE_TAG_SEGMENT, type SchemaCacheTags, type SearchHit, type UnresolvedBlockRef, VISITOR_ADDRESS_HEADER, createContentApiHandler, isResolvedBlockTree };
+//# sourceMappingURL=index.d.mts.map