configSchema.js

/**
 * The configuration schema: the single source of truth for every option the plugin
 * understands. Each option declares its default, a description, and how a change takes
 * effect — everything `config.js` (defaults, merge validation, redaction, restart
 * warnings) and the management API (a machine-readable schema for the admin UI) derive
 * from.
 *
 * Field reference for `option(default, description, extra)`:
 *   scope     'live' (default) — a change via the host's options `change` event takes
 *             effect without a restart (per request, per timer tick, or on the next
 *             scheduled cycle). 'restart' — the value is consumed once at worker boot;
 *             a live change is reported as pending-restart and otherwise ignored.
 *             Groups may set a scope their children inherit.
 *   secret    true — the value is redacted to a presence marker wherever config is
 *             read back (management API, logs).
 *   enum      Allowed values; anything else is rejected at apply time (default kept).
 *   unit      Display/documentation hint ('ms', 'percent'). No behavioral effect.
 *   min/max   Numeric bounds enforced at apply time (violation keeps the default).
 *   nonEmpty  true — an empty string/array is rejected at apply time (default kept).
 *             Reserved for values where empty is catastrophic rather than unwise.
 *   itemType  Display hint for array options ('string' | 'object').
 *   items     { integer?, min?, max?, not? } — a rule every entry of a list of NUMBERS must meet.
 *             A list with one entry breaking it is rejected whole at apply time (default
 *             kept), like `itemEnum`, and for the same reason: it is for lists where a
 *             rogue entry does harm rather than nothing.
 *   uiEditable
 *             false — the console must refuse to write this option, and says so instead of
 *             offering a control. Inherited by a group's children, like `scope`. Reserved for
 *             options whose own edit would remove the ability to edit (`management.enabled`
 *             locks the console out; the `management.overrides` group is the machinery the
 *             console writes THROUGH). `secret: true` implies it — a secret comes from its
 *             environment variable, so there is nothing for a form to set.
 *   movedFrom Dotted path this option (or group) lived at before the v0.25.0
 *             reorganization. The old path still applies with a deprecation warning.
 *
 * Descriptions are user-facing documentation: they are served by the management API and
 * will back the admin UI's config editor. Write them for an operator, not a code reader.
 */

const SECOND = 1000;
const MINUTE = 60 * SECOND;
const HOUR = 60 * MINUTE;
const DAY = 24 * HOUR;

const OPTION = Symbol('option');
const GROUP = Symbol('group');

const option = (defaultValue, description, extra = {}) => ({
	[OPTION]: true,
	default: defaultValue,
	description,
	...extra,
});

const group = (description, children, extra = {}) => ({
	[GROUP]: true,
	description,
	children,
	...extra,
});

export const isOption = (node) => !!node?.[OPTION];
export const isGroup = (node) => !!node?.[GROUP];

// The device-appropriate browser UAs Harper's own origin fetches present (the origin may serve
// device-specific HTML off them). Each kind of fetch appends its own product token, so the origin's
// logs can tell the miss proxy (`HarperProxy`) from the change probe (`HarperProbe`).
const DEVICE_BROWSER_UAS = {
	mobile:
		'Mozilla/5.0 (Linux; Android 11; Pixel 5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/W.X.Y.Z Mobile Safari/537.36',
	tablet:
		'Mozilla/5.0 (Linux; Android 7.0; Pixel C Build/NRD90M; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/52.0.2743.98 Safari/537.36',
	desktop:
		'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/W.X.Y.Z Safari/537.36',
};
const PROXY_TOKEN = 'HarperProxy/1.0';
const PROBE_TOKEN = 'HarperProbe/1.0';

// Database/table names are fixed (defined statically in src/schemas/schema.graphql).
// Tables are split across databases by write-transaction coupling so the hot queue
// (render_schedule) is isolated from target, page-cache, and sitemap writes.
export const configSchema = group('Prerender plugin configuration.', {
	domains: option(
		[],
		'Allowlist of hostnames considered indexable. Pages on other hosts are rendered but ' +
			'never marked indexable/cached. Empty = allow all.\n\n' +
			'Also the hosts a SITEMAP fetch may send `origin.securityToken` to (and pin to ' +
			'`origin.staging.ip`), beside the root sitemap\u2019s own host — re-decided on every redirect ' +
			'hop. A child sitemap on another host of this deployment needs listing here; empty trusts only ' +
			'the root\u2019s host.',
		{ itemType: 'string' }
	),

	ingress: group(
		'Request-ingestion model: how incoming bot requests are recognized, which paths are ' +
			'prerendered, and how the target URL and device type are derived.\n\n' +
			"mode 'prefix' — native model: bot requests arrive at `${botPathPrefix}<absolute-url>` " +
			'and the device type comes from a header (`deviceTypeHeader`).\n' +
			"mode 'forwarded' — reverse-proxy / CDN model: the proxy routes a restricted set of " +
			'paths to the plugin. The device type is the first path segment, the target URL is ' +
			'reconstructed from the forwarded host/proto headers, and `routes` both identifies ' +
			"which requests are prerender requests and sets each route's query-param allowlist.",
		{
			mode: option('prefix', "Request-ingestion model: 'prefix' (native) or 'forwarded' (reverse-proxy / CDN).", {
				enum: ['prefix', 'forwarded'],
			}),
			botPathPrefix: option(
				'/p/',
				'Requests whose path starts with this prefix are treated as bot prerender requests ' +
					'(e.g. `/p/<absolute-url>`). Prefix mode only.',
				{ movedFrom: 'botPathPrefix', nonEmpty: true }
			),
			deviceTypeSource: option(
				'header',
				"Where the device type comes from in forwarded mode: 'path' (first path segment, " +
					"consumed when it is a supported device type) or 'header'.",
				{ enum: ['path', 'header'] }
			),
			deviceTypeHeader: option('x-device-type', 'Request header carrying the device type.'),
			forwardedHostHeader: option('x-forwarded-host', 'Header carrying the original public host (forwarded mode).'),
			forwardedProtoHeader: option('x-forwarded-proto', 'Header carrying the original public scheme (forwarded mode).'),
			defaultProtocol: option('https', 'Scheme assumed when the forwarded-proto header is absent.', {
				enum: ['https', 'http'],
			}),
			routes: option(
				[],
				'Ordered route list (forwarded mode). Each entry is ' +
					"{ match: 'exact' | 'prefix' | 'contains', path: string, mode?: 'prerender' | 'passthrough', " +
					'queryParams?: string[], renderInterval?: number, discoverTargets?: boolean, demandFloor?: number, ' +
					"departureAction?: 'none' | 'expire' | 'render', arrivalAction?: 'none' | 'render', " +
					'rawCache?: boolean, rawFacts?: boolean | string[], documentCheck?: boolean | string[], ' +
					'negativeCache?: boolean, entityPrefix?: string, entityServe?: boolean }.\n\n' +
					'FIRST MATCH WINS, so order most-specific first. That ordering is what lets a passthrough ' +
					'carve-out sit inside a prerendered prefix (`/products/clearance/` above `/products/`) ' +
					'without a second list and a precedence rule.\n\n' +
					"`mode` (default 'prerender') decides the class:\n" +
					'  prerender — cache it, schedule it, serve it from cache. `queryParams` is its cache-key / ' +
					"origin-fetch query allowlist (same semantics as `cacheKey.queryParams`: ['*'] keeps all, " +
					'[] drops all).\n' +
					'  passthrough — proxy it live, never cache or schedule it, and don’t report it. A declaration ' +
					'that the CDN forwards this path and we have chosen not to prerender it. `queryParams` is ' +
					'REJECTED here: with no cache there is no key for it to shape, so it could only strip params ' +
					'off the proxied origin fetch and hand the visitor the wrong page.\n\n' +
					"A path matching NOTHING is 'unclassified': still proxied (never blocked), never cached, and " +
					'counted for reporting so the gap can be fixed at the CDN or here.\n\n' +
					'`renderInterval` (ms, prerender routes only) sets the render cadence for every URL the route ' +
					"matches. Precedence: route > the target's stored interval (sitemap `<changefreq>` or an " +
					'explicit API write) > `render.defaultInterval` — resolved at schedule time on every cycle, so ' +
					"changing it here takes effect on each URL's next render with no data migration. A per-URL " +
					'exception is an `exact` route ordered above its class (e.g. the homepage `exact /` at 2h above ' +
					'a 6h section prefix); a route that should defer to sitemap changefreq simply doesn’t set one.\n\n' +
					"OPERATIONAL NOTE: if the CDN edge-caches a route's responses with a fixed TTL from its own " +
					"property settings (not from our response headers), that TTL and the route's renderInterval " +
					'must be kept aligned BY HAND — rendering much faster than the edge TTL burns renders the edge ' +
					'never serves, and much slower means the edge re-fetches stale content. Neither side can see ' +
					'the other drift.\n\n' +
					'`demandFloor` (ms, prerender routes only) — the FASTEST cadence the demand ladder ' +
					"(`render.demand`) may grant this route's pages: rungs faster than the floor are unreachable " +
					'for them. This is how a deployment keeps fast global rungs for a corpus that earns them ' +
					'(listing pages that churn intraday) without a breadth-sweeping crawler promoting a much ' +
					'larger corpus onto the same rungs — a crawler that recrawls EVERYTHING daily makes ' +
					'"visited" true everywhere, and without a floor the ladder would grant the whole route the ' +
					'fast cadence at corpus scale. A floor at or above the granted cadence leaves the route ' +
					'resting at that cadence (single-rung). Stored rungs below a newly-raised floor read as the ' +
					'floor immediately and re-stamp on their next ladder decision. Live, like renderInterval.\n\n' +
					"`departureAction` (default 'none', prerender routes only) — what happens when a URL on " +
					'this route LEAVES the sitemap that listed it. A refresh unlinks such a target ' +
					'(`sitemapUrl -> null`) and leaves it rendering on its own cadence, which is the right ' +
					'default for a URL that merely stopped being declared. On a retail catalog it is not: a ' +
					'product that sells out or is withdrawn leaves the product sitemap the same day, while its ' +
					'page keeps serving the snapshot taken when it was still available.\n' +
					'  none    — the pre-0.68.0 behaviour. Unlink and nothing else.\n' +
					'  expire  — hard-expire the cached pages (past `page.swrTtl`, so they stop serving rather ' +
					'than serving stale) and let the URL re-render on its own cadence. Bots fall through to the ' +
					'origin in the meantime, which is correct but is origin load.\n' +
					'  render  — hard-expire AND file the URL to render at the current minute, so one render ' +
					'restores a correct page. This is the usual choice.\n' +
					'Departure is a statement about the DECLARATION, not the page: the origin typically still ' +
					'serves the URL with out-of-stock markup, so this is a RE-CHECK and the render’s own verdict ' +
					'decides what follows — a page that is merely unavailable re-renders and stays, and one the ' +
					'origin has actually retired answers 404/410 and is retired by the suppression path. Set it ' +
					'only on routes where departure carries that meaning: a product URL leaving a product ' +
					'sitemap says something about that product, while a listing URL leaving a paginated sitemap ' +
					'usually means the catalog was re-bucketed, and acting on it would expire current pages. ' +
					'Bounded and observable by `sitemap.departure`.\n\n' +
					"`arrivalAction` (default 'none', prerender routes only) — the other half: what happens when a " +
					'URL on this route REJOINS a sitemap after an earlier walk unlinked it. On the same retail ' +
					'catalog a product comes back to the sitemap the day it is restocked, and its cached page — ' +
					'last rendered while it was unavailable — keeps serving out-of-stock markup until its next ' +
					'cadence render.\n' +
					'  none    — re-attribute and nothing else, as before.\n' +
					'  render  — hard-expire the cached pages and file the URL to render at the current minute: ' +
					'the departure `render` action, through the same code.\n' +
					'A rejoin is told from a paginated sitemap\u2019s boundary shear (a URL moving to a later child ' +
					'is unlinked and re-attached inside ONE walk) by `Target.unlistedAt`, which the unlinking walk ' +
					'stamps with its own start — only a stamp from an earlier walk counts. Targets unlinked before ' +
					'v0.89.0 carry no stamp, so their rejoin is not seen. Bounded and observable by ' +
					'`sitemap.arrival`.\n\n' +
					'`discoverTargets` (default true, prerender routes only) — whether a bot visiting an UNKNOWN ' +
					'URL on this route creates a target for it. Set false on routes whose URL space is ' +
					'combinatorial (faceted navigation, filter/sort permutations): crawlers walking those links ' +
					'mint every novel combination into permanent render load, and the corpus grows without bound. ' +
					'Gated URLs are still served (origin proxy on a miss) — they just never enter the render ' +
					'rotation; the sitemap pipeline is unaffected, so declared URLs on the route still schedule. ' +
					'NOTE: flipping this false stops NEW targets only. Existing discovered targets keep rendering ' +
					'until deleted — see the discovery-purge admin action, and gate BEFORE purging or crawlers ' +
					're-mint what the purge removes.\n\n' +
					'`rawCache` (default false, prerender routes only, requires `render.raw.enabled`) — whether a ' +
					'MISS on this route stores the origin document it just fetched, so the next crawler asking ' +
					'for that URL is a cache hit instead of another origin round trip. It replaces an origin ' +
					'proxy, never a render: a stale or invalidated snapshot still proxies live. Pair it with ' +
					'`discoverTargets: false` — gated URLs are exactly the population this is for, and gating ' +
					'without it leaves them missing on every request forever. Enable it only on a route whose ' +
					'server-rendered document already carries its SEO surface; see `render.raw`.\n\n' +
					'`rawFacts` (default off; only meaningful with `rawCache`) — the page facts to read off each document ' +
					'as it is stored and keep beside it (`RawPage.facts`), so a stored document can be compared with the ' +
					'origin without reading its body: `true` for every head fact (title, metaDescription, canonical, ' +
					'product, breadcrumbs), or an array naming them, plus `itemList` for a listing page’s products. ' +
					'The scan stops once it has what was named, so name only what will be compared: on a template ' +
					'whose head is mostly inline CSS, `[title, metaDescription, canonical]` reads ~1 KB where `true` ' +
					'reads the whole head. Costs tens of microseconds per stored document, after the response.\n\n' +
					'`documentCheck` (default off; requires `changeProbe.serveCheck`) \u2014 check a cached page on this ' +
					'route against the ORIGIN DOCUMENT itself, for a route no `changeProbe` endpoint rule covers ' +
					'(listing pages): the facts named (`true` = title, metaDescription, canonical and `itemList`) ' +
					'are read off the served page and off the origin\u2019s document now, and compared, `itemList` ' +
					'by price and availability of the products listed in both, so re-ranking is not a change.\n\n' +
					'`negativeCache` (default false, prerender routes only, requires `render.negative.enabled`) — ' +
					'whether a MISS on this route that the origin answers 404/410 stores that response, so the next ' +
					'crawler asking for the same dead URL is answered without another origin round trip. Like ' +
					'`rawCache` it replaces an origin proxy and nothing else, and it never answers a URL a sitemap ' +
					'lists. Meant for a detail-page route whose dead URLs crawlers keep re-asking for; see ' +
					'`render.negative`.\n\n' +
					'`entityPrefix` (prerender routes only; off when absent) — a regular expression, anchored at the ' +
					'start of the URL PATH, whose match is the part of the URL that identifies ONE entity, e.g. ' +
					"`'^/product/prd-[^/]+/'` on a `/product/prd-` route. Traffic discovery then refuses to mint a " +
					'target for an unknown URL when another URL of the same entity (a target whose URL starts with ' +
					'this URL\u2019s origin plus the match) is already in rotation: crawlers requesting an old or ' +
					'invented slug of a product whose correct URL is tracked no longer cost a render that ends ' +
					'suppressed as `canonical-mismatch`. The URL is still served (a miss proxies the origin). ' +
					'Sitemap-listed URLs are always created. Siblings that are all SUPPRESSED do not block, so a ' +
					'product whose slug really changed is discovered at its new URL once the old URL\u2019s next ' +
					'render has suppressed it — a delay of one render cycle of the old target, never a permanent ' +
					'block. THE MATCH MUST END ON `/`: a prefix that stops mid-segment is a string prefix of other ' +
					"entities' URLs (`prd-123` of `prd-1234`), so a match that does not end in `/` is ignored for " +
					'that URL (it is discovered as if no entityPrefix were set) and a pattern whose source does not ' +
					'end in `/` is warned about. Every URL under one prefix counts as the same entity, query variants ' +
					'the route keeps included, so do not set this on a route where several URLs per entity are ' +
					'distinct pages. The pattern runs against crawler-supplied paths, so keep it linear — a literal ' +
					'prefix plus `[^/]+` segments, no nested quantifiers. Governed by `ingress.entityGate` (dry run ' +
					'by default).\n\n' +
					'`entityServe` (default false; prerender routes with an `entityPrefix` only) — answer a TRUE miss ' +
					'for a URL with no target of its own (or one suppressed as a canonical verdict) from the cached ' +
					'render of its entity\u2019s canonical URL, ' +
					'instead of the origin: the crawler asking for `/product/prd-1/old-slug.jsp` gets the page cached ' +
					'for `/product/prd-1/right-slug.jsp`, which declares the canonical exactly as the origin would. ' +
					'Served only when one target of the entity in rotation has a fresh, indexable 200 page for the ' +
					'device, that page\u2019s own canonical names it, and its canonical was confirmed against the ' +
					'origin since the last anchor and not heard re-slugged since by the entity registry (see ' +
					'`ingress.entityServe`); anything else falls through to the ordinary miss path. Setting it also ' +
					'lets every document proxied from the origin on the route teach the registry the canonical it ' +
					'declares (the entity registry, `entities`). ONLY FOR A SITE THAT ANSWERS EVERY SPELLING OF AN ENTITY WITH THE SAME ' +
					'DOCUMENT. The experiment that settles it: fetch two spellings of one product from the origin and ' +
					'compare everything but per-response noise — the canonical, title, description, offers and ' +
					'breadcrumbs must be identical, and the canonical must name the same URL from both. Governed by ' +
					'`ingress.entityServe` (dry run by default).',
				{ itemType: 'object' }
			),
			discoveryBots: option(
				['*'],
				'Bots whose visits may create NEW targets (traffic discovery), by the bot name the analytics ' +
					"registry resolves (analytics.bots / derived names / the literal 'other'), compared " +
					"case-insensitively. ['*'] (default) trusts every bot; [] disables traffic discovery " +
					'site-wide (sitemap-only corpus); a list trusts exactly those names. Third-party crawlers ' +
					'with broken link extractors invent malformed URLs from rendered markup and re-request them ' +
					'forever — restricting minting to the search engines that matter ends that class at the ' +
					'source. Creation-only: serving, the demand ladder, invalidation reenqueue, and sitemap ' +
					'ingestion are all unaffected.',
				{ itemType: 'string' }
			),
			entityGate: group(
				'The entity discovery gate. Nothing here does anything until a route declares ' +
					'`ingress.routes[].entityPrefix` — see that field for what an entity is.\n\n' +
					'WHAT IT DOES. When a bot requests an unknown URL on such a route and discovery would mint a ' +
					'target for it, the gate first reads the targets that share its entity prefix (one bounded ' +
					'primary-key range read of at most 3 rows — fixed, not tunable: measured, the first sibling in ' +
					'rotation was within the first 3 keys for every sampled entity — detached from the response and ' +
					'node-local). If one of them is in rotation, the URL is not minted. If there are none, or every ' +
					'one is suppressed, it is minted exactly as before. Any failure mints.\n\n' +
					'WHAT IT SAVES. Each refused mint is a render (and an origin document fetch) that would have ' +
					'ended `suppressed/canonical-mismatch`, then re-rendered on the suppression recheck until ' +
					'`maxStrikes` deleted it and the next crawler hit minted it again. Existing suppressed rows are ' +
					'left alone — they age out through `maxStrikes` as before, and once the gate is armed they are ' +
					'not re-minted.\n\n' +
					'Observed on `prerender_ops` / `entity_gate`, one emit per evaluation by outcome; armed ' +
					'refusals are also counted on `discovery_gated` with the gate name `entity`.',
				{
					enabled: option(
						true,
						'Master switch. Routes still have to opt in with `entityPrefix`, so leaving this on costs ' +
							'nothing until one does; it exists so an operator can stop the gate during an incident ' +
							'without editing the route list. Off = no sibling read, nothing counted, every unknown URL ' +
							'minted.'
					),
					dryRun: option(
						true,
						'Evaluate and count, but mint anyway. The default, because the number to know first is how ' +
							'many mints the gate WOULD refuse — `entity_gate` outcome `would-gate` — which is read ' +
							'against `render` outcome `suppressed`/`canonical-mismatch` before arming it. Turn it off ' +
							'to arm the gate.'
					),
				}
			),
			entityServe: group(
				'The entity serve. Nothing here does anything until a route sets `ingress.routes[].entityServe` ' +
					'beside its `entityPrefix` — see that field for what it does and when a site qualifies.\n\n' +
					'WHEN IT SERVES. On a true miss (no page for this key) for a URL with no query string and no ' +
					'target of its own (one suppressed as a canonical verdict counts as none: its own render said the ' +
					'product lives elsewhere), the targets sharing its entity prefix are read (one bounded primary-key ' +
					'range read of at most 8 rows, node-local). One of them in rotation must have a page for this ' +
					'device that is a 200, indexable, inside its own expiry (not SWR) and not covered by an ' +
					'invalidation it predates; none falls through, and more than one falls through unless the entity ' +
					'registry names one of them. That page must have been rendered since the threshold ' +
					'below, or checked against the origin since then by a check that compared its canonical and ' +
					'found it the same (`PageCheck.canonicalAgreed` — the serve-time check and the probe sweep write ' +
					'it, so the probe rule must map `canonical`); unless the registry is switched off, it must not have ' +
					'heard the origin name another canonical since (`moved`); and its own `<link rel=canonical>` ' +
					'must name it. ' +
					'An unconfirmed page is offered to the serve-time check, under that check\u2019s own switches and ' +
					'budget. Then it is served as `bot_serve` source and status `entity`.\n\n' +
					'WHY THE CONFIRMATION. An origin re-spells slugs. Between a re-spell and the old page\u2019s ' +
					're-render, the old page names its old slug while the origin declares the new one; served at ' +
					'every spelling, the contradiction would spread. Confirmation since the anchor bounds it to what ' +
					'the page already serves at its own URL.\n\n' +
					'ARM THE ENTITY GATE WITH IT. A spelling this does not answer (every one, in a dry run) goes to ' +
					'the origin, and a minting crawler\u2019s miss mints it; a spelling with a target is never ' +
					'entity-served. With `ingress.entityGate.dryRun: true` only each spelling\u2019s first request ' +
					'can be answered, and `would-serve` undercounts what arming would answer by its repeats (read ' +
					'as `has-target`). A served spelling is never minted: it was not a miss.\n\n' +
					'ARM ADOPTION WITH IT (`entities.adopt.dryRun: false`; the registry is on by default): with the gate armed, adoption ' +
					'is what files a re-slugged product\u2019s new canonical, and the registry is what tells this ' +
					'serve the old page has moved.\n\n' +
					'Observed on `prerender_ops` / `entity_serve`, one emit per evaluation by outcome, and ' +
					'`entity_serve_ms`, each evaluation\u2019s duration.',
				{
					enabled: option(
						true,
						'Master switch. Routes still have to opt in with `entityServe`, so leaving this on costs ' +
							'nothing until one does; it exists so an operator can stop entity serves during an incident ' +
							'without editing the route list. Off = no read, nothing counted, every miss as before.'
					),
					dryRun: option(
						true,
						'Evaluate and count, but answer every miss as before. The default, because the number to know ' +
							'first is how many misses it WOULD answer — `entity_serve` outcome `would-serve` — and why the ' +
							'rest fall through. Turn it off to serve. Unconfirmed candidates are offered to the serve-time ' +
							'check in a dry run too: confirming them is that check\u2019s ordinary job, under its own ' +
							'switches and budget.'
					),
					maxConfirmAge: option(
						0,
						'How recent a confirmation must be, at most, beside the anchor: the threshold is the later of ' +
							'the last anchor (`changeProbe.mode: anchored`) and now minus this. 0 = the anchor alone. ' +
							'Outside anchored mode the anchor does not exist, so with 0 nothing is ever confirmed and ' +
							'nothing is served — set this to the longest a page may go unconfirmed there.',
						{ unit: 'ms', min: 0 }
					),
				}
			),
			excludePathPatterns: option(
				['/search/'],
				'Paths never auto-scheduled for rendering. Compiled into `routes` as ' +
					"{ match: 'contains', mode: 'passthrough' } entries, PREPENDED so an exclude still beats any " +
					'prerender route it overlaps. Matched against the PATH only (never the query string). ' +
					'Prefer declaring a `contains`/`passthrough` route directly.',
				{ movedFrom: 'excludePathPatterns', itemType: 'string' }
			),
			report: group(
				'Periodic aggregated report of paths served without prerendering, bucketed by first path ' +
					'segment. Replaces a per-request warning that was unusable at crawler volume. Runs on EVERY ' +
					'worker (the counters are in-process), so each line carries node + worker and a reader sums ' +
					'across them.',
				{
					enabled: option(true, 'Emit the periodic unrouted-path report.'),
					interval: option(
						5 * MINUTE,
						'How often each worker flushes its tally. At most 2147483647 (~24.8 days), Node’s timer ' +
							'ceiling: past it a timer fires every millisecond rather than never.',
						{ unit: 'ms', min: SECOND, max: 2147483647 }
					),
					maxBuckets: option(200, 'Distinct buckets tracked per class before overflow counting.', { min: 1 }),
					topN: option(20, 'Buckets listed per log line, highest count first.', { min: 1 }),
				}
			),
		}
	),

	deviceTypes: group('Device variants the service renders and serves.', {
		supported: option(
			['desktop', 'mobile', 'tablet'],
			'Device types the service understands; unrecognized values fall back to the first entry.',
			{ itemType: 'string', nonEmpty: true }
		),
		default: option(
			['desktop', 'mobile'],
			'Device types every render job renders (one job per URL renders all of them). Empty is refused at ' +
				'apply time and the default kept: a job naming no device is one the browser cannot act on, and the ' +
				'schedule code would otherwise have to guess.',
			{ itemType: 'string', nonEmpty: true }
		),
	}),

	cacheKey: group(
		'How a request URL becomes a cache identity. Changing any of these reshapes every key: ' +
			'existing cached pages and schedules are orphaned (not migrated), so treat a live change ' +
			'as a full cache rebuild.',
		{
			delimiter: option('|', 'Separator joining the key attributes.', { nonEmpty: true }),
			attributes: option(['url', 'deviceType'], 'Attributes joined (in order) to form the key.', {
				itemType: 'string',
				nonEmpty: true,
			}),
			queryParams: option(
				['page'],
				'URL normalization used to build the cache key: an allowlist of query parameters to retain ' +
					'(others are dropped; the remaining ones are sorted for a stable key).\n' +
					"  ['page'] — keep only `?page=` (default)\n" +
					"  ['*'] — keep all query params\n" +
					'  [] — drop all query params\n' +
					'In forwarded mode a matched route’s own `queryParams` takes precedence.',
				{ movedFrom: 'url.queryParams', itemType: 'string' }
			),
			decodeReserved: option(
				[':', ',', '@'],
				'RESERVED characters to decode when they appear percent-encoded, so one logical URL ' +
					'spelled two ways is one cache key. The UNRESERVED set (letters, digits, `- . _ ~`) is ' +
					'always decoded — RFC 3986 says those escapes denote the same character, so it holds for ' +
					'every site. These do not: whether `%3A` and `:` name the same page is a fact about how ' +
					'your origin parses URLs.\n' +
					'  [":", ",", "@"] — the characters WHATWG `new URL()` and Chrome emit literally in a ' +
					'query, so a sitemap loc, a CDN-forwarded request and a Chrome redirect target agree (default)\n' +
					'  [] — decode nothing beyond the unreserved set (what a CDN does)\n' +
					'Structural characters are refused: decoding `&` `=` `+` `#` `/` `%` or `|` would reparse ' +
					'the URL into a different shape. Beware list-valued params — an API that reads `?ids=1,2,3` ' +
					'as three values and `%2C` as a literal comma inside one is a site where `,` must be removed ' +
					'from this list.',
				{ itemType: 'string', itemEnum: [':', ',', '@', ';', '$', "'", '(', ')', '!', '*'] }
			),
			trailingSlash: option(
				'strip',
				'Whether `/a/` and `/a` are one cache key.\n' +
					'  strip — drop a trailing slash on a non-root path, so they collapse (default)\n' +
					'  preserve — keep them apart, and answer each with what the origin says about it\n' +
					'No standard makes them one resource, and it can differ per ROUTE on one site: an origin ' +
					'that 404s or 403s the slashed form is giving a different answer, and stripping has us ' +
					'reply on its behalf with a page it refused. Check before choosing — request both ' +
					'spellings of a path on each route shape you serve.',
				{ enum: ['strip', 'preserve'] }
			),
			plusIsSpace: option(
				false,
				'Treat `%20` and `+` in the QUERY as one spelling of a space (folded to `+`), so a ' +
					'crawler-invented re-encoding is the same cache key as the URL your sitemap declares — ' +
					'not a second target rendering the same page forever.\n' +
					'Only enable it for an origin that FORM-DECODES its query, where `+` means space and the ' +
					'two spellings cannot name different resources. One request per allowlisted parameter ' +
					'settles that for every URL on the site: ask for a value containing a literal plus ' +
					'(`?f=A%2BB`), then the same value with a raw `+` (`?f=A+B`). If the second resolves as a ' +
					'SPACE (its canonical comes back `A%20B`), the origin form-decodes. If the two return ' +
					'different pages, leave this off — folding would serve one page under the other’s URL.\n' +
					'`%2B` is never folded: a literal plus inside a value is a different value.\n' +
					'MIRROR THIS IN THE RENDERER (`@harperfast/prerender-browser` `cacheKey.plusIsSpace`). It ' +
					'changes which URLs are the same key, so a renderer left unfolded reads every folded URL ' +
					'as canonicalizing elsewhere and retires it.\n' +
					'Enabling re-keys every affected URL: their cached pages are orphaned and re-render.'
			),
		}
	),

	origin: group('How Harper fetches from the origin: identification, staging routing, and header hygiene.', {
		securityToken: group(
			'Shared secret sent to the origin so it can distinguish the prerender service (and bypass ' +
				'bot mitigation). Set the value per deployment — preferably via `valueEnv` so the secret ' +
				'stays out of config.yaml.',
			{
				header: option('x-harper-renderer-bypass', 'Header name carrying the token.', { nonEmpty: true }),
				value: option('', 'The token itself. Prefer `valueEnv`.', { secret: true }),
				valueEnv: option(
					'',
					'If set, the token is sourced from this environment variable at config-apply time and takes ' +
						'precedence over `value` (keeps the secret out of config.yaml). The environment itself is ' +
						'loaded once at boot (loadEnv), so changing the variable’s VALUE still needs a restart; ' +
						'changing which variable is read does not.',
					// FILE-ONLY, exactly like the secret it selects. Writing this from the console would set the
					// token by proxy: point it at an environment variable whose value you already know and the
					// secret becomes that value. That is the bypass `secret: true` exists to prevent, so the
					// pointer has to be as unwritable as the target.
					{ uiEditable: false }
				),
			},
			{ movedFrom: 'securityToken' }
		),
		staging: group(
			'Staging passthrough — for verifying an origin against a staging edge (e.g. the CDN’s staging ' +
				'network). When `ip` is set, a cache-MISS origin fetch that carries the `header` request header ' +
				'is connected to `ip` instead of the public origin. The Host header and TLS SNI stay the real ' +
				'origin host (only the TCP address is pinned), so the staging edge serves the right property and ' +
				'presents a valid certificate.\n\n' +
				'The header is only a toggle: the connect address is always the configured `ip`, never a value ' +
				'from the request, so a request can’t repoint the fetch at an arbitrary host. The cache key does ' +
				'not include the header, so cache HITS always return the normal cached page regardless of it. ' +
				'Empty `ip` disables the feature — production is unaffected unless a staging IP is explicitly ' +
				'configured.\n\n' +
				'The sitemap refresh reuses this `ip` too, but unconditionally (no toggle header — it has no ' +
				'incoming request): whenever `ip` is set, every sitemap fetch is pinned to it, so all ' +
				'Harper→origin traffic hits the same edge. The security token often only authenticates against ' +
				'the staging edge, so a direct prod sitemap fetch is bounced with a 403.\n\n' +
				'Toggling staging↔prod contaminates the URL-keyed page cache; wipe it when switching.',
			{
				ip: option('', 'Staging edge IP. Empty disables staging passthrough entirely.'),
				header: option('x-harper-staging', 'Request header that toggles the staging connect on a miss fetch.'),
			},
			{ movedFrom: 'staging' }
		),
		userAgents: group(
			'Per-device-type User-Agent strings sent to the origin on the proxy (cache-miss passthrough) ' +
				'fetch. Each carries a `HarperProxy/1.0` product token so Harper’s proxy traffic is identifiable ' +
				'in origin/CDN logs while still presenting a real, device-appropriate browser UA (the origin ' +
				'serves device-specific HTML off it).\n\n' +
				'With `forwardUserAgent.enabled` these are only the fallback, for a request that arrived ' +
				'without a User-Agent.',
			{
				mobile: option(`${DEVICE_BROWSER_UAS.mobile} ${PROXY_TOKEN}`, 'UA for mobile proxy fetches.'),
				tablet: option(`${DEVICE_BROWSER_UAS.tablet} ${PROXY_TOKEN}`, 'UA for tablet proxy fetches.'),
				desktop: option(`${DEVICE_BROWSER_UAS.desktop} ${PROXY_TOKEN}`, 'UA for desktop proxy fetches.'),
			},
			{ movedFrom: 'userAgents' }
		),
		forwardUserAgent: group(
			'Send the CRAWLER’S OWN User-Agent to the origin on the proxy fetch, with `suffix` appended, ' +
				'instead of the fixed `userAgents` browser strings. Default off.\n\n' +
				'WHY: with the fixed strings the origin can tell Harper’s fetches from direct traffic, but every ' +
				'one of them looks like the same browser — the origin’s own bot metrics cannot say which crawler ' +
				'a fetch was made for. Forwarded, `Googlebot/2.1 (…) HarperProxy/1.0` is both: the crawler, and ' +
				'Harper on its behalf. An origin-side report that counts crawlers by UA substring must now ' +
				'exclude `suffix`, or it counts each proxied miss twice (the edge already logged the crawler’s ' +
				'own request).\n\n' +
				'Only the proxy fetch is affected — it is the one made on behalf of a single crawler. Renders, ' +
				'change probes, serve checks, the negative cache’s background re-checks and sitemap fetches are ' +
				'Harper’s own traffic and keep their own UAs.\n\n' +
				'SETTLE TWO THINGS WITH WHOEVER RUNS THE EDGE BEFORE ENABLING. (1) A crawler UA from Harper’s ' +
				'addresses fails the crawler’s IP verification, so everything the edge does to an unverified ' +
				'crawler must exempt requests carrying `securityToken`: the rule that routes bot traffic to ' +
				'Harper (else the fetch comes straight back here), and bot mitigation’s deny, challenge or ' +
				'serve-alternate actions (else the crawler is relayed a 403, or a 200 page the raw cache stores ' +
				'and replays). (2) The raw cache (`render.raw`) stores a proxied document and replays it to ' +
				'OTHER crawlers — correct only if the origin answers crawlers the same as each other. One ' +
				'experiment settles both: fetch a URL through the edge, with the token, once with a browser UA ' +
				'and once with a crawler UA plus `suffix`, and compare status, canonical and body (past ' +
				'per-request churn). Any difference means leave this off.',
			{
				enabled: option(false, 'Forward the crawler’s User-Agent on the proxy fetch.'),
				suffix: option(
					PROXY_TOKEN,
					'Product token appended to the forwarded UA, after one space, so Harper’s fetches stay ' +
						'identifiable. Empty forwards the crawler’s UA verbatim.'
				),
			}
		),
		ignoredHeaders: option(
			[],
			'Additional downstream request header names never forwarded to the origin, on top of the ' +
				'always-ignored set (hop-by-hop headers plus host, user-agent, accept-encoding, cookie, ' +
				'authorization, and the security-token/debug header names). Matched case-insensitively.',
			{ movedFrom: 'ignoredHeaders', itemType: 'string' }
		),
		maxResponseHeaderBytes: option(
			64 * 1024,
			'Largest response head Harper will accept from the origin, summed across every header name ' +
				'and value in the response (not per header).\n\n' +
				'Undici defaults this to Node’s `http.maxHeaderSize` (16 KiB), which is a header-flood ' +
				'mitigation for servers accepting untrusted requests — too strict for a reverse proxy reading ' +
				'its own origin. A real origin can exceed 16 KiB on a single page (several Set-Cookie plus ' +
				'CSP, Link rel=preload, NEL, Report-To), and undici responds by destroying the connection ' +
				'with UND_ERR_HEADERS_OVERFLOW, so the crawler gets a 500 for a page browsers and the CDN ' +
				'load normally. It fails deterministically for those URLs, since it is a property of the ' +
				'origin’s response rather than a transient. Hence a default well above Node’s, matching what ' +
				'a CDN in front of the same origin already tolerates.\n\n' +
				'Raising it raises the worst-case memory held per connection while a response head is ' +
				'parsed, which is why it is bounded at both ends. The 1 MiB ceiling is far above any ' +
				'legitimate response head — it exists to catch a typo (a stray factor of a thousand) ' +
				'before it becomes an out-of-memory risk multiplied across concurrent connections.\n\n' +
				'Restart-scoped: undici fixes `maxHeaderSize` when the dispatcher is constructed and offers ' +
				'no way to change it afterwards, so a live edit is reported as pending-restart and the ' +
				'running dispatchers keep the value they were built with.',
			{ unit: 'bytes', min: 16 * 1024, max: 1024 * 1024, scope: 'restart' }
		),
	}),

	debugHeader: group('Debug response headers, emitted when the request carries this header (any value).', {
		key: option('x-harper-prerender-debug', 'Request header name that turns on debug response headers.', {
			nonEmpty: true,
		}),
	}),

	renderNow: group(
		'On-demand render control. When enabled, an authorized GET bot request gets two orthogonal ' +
			'levers (both ignored for unauthorized requests, so real crawler traffic is unaffected):\n' +
			'  1. Cache freshness — a request `Cache-Control: no-cache`/`no-store` SKIPS the served cache ' +
			'(forces a miss).\n' +
			'  2. Miss behavior — the `missHeader` value picks what to do on a miss/skip: ‘prerender’ ' +
			'(force an immediate one-off render and long-poll for the fresh result) or ‘origin’ (proxy ' +
			'the origin, same as a normal miss). Absent → `defaultMissMode`.\n' +
			'So `defaultMissMode: prerender` + no Cache-Control = "serve cache, else render now" ' +
			'(warm-on-demand); adding `Cache-Control: no-cache` = "always render fresh now".',
		{
			enabled: option(
				false,
				'Enable the on-demand render levers. Enabling is necessary but not sufficient — a non-empty ' +
					'`token` (or a `valueEnv` that resolves to one) is also required, so this cannot open the ' +
					'levers on its own.'
			),
			header: option(
				'x-harper-render-now',
				'Request header that authorizes the on-demand levers. The header VALUE must equal the ' +
					'configured `token`; presence alone never authorizes.'
			),
			token: option(
				'',
				'Expected value of `header`. **Required** — there is no unauthenticated mode: an empty token ' +
					'leaves renderNow DISABLED (the levers stay off even when `enabled` is true) rather than ' +
					'authorizing anyone who sends the header, and is reported at config-apply time.\n\n' +
					'This fails CLOSED deliberately. The levers let a caller bypass the served cache and force ' +
					'a synchronous render that occupies the request for up to `timeoutMs`, so on a path that ' +
					'takes public crawler traffic an absent or unresolved token must not degrade to "authorize ' +
					'everyone". Prefer `valueEnv` so the secret stays out of config.yaml, and never commit a ' +
					'guessable placeholder — a value like "true" is not meaningfully better than none.',
				{ secret: true }
			),
			valueEnv: option(
				'',
				'If set, the token is sourced from this environment variable at config-apply time and takes ' +
					'precedence over `token`. Same boot-time caveat as `origin.securityToken.valueEnv`.',
				// File-only for the same reason as `origin.securityToken.valueEnv`: it sets the token by proxy.
				{ uiEditable: false }
			),
			missHeader: option('x-harper-render-miss', "Request header picking miss behavior: 'prerender' | 'origin'."),
			defaultMissMode: option('prerender', 'Miss behavior when `missHeader` is absent.', {
				enum: ['prerender', 'origin'],
			}),
			timeoutMs: option(30 * SECOND, 'Give up waiting for the fresh render after this long.', {
				unit: 'ms',
				min: 1,
			}),
			pollIntervalMs: option(250, 'How often to re-check the cache for the fresh render.', {
				unit: 'ms',
				min: 10,
			}),
			fallback: option(
				'origin',
				'What to serve when a prerender doesn’t land before `timeoutMs`:\n' +
					"  'origin' — proxy the origin (same as a normal cache miss)\n" +
					"  'stale' — serve the existing cached page if any, else fall back to origin\n" +
					"  'error' — respond 504",
				{ enum: ['origin', 'stale', 'error'] }
			),
		}
	),

	network: group('How other cluster nodes and the render fleet reach this node over HTTPS.', {
		publicPort: option(
			0,
			'Port other nodes and the render fleet use to reach this node’s HTTP API: the port in every ' +
				'render job’s `callbackOrigin` (where the fleet posts its result) and in every peer call ' +
				'(the serve-path rescue, the invalidation heal, the explainer’s owner read).\n\n' +
				'0 (default) = Harper’s own `http.securePort`, which is right when that port is published ' +
				'on the host. Set it when the host fronts Harper on a different port: newer Fabric hosts ' +
				'bind the container’s 9926 to loopback only and publish it on 443, so there nothing ' +
				'off-host can reach `:9926` and every result post fails — set `publicPort: 443`. The render ' +
				'fleet claims on its own `queuePort`, which must be changed to match. A localhost origin ' +
				'ignores this (it speaks plain http on Harper’s plain port).',
			{ min: 0, max: 65535 }
		),
	}),

	peerRescue: group(
		'Cluster peer rescue for the serve path. A cache serve reads the stored body before committing ' +
			'a status; when that LOCAL read fails — the blob file is gone (a dangling reference), or the ' +
			'read outlived `page.blobReadBudgetMs` (a base copy is streaming that blob) — the bytes are ' +
			'fetched from the URL’s residency owner over the cluster’s own HTTPS instead of proxying the ' +
			'origin. The owner granted every render claim for its keys, so its blob is a written original, ' +
			'never a received replica: it is the node most likely to hold complete bytes, a few ' +
			'milliseconds away, and the rescued response is the real prerendered snapshot rather than raw ' +
			'un-prerendered origin markup. The origin remains the backstop whenever the rescue misses ' +
			'(the owner is this node, unreachable, past `timeoutMs`, or its own read fails).\n\n' +
			'Enabling also serves the endpoint peers call (`GET /prerender_peer/page`), gated on `token`. ' +
			'Set the SAME token on every node: a node with a different or empty token answers 403/404 and ' +
			'its peers simply fall back to the origin, so a staggered rollout degrades softly rather than ' +
			'breaking serves.',
		{
			enabled: option(
				false,
				'Enable the rescue (and the endpoint that serves peers). Necessary but not sufficient — a ' +
					'non-empty `token` (or a `valueEnv` that resolves to one) is also required, so this cannot ' +
					'open an unauthenticated endpoint on its own.'
			),
			header: option('x-harper-peer-token', 'Request header carrying the shared token on peer calls.', {
				nonEmpty: true,
			}),
			token: option(
				'',
				'The shared cluster secret, identical on every node. **Required** — there is no ' +
					'unauthenticated mode: an empty token leaves the feature DISABLED (no rescues attempted, the ' +
					'endpoint answers 404) rather than serving cached pages to anyone who finds the path. ' +
					'Compared timing-safely. Prefer `valueEnv` so the secret stays out of config.yaml, and never ' +
					'commit a guessable placeholder.',
				{ secret: true }
			),
			valueEnv: option(
				'',
				'If set, the token is sourced from this environment variable at config-apply time and takes ' +
					'precedence over `token`. Same boot-time caveat as `origin.securityToken.valueEnv`.',
				// File-only for the same reason as `origin.securityToken.valueEnv`: it sets the token by proxy.
				{ uiEditable: false }
			),
			timeoutMs: option(
				500,
				'Deadline for the whole peer fetch (connect through body). A healthy rescue is a few ' +
					'milliseconds of intra-cluster round trip plus the owner’s sub-millisecond blob read, so ' +
					'this only trips when the owner is down, saturated, or mid-copy itself — at which point the ' +
					'origin fallback proceeds exactly as it would have without the rescue. Keep it in the same ' +
					'order as `page.blobReadBudgetMs`: the two are additive on the worst-case path ' +
					'(budget + rescue timeout + origin).',
				{ unit: 'ms', min: 1 }
			),
		}
	),

	management: group(
		'Management API, served at the fixed path `/prerender_admin` (resource endpoint names are ' +
			'fixed, like the database/table names). Gated on Harper’s own authentication: every endpoint ' +
			'except the login/session/index routes requires a `super_user`. The console UI consuming this ' +
			'API is the separate `@harperfast/prerender-console` component.',
		{
			enabled: option(
				true,
				'Serve the management API (and therefore anything the console can show).',
				// Not editable from the console for the obvious reason: one click would take the console
				// away, and getting it back needs a config-file edit. It stays live-reloadable from the
				// file, which is the right place for a switch whose off position is unreachable.
				{ uiEditable: false }
			),
			overrides: group(
				'Operator-set config overrides — the layer between the deployed `config.yaml` and the ' +
					'running config, stored one row per option path in `config.ConfigOverride` and ' +
					'written from the console.\n\n' +
					'Precedence is `schema defaults < config.yaml < these rows`. A deployed file change still ' +
					'takes effect for every option nobody has overridden, clearing an override reverts that one ' +
					'option to the deployed value, and clearing all of them returns the cluster to exactly its ' +
					'deployed state. The rows replicate, so the console writes once on whichever node it ' +
					'reached and every node converges.\n\n' +
					'This whole group is file-only: it is the machinery the console writes through, and ' +
					'editing the mechanism with the mechanism is how you end up locked out of both.',
				{
					enabled: option(
						true,
						'Honor stored overrides. FALSE IS THE KILL SWITCH: the rows are left in place but ' +
							'ignored, so the cluster runs exactly its deployed `config.yaml` again. This is the ' +
							'recovery path for an override that broke something, and the reason it has to live in ' +
							'the file — an override you need to undo is a poor thing to undo through the override ' +
							'layer.'
					),
					subscribe: option(
						true,
						'Watch the override table so a console edit converges in about a second instead of ' +
							'waiting out `syncInterval`. Subscribing requires the table’s audit log (Harper turns ' +
							'it on when you subscribe) and attaches its commit listener to the whole DATABASE’s ' +
							'audit store, which is why this table lives alone in `config`: every commit in a ' +
							'subscribed table’s database schedules a pass over the transaction log, so a ' +
							'subscription sharing a database with the hot target/schedule tables would tax every ' +
							'write to them. False leaves the backstop poll as the only path, which is correct ' +
							'behavior, just slower.'
					),
					syncInterval: option(
						30 * SECOND,
						'Backstop re-read cadence for the override table, run on EVERY worker rather than one per ' +
							'node: each worker holds its own config object, and the failure this covers — that ' +
							'worker\u2019s subscription is gone — is per-worker by definition. The live path ' +
							'is the subscription above; this exists so a subscription that was never established, ' +
							'or a worker whose boot read failed, still converges — the layer gets a bound on how ' +
							'stale it can be that does not depend on a callback firing. A re-read whose result is ' +
							'unchanged does not re-apply, so the steady-state cost is one bounded scan of a table ' +
							'with at most a few dozen rows. 0 disables the backstop, and the ceiling is node’s own ' +
							'timer limit of 2^31-1 ms (~24.8 days) — past it a timer fires every millisecond ' +
							'rather than never.',
						{ unit: 'ms', min: 0, max: 2147483647 }
					),
				},
				{ uiEditable: false }
			),
			proxyToOwner: option(
				true,
				'The URL explainer reads node-locally (a cross-node point read on the residency-pinned ' +
					'schedule table awaits Harper’s replication fetch, which has no timeout). When the row is ' +
					'owned by another node, ask that node over HTTPS instead — a bounded request, forwarding only ' +
					'the caller’s own credentials, which the peer re-authorizes. Set false to keep every read ' +
					'strictly node-local and accept an inconclusive schedule row.'
			),
			peerTimeoutMs: option(2500, 'Timeout for the peer-node explainer request.', { unit: 'ms', min: 1 }),
			scanCap: option(
				20000,
				'Ceiling on rows touched by a management scan (the suppressed-target count, a sitemap’s ' +
					'target count; the analytics scan has its own `analytics.scanCap`). Counting is a capped index walk — at 1M+ targets an uncapped count is not a ' +
					'page-load query — so results past this are reported as truncated rather than silently ' +
					'undercounted. The queue counts are not scans: they come from the queue keeper.\n\n' +
					'At most 1,000,000, 50x the default. It is editable from the console, and each walk it ' +
					'bounds runs on a worker that also serves bot traffic. The largest such walk (every ' +
					'suppressed target) is useful up to about this size; past it the answer is "a lot", and a ' +
					'truncated count already reports that.',
				{ min: 1, max: 1_000_000 }
			),
			backlogSnapshotInterval: option(
				15 * MINUTE,
				'How often the backlog snapshot recomputes (worker 0 of each node): the queue keeper’s counts ' +
					'and histogram, plus the table counts, which are scans and so never run on dashboard page load. ' +
					'Its `overdue` count includes in-flight jobs (their rows keep their past due time until the ' +
					'render lands). 0 disables the timer; the console’s Recompute button still triggers a one-off ' +
					'pass. At most 2147483647 (~24.8 days), Node’s timer ceiling: past it a timer fires every ' +
					'millisecond rather than never, so a large value is not a way to switch this off — 0 is.',
				{ unit: 'ms', min: 0, max: 2147483647 }
			),
			snapshotTableCounts: option(
				true,
				'Include the four table counts (targets, pages, sitemaps, suppressed) in each backlog ' +
					'snapshot. The counts go through Harper’s getRecordCount, which on RocksDB tables past ' +
					'the sampling budget issues ONE synchronous native full-key iteration — measured 2.47s ' +
					'on a ~2.2M-key table, during which every request routed to that worker waits ' +
					'(harper-pro#664). False keeps the snapshot itself (the queue counts and the queue_health ' +
					'gauges, which never take that walk) while the console shows the counts as unavailable.',
				{}
			),
			pageSize: option(
				50,
				'Rows per page for the console’s sitemap-entry and page-cache tables. Also bounds the ' +
					'per-entry state lookups a sitemap detail performs (point reads, one per row). At most ' +
					'500, 10x the default: a sitemap page costs two point reads per row, and a page longer than ' +
					'this is a table nobody reads on one screen.',
				{ min: 1, max: 500 }
			),
			analytics: group(
				'The console’s Traffic/queue-health charts: ONE bounded primary-key scan of this node’s ' +
					'`system.hdb_analytics` per refresh (never one scan per metric name — the table is ' +
					'indexed only by time, so a name is a scan and a series is a row), bucketed ' +
					'server-side and cached per worker. The console never polls; a scan happens only when ' +
					'an operator loads a view whose cached window has expired.',
				{
					enabled: option(true, 'Serve GET /prerender_admin/analytics and the console panels that read it.'),
					maxRange: option(
						DAY,
						'Ceiling on the window one analytics request may ask for. The scan cost scales ' +
							'directly with the window (rows = active metric combos × aggregate periods), so ' +
							'this is the knob that bounds the worst read an operator can trigger. At most 7 days, ' +
							'7x the default and the console’s longest range (24h). A longer window would be ' +
							'decided by `scanCap` rather than by the range, and would come back truncated.',
						{ unit: 'ms', min: MINUTE, max: 7 * DAY }
					),
					cacheTtl: option(
						MINUTE,
						'How long a scanned window is served from the per-worker cache before a refresh ' +
							're-scans. Matches Harper’s default analytics aggregation period — refreshing ' +
							'faster cannot surface new rows, only repeat the scan.',
						{ unit: 'ms', min: 0 }
					),
					scanCap: option(
						150000,
						'Ceiling on rows one analytics scan walks. The walk runs NEWEST-FIRST, so past the ' +
							'cap it is the oldest end of the window that is shed, and the response reports ' +
							'the window it actually covered rather than presenting a partial range as the ' +
							'full one.\n\n' +
							'Memory does not grow with this: each row is folded into its series as it is read, ' +
							'so a scan holds one accumulator per metric combo, not the rows. What grows is the ' +
							'time one scan keeps a serving worker busy, which is what the ceiling bounds. At ' +
							'3,000,000 it is 10x the ~300,000 rows a busy node writes in 24h, which covers the ' +
							'7-day `maxRange` ceiling at that rate.',
						{ min: 1000, max: 3_000_000 }
					),
				}
			),
		}
	),

	page: group('Cached-page lifetimes.', {
		ttl: option(DAY, 'Default cached-page TTL.', { unit: 'ms', min: 1 }),
		minTtl: option(6 * HOUR, 'Floor for sitemap-derived TTLs.', { unit: 'ms', min: 1 }),
		swrTtl: option(3 * HOUR, 'Stale-while-revalidate window.', { unit: 'ms', min: 0 }),
		blobReadBudgetMs: option(
			500,
			'How long a cache serve may spend reading the stored body before giving up and proxying to ' +
				'the origin instead.\n\n' +
				'The body is read to completion before the response commits a status, so that a record whose ' +
				'blob file is gone becomes an origin serve rather than a truncated 200. Without a budget that ' +
				'read inherits Harper’s own retry window (`storage_blobReadTimeout`, default 20s): a blob ' +
				'whose bytes are still arriving — which any base copy produces in quantity — puts the reader ' +
				'into an incomplete-content retry loop, and the crawler waits it out. Measured on a 4-node ' +
				'production cluster mid-copy: a cohort of cache hits averaging 13.6s, p95 17.5s, ~13% of hits ' +
				'on the worst node, while the same node’s median hit was 2.3ms.\n\n' +
				'A healthy read is nowhere near this: p50 0.75ms and p99 0.94ms for a ~223KB body on cold ' +
				'NVMe, so 500ms is ~500x the p99 and only a blob that is genuinely stuck can trip it. Keep it ' +
				'BELOW typical origin latency (~500-600ms here) so falling back is faster than waiting; ' +
				'raising it past `storage_blobReadTimeout` disables it entirely. 0 disables the budget and ' +
				'restores the unbounded wait.\n\n' +
				'Capped at 2147483647 because `setTimeout` stores its delay as a signed 32-bit int: a larger ' +
				'value does not mean "effectively never", it makes Node warn and fire the callback after 1ms — ' +
				'so a fat-fingered budget would time out EVERY cache hit and send all traffic to the origin. ' +
				'The cap turns that into a rejected value that keeps the default.',
			{ unit: 'ms', min: 0, max: 2147483647 }
		),
		serveLinkHeader: option(
			false,
			'Serve the origin document’s `Link` response header with a cached page. OFF until the stored ' +
				'rows have been sampled — the check below — because what the renderer stores there is not ' +
				'known to be what a crawler should get.\n\n' +
				'The renderer keeps the header off the response it rendered so that a canonical or hreflang ' +
				'alternate declared in HTTP (rather than in the markup) can reach the crawler with the snapshot, ' +
				'which is what a browser loading the same URL receives. Releases before 0.97.0 stripped it with no ' +
				'way to turn that off, a rule inherited from a predecessor codebase whose proxy path relayed ' +
				'the origin’s headers wholesale. But the stored value can also carry the live page’s resource hints ' +
				'(`preload`, `preconnect` — some of them injected by a CDN, not the origin), and for a render ' +
				'that followed a client-side redirect it is the SOURCE document’s header, not the page served.\n\n' +
				'THE CHECK: sample stored pages’ `headers` for `link` and read the `rel` values. Enable this when ' +
				'they are canonical/alternate entries that match the page; leave it off when they are mostly ' +
				'resource hints and the edge in front of this plugin acts on them for bot traffic (103 Early ' +
				'Hints, for example). A proxied (cache-miss) response is unaffected either way — it never ' +
				'carries `Link`.'
		),
		snapshotValidators: option(
			false,
			'Give a rendered page its own validators: `ETag: W/"<lastCachedMs>-<deviceType>"` and ' +
				'`Last-Modified` = its render time. With them, a crawler that already holds the current render ' +
				'gets a 304 from the cache instead of the whole snapshot again.\n\n' +
				'OFF by default because it changes what crawlers receive. A site whose origin sends no ' +
				'validators has never had a conditional request answered from this cache; turning this on ' +
				'starts crawlers revalidating and the cache answering 304s — a change to crawl traffic worth ' +
				'measuring (`response_304` beside `bot_serve`), and the edge in front has to pass ' +
				'`If-None-Match` / `If-Modified-Since` through and relay the 304.\n\n' +
				'Either way a rendered page NEVER carries the origin document’s `ETag` / `Last-Modified`: they ' +
				'describe the raw document, not the snapshot, so a re-render that changed client-rendered ' +
				'content under an unchanged origin ETag would answer 304 and the crawler would keep the old ' +
				'snapshot. A raw-cache document is the origin’s own document (gzipped before it is stored when the origin sent it uncompressed) and keeps the origin’s validators; ' +
				'a proxied response carries whatever the origin sent.'
		),
	}),

	invalidation: group(
		'Bulk cache invalidation. An invalidation records ONE ROW naming a scope and an instant; from then ' +
			'on, any cached page in that scope rendered before that instant stops being served and bots get ' +
			'the origin instead, until the page re-renders on its normal cadence.\n\n' +
			'Nothing is rewritten — not the cached pages, not the render schedule — so recording one costs a ' +
			'single 102-byte write instead of the ~61.8MB of audit per node a corpus rewrite costs, and UNDO ' +
			'IS INSTANT: delete the row and every page still inside its own expiry/stale-while-revalidate ' +
			'window serves again on the next request. Pages already past that window cannot come back, ' +
			'because their own lifetime expired while the invalidation was active; that asymmetry is inherent ' +
			'to not rewriting anything.\n\n' +
			'A scope is `all` or one prerender route from ingress.routes, written `route:<match>:<path>`. ' +
			'There are deliberately no free-text prefix scopes: a prefix cannot be checked against a closed ' +
			'set, so a typo would record a row that reports as applied and matches nothing — the worst ' +
			'failure available, because the mitigation appears to have worked. For a narrower blast radius, ' +
			'declare a narrower route.\n\n' +
			'TWO THINGS THIS CANNOT DO, both worth knowing before you rely on it. THE CDN EDGE IS NOT ' +
			'INVALIDATED and keeps its own TTL, and neither is a copy a crawler already holds. And origin ' +
			'markup carries correct price, availability, canonical, title and meta description, but not ' +
			'reviews or most images — so an invalidated page serves a thinner document than a rendered one.',
		{
			enabled: option(
				true,
				'Consult invalidation rows when serving, and allow the API to record them.\n\n' +
					'FALSE IS A KILL SWITCH, not a feature flag: every active invalidation stops applying at once ' +
					'and the whole corpus serves pre-invalidation bytes again. It exists because at 3am you want a ' +
					'way to take a new mechanism out of the serve path — but while any row exists it is reported as ' +
					'a config warning, a log line and a console banner, because silently serving content somebody ' +
					'deliberately invalidated is the one outcome this feature must never produce.'
			),
			pad: option(
				10 * MINUTE,
				'Added to `invalidatedAt` before comparing, so the comparison errs toward invalidating.\n\n' +
					'It covers two things. Cross-node clock skew: a page’s `lastCached` is stamped by whichever ' +
					'node rendered it and the epoch by whichever node recorded it. And — the certain one — renders ' +
					'ALREADY IN FLIGHT: a job claimed a moment before you invalidate fetched pre-change content but ' +
					'stamps `lastCached` at completion, so with no pad that page outlives the invalidation for a ' +
					'full render interval. That window is legitimately as long as `queue.jobLeaseTime` (a job may ' +
					'post back any time inside its lease, and does under backlog — exactly the state incidents ' +
					'create), so keep this at or above jobLeaseTime; a smaller value is reported as a config ' +
					'warning. The cost of over-including a page is one extra render of it.',
				{ unit: 'ms', min: 0 }
			),
			lkgMaxAge: option(
				5 * MINUTE,
				'How long a worker may reuse its last successful resolution when a read fails.\n\n' +
					'Past this, resolution fails OPEN — serving from cache as though nothing were invalidated — ' +
					'rather than trusting a stale answer. Both halves matter: without a bound, one transient read ' +
					'error after a clear would pin a worker on a deleted epoch for the rest of its life, with the ' +
					'console showing nothing active and offload quietly sagging. Failing open is the right default ' +
					'because this table’s normal state is EMPTY, so "unknown" almost certainly means "nothing is ' +
					'invalidated", and failing closed would turn a cosmetic storage fault into a total offload ' +
					'outage. Set 0 to fail open on the first read error.',
				{ unit: 'ms', min: 0 }
			),
			syncInterval: option(
				MINUTE,
				'How often each worker re-reads the invalidation table as a BACKSTOP to its subscription.\n\n' +
					'Every worker holds the table in memory and the serve path resolves epochs from that copy with no ' +
					'read at all; a subscription re-reads it the moment any row changes, on any node, so an ' +
					'invalidation and its undo both reach every worker within about a second. This interval bounds ' +
					'the one failure the subscription cannot report — delivery stopping silently — to at most this ' +
					'long of a stale view. It costs one read of a single-digit table per worker per interval, against ' +
					'the two point reads per cache-servable request the view replaced. While the subscription is ' +
					'down or the copy has not loaded, the serve path reads the table per request instead, and each ' +
					'tick also retries the subscription.',
				{ unit: 'ms', min: SECOND, max: 2147483647 }
			),
			maxScopes: option(
				16,
				'Ceiling on simultaneously active scopes. Bounds the console walk and the operator surface — NOT ' +
					'the serve-path read, which is at most two point reads by known key (`all` plus the one route ' +
					'the request matched) however many rows exist.',
				{ min: 1 }
			),
			verification: group(
				'PER-PAGE EXEMPTION. Let a page an invalidation would refuse be served anyway when the change ' +
					'probe has PROVED it is still current — `pageCheck` compared the cached page\u2019s own claims against ' +
					'the origin after the epoch and they agreed.\n\n' +
					'WHY THIS EXISTS. A bulk invalidation refuses everything in scope rendered before the epoch because ' +
					'it cannot tell what actually changed. Measured during a route-wide trip on a four-node deployment, ' +
					'only 22-29% of the scope had genuinely moved; the rest were origin-proxied for up to a full render ' +
					'interval while being byte-for-byte correct. This turns "predates the epoch" into "lacks evidence", ' +
					'which is the question the invalidation was always asking.\n\n' +
					'WHAT IT ASSERTS, EXACTLY: the fields the probe rule watches still match. Nothing more. A promo flip ' +
					'also moves badges, banners and copy no probe looks at, so a verified page is "price and availability ' +
					'confirmed", never "fresh". Judge whether that is the right bar for what you invalidate FOR.\n\n' +
					'REQUIRES `changeProbe.pageCheck` on the rule whose `invalidateScope` recorded the invalidation. A ' +
					'signature match alone is NOT sufficient and is deliberately not accepted: it says the origin has not ' +
					'moved since the last probe, which says nothing about whether the cached page was ever right.',
				{
					enabled: option(
						false,
						'Off by default, like `invalidation.reenqueue.enabled` and `render.reconcile.enabled` \u2014 enable it ' +
							'after one rehearsal, not on the deploy that introduces it. While off, nothing is written and ' +
							'nothing is read: every page is refused on the epoch comparison alone, exactly as before.\n\n' +
							'EVERY FAILURE FAILS CLOSED. Absent row, unprobed URL, failed probe, read error, unreadable ' +
							'timestamp \u2014 all mean NOT VERIFIED, and the page keeps being proxied. That is the opposite of ' +
							'`invalidation.lkgMaxAge`, which fails OPEN, and the asymmetry is the point: an unknown epoch ' +
							'almost certainly means "nothing is invalidated", while unknown evidence means "I cannot prove ' +
							'this page is current".'
					),
				}
			),
			reenqueue: group(
				'DEMAND-DRIVEN HEAL. When an invalidation is what made a request non-servable, lower that URL’s ' +
					'due time so the pages bots actually crawl heal first instead of waiting out their cadence in ' +
					'crawl order. The request itself is the trigger — no timer, no table scan, no cursor — and only ' +
					'the node that OWNS the key by residency acts, because its guards (the live lease, the ' +
					'authoritative schedule read) are node-local.\n\n' +
					'THERE IS DELIBERATELY NO CORPUS-WIDE SWEEP, and there will not be one. At a measured fleet ' +
					'ceiling of 71,289 renders/hr the 1,530,046-key long-tail corpus floors a full re-render at 21.5h ' +
					'at 100% utilisation — against the 48h those pages wait anyway, with measured utilisation already ' +
					'98% and a 3.05h standing backlog — while rewriting the corpus costs ~61.8MB of audit per node ' +
					'that pacing provably does not reduce (batching kept 162 B/write, took 8.9x longer and made ' +
					'claim’s max latency WORSE). Cadence-heal plus this accelerator is the whole mechanism.\n\n' +
					'Scale, so the ceilings below read as the small numbers they are: ~4,000 bot requests/day ' +
					'cluster-wide against 1.6M cache keys, of which crawlers request about 0.25%.',
				{
					enabled: option(
						false,
						'Off by default, like `render.reconcile.enabled`: enable it after one rehearsal, not on the ' +
							'same deploy that introduces it. While off, an invalidation adds NOTHING to the queue — zero ' +
							'schedule writes, zero audit — and every page heals on its own cadence.'
					),
					spreadWindow: option(
						15 * MINUTE,
						'Jitter window a lowered due time lands in: `now + hash(url) % spreadWindow`, seeded off the ' +
							'URL half of the cache key so a page’s device variants land on the SAME minute (see ' +
							'util/time.js — de-aligned variants show a content change on one device and not the other, ' +
							'permanently, cycle over cycle).\n\n' +
							'NEVER "now". Collapsing due times onto one instant piles every accelerated row onto one ' +
							'minute (before v0.93.0 that pile also slowed the index claim scan 32x).\n\n' +
							'MUST BE >= `queue.jobLeaseTime`, and a smaller value is reported as a config warning and ' +
							'then clamped up to it — because a narrow window is a smaller version of the same pile, not ' +
							'because the two quantities are coupled. `queue.jobLeaseTime` is floored at 2 minutes, which ' +
							'makes it the smallest spread this system already trusts. (Overwriting a render in flight is a ' +
							'DIFFERENT hazard and is closed elsewhere, exactly: the accelerator refuses outright when any ' +
							'device key of the URL holds a live claim lease.)',
						{ unit: 'ms', min: 0 }
					),
					crossNode: group(
						'FORWARD A HEAL TO THE KEY\u2019S OWNER instead of discarding it. Without this, a heal is refused ' +
							'outright whenever the crawler landed on a node that does not own the key by residency \u2014 measured ' +
							'at 84-85% of all attempts on a four-node deployment, because bot traffic lands where the CDN\u2019s ' +
							'geo-routing sends it while residency is hashed over the key, and the two are independent. The ' +
							'module\u2019s "crawlers revisit" fallback assumes those two distributions match; where traffic is ' +
							'concentrated on one node they do not, and a quarter of the corpus never heals on demand at all.\n\n' +
							'THE OWNER DECIDES, this only carries the request. Three of the accelerator\u2019s guards \u2014 the live-lease ' +
							'check, the authoritative schedule read, and therefore "never raise a due time" \u2014 can only be ' +
							'evaluated on the owner, so writing from the receiving node instead would trade coverage for ' +
							'delayed renders.\n\n' +
							'COST IS BOUNDED BY `maxPerMinute`, NOT BY TRAFFIC: the slot is reserved before the call, so this ' +
							'is at most that many requests per node per minute however much bot traffic arrives.\n\n' +
							'REQUIRES `peerRescue.token` and `peerRescue.header`, reusing that shared cluster secret rather ' +
							'than minting a second one \u2014 same trust boundary (node-to-node, on the serve path, with no user ' +
							'credential available to forward), and one secret to rotate instead of two. With either unset this ' +
							'is inert and the endpoint answers 404.',
						{
							enabled: option(
								false,
								'Off by default, like the accelerator itself. While off, a heal for a key this node does not own ' +
									'is refused as `not-owner` exactly as before, and the `/prerender_peer/heal` endpoint does not ' +
									'exist.'
							),
							timeoutMs: option(
								2000,
								'Deadline for one forwarded heal. Generous is pointless here: the request that triggered it has ' +
									'already been answered, this is a repair running detached, and a peer that cannot answer in ' +
									'seconds will not heal anything useful. A timeout is counted as `forward-failed`.\n\n' +
									'Capped at the 32-bit signed maximum because this value reaches `setTimeout`: past that Node ' +
									'emits TimeoutOverflowWarning and fires the timer IMMEDIATELY, so a fat-fingered value would ' +
									'abort every forwarded heal on the spot rather than allowing a long one. The cap turns that ' +
									'into a rejected value that keeps the default.',
								{ unit: 'ms', min: 1, max: 2147483647 }
							),
						}
					),
					maxPerMinute: option(
						10,
						'Per-node ceiling on accelerated REQUESTS per minute, shared across every worker on the node ' +
							'(one minute-bucketed counter in a shared buffer). One accelerated request writes at most one ' +
							'schedule row per schedule row the URL has — normally just its URL row; plus any pre-0.66.0 ' +
							'per-device row that has not yet converted, and a per-device row for the served device when ' +
							'that one is merely `supported` — so the write ceiling is this number times those rows.\n\n' +
							'Sized so its CEILING is defensible, not just its typical. 10/min/node is 14,400 ' +
							'requests/node/day ≈ 14,400 schedule writes ≈ 1.2MB of audit/node/day once the corpus holds one ' +
							'row per URL (it was ~28,800 writes / 2.3MB at one row per device), and each write is a job that ' +
							'renders every device — about 7% of measured spare fleet render capacity (~792,700 renders/day ' +
							'spare against a 1,710,936/day ceiling and ~918,000/day of baseline cadence demand) — against a ' +
							'measured demand of roughly 1,000 owner-node candidate requests/day CLUSTER-WIDE, i.e. ~14x ' +
							'headroom. Raising it toward 120 would authorise ~87% of all spare fleet capacity, which is why ' +
							'it is not the default.',
						{ min: 1 }
					),
				}
			),
		}
	),

	changeProbe: group(
		'CHANGE-DRIVEN RE-RENDERING. Instead of guessing how often a page changes with an interval, ask ' +
			'the origin — cheaply — whether the fields bots care about actually changed, and re-render only ' +
			'then. A probe is one small HTTP request per URL: either an endpoint the page itself consults ' +
			'(`source: request` — e.g. a product price/availability API, typically thousands of times ' +
			'cheaper than a render), or the page document’s own schema.org JSON-LD Product offers ' +
			'(`source: document` — nothing site-specific to configure). The extracted fields are reduced to ' +
			'a signature stored on the target; a later probe that observes a different signature expires the ' +
			'cached pages and files the URL due now.\n\n' +
			'TWO CADENCES FOR TWO KINDS OF CHANGE. The rolling SWEEP (sweepInterval) walks the whole ' +
			'registry and catches continuous, per-URL drift — availability sell-through, item-level price ' +
			'moves. The CANARY (canary.*) probes a small fixed cohort every few minutes, because commerce ' +
			'price does not drift — it STEPS at promotional events, most of a catalog at once, which a ' +
			'sample of hundreds sees within minutes while a full sweep is still hours away. On a canary ' +
			'trip the rule’s `invalidateScope` records a bulk invalidation: pre-change snapshots stop ' +
			'serving immediately (bots get origin content, which is correct by definition) while ' +
			're-renders refill on their own machinery. Detection and response are different mechanisms on ' +
			'purpose — re-rendering a large corpus takes the fleet hours; invalidating it takes one row.\n\n' +
			'A PROBE FAILURE CHANGES NOTHING, by design: fetch errors, non-2xx, unparseable bodies and ' +
			'extractions that yield no values leave the stored signature untouched and trigger nothing. ' +
			'The probe is an accelerator on top of the baseline render cadence, never a gate on it — the ' +
			'failure mode to survive is the origin replatforming under a rule, which surfaces as a high ' +
			'probe_failed share and a loud log line, not as schedule churn. Probes run owner-scoped on ' +
			'worker 0 of every node (each node probes the URLs it owns), carry the security token like every ' +
			'other origin fetch but their own User-Agents (`userAgents`, `HarperProbe/1.0`), and are ' +
			'rate-capped per node — AGREE THE RATE ' +
			'WITH WHOEVER RUNS THE ORIGIN before enabling a sweep over a large corpus: probe endpoints ' +
			'are typically uncached, so every request is origin backend work.',
		{
			enabled: option(false, 'Master switch. Off = no probes, no timers, nothing stored.'),
			dryRun: option(
				true,
				'Probe, count and log every decision — but re-render nothing and invalidate nothing. ' +
					'Signatures ARE written in dry run (the demand-ladder precedent), so each pass reports fresh ' +
					'changes and a measured week converges on the true change rate instead of re-reporting the ' +
					'same delta. Default ON: enabling `enabled` alone changes no schedule until this is turned off.'
			),
			rules: option(
				[],
				'What to probe and how — an array of rule objects; the FIRST rule whose pathPattern matches a ' +
					'target’s URL path claims it (order most-specific first). Invalid rules are dropped ' +
					'individually with a warning, like ingress.routes entries.\n\n' +
					'Rule shape:\n' +
					'  pathPattern      (required) regular expression matched against the URL path; capture ' +
					'groups feed the template.\n' +
					'  source           "document" (default): GET the page itself and extract its JSON-LD ' +
					'Product offers (price, currency, availability) — generic, works for any site with ' +
					'standard product markup. "request": probe a configured endpoint instead.\n' +
					'  request.urlTemplate  (request mode, required) absolute URL with $1..$9 replaced by ' +
					'pathPattern’s capture groups, URI-component-encoded. The origin security token and the ' +
					'staging-IP pin are attached ONLY when this endpoint shares the probed page’s origin — a ' +
					'third-party host gets a plain fetch, never the bypass secret. Redirects are not followed ' +
					'(a redirecting endpoint is a failed probe, and the failure metrics say so).\n' +
					'  request.method   GET (default) | POST.\n' +
					'  request.headers  extra request headers, e.g. { accept: "application/json" } — many JSON ' +
					'endpoints require an explicit accept and fail with a 200-shaped error without it.\n' +
					'  request.body     request body string (e.g. "{}").\n' +
					'  extract          (request mode, required) value paths into the JSON response, e.g. ' +
					'"payload.products[0].prices[0].salePrice" — the extracted values ARE the watched content; ' +
					'everything else in the response is ignored. A path may end at an object or array, which is ' +
					'signed whole, and `[*]` projects the rest of the path over every element of an array ' +
					'("payload.products[0].variants[*].availability" -> one value per variant) — the way to watch ' +
					'per-variant state without signing fields that move on their own ' +
					'(inventory counters, store data). A trailing tuple, `[*].{a,b.c}`, projects each element to ' +
					'`[a, b.c]` (dotted inner paths, no brackets) so per-variant fields stay attached to their key — ' +
					'e.g. "payload.products[0].variants[*].{sku,availability,price.value}" for a `skus` page check. ' +
					'Projections (tuples included) are sorted, so a reordered array is not a change. An extraction where every path yields null is a ' +
					'FAILED probe, never a new signature, so an endpoint shape change cannot mass-trigger.\n' +
					'  EDITING A RULE. The rule’s observation (endpoint, method, headers, body, extract, ' +
					'statusSignals) is fingerprinted and stored beside every baseline. Change any of it and each ' +
					'matched URL is RE-BASELINED on its next probe — new observation stored, nothing compared, ' +
					'nothing triggered, not counted by the canary — instead of the new signature shape reading as ' +
					'100% of the corpus changing at once. A rule edit therefore costs one pass without detection ' +
					'for that rule and needs no dry-run cycle. APPENDING paths to the end of `extract` is the ' +
					'exception and costs no blind pass: a baseline taken before the append is still compared on ' +
					'the slots it has — changes trigger, pageCheck applies, the canary counts it — and the same ' +
					'write upgrades it to the full observation (counted as `extended` in the pass record). The ' +
					'appended path has no baseline until that write, so a change in it alone is detected from ' +
					'the following pass. Removing, reordering or editing an existing path, or appending while ' +
					'changing anything else above, is a full re-baseline. Label, pathPattern, invalidateScope ' +
					'and pageCheck are not part of the fingerprint: they change what is matched or done, not ' +
					'what is observed.\n' +
					'  statusSignals    optional [{ status, signature, contains? }] — statuses this endpoint uses ' +
					'to SAY something rather than to fail, mapped to a fixed signature. An endpoint that answers ' +
					'a legitimate state with an error status (most usefully "no longer available" as a 4xx with ' +
					'a code in the body) is otherwise read as a failed probe, which leaves the signature ' +
					'untouched and triggers nothing — so the one transition that most needs detecting, ' +
					'available -> unavailable, is exactly the one the probe cannot see. The signature is an ' +
					'opaque literal compared for equality like any other, so the transition is detected in BOTH ' +
					'directions. `contains` guards on a body substring (match the endpoint’s error CODE, not its ' +
					'prose, which gets reworded). Only non-2xx statuses may carry a signal; a 2xx is extracted ' +
					'normally. A declared signal outranks the origin-pushback classification, so do not declare ' +
					'one for 429/503 unless that status really is a state on this endpoint rather than an ' +
					'overloaded origin. CAUTION: if the endpoint starts answering the signaled status for ' +
					'EVERYTHING, every matched URL flips to the same signature at once and is acted on, and the ' +
					'canary treats it as the mass change it looks like.\n' +
					'\n\nPAGE CHECK (`pageCheck`). The comparison above asks "did the origin change since I last ' +
					'looked", which is structurally blind to a value that changes and changes BACK between two ' +
					'passes — and if a render landed inside that window, the cached page keeps the transient value ' +
					'until its interval expires (measured at ~2.7% of served product pages on one deployment, all ' +
					'of them a page reading OutOfStock for something the origin says is available). Set ' +
					'`pageCheck: { enabled: true, priceFrom: <i>, availableFrom: <i> }` and the render path records ' +
					'what each page CLAIMS, so the pass can also ask "does the page still agree with the origin". ' +
					'The two indices are positions in this rule\u2019s own `extract` array — site-specific by ' +
					'nature, since only the operator knows which field is the price their page prints — and the ' +
					'block is dropped whole if either is out of bounds, because a half-applied mapping compares the ' +
					'wrong column. REQUIRES @harperfast/prerender-browser >= 1.20.0, which posts the page\u2019s offers ' +
					'with the render result: there is deliberately NO fallback to parsing the stored HTML (a regex scan ' +
					'and JSON parse of a ~1MB document on the hottest write path, to recover what the browser already ' +
					'had structured), so against an older renderer pageCheck records nothing and detects nothing \u2014 ' +
					'logged hourly rather than failing silently. `source: request` only: in document mode the stored signature already IS the ' +
					'page\u2019s offers. A page yielding no Product offers records nothing, exactly as a failed ' +
					'probe changes nothing, so a markup change cannot make every page look like a disagreement \u2014 ' +
					'and each dimension compares only when BOTH sides make a readable claim (availability must ' +
					'reduce to a recognized schema.org verdict on the page, and at the endpoint to a boolean, an ' +
					'availability word, or a `[*]` list of per-variant words; price must parse as a number on the ' +
					'page), so an unrecognized vocabulary or price format degrades to detecting nothing rather ' +
					'than expiring everything. Availability words are matched after dropping case and separators ' +
					'(InStock, IN_STOCK, "In Stock" and https://schema.org/InStock are one word); the built-in ' +
					'vocabulary is Google’s (InStock, InStoreOnly, OnlineOnly, LimitedAvailability, Available / ' +
					'OutOfStock, SoldOut, Discontinued, Unavailable), and `pageCheck.availableValues` / ' +
					'`pageCheck.unavailableValues` (arrays of words) extend or override it per rule for an endpoint ' +
					'with its own vocabulary. A per-variant list reads in stock when ANY variant is, exactly as the ' +
					'page’s offers are read. ' +
					'Detection is one extra node-local write per render and no extra origin traffic.\n' +
					'\n\nTHE PAGE RECORD (`pageCheck.fields`). The claim pair above generalizes to every field a page ' +
					'visibly states. With @harperfast/prerender-browser >= 1.37.0 each render also posts `pageFacts` ' +
					'(canonical, title, metaDescription, h1, product.name, product.brand, product.image, ' +
					'product.rating.value, product.rating.count, product.offers, breadcrumbs), and a rule that maps ' +
					'fields stores them per URL and compares each mapped field on every probe. That does three things: ' +
					'(1) a page that DISAGREES with the origin on any mapped field is re-rendered, like a claim-pair ' +
					'disagreement; (2) an origin CHANGE that the cached page already shows (a cadence render landed after ' +
					'it) is NOT re-rendered — every changed slot must be a mapped slot whose record agrees with the new ' +
					'value, and the baseline simply moves (counted `caughtUp`); (3) with `ignoreChanges`, changes to ' +
					'fields the page cannot show stop re-rendering at all. Shape: `pageCheck: { enabled: true, ' +
					'fields: [{ slot: <i>, fact: "<fact>", compare: "<comparator>" }, ...], ignoreChanges: [<i>, ...] }` ' +
					'(both, like the claim pair, apply only while `enabled` is true), where `slot` indexes ' +
					'`extract`. A field may carry `pathPattern` (a regular expression on the URL path, like the ' +
					'rule\u2019s own): it is then compared only on the URLs that match, and is no claim at all on the ' +
					'rest \u2014 for an endpoint that states one page type faithfully and another with a placeholder ' +
					'(a collection page whose endpoint title is the site name: `pathPattern: "^/product/prd-(?!c)"`). ' +
					'The comparators are a closed set, each applying to certain facts: ' +
					'"text" (exact after Unicode NFC, whitespace collapse and trim — no case folding and NO HTML ' +
					'stripping: an endpoint’s description may carry markup the page’s meta tag repeats verbatim), ' +
					'"path" (URL path only — origin, query and fragment ignored, a relative value resolved against the ' +
					'page URL; for canonical and product.image, whose URLs typically differ by size parameters alone), ' +
					'"number" (numeric equality, "4.0" = 4; optional `tolerance`), "priceSet" (against the SET of prices ' +
					'the page’s offers print: a single endpoint price must be among them, and for a list EVERY price ' +
					'the page prints must still be in the endpoint’s set — not equality, so a page that lists only some ' +
					'variants cannot disagree forever; use "skus" for per-variant exactness), "names" (an ordered list of ' +
					'strings, or of objects carrying `nameKey`, default "name", matched against the TAIL of the page’s ' +
					'breadcrumbs — a leading home crumb needs no configuration; extract the list itself, not a `[*]` ' +
					'projection, since projections are sorted) and "skus" (per-variant tuples from a `[*].{…}` projection ' +
					'against the page’s offers keyed by SKU, over the SKUs both list; `tuple` names each tuple ' +
					'position, default ["sku", "availability", "price"]). EVERY COMPARATOR FAILS TOWARD NO CLAIM: null, ' +
					'absent or unparseable on either side is not compared, never a disagreement, and never evidence ' +
					'that a page caught up. A bad entry is dropped alone with a warning. A mapping that is wrong anyway ' +
					'is caught by `changeProbe.mappingGuard`. The record is stored only for a rule that maps fields, ' +
					'from the first device variant, and only when the render stored every default device (otherwise ' +
					'null — a partial render cannot vouch for the device page it did not replace); records over 16 KB ' +
					'are refused, not truncated. `pageCheck` may carry `fields` and/or `ignoreChanges` without ' +
					'priceFrom/availableFrom. Like the rest of pageCheck, none of this is in the rule fingerprint: ' +
					'adding or editing a mapping re-baselines nothing.\n' +
					'  pageCheck.ignoreChanges  extract indices whose origin changes never trigger a re-render — ' +
					'fields the page cannot show (an inventory counter the endpoint returns beside the price). A change ' +
					'confined to them writes the new baseline and triggers nothing (counted `ignored`), and the canary ' +
					'does not count it as a change, so a site-wide edit of such a field cannot trip a bulk ' +
					'invalidation. A status-signal literal is a state, not slots, and is never ignored.\n' +
					'  pageCheck.offersLimit  the most offers the origin’s structured data lists on one page, when it ' +
					'caps them (default null: it lists every variant). A page listing exactly this many may leave out ' +
					'the variant that carries the endpoint’s price, so a SINGLE endpoint price absent from it — the ' +
					'claim pair’s, or a "priceSet" field on a scalar slot — is no claim rather than a disagreement, and ' +
					'never proof the page is current either (no verification, no check, no caught-up: a page whose listed ' +
					'prices are all stale misses the price the same way); a price it does list still agrees. Exactly, not ' +
					'at least: the claim counts every Product offer on the page, and several products past the cap ' +
					'between them were each listed in full. Without it such a product disagrees on every pass and its re-render ' +
					'lists the same offers again (measured on one origin capped at 50: most single-price disagreements ' +
					'were exactly this). List "priceSet" fields and "skus" compare what the page lists already. To find ' +
					'the cap, count the Product offers on a product with many variants against the endpoint’s variant ' +
					'list. A claim recorded by an older release carries no offer count and compares as before until ' +
					'its page is re-rendered.\n' +
					'  PER-SLOT STATS. Pass records decompose `changed` by slot (`slotChanges`) and page mismatches by ' +
					'mapped field (`fieldMismatch`), in `GET /prerender_admin/change-probe` and the pass log line.\n' +
					'  invalidateScope  optional invalidation scope ("all" or "route:<match>:<path>") the canary ' +
					'records on a mass change. Empty = the canary detects and logs only.\n' +
					'  label            optional name for logs and the admin surface.',
				{ itemType: 'object' }
			),
			mode: option(
				'interval',
				'How the sweep is scheduled.\n\n' +
					'"interval" (default) fires a discrete pass every `sweepInterval`. That model asks the ' +
					'operator to solve `sliceSize / effectiveRate <= sweepInterval` BY HAND, and to re-solve ' +
					'it every time the corpus grows or the origin has a bad week — because when the answer ' +
					'stops holding, the overrunning pass is simply skipped (`sweepRunning` is still set) and ' +
					'the cadence silently doubles with nothing in metrics saying so. It also idles: a slice ' +
					'that takes 9h of a 12h interval leaves 3h in which nothing is probed at all, so ' +
					'detection latency is bimodal rather than uniform.\n\n' +
					'"continuous" never stops walking and never re-solves anything: it derives its rate each ' +
					'batch from remaining rows over remaining budget (`cycleTarget`), so corpus growth and ' +
					'time lost to backoff are absorbed as they happen. `ratePerSecond` stays a hard ceiling. ' +
					'A target that cannot be met at the ceiling is reported (`probe_cycle_behind`) rather ' +
					'than silently missed — which is the whole point of the mode.\n\n' +
					'"anchored" runs ONE full pass a day, starting at `anchorTime` in `anchorTimezone` and ' +
					'paced to `anchorWindow` (0 = as fast as `ratePerSecond` allows). For an origin whose content ' +
					'moves on a schedule — a retailer whose prices change only at its own midnight — this puts ' +
					'the walk right after the change instead of spreading it over the day, so detection latency ' +
					'is the pass length rather than up to a cycle, and the corpus is current for the day by the ' +
					'time the pass ends. A restart does not start a pass of its own in this mode (baselines ' +
					'persist): it RESUMES a pass it cut short from the walk cursor, and CATCHES UP the pass for an ' +
					'anchor it was down for (no acting pass started since the most recent anchor). An anchor that ' +
					'fires while another sweep holds the node interrupts a dry run or a reseed, and waits for any ' +
					'other pass and runs after it — never skipped silently (`probe_anchor`). The canary keeps its ' +
					'own cadence, so an off-schedule mass change is still caught; only the full walk is anchored.\n\n' +
					'Switching is safe in every direction and takes effect on the next config apply; a pass ' +
					'in flight finishes under the rules it started with.',
				{ enum: ['interval', 'continuous', 'anchored'] }
			),
			anchorTime: option(
				'00:15',
				'ANCHORED MODE ONLY: local time of day ("HH:MM") the daily pass starts, interpreted in ' +
					'`anchorTimezone`. Put it just AFTER the origin’s scheduled change lands (a few minutes ' +
					'after its midnight, not at it) so the first probes see the new state rather than the ' +
					'tail of the old one.',
				{ nonEmpty: true }
			),
			anchorTimezone: option(
				'UTC',
				'IANA timezone `anchorTime` (anchored mode) and the `canary.schedule` windows are interpreted in.',
				{ nonEmpty: true }
			),
			anchorWindow: option(
				0,
				'ANCHORED MODE ONLY: wall-clock budget the daily pass paces itself to, like `cycleTarget` ' +
					'for one pass. 0 (default) runs at the `ratePerSecond` ceiling and finishes as early as the ' +
					'agreed rate allows; set it to spread the pass deliberately (e.g. 6h) when the origin would ' +
					'rather see a lower steady rate than a short burst.',
				{ unit: 'ms', min: 0 }
			),
			sweepInterval: option(
				DAY,
				'How often each node walks its slice of the registry probing every matched URL. ' +
					'INTERVAL MODE ONLY — ignored when `mode` is "continuous", where `cycleTarget` sets the ' +
					'cadence and there is no gap between passes to schedule.',
				{
					unit: 'ms',
					min: MINUTE,
					// setInterval stores its delay as a signed 32-bit int; past this it fires immediately
					// and the sweep hot-loops (the page.blobReadBudgetMs lesson).
					max: 2147483647,
				}
			),
			cycleTarget: option(
				DAY,
				'CONTINUOUS MODE ONLY: the wall-clock budget for covering every owned, matched URL once — ' +
					'i.e. the worst-case detection latency you are asking for. The pass paces itself to land ' +
					'on it: remaining rows over remaining budget, recomputed every batch.\n\n' +
					'This is a TARGET, never a licence. `ratePerSecond` is the ceiling agreed with whoever ' +
					'runs the origin and is never exceeded to hit a target, so an unreachable one is missed ' +
					'openly — every batch that wants more than the ceiling counts a `probe_cycle_behind`, and ' +
					'a sustained count means the corpus has outgrown its agreed rate and wants a longer ' +
					'target or a conversation about the ceiling.\n\n' +
					'THE FIRST CYCLE AFTER A RESTART RUNS AT THE CEILING. Pacing needs a denominator and the ' +
					'slice size is only known once a cycle has finished counting it; a cycle target cannot be ' +
					'honoured against an unknown corpus, and guessing one would pace to a fiction. So the ' +
					'first cycle measures, and every cycle after it paces.',
				{ unit: 'ms', min: MINUTE }
			),
			ratePerSecond: option(
				10,
				'Sustained probe-request ceiling per node. THE ORIGIN-PROTECTION KNOB: probe endpoints are ' +
					'typically no-store, so every probe is backend work for the origin — size this with the ' +
					'origin’s operator, not from what the fleet can send. Also what sizes a sweep: a 200k-URL ' +
					'node slice at 10/s is ~5.6h per pass.',
				{ min: 1 }
			),
			concurrency: option(
				4,
				'Probe requests in flight at once per node. Bounds burstiness within the rate cap — the pacing ' +
					'holds the sustained rate to ratePerSecond whatever origin latency does.',
				{ min: 1 }
			),
			scope: option(
				'all',
				'Which targets the sweep and the canary probe.\n\n' +
					'"all" (default) probes every owned, rule-matched target, however it entered the registry.\n\n' +
					'"listed" probes a target only while a sitemap lists it (`sitemapUrl` set) or for ' +
					'`unlistedGrace` after a walk unlinked it (`Target.unlistedAt`). Targets no sitemap has listed ' +
					'(discovered from traffic), targets unlinked longer ago than the grace, and targets unlinked ' +
					'before v0.89.0 (which carry no stamp) are skipped and counted as `outOfScope` in the pass ' +
					'stats — the origin requests saved per pass. The canary cohort is built from, and re-checked ' +
					'against, the same selection. Suppressed targets are skipped under either scope, as always.\n\n' +
					'ONLY SAFE WHERE THE SITEMAP IS THE AVAILABILITY FEED AND DEPARTURE IS ARMED. On a catalog ' +
					'whose product sitemap drops an item the day it sells out, the departure check ' +
					"(`ingress.routes[].departureAction: 'render'` with `sitemap.departure.dryRun: false`) already " +
					'expires and re-renders that page, so probing the unlisted long tail buys little. Anywhere else ' +
					'this simply stops watching those pages: an unlisted page whose price or availability changes ' +
					'keeps its snapshot until its cadence render. A config warning names the case where no route ' +
					'has departure armed, and a pass that skips more rule-matched targets than it probes logs a ' +
					'warning (most of the watched corpus not being in any sitemap is either a site this setting is ' +
					'wrong for, or sitemaps that stopped listing what they used to).\n\n' +
					'A FAILED sitemap walk cannot shrink the scope — it unlinks nothing. A child sitemap that parses ' +
					'but is truncated can, once it has stayed truncated for longer than the grace. Switching to ' +
					'"listed" in continuous or anchored mode paces its first cycle against the old, larger slice, ' +
					'so that cycle finishes early; the next one paces to the real slice.',
				{ enum: ['all', 'listed'] }
			),
			unlistedGrace: option(
				2 * DAY,
				'SCOPE "listed" ONLY: how long after a sitemap walk unlinks a target it is still probed. A URL ' +
					'briefly missing from one walk (a truncated child sitemap, an origin rebuilding its sitemaps) ' +
					'keeps being watched while later walks decide whether it really left, and a real departure is ' +
					'still probed while its re-render lands. Measured from the start of the walk that unlinked it. ' +
					'0 probes only currently-listed targets.',
				{ unit: 'ms', min: 0 }
			),
			reprobeAfter: option(
				12 * HOUR,
				'RETIRED in v0.97.0 — accepted so existing configs and overrides stay valid, read by nothing. It ' +
					'skipped a URL whose stored baseline was younger than this, meant to spare a restarted pass the ' +
					'ground it had covered. But a baseline is only WRITTEN on a change, a seed or a re-baseline — an ' +
					'unchanged probe writes nothing — so the age test skipped exactly the URLs that had recently ' +
					'CHANGED and never the quiet ones: a change caught by an off-schedule pass was then skipped by the ' +
					'next scheduled pass, and a reprice landing in between waited a further full pass. A pass now ' +
					'skips only URLs written since IT (or the pass it resumes) began, which needs no setting, and an ' +
					'interrupted anchored pass resumes from its walk cursor. The canary never skipped and still does ' +
					'not. Remove it from config at leisure.',
				{ unit: 'ms', min: 0 }
			),
			backoffMax: option(
				64,
				'How far the pacing window may stretch when the origin pushes back, as a multiple of the ' +
					'normal window. `ratePerSecond` is sized with the origin’s operator for a HEALTHY origin ' +
					'and says nothing about one having a bad afternoon; a sweep that holds its configured rate ' +
					'through 429s and 503s adds load to something already failing. On any batch containing a ' +
					'pushback response (429/502/503/504, connect or read timeouts) the window doubles; on a ' +
					'clean batch it halves back toward normal — immediate response, gradual recovery. An ' +
					'explicit `Retry-After` outranks the computed wait. At the default the probe can slow ' +
					'itself to ~1/64th of its configured rate before giving up. 1 disables backoff.',
				{ min: 1 }
			),
			load: group(
				'The LOCAL-load governor: slow the probe when the node it runs ON is struggling, not just ' +
					'when the origin it probes is.\n\n' +
					'The origin backoff cannot see this class of trouble at all. A node losing its event loop ' +
					'to the serve path returns no 429s and no timeouts, so the probe reads a perfectly healthy ' +
					'origin and holds its configured rate straight through the congestion it is adding to. ' +
					'That is survivable for a bounded pass that ends; it is not for a continuous one that ' +
					'never does, which is why this exists and why it belongs with `mode: continuous`.\n\n' +
					'OFF BY DEFAULT, AND DELIBERATELY SO IN INTERVAL MODE. In interval mode a governor that ' +
					'slows the pass can push it past `sweepInterval`, where it is silently skipped and the ' +
					'cadence halves — so a safety feature would degrade the cadence invisibly. Continuous ' +
					'mode has no window to overrun: a slowdown just shows up as `probe_cycle_behind`. Turn ' +
					'this on there.',
				{
					enabled: option(false, 'Master switch for the local governor. Off = the lag is never read.'),
					lagThreshold: option(
						50,
						'p95 event-loop delay ABOVE the sampling floor, over one batch, past which the pacing ' +
							'window widens (and under which it recovers). The floor is subtracted for you — the ' +
							'raw histogram reads back at roughly its own resolution on a completely idle loop, so ' +
							'a threshold compared against the raw number would be resolution-dependent and trip on ' +
							'an idle node (see util/loopLag.js). Measured for calibration: an idle worker reads ' +
							'~1ms of excess; one held in 40ms synchronous blocks reads ~41ms. The default sits ' +
							'well clear of idle noise and well under the multi-second native stalls that actually ' +
							'hurt the serve path.\n\n' +
							'p95 rather than mean ON PURPOSE: what costs a served request is the tail — one long ' +
							'synchronous call — and a mean over one batch dilutes exactly that into nothing.',
						{ unit: 'ms', min: 1 }
					),
					backoffMax: option(
						8,
						'How far local pressure alone may stretch the pacing window, as a multiple. Lower than ' +
							'the origin `backoffMax` (64) because the failure modes are not comparable: an origin ' +
							'shedding load wants to be left alone almost entirely, whereas a busy node still has ' +
							'to make progress on the corpus — a probe that stalls out completely stops bounding ' +
							'staleness, which is a different way to serve wrong prices. 1 disables the governor ' +
							'while still reading the lag (useful for sizing the threshold before arming it).',
						{ min: 1 }
					),
					resolution: option(
						10,
						'Sampling resolution of the event-loop histogram. Also its noise floor, which is why it ' +
							'is subtracted from every reading. Finer resolution samples more often for a slightly ' +
							'tighter floor; there is little reason to move it.',
						{ unit: 'ms', min: 1, max: 1000, scope: 'restart' }
					),
				}
			),
			abortAfterDistress: option(
				50,
				'Consecutive pushback/timeout responses that end the pass. An origin refusing this many in a ' +
					'row is down rather than busy, and backing off further only crawls a doomed pass into the ' +
					'next one’s window while holding the sweep lock. The next scheduled pass is the retry and ' +
					'it starts clean. 0 disables the circuit breaker.',
				{ min: 0 }
			),
			chunkSize: option(
				2000,
				'Registry rows collected per read transaction during a sweep. Each chunk’s cursor opens, ' +
					'fills, and closes BEFORE any probe or write runs — a paced pass takes hours and no read ' +
					'transaction may live anywhere near that long (see the scan group).',
				{ min: 10 }
			),
			trigger: group(
				'What a detected change does, and how many at once. A change is ACTED ON WHEN IT IS FOUND: the ' +
					'cached pages are hard-expired (the probe knows they are wrong, so one more serve is a served ' +
					'mismatch) and the render is filed at the current minute, marked on the schedule row ' +
					'(`changedAt`) so the render queue ranks it `queue.ready.changedHeadStart` cadences ahead of ' +
					'routine rotation. Nothing detected is deferred and there is no per-pass budget: the render ' +
					'queue orders the work, and the render fleet\u2019s capacity bounds how fast changed pages ' +
					're-render, not how fast a known-wrong page stops being served (util/changeActions.js).\n\n' +
					'Actions run BESIDE the walk rather than inside it, so the pass runs at its probe rate ' +
					'whatever the change rate: awaiting them in the row handler once took a pass from 9.2h to a ' +
					'projected ~21h, and pass duration is detection latency. The new baseline is written only ' +
					'after its action succeeds, so a failure or a restart leaves the change detectable.',
				{
					concurrency: option(
						8,
						'Actions in flight at once. When every slot is busy the pass waits for one (backpressure) ' +
							'rather than refusing the change, so this bounds the database load a change wave puts on ' +
							'the node — each action is a read and a patch per device page plus the schedule and ' +
							'baseline writes — never how much of the wave is acted on.',
						{ min: 1 }
					),
				}
			),
			renderCheck: option(
				true,
				'Check each render against the probe’s last observation of the origin as it lands (rules with the ' +
					'`pageCheck` price/availability pair only). A page whose claim DISAGREES with the stored endpoint ' +
					'signature is SUSPECT, and ONE confirming probe of that URL decides: if the origin, asked again, also ' +
					'disagrees with the page, the page is hard-expired and its render re-filed ahead of rotation, exactly ' +
					'as a detected change is; if it agrees (the origin moved since the probe last looked, and the render ' +
					'shows it), the baseline is updated and nothing is expired. It catches a render claimed before a ' +
					'probe found a change and landing after it, and a render that captured a stale CDN or origin copy — ' +
					'pages the pass would otherwise not look at again until its next run. No request is made when the ' +
					'origin is known to have moved since the probe last observed the URL (the most recent anchor in ' +
					'anchored mode, an active invalidation’s trip): the pass will compare that page itself. One ' +
					'confirmation per stored observation bounds a page that disagrees every time. The confirming ' +
					'requests come out of the SAME node-wide `ratePerSecond` budget as the sweep — only the headroom a ' +
					'running sweep leaves (none while it runs at the ceiling or the origin pushes back; all of it when ' +
					'no sweep runs) — and are shed, left to the pass, when the next slot is over a minute away. Dry run ' +
					'counts only and asks nothing. Outcomes are ' +
					'`probe_render_mismatch`. Costs no read, write or request on a render that agrees.'
			),
			serveCheck: group(
				'CHECK A CACHED PAGE AGAINST THE ORIGIN WHEN A BOT ASKS FOR IT (util/serveCheck.js), default off. ' +
					'A page served from cache that has not been checked since the last anchor (`anchorTime`, the ' +
					'nightly update), or, for the `sample` of URLs, within `maxAge`, is served as usual and ONE ' +
					'check is queued in the background (stale-while-revalidate): the rule\u2019s endpoint for a URL a ' +
					'`pageCheck` rule matches, or the document itself on a route with `documentCheck`. It is ' +
					'compared with what the page actually served claims, read off the served bytes ' +
					'(util/documentFacts.js), with the same comparators the sweep uses. Every verdict is recorded ' +
					'(`PageCheck`, replicated, so no node asks again about that page in the window); a ' +
					'disagreement expires the page and re-files its render exactly as a detected change does. The ' +
					'same disagreement again on a page rendered after it, the origin unchanged, is systematic, not a ' +
					'change: it is held (`serve_check` held) and not re-rendered again.\n\n' +
					'Nothing waits on it: the read, the scan and the queueing happen after the response, and the ' +
					'request itself runs on the node-wide probe budget, paused node-wide while the origin pushes ' +
					'back. While it is armed a pass leaves the checks what they are using (up to `share` of ' +
					'`ratePerSecond`; all of it when no pass runs), so the total stays at `ratePerSecond`, and the ' +
					'sweep skips every URL a check observed exactly as its baseline stands since the pass began, so ' +
					'the anchored round costs the origin no more than the pass did, ordered by demand instead of by ' +
					'key. `maxAge` re-checks cost what they cost: up to one request per requested page per window. ' +
					'Raw documents with stored facts (`rawFacts`) are checked the same way, and a disagreeing one is ' +
					'deleted. The probe\u2019s own `dryRun` keeps these dry too.\n\n' +
					'`dryRun` counts what WOULD be checked (`serve_check` would-check, and its distinct URLs as the ' +
					'`would-check` series of `/prerender_admin/crawl-breadth`) and asks nothing.',
				{
					enabled: option(false, 'Master switch. Off: nothing is read, queued or asked.'),
					dryRun: option(
						true,
						'Count the checks that would run (`serve_check` outcome `would-check`, by source) and their ' +
							'distinct URLs, and make no request, write or expiry.'
					),
					maxAge: option(
						12 * HOUR,
						'Re-check a page whose last check (or render) is older than this, even within one anchor ' +
							'window, for the `sample` of URLs. 0 = only once per anchor window.',
						{ unit: 'ms', min: 0 }
					),
					sample: option(
						1,
						'The fraction of URLs (stable, by hash) the `maxAge` re-check applies to. The anchor check ' +
							'applies to every URL. Lower it to measure the intra-day change rate on a cohort before ' +
							'paying for it everywhere.',
						{ min: 0, max: 1 }
					),
					bots: option(
						['*'],
						'Bots whose requests may trigger a check, by the same names and rules as ' +
							'`ingress.discoveryBots`. Every bot by default: a crawler that does not matter for ' +
							'shopping still refreshes a page before one that does asks for it.'
					),
					share: option(
						0.5,
						'Of the node\u2019s `ratePerSecond`, the most a running pass leaves to these checks (and the ' +
							'render re-check). It leaves what they USE \u2014 their rate over the last few seconds, at ' +
							'least a tenth of the ceiling, and twice that rate only while checks are WAITING for budget ' +
							'\u2014 so a quiet afternoon costs the pass about 10%, a burst of due pages at the anchor ' +
							'gets up to this share within seconds, and checks held back by something other than the ' +
							'budget leave the pass the rest instead of idling it. A pass never runs below 1 request/s, ' +
							'so below a `ratePerSecond` of 2 it leaves nothing and checks wait for the pass to end.',
						{ min: 0, max: 1 }
					),
					maxPending: option(
						1000,
						'Checks queued per worker before more are dropped (`busy`). A dropped check is asked again ' +
							'by the next request for that page.',
						{ min: 1 }
					),
					concurrency: option(
						16,
						'Checks in flight per worker, each holding its place while it waits for its budget slot. ' +
							'NOT the rate: the node-wide budget paces the requests, so this only has to be high ' +
							'enough for the workers bots actually land on to fill it. A check is in flight for its slot ' +
							'wait, the request and a record write, and bots need not spread evenly over workers: at a ' +
							'fixed 4, one deployment measured ~5.8 checks/s with its whole 10/s budget free and queues ' +
							'overflowing (`busy`).',
						{ min: 1, max: 256 }
					),
					maxWait: option(
						10 * MINUTE,
						'The longest a queued check waits for its slot in the node\u2019s probe budget before it is ' +
							'shed (`shed`); the next request for the page queues it again.',
						{ unit: 'ms', min: SECOND }
					),
				}
			),
			userAgents: group(
				'Per-device-type User-Agent strings every probe request sends — the sweep, the canary and ' +
					'`serveCheck` alike — and the negative cache’s background re-check (`render.negative`), which ' +
					'checks a stored 404 the same way a serve check checks a cached page. The same device browser ' +
					'strings as `origin.userAgents` but with a `HarperProbe/1.0` product token, so the origin’s ' +
					'logs can tell probe traffic from the miss proxy’s (`HarperProxy/1.0`). A rule’s endpoint and ' +
					'the sweep send `desktop`; a serve check reading the document, and a re-check, send the ' +
					'served device’s, so a device-specific origin answers with the document that page was ' +
					'rendered from.',
				{
					mobile: option(`${DEVICE_BROWSER_UAS.mobile} ${PROBE_TOKEN}`, 'UA for mobile probe requests.'),
					tablet: option(`${DEVICE_BROWSER_UAS.tablet} ${PROBE_TOKEN}`, 'UA for tablet probe requests.'),
					desktop: option(`${DEVICE_BROWSER_UAS.desktop} ${PROBE_TOKEN}`, 'UA for desktop probe requests.'),
				}
			),
			requestTimeout: option(10 * SECOND, 'Per-probe timeout, headers and body both.', {
				unit: 'ms',
				min: SECOND,
			}),
			maxResponseBytes: option(
				5 * 1024 * 1024,
				'Largest probe response read before the probe is failed. Bounds document-mode reads; API-mode ' +
					'responses are typically a few KB.',
				{ min: 1024 }
			),
			startDelay: option(5 * MINUTE, 'Grace after boot before the first sweep.', {
				unit: 'ms',
				min: 0,
				// Bounded so startDelay + startJitter can never exceed setTimeout's signed-32-bit delay.
				max: DAY,
				scope: 'restart',
			}),
			startJitter: option(
				5 * MINUTE,
				'Per-node spread on the first sweep, so a rolling restart doesn’t sync every node’s registry ' +
					'walk and origin probes.',
				{ unit: 'ms', min: 0, max: DAY, scope: 'restart' }
			),
			canary: group(
				'The mass-change detector: a fixed per-node cohort probed on a fast cadence, tripping when a ' +
					'large fraction changed in one pass. Cohort membership is deterministic — the `count` matched ' +
					'URLs with the smallest hashes, a keyspace-uniform sample rebuilt by every sweep. (The ' +
					'bootstrap build after a restart uses a cheaper key-order sample until the first sweep ' +
					'replaces it.) It acts on the origin changes it finds, exactly as the sweep does; a cached page ' +
					'that disagrees with an UNCHANGED origin is counted (`pageMismatch`) and left to the sweep, which ' +
					're-renders it once per pass — re-probed every interval, a page a re-render cannot fix would ' +
					'otherwise re-render every interval. Its comparisons do not feed `mappingGuard`, which reads a ' +
					'whole slice, not one cohort.',
				{
					interval: option(
						30 * MINUTE,
						'How often the cohort is probed — all day, or outside the `schedule` windows when one is set. ' +
							'0 disables the canary (with a schedule: disables it outside the windows).',
						{
							unit: 'ms',
							min: 0,
							max: 2147483647, // setInterval's signed-32-bit delay cap — see sweepInterval
						}
					),
					schedule: option(
						[],
						'OPTIONAL time-of-day cadence; empty (the default) probes every `interval`, all day. Each entry is ' +
							'`{ from: "HH:MM", to: "HH:MM", interval: <ms, >= 60000> }` in `anchorTimezone` (the anchor’s zone ' +
							'and DST handling): inside the window the cohort is probed at its start and then every ' +
							'`interval`; outside every window, every `canary.interval` (0 = not at all). A window may wrap ' +
							'midnight; the first one containing an instant applies; an invalid entry is dropped with a ' +
							'warning.\n\n' +
							'WHY. On a site that reprices on a schedule a mass change comes at one time of day, and a ' +
							'500-URL cohort every 30 minutes around the clock is ~24k origin calls per node per day spent ' +
							'mostly confirming nothing happened. E.g. `interval: 14400000` (4h) with `schedule: [{ from: ' +
							'"23:50", to: "03:00", interval: 600000 }]` (10 min) probes densely across a midnight reprice ' +
							'and every 4h elsewhere — ' +
							'but an OFF-schedule mass change is then seen up to `interval` late, so keep the outside ' +
							'interval within what that exposure can bear.',
						{ itemType: 'object' }
					),
					count: option(
						500,
						'Cohort size per rule per node. At the default threshold this resolves a mass change with ' +
							'comfortable margin while costing ~count probes per interval.',
						{ min: 10 }
					),
					threshold: option(
						0.1,
						'Changed fraction of compared canaries (changed / (changed + unchanged)) at or above which ' +
							'the pass counts as a mass change. Measured promotional events reprice most of a catalog at ' +
							'once, so the default has a wide gap to per-URL drift noise.',
						{ min: 0, max: 1 }
					),
					minSample: option(
						50,
						'Fewest COMPARED canaries (seeds and failures excluded) a pass needs before the threshold ' +
							'is consulted at all — below it a handful of changes would read as a mass event.',
						{ min: 1 }
					),
					holdoff: option(
						6 * HOUR,
						'How long after recording a scope’s invalidation the canary will not re-record it. ' +
							'Re-stamping is NOT idempotent: it would re-invalidate every page rendered since the trip — ' +
							'exactly the pages that just healed. A genuine second event inside the holdoff still heals ' +
							'per-URL via the sweep; past it, a still-tripping canary re-records.',
						{ unit: 'ms', min: 0 }
					),
				}
			),
			mappingGuard: group(
				'The MAPPING-DEFECT GUARD for `pageCheck.fields`. A field mapped to the wrong slot, or compared the ' +
					'wrong way, disagrees with nearly every page — and every disagreement is a re-render, so one bad ' +
					'mapping would otherwise re-render its whole corpus on every pass. A correct mapping disagrees only ' +
					'when the page really is wrong, and on a WITNESSED page (rendered after the stored baseline was ' +
					'taken, the origin unchanged since) that takes a genuine round trip — the value changed and changed ' +
					'back between two probes with a render in between, measured well under 1%.\n\n' +
					'So each node counts, per mapped field, witnessed comparisons and witnessed disagreements, and ' +
					'DISARMS the field when its disagreement rate reaches `threshold` over at least `minWitnessed` ' +
					'comparisons: it stops triggering re-renders (and stops vouching for caught-up changes and ' +
					'verifications), a warning names the rule and slot, and its mismatches are still counted ' +
					'(`fieldMismatch` in the pass record; the guard’s own counts are `fieldGuard`). It RE-ARMS when the ' +
					'rate since falls below `rearmBelow` (or the mapping is edited, or the process restarts): an ' +
					'origin whose endpoint and page disagree for a few hours — a large reprice, the endpoint updated ' +
					'and the page not yet — makes a correct mapping disagree on a cluster of pages, and those pages ' +
					'are the ones most worth correcting once it passes. Each verdict is on at least `minWitnessed` ' +
					'comparisons made since the last one, and each re-arm of the same field waits twice as long as the ' +
					'one before, easing back with every full pass it spends armed (a mapping wrong on part of the slice ' +
					'would otherwise disarm and re-arm every pass). Only ' +
					'the sweep feeds it; the canary reads it. It never suppresses an individual ' +
					'disagreement — a single one is exactly the round trip the page check exists to catch. Disarming ' +
					'never hides an ORIGIN change: those trigger on the signature as always; a disarmed field only stops ' +
					'correcting pages that are wrong while the origin is unchanged.\n\n' +
					'The rate is RECENT, not lifetime: both counts halve each time the sample reaches ten times ' +
					'`minWitnessed`, so a mapping that was right for a week and then broke (the site changed its page ' +
					'template) is disarmed within a few thousand comparisons instead of after outweighing the week.\n\n' +
					'In dry run the guard counts and disarms too, which is the point of a dry-run week: a broken ' +
					'mapping announces itself before anything is armed.',
				{
					threshold: option(
						0.2,
						'Witnessed disagreement rate at or above which a mapped field is disarmed. The default sits ' +
							'far from both ends: a wrong mapping disagrees on nearly every comparison, a correct one on ' +
							'the rare round trip (a correct mapping would need twenty times the measured round-trip ' +
							'rate to reach it).',
						{ min: 0, max: 1 }
					),
					minWitnessed: option(
						200,
						'Fewest witnessed comparisons of a field before `threshold` is consulted. Large enough that a ' +
							'correct mapping cannot reach the threshold by chance (at a 1% true rate, 20% of 200 is ~40 ' +
							'disagreements where ~2 are expected); small enough that a broken mapping is disarmed after ' +
							'about this many spurious re-renders per node rather than a corpus of them.',
						{ min: 1 }
					),
					rearmBelow: option(
						0.05,
						'Disagreement rate, over at least `minWitnessed` witnessed comparisons since the field was ' +
							'disarmed, below which it is re-armed (logged RE-ARMED). Between a correct mapping’s steady ' +
							'state (well under 1%; a few percent the day after a large reprice) and a broken one’s (nearly ' +
							'every comparison). 0 never re-arms — a disarmed field then stays so until its mapping is ' +
							'edited or the process restarts, the behavior before this option. At or above `threshold` there ' +
							'is no gap between the two, and the fresh sample each verdict needs is the only damping. After k ' +
							're-arms a field needs `minWitnessed` x 2^k comparisons since its disarm to re-arm again (k up ' +
							'to 10), and each full pass it spends armed takes one off k.',
						{ min: 0, max: 1 }
					),
				}
			),
		}
	),

	render: group('Render scheduling: cadence, failure handling, schedule repair, and raw-document caching.', {
		raw: group(
			'RAW-DOCUMENT CACHING. Cache the origin document a miss already fetched, for URLs that are not ' +
				'in the render rotation — no browser, no render capacity, no second origin request.\n\n' +
				'THE PROBLEM IT SOLVES. On a large catalog the crawlable URL space is far bigger than the ' +
				'corpus worth rendering: facet and parameter combinations a bot invents by following links own ' +
				'no target, are never scheduled, and therefore MISS ON EVERY REQUEST. Measured on one ' +
				'deployment, 89.8% of requests to the listing route were exactly that — each one an origin ' +
				'fetch for a document the origin had already served, minutes earlier, to a different crawler. ' +
				'Caching it turns those misses into hits at the cost of one write.\n\n' +
				'WHEN IT IS THE RIGHT ANSWER: a route whose SERVER-RENDERED document already carries its whole ' +
				'SEO surface — title, meta description, canonical, JSON-LD offers, the product grid — so the ' +
				'render adds only interactive chrome. Verify that for a route before enabling it on that route; ' +
				'a raw document is NOT a rendered snapshot and this setting will not tell you the difference.\n\n' +
				'IT ONLY EVER REPLACES AN ORIGIN PROXY, never a render and never a cached snapshot. A raw page ' +
				'is read only when `PrerenderedPage` held nothing at all — a true miss. A stale or invalidated ' +
				'snapshot means a render is coming and the LIVE origin is the better answer, so those keep ' +
				'proxying exactly as before. Raw serves are reported under their own cache status, so ' +
				'`bot_serve` and `page_age` keep meaning what they meant.\n\n' +
				'Off by default, and off for every route until a route opts in with `rawCache: true`.',
			{
				enabled: option(false, 'Master switch. Off = nothing is stored, nothing is read, no extra reads.'),
				maxBytes: option(
					1048576,
					'Largest document to store, in bytes AS THE ORIGIN SENT IT — normally compressed (the ' +
						'origin is asked for gzip), so this bounds memory rather than the decompressed size a search ' +
						'engine sees. A body the origin sends UNCOMPRESSED counts at its full size here (that is ' +
						'what the capture holds in memory), and is gzipped before it is stored, so its stored size ' +
						'is usually far smaller. Over the cap the document is served and NOT stored, and the ' +
						'capture is abandoned so nothing further is buffered for it.\n\n' +
						'BUDGET ~2x THIS PER IN-FLIGHT CAPTURE, not 1x. A capture holds one copy of the bytes, and ' +
						'the `tee()` retains a second for the branch the crawler has not read yet — measured with a ' +
						'stalled reader, a 768 KB document held 1.5 MB. The total is bounded by ' +
						'`maxConcurrentCaptures`, so the worst case is roughly `2 x maxBytes x maxConcurrentCaptures` ' +
						'per worker.',
					{ unit: 'bytes', min: 1 }
				),
				maxConcurrentCaptures: option(
					16,
					'How many responses may be captured at once, per worker. Past it a response is served ' +
						'without being stored.\n\n' +
						'THIS EXISTS BECAUSE CAPTURING REMOVES BACKPRESSURE. Without a capture a slow client costs ' +
						'socket buffers — the reader stops, the TCP window closes, and the ORIGIN holds the data. ' +
						'The capture reads in a tight loop, so it drains the origin at full speed however slowly ' +
						'the client reads, and this worker’s heap becomes the buffer instead. On a route that is ' +
						'mostly misses, a client opening many connections and reading slowly would otherwise have a ' +
						'heap lever it controls. Degrading to "this one is not stored" costs nothing — the next ' +
						'request stores it — while degrading to heap pressure takes the serve path down with it.',
					{ min: 1 }
				),
				expiry: option(
					'midnight',
					'When a stored document goes stale: `midnight` (the next local midnight in ' +
						'`expiryTimezone`) or `interval` (use `expiryMs`).\n\n' +
						'`midnight` EXISTS FOR STEP-CHANGE ORIGINS. Where a catalog reprices at a fixed hour rather ' +
						'than drifting continuously, an interval is the wrong shape: a document fetched at 23:00 ' +
						'with a 6h TTL serves post-change prices for five hours, while one fetched at 01:00 expires ' +
						'long before anything about it has changed. Aligning expiry to the change boundary makes ' +
						'every stored document correct for exactly as long as it is correct, and no longer.\n\n' +
						'There is no herd to spread: raw pages refill on demand, one request at a time, so expiring ' +
						'a whole route at once produces misses at the rate crawlers actually arrive.',
					{ enum: ['midnight', 'interval'] }
				),
				expiryMs: option(
					21600000,
					'Lifetime of a stored document when `expiry` is `interval`. Ignored under `midnight`.\n\n' +
						'SEPARATE FROM `expiry` ON PURPOSE. The two used to be one option accepting either the ' +
						'string `midnight` or a number of milliseconds — which the config merge cannot express: it ' +
						'type-checks every value against its default, so a numeric override of a string-defaulted ' +
						'option was REJECTED with one log line and the default silently kept. The documented ' +
						'setting did nothing.',
					{ unit: 'ms', min: 1 }
				),
				expiryTimezone: option('UTC', 'IANA timezone `expiry: midnight` is resolved in.', { nonEmpty: true }),
				contentTypes: option(
					['text/html'],
					'Content types eligible for storage, matched against the leading type of the response ' +
						'`content-type` (parameters ignored). Anything else is served and not stored.'
				),
				ignoreNoStore: option(
					false,
					'Store a document even when the origin sends `Cache-Control: no-store`. Off by default, and ' +
						'`assumeShared` does not imply it: `no-store` is the origin asking caches not to keep the ' +
						'response at all. It is a switch because some origins send it on every document while a CDN, ' +
						'and this plugin\u2019s own page cache, keep them anyway; on such an origin a stored document is ' +
						'no different from the pages already cached. Pair it with `rawFacts` and ' +
						'`changeProbe.serveCheck` on a route where prices move, so a stored copy is checked against ' +
						'the origin rather than trusted until it expires. Leave it off for an origin whose `no-store` ' +
						'means something.'
				),
				assumeShared: option(
					false,
					'Store a document even when the origin marks it as NOT a shared artifact — a `Set-Cookie` ' +
						'on the response, or `Cache-Control: private`.\n\n' +
						'WHY THIS IS A SWITCH AND NOT A DEFAULT. Both signals are heuristics for one question: is ' +
						'this response the same for every crawler? A `Set-Cookie` usually means the body was ' +
						'personalized, and storing one then replays somebody’s session to everybody — so the ' +
						'default refuses, and must keep refusing for an origin nobody has checked.\n\n' +
						'BUT AN ORIGIN CAN BE WRONG ABOUT ITSELF. Where a CDN in front already serves ONE cached ' +
						'copy of these documents to every visitor, with none of the session cookies in its cache ' +
						'key, the origin’s `private` and `Set-Cookie` are about session BOOTSTRAP and say nothing ' +
						'about the body — and refusing on them stores nothing at all. Measured on one deployment: ' +
						'`Set-Cookie` on 8 of 8 listing responses and `private` on 4 of 8, so an enabled route ' +
						'filled ZERO documents against 33,572 misses an hour, every one of them refused.\n\n' +
						'VERIFY BEFORE SETTING IT: fetch the same URL as two DIFFERENT visitors and diff the ' +
						'bodies. If the only differences are per-request telemetry — a bot-manager sensor payload, ' +
						'a request id, a nonce — the document is shared and this is safe. If any CONTENT differs, ' +
						'it is not, and no CDN behaviour makes it so.\n\n' +
						'“DIFFERENT VISITORS” MEANS DIFFERENT IP AND LOCALE, NOT JUST A FRESH COOKIE JAR. Two cold ' +
						'fetches from one machine share their source address, `accept-language` and `referer`, and ' +
						'the origin fetch forwards all of those (only `cookie`, `authorization`, `host`, ' +
						'`user-agent`, `accept-encoding` and `origin.ignoredHeaders` are stripped) while the cache ' +
						'key is url + device alone. So that pair of fetches is blind BY CONSTRUCTION to ' +
						'geo-, IP- and locale-driven variance — store selection, currency, translated copy — which ' +
						'is the personalization a retail origin is most likely to have. Vary the vantage point.\n\n' +
						'Nothing reads `Vary`. An origin naming a request header there is declaring the response ' +
						'varies on something this cache key does not contain, and with `Set-Cookie` and `private` ' +
						'both suppressed it is the last standard statement left; check it by hand before enabling.\n\n' +
						'A literal `no-store` is still refused. That is the origin instructing caches not to keep ' +
						'the response at all, which is a different statement from “not for shared caches”.\n\n' +
						'WHAT THE METRIC CAN AND CANNOT TELL YOU. A document stored under this setting is counted ' +
						'as `stored-unshared` rather than `stored`, so the share of a route the origin calls ' +
						'personal stays visible. Read it as a CENSUS, not an alarm: on an origin that sets a ' +
						'cookie on every response it is 100% from the first minute and cannot rise, so no ' +
						'threshold on it detects anything. Re-running the body diff above is the detector.\n\n' +
						'A STORED `private` IS RELAYED ON EVERY RAW HIT, because the stored headers are the ' +
						'origin’s own and `cache-control` is relayed from storage exactly as the origin proxy ' +
						'already relays it on a miss. So this is not a change for those URLs — but a downstream ' +
						'shared cache that honours `private` will not cache the hit, so do not expect edge offload ' +
						'on it.'
				),
				deviceIndependent: option(
					false,
					'Store ONE document per URL and serve it to every device, instead of one per URL per device.\n\n' +
						'WHY THE DEFAULT IS PER-DEVICE. The origin fetch is made with a per-device User-Agent ' +
						'(`origin.userAgents`), and an ADAPTIVE origin answers those with different HTML. Keyed by ' +
						'URL alone, whichever device missed first would decide what every other device is served — ' +
						'a desktop page to a smartphone crawler, under a 200, with nothing reporting it.\n\n' +
						'RAW DOCUMENTS ONLY, AND THAT IS WHY THIS CAN BE SAFE. A rendered snapshot has its device’s ' +
						'layout baked in, so rendered pages stay per device regardless. A raw document is served ' +
						'UNRENDERED: the crawler lays it out at its own viewport, so what matters is not whether the ' +
						'two devices’ HTML differs but whether each device’s HTML RENDERS correctly at the other ' +
						'device’s viewport.\n\n' +
						'WHEN TO TURN IT ON: an origin whose documents render the same page at a given viewport ' +
						'whichever device’s document it is — responsive, or adaptive only in hints the page ' +
						'recomputes at render time. There the per-device key makes each device miss on its own — ' +
						'a desktop crawler’s fetch never answers the smartphone crawler asking for the same URL ' +
						'minutes later.\n\n' +
						'VERIFY BY RENDERING, NOT BY DIFFING MARKUP. For a few URLs, capture each device’s document ' +
						'(cache-busted — see below), load EACH document at EACH device profile (viewport, UA, touch) ' +
						'with the navigation answered from the captured document, and compare what renders — layout ' +
						'(column count, element widths, horizontal overflow), visible text, loaded images — against ' +
						'a same-document repeat as the noise floor. Measured on one deployment whose SSR differed by ' +
						'UA in three places (a component flag, eager-vs-lazy image hints, an extra facet entry in ' +
						'hydration data): every rendered measure followed the viewport and none followed the ' +
						'document, so it was enabled. A markup diff would have called that origin unsafe.\n\n' +
						'THE CACHE-BUSTER IS NOT OPTIONAL. A CDN whose document cache key has no device in it hands ' +
						'every UA whichever copy was filled first, so an un-busted comparison can read an adaptive ' +
						'origin as byte-identical — measured on one deployment, un-busted fetches with the mobile UA ' +
						'returned the desktop document 5 times in 6.\n\n' +
						'PER-DEVICE ROWS ARE NOT RELIABLY PER-DEVICE ANYWAY where the proxy’s origin fetch goes ' +
						'through a device-blind document cache: a row takes the other device’s document whenever that ' +
						'device filled the edge object within its TTL. Measured on the deployment above, 1 row in 9 ' +
						'written by real crawler traffic held the other device’s markup.\n\n' +
						'SIZE THE GAIN BEFORE PAYING FOR IT. The extra hits are exactly the first request of the ' +
						'second device for a URL both devices ask for while the row lives, so the gain is bounded by ' +
						'the smaller device’s share of distinct URLs. And where the CDN caches the bot-path response ' +
						'itself, most repeats never reach this cache at all.\n\n' +
						'THE ORIGIN CAN STILL VETO IT. A response whose `Vary` names `User-Agent`, any `Sec-CH-*` ' +
						'client hint, `DPR`/`Viewport-Width`/`Width`/`Device-Memory`, `ingress.deviceTypeHeader`, or ' +
						'`*` is the origin declaring the body depends on the device, and it is refused ' +
						'and counted as `vary-device` rather than shared. That catches an origin that turns adaptive ' +
						'AND says so. Many adaptive origins sniff the UA without declaring it, and those pass this ' +
						'check silently; only re-running the cross-device render comparison catches a change there.\n\n' +
						'Flipping it in either direction needs no migration: the other key shape’s rows are simply ' +
						'never read again and expire on their own. That relies on the two shapes not colliding, which ' +
						'holds for the default `cacheKey.delimiter` (`|` never survives into a canonical URL) but not ' +
						'for one that can occur in a URL: with `/`, a URL ending `/<device>` reads as its parent’s ' +
						'per-device key for one expiry window after the flip.'
				),
			}
		),
		negative: group(
			'NEGATIVE CACHING. Keep the origin’s own 404/410 for a URL, and answer the next crawler asking for ' +
				'the same dead URL from it instead of asking the origin again.\n\n' +
				'THE PROBLEM IT SOLVES. Crawlers keep asking for URLs that stopped existing long ago, and they ' +
				're-ask on a schedule. Measured on one deployment: origin 404s were a third of all origin ' +
				'fetches, a dead product page cost the origin nearly a full page build (336 ms against 416 ms ' +
				'for a live one), and one crawler re-asked each dead URL about every 55 minutes — half of all ' +
				'repeat gaps fell between 50 and 60 minutes. Each of those repeats is an origin request that can ' +
				'only ever answer the same thing.\n\n' +
				'THREE WINDOWS, measured from the last time the ORIGIN confirmed the status (`checkedAt`):\n' +
				'  - inside `freshMs`: the stored response answers and the origin is not asked. This is the only ' +
				'part that saves origin requests.\n' +
				'  - past `freshMs`, inside `lifeMs`: the stored response answers AT ONCE and the origin is ' +
				're-checked in the background (a HEAD, or a GET once the stored body is older than `lifeMs`, which ' +
				'replaces it). A 404/410 refreshes `checkedAt`; a 200 or a redirect drops ' +
				'the entry, so the next request sees the live page; anything else (5xx, a timeout) keeps serving ' +
				'until the life ends. This buys response time and fast recovery, not offload.\n' +
				'  - past `lifeMs`: the request proxies as if nothing were stored, and a 404 stores again.\n\n' +
				'IT ONLY EVER REPLACES AN ORIGIN PROXY on a true miss, after the raw cache: a URL with a cached ' +
				'page, stale or not, is never answered from here. It never answers a URL whose Target a sitemap ' +
				'lists (`skipTargets`), checked on every read, so a relisted product answers live on every node as ' +
				'soon as the sitemap walk attaches it. An explicit `missHeader: origin` bypasses it, like the raw ' +
				'cache. Nothing here is ever rendered, so a stored response owns no target and records no demand.\n\n' +
				'COUNTED HONESTLY. A fresh answer is `bot_serve` source `negative`, cacheStatus `negative`. An answer ' +
				'whose background re-check went to the origin is source `origin`, cacheStatus `negative-revalidate`: ' +
				'the crawler did not wait, but the origin still did the work, so offload counts it against. The ' +
				're-check itself is `origin_fetch` reason `revalidate`, one per such answer.\n\n' +
				'Off by default, and off for every route until a route opts in with `negativeCache: true`.',
			{
				enabled: option(false, 'Master switch. Off = nothing is stored, nothing is read, no extra reads.'),
				dryRun: option(
					true,
					'Store, re-check and time exactly as armed, but never ANSWER from a stored response: every ' +
						'request still proxies. What an armed cache would have done is counted on ' +
						'`prerender_ops negative_cache` — `would-serve` (the origin requests `freshMs` would save) and ' +
						'`would-revalidate` — and the gap since the last confirmation on `negative_gap`, which is the ' +
						'live curve to choose `freshMs` from.\n\n' +
						'THE RISK NUMBER IS `would-serve-live`: requests an armed cache would have answered with a stored ' +
						'404 while the origin, asked anyway, answered 200. It is the recovery exposure measured directly, ' +
						'and it should sit near zero before this is turned off.\n\n' +
						'The dry run refreshes `checkedAt` only where an armed cache would have asked the origin, so ' +
						'`would-serve` is exactly what arming saves rather than an overcount.'
				),
				statuses: option(
					[404, 410],
					'Origin statuses to keep. Anything else is never stored. Each entry must be an integer 4xx ' +
						'other than 429, and a list with any other entry is refused whole (the default is kept). A 5xx ' +
						'or a 429 is the origin failing to answer, not a statement that the page does not exist, so ' +
						'storing one would replay an outage to crawlers. A string such as "404" never equals a ' +
						'status, so it would store nothing.',
					{ items: { integer: true, min: 400, max: 499, not: [429] } }
				),
				freshMs: option(
					HOUR,
					'How long after the origin last confirmed the status a stored response answers WITHOUT asking ' +
						'the origin. The one number that decides the saving.\n\n' +
						'CHOOSE IT FROM THE CRAWLERS’ REPEAT GAPS, NOT FROM A ROUND NUMBER. Savings step at multiples ' +
						'of a crawler’s re-ask period rather than rising smoothly: on the measured deployment 50 ' +
						'minutes saved 9.9% of 404 origin fetches, 55 minutes 29.3%, 2h 42.9% and 2h15m 43.7%. A ' +
						'window a little past a step catches the crawler’s jitter. The dry run records every gap on ' +
						'`negative_gap`.\n\n' +
						'The cost of a longer window is a URL that comes back answering 404 to a crawler for up to this ' +
						'long. Recoveries were rare where measured (about 2 in 60 URLs that stopped 404ing), and the ' +
						'sitemap check on every read covers the common case of a relisted product.',
					{ unit: 'ms', min: 1 }
				),
				lifeMs: option(
					6 * HOUR,
					'How long a stored response may answer at all. Between `freshMs` and this, it answers and the ' +
						'origin is re-checked in the background. It bounds storage (a row lives this long past its last ' +
						'confirmation) and how old a stored BODY can be: once the bytes are older than this, the next ' +
						'check that goes to the origin anyway (a re-check, or an excluded bot’s proxied request) ' +
						'replaces them instead of confirming them, so no body is served more than about twice this old. ' +
						'Until then a re-check is a HEAD, which refreshes the ' +
						'status, not the bytes. Must be at least `freshMs`.',
					{ unit: 'ms', min: 1 }
				),
				deviceIndependent: option(
					false,
					'Store ONE response per URL and answer every device from it, instead of one per URL per device. ' +
						'A 404 is almost never device-specific, so this is usually safe and adds a little to the saving ' +
						'(about one point on the measured deployment); per-device stays the default for the same reason ' +
						'as `render.raw.deviceIndependent`, because the body is the origin’s and an adaptive origin ' +
						'could send a different one.'
				),
				excludeBots: option(
					[],
					'Bot names (as `getBotName` labels them, case-insensitive) never answered from a stored response. ' +
						'Their requests still proxy and still refresh or store entries for everyone else.\n\n' +
						'WHY IT EXISTS: a merchant or ads crawler that fetches a relisted product’s landing page while a ' +
						'stale 404 is stored can disapprove the listing, and a user-triggered agent (a read-aloud fetch) ' +
						'is a real person. On a deployment with a shopping feed, list the search engine’s crawlers here; ' +
						'their share of the repeats is usually small, so leaving them out costs little.',
					{ itemType: 'string' }
				),
				skipTargets: option(
					'listed',
					'Which URLs are never answered from a stored response because they have a Target: `listed` (a ' +
						'sitemap lists the Target) or `any` (the URL has any Target at all). Checked on every read and ' +
						'again before every store — a local read, since Target replicates.\n\n' +
						'`listed` is the default because a sitemap listing is the origin declaring the page exists, which ' +
						'outranks a stored 404, and it is exactly the case that recovers: listed products that 404 ' +
						'briefly are the transient tail. `any` also leaves out a retired product the rotation still ' +
						'holds, which recovers on its next recheck render instead.',
					{ enum: ['listed', 'any'] }
				),
				assumeShared: option(
					false,
					'Store a response even when the origin marks it as not shared — a `Set-Cookie`, or ' +
						'`Cache-Control: private`. Same question, same check before setting it, as ' +
						'`render.raw.assumeShared`; stored under it counts as `stored-unshared`.'
				),
				ignoreNoStore: option(
					false,
					'Store a response even when the origin sends `Cache-Control: no-store`.\n\n' +
						'A literal `no-store` is the origin asking caches not to keep the response at all, and the raw ' +
						'cache always honours it. It is a switch here because some origins send it on every document ' +
						'while a CDN, and this plugin’s own page cache, keep them anyway; on such an origin the 404s ' +
						'are no different from the pages already cached. Leave it off for an origin whose `no-store` ' +
						'means something.'
				),
				maxBytes: option(
					1048576,
					'Largest response body to store, in bytes as the origin sent it. Over it, served and not ' +
						'stored. Same capture, same ~2x-per-capture memory rule, as `render.raw.maxBytes`. SIZE IT ' +
						'FOR AN UNCOMPRESSED BODY: origins that gzip their pages often send error pages ' +
						'uncompressed (one production origin sends every 404 uncompressed, 79-699 KB, a retired ' +
						'product’s full page), and such a body counts at its full size here. It is gzipped ' +
						'before it is stored (7-13x smaller on those pages).',
					{ unit: 'bytes', min: 1 }
				),
				maxConcurrentCaptures: option(
					16,
					'How many responses may be captured at once, per worker, for the same backpressure reason as ' +
						'`render.raw.maxConcurrentCaptures`. Past it a response is served without being stored.',
					{ min: 1 }
				),
				maxConcurrentChecks: option(
					8,
					'How many background re-checks may be in flight at once, per worker. Past it a stored response ' +
						'still answers but nobody asks the origin (counted as `recheck-busy`), so under origin distress ' +
						'the re-checks shed and the origin sees fewer requests, not more. A URL already being re-checked ' +
						'joins that check instead of starting a second (`recheck-joined`).',
					{ min: 1 }
				),
			}
		),
		defaultInterval: option(
			DAY,
			'How often a target is re-rendered when nothing more specific applies. Cadence is relative to ' +
				'each render’s completion (not a fixed time-of-day), and a target’s first render is jittered ' +
				'across its interval — so the fleet renders as a smooth stream rather than a daily herd. Full ' +
				'precedence, resolved at schedule time: matched route `renderInterval` (ingress.routes) > the ' +
				'target’s stored interval (sitemap `changefreq` / explicit API write) > this default.',
			{ unit: 'ms', min: 1 }
		),
		demand: group(
			'Demand-driven cadence: move a target UP or DOWN a fixed ladder of render intervals based ' +
				'on whether bots actually visit it, inside the same total render budget. Hot pages get a ' +
				'tighter freshness bound; pages nothing crawls get a looser one.\n\n' +
				'A render interval only bounds staleness for content that drifts with TIME. On this corpus ' +
				'that is AVAILABILITY (~0.04%/hour, continuous, and directionally in-stock -> out-of-stock, ' +
				'i.e. the cache claims stock for sold-through items), so each rung is really an ' +
				'availability-error budget: 6h ~ 0.24%, 12h ~ 0.5%, 24h ~ 1%, 48h ~ 2%. Price does NOT ' +
				'drift that way — it steps at promotional events, most of the catalog at once — so no ' +
				'affordable interval bounds it and this does not try.\n\n' +
				'COST IS NOT SELF-LIMITING. It scales with the fraction of the corpus bots touch, which ' +
				'grows as search-engine traffic ramps. `maxFastFraction` is the backstop and the level ' +
				'histogram logged every `statsInterval` is the early warning — watch it before trusting it.\n\n' +
				'A CONSUMER of the demand tracker (`demand.*`, where the visit ring and its sizing live since ' +
				'v0.95.0): it acts only while `demand.enabled` is on too.',
			{
				enabled: option(
					false,
					'Master switch. Off = `resolveRenderInterval` is used unchanged. Needs `demand.enabled`: with ' +
						'the tracker off there is nothing to decide on, and the ladder rests every target at base.'
				),
				dryRun: option(
					true,
					'Compute and LOG every ladder decision but schedule with the unchanged base interval. ' +
						'A week of this reports the steady-state level distribution — and therefore the render ' +
						'budget — before you pay for it. Default ON: enabling `enabled` alone changes no ' +
						'SCHEDULE until this is turned off.\n\n' +
						'One write does happen in dry-run, deliberately: a rung move persists to ' +
						'`Target.demandInterval` (only on an actual move, never on hold). That persistence is ' +
						'what makes the dry-run histogram converge to the steady-state distribution instead ' +
						'of reporting first-step decisions forever — and it means the measured week is not ' +
						'free of replicated Target writes (~one per target that moves, per rung walked, plus ' +
						'boundary pages that flap). Turning the ladder fully off leaves `demandInterval` in ' +
						'place, ignored; a later re-enable resumes from the stored rung rather than from base.'
				),
				ladder: option(
					[6 * HOUR, 12 * HOUR, 24 * HOUR, 48 * HOUR],
					'Render intervals a target may occupy, ascending. The route/stored interval is the ' +
						'CEILING — the ladder reallocates within the cadence the route already grants and never ' +
						'schedules slower than it. An interval that is not itself a rung participates as its ' +
						'own top rung: it rests at its granted cadence and may only move through the rungs ' +
						'FASTER than it — never snapped to a rung in either direction (a 1h route parked at ' +
						'6h, or a weekly sitemap route pulled to 48h at 3.5x its granted render budget). ' +
						'Bottoming out at 6h rather than 1h is deliberate: 1h buys ' +
						'~0.04% availability error against 6h\u2019s ~0.24% for six times the render cost, and the ' +
						'fast rungs are where a runaway hot set becomes unaffordable. A route can bound how much ' +
						'of this ladder its pages may use with `ingress.routes[].demandFloor` \u2014 rungs faster than ' +
						'a route\u2019s floor are unreachable for that route.',
					{ unit: 'ms' }
				),
				promoteWindows: option(
					2,
					'How many consecutive windows of the CANDIDATE (faster) interval must each contain a ' +
						'visit before a target is promoted. 1 promotes on "visited at all this interval", which ' +
						'settles at rendering twice per visit; 2 asks whether a render at the faster rung would ' +
						'actually have been seen, and settles near once per visit.',
					{ min: 1 }
				),
				maxFastInterval: option(
					12 * HOUR,
					'Rungs strictly below this count as "fast" for `maxFastFraction` and the logged ' + '`fastFraction`.',
					{ unit: 'ms', min: 1 }
				),
				maxFastFraction: option(
					0.05,
					'Budget backstop: the share of LADDER decisions allowed to land on a fast rung. ' +
						'Exceeding it is logged as a warning — the hot set has grown past what the ladder was ' +
						'sized for.\n\n' +
						'The denominator is the `graded` count in the histogram — promoted + demoted + held — ' +
						'not every reschedule. Decisions where the ladder had no choice are excluded: a route ' +
						'whose granted cadence is at or below the fastest rung has a one-entry effective ladder ' +
						'(`singleRung`), and a cold visit filter holds without deciding (`skippedCold`). ' +
						'Counting those made the number a readout of the ROUTE MIX — a deployment with any ' +
						'route below `maxFastInterval` had a structural floor it could never get under, so the ' +
						'warning fired continuously with zero promotions.\n\n' +
						'Within the graded set it is decision-weighted, which is what a budget cap wants: ' +
						'decisions are renders, so a target on the 6h rung contributes 8x one at 48h and the ' +
						'fraction reads as the share of the eligible render BUDGET spent on fast rungs. At the ' +
						'0.05 default with the default ladder, that is roughly 0.65% of eligible targets fully ' +
						'promoted to 6h — near the ~0.5% hot fraction the split was sized for. Beside it, ' +
						'`promotedFast` counts promotions ONTO a fast rung: the budget being reallocated right ' +
						'now, and zero once the distribution settles.\n\n' +
						'ALERT ON THE POOLED RATIO, not on any single emitted number: ' +
						'`sum(demand_fast) / sum(demand_graded)` across workers and nodes. The counters are ' +
						'per worker per interval and worker volumes are very unequal (production has had ' +
						'graded 3 on one worker and 50 on a sibling in the same interval), so averaging ' +
						'per-worker ratios overstates the result — 1/3 and 1/50 average to 0.175 against a ' +
						'pooled 0.038. The per-worker `fastFraction` in the log line is a diagnostic for that ' +
						'worker; its warning is suppressed below `1 / maxFastFraction` graded decisions, where ' +
						'a single fast decision would exceed the limit on its own and the ratio therefore says ' +
						'nothing.',
					{ min: 0, max: 1 }
				),
				statsInterval: option(15 * MINUTE, 'How often the level histogram + promote/demote counters are logged.', {
					unit: 'ms',
					max: 2147483647,
					min: SECOND,
				}),
			}
		),
		suppression: group(
			'What happens when a render proves a URL non-indexable (noindex, canonical mismatch, redirect ' +
				'loop, HTTP error page). The target is not deleted — it is marked `state: suppressed` and ' +
				'rescheduled at `recheckInterval`, so the verdict re-proves (or heals) itself on cadence, and ' +
				'discovery stops re-creating it. `maxStrikes` consecutive non-indexable verdicts delete the ' +
				'target outright; crawler re-discovery restarts the cycle at bounded cost.\n\n' +
				'Verdicts are not all equally permanent, so the knobs split by HTTP status:\n' +
				'  - 404/410 (`gone`): the origin’s strongest statement that the page no longer exists. ' +
				'Rechecking it on the default cadence is almost pure waste, so it gets fewer, further-apart ' +
				'rechecks before deletion — and, when no sitemap lists the URL, deletion on the FIRST verdict ' +
				'(`gone.maxStrikesUnlisted`), because a 404 at the origin is itself what stops discovery ' +
				're-creating the target.\n' +
				'  - 401/403 never suppress at all: an auth-shaped error is far more likely a broken renderer ' +
				'credential or an origin rule change than a page verdict, and striking on it would mass-delete ' +
				'healthy targets during an outage.\n' +
				'  - 408/429/5xx never suppress either: the origin failed to serve the page, it didn’t disavow ' +
				'it — the target and its cached page both survive and the render retries under `failureRetry`.',
			{
				recheckInterval: option(7 * DAY, 'Re-render cadence for a suppressed target.', { unit: 'ms', min: 1 }),
				maxStrikes: option(4, 'Consecutive non-indexable verdicts before the target is deleted.', { min: 1 }),
				gone: group('Tighter knobs for 404/410 verdicts.', {
					recheckInterval: option(14 * DAY, 'Re-render cadence for a gone (404/410) target.', {
						unit: 'ms',
						min: 1,
					}),
					maxStrikes: option(2, 'Consecutive gone verdicts before a SITEMAP-LISTED target is deleted.', { min: 1 }),
					maxStrikesUnlisted: option(
						1,
						'Consecutive gone verdicts before a target NO SITEMAP LISTS is deleted. Separate from ' +
							'`maxStrikes` because the two are not symmetric, and the asymmetry runs the opposite way to ' +
							'the intuition.\n\n' +
							'A suppressed row is the verdict memory that stops a URL being re-created, so deleting one ' +
							'hands that job back to whatever created the target. For an unlisted target that is ' +
							'discovery, and discovery mints only on a 200 from the origin — a URL the origin answers ' +
							'404/410 for cannot be re-minted by a crawler hit, so retiring it is terminal and the row, ' +
							'its schedule row and every recheck render it would have cost are pure waste. Hence a ' +
							'default of 1: retire on the first verdict.\n\n' +
							'For a SITEMAP-LISTED target the refresh re-creates it on the very next pass (an absent ' +
							'target is a CREATE; a suppressed one is skipped), so deleting trades one recheck per ' +
							'`recheckInterval` for a full render per `sitemap.refreshInterval` — at a 6h refresh ' +
							'against a 14d recheck that is ~28x MORE render work. Those keep counting `maxStrikes`.\n\n' +
							'Scoped to gone verdicts on purpose: noindex and canonical-mismatch verdicts come from ' +
							'pages the origin serves 200 for, so discovery re-mints them on the next bot request ' +
							'(a `<meta>` noindex is not even visible to the header check) and retiring those on sight ' +
							'would loop the same way. Set equal to `maxStrikes` to restore the pre-0.67.0 behaviour.',
						{ min: 1 }
					),
					reopen: group(
						'REOPEN A GONE TARGET ON EVIDENCE OF LIFE. A gone suppression deletes the pages and parks the ' +
							'target for `recheckInterval`, and until then every other signal skips it: the sitemap walk, ' +
							'the arrival check, the change probe and discovery all treat a suppressed row as settled. So a ' +
							'product that comes back waits the full recheck (14 days by default) to be rendered again, ' +
							'while bots are served the live origin page meanwhile. Measured on one deployment: both ' +
							'sitemap-listed products sampled 404ing on one day answered 200 three days later.\n\n' +
							'THE EVIDENCE IS AN ORIGIN 200 THE PLUGIN ALREADY SAW: a bot request proxied to the origin for ' +
							'a gone-suppressed target (any bot — the row proves the URL is real, so the discovery gate ' +
							'does not apply), a negative-cache re-check that found the page live, or the sitemap listing ' +
							'the URL again (through the arrival check). Each files the target’s recheck due now, and the ' +
							'render’s own verdict decides: indexable reactivates it, a 404 suppresses it again.\n\n' +
							'Gone verdicts only. A noindex or canonical-mismatch page answers 200 by definition, so a 200 ' +
							'proves nothing about it and reopening it would loop. A route that does not add targets from ' +
							'traffic (`discoverTargets: false`) never pays the Target read this needs.',
						{
							enabled: option(
								true,
								'Master switch. On by default and inert under `dryRun`, which is also the default: the ' +
									'counts on `prerender_ops gone_reopen` size the effect before anything is filed.'
							),
							dryRun: option(
								true,
								'Count what would be reopened (`would-file`) without filing anything. The arrival path ' +
									'reports the same verdict as `would-reopen` in the sitemap arrival tally.'
							),
							dedupeMs: option(
								6 * HOUR,
								'A URL reopened within this window is not reopened again (`deduped`), per worker: a ' +
									'crawler asking every hour must not file a render every hour while the first one is ' +
									'still waiting to be claimed.',
								{ unit: 'ms', min: 0 }
							),
							maxPerMinute: option(
								60,
								'Most reopens filed per minute per worker (`capped` past it). A mass relisting — a ' +
									'retirement wave reversed — reaches the queue as a stream rather than all at once; a ' +
									'capped URL is simply reopened by its next bot request.',
								{ min: 1 }
							),
						}
					),
				}),
			}
		),
		failureRetry: group(
			'Retry shape for the HTTP failures that never suppress (401/403 auth-shaped, 408/429/5xx ' +
				'transient), and for a render that simply failed (crash, timeout, settle error). The first ' +
				'`fastRetries` consecutive failures DELIBERATELY DO NOT RELEASE the job’s claim lease, so the ' +
				'retry comes on lease expiry (`queue.jobLeaseTime`) — an origin blip recovers fast, and the ' +
				'cached page’s stale-while-revalidate window covers bots throughout. From the next strike on, ' +
				'the retry drops to the target’s normal cadence and then backs off from there ' +
				'(`backoffFactor`, `maxBackoff`, `nonSitemapPenalty`): a persistently failing page must not ' +
				'hot-loop 100+ renders a day. Past `page.swrTtl` the kept page stops serving and bots fall through to ' +
				'the origin on purpose — its answer (a live page for auth-shaped failures, an honest 5xx for ' +
				'transient ones) is the truth, and serving arbitrarily old snapshots while users get errors ' +
				'would break bot/user parity. Strikes are the target’s one shared counter; any successful ' +
				'render clears it.\n\n' +
				'Two consequences of the lease being node-local shared-buffer state rather than a stored due ' +
				'time: a worker restart collapses the fast-lane wait to zero (the job is simply re-granted), ' +
				'and during a broad origin failure every job takes this lane, so no lease is released at all ' +
				'for that window.',
			{
				fastRetries: option(
					2,
					'Consecutive failures retried on lease expiry before dropping to the target’s cadence. Each ' +
						'such retry waits out a full queue.jobLeaseTime.',
					{
						min: 0,
					}
				),
				backoffFactor: option(
					2,
					'Multiplier applied per strike once the fast lane is exhausted. The first escalation waits ' +
						'exactly one normal interval; each strike after that multiplies by this. 1 disables ' +
						'backoff and restores the flat pre-0.37.0 cadence.',
					{ min: 1 }
				),
				maxBackoff: option(
					7 * DAY,
					'Ceiling on the backed-off wait. Never shortens a retry below the target’s own cadence — a ' +
						'ceiling under the interval (a 48h page against a 24h ceiling) would otherwise make a ' +
						'FAILING page come due more often than a healthy one.',
					{ unit: 'ms', min: 1 }
				),
				nonSitemapPenalty: option(
					4,
					'Extra wait multiplier for a failing target with no sitemap source, applied from the SECOND ' +
						'escalation on — every target gets one honest retry at its normal cadence first, so a ' +
						'single failure never deprioritizes a URL. Sitemap URLs are the corpus we promised to ' +
						'keep fresh, so they stay on the base curve while discovered URLs back off harder. ' +
						'Priority is expressed purely as a due time — `claim` orders by nextRenderTime alone — ' +
						'so this needs no priority field and no second index. 1 treats both alike.',
					{ min: 1 }
				),
			}
		),
		redirects: group(
			'A redirect that proves nothing permanent (302/303/307, a client-side redirect’s 200, or any ' +
				'redirect onto a route class we don’t serve) keeps the source target on the theory the page is ' +
				'coming back. A source that answers that way EVERY interval is de facto permanent, so each such ' +
				'result counts a strike (the same shared counter suppression uses; any successful render clears ' +
				'it) and `maxStrikes` consecutive ones retire the source outright. Retiring is safe, not ' +
				'destructive: bot traffic for the URL is proxied to the origin — which serves the redirect ' +
				'itself — and on-demand discovery re-creates whatever the origin actually serves.',
			{
				maxStrikes: option(4, 'Consecutive impermanent-redirect results before the source is retired.', {
					min: 1,
				}),
			}
		),
		targetMissing: group(
			'What a render result does when its URL has NO Target on the node processing it, for a row that ' +
				'is part of a recurring rotation (it carries a cadence). A render-now one-off is targetless by ' +
				'construction and is unaffected: it stores its page and its row is dropped.\n\n' +
				'A recurring row can meet a missing target because the target has not replicated to this node yet: ' +
				'`Target` and `RenderSchedule` are separate databases, so a newly created target can arrive after ' +
				'its schedule row, and a replica can lose a target outright. Dropping the row then is TERMINAL and ' +
				'silent — nothing re-creates a schedule for a target that exists. Measured on a four-node ' +
				'deployment: 734 live targets, most of them sitemap-declared, lost their rows this way during ' +
				'three days of write overload and went unrendered for five weeks.\n\n' +
				'So the row is DEFERRED instead: re-filed `deferMs` out without storing the page, and dropped only ' +
				'once its target has been missing for `graceMs`. A target that arrives in the meantime is rendered ' +
				'and rescheduled normally on the next pass. A truly orphaned row costs at most graceMs / deferMs ' +
				'extra renders before it is dropped, with a warning.',
			{
				deferMs: option(6 * HOUR, 'How far out a deferred row is re-filed while its target is missing.', {
					unit: 'ms',
					min: MINUTE,
				}),
				graceMs: option(
					24 * HOUR,
					'How long a recurring row may find its target missing before it is dropped. Size it above the ' +
						'longest replication lag you expect `render_service` to recover from.',
					{ unit: 'ms', min: 0 }
				),
			}
		),

		reconcile: group(
			'Periodic repair of targets whose RenderSchedule row is missing. A target and its schedule are ' +
				'two commits in two databases (the schedule routed to the node owning the URL), so the pair can ' +
				'end up half-written — and for a URL that is not in a sitemap, NOTHING otherwise re-creates the ' +
				'schedule: the URL stops rendering silently and permanently. Runs on worker 0 of every node, ' +
				'each covering only the keys it owns.\n\n' +
				'The repair write goes through the schedule funnel, and the queue keeper sees it like any other ' +
				'write.',
			{
				enabled: option(true, 'Run the periodic schedule-repair sweep.'),
				interval: option(
					6 * HOUR,
					'How often each node sweeps its own slice of the keyspace. At most 2147483647 (~24.8 days), ' +
						'Node’s timer ceiling: past it a timer fires every millisecond rather than never, so a large ' +
						'value is not a way to switch the sweep off — `enabled: false` is.',
					{ unit: 'ms', min: SECOND, max: 2147483647 }
				),
				startDelay: option(5 * MINUTE, 'Grace after boot before the first sweep.', {
					unit: 'ms',
					min: 0,
					scope: 'restart',
				}),
				startJitter: option(
					5 * MINUTE,
					'Per-node spread on the first sweep, so a rolling restart doesn’t sync the sweeps.',
					{ unit: 'ms', min: 0, scope: 'restart' }
				),
				maxRestores: option(
					5000,
					'Ceiling on rows RESTORED per sweep. The scan always runs to completion, so a truncated sweep ' +
						'still reports the true size of the gap — the cap bounds only how much is repaired at once, ' +
						'since a membership change can strand a large slice of the keyspace and rewriting millions of ' +
						'rows in one pass would be its own outage.',
					{ min: 1 }
				),
			}
		),

		pageOrphanSweep: group(
			'Deletion of cached PAGES that no Target owns (POST /prerender_admin/sweep-orphan-pages) — the ' +
				'population every other sweep is blind to, since they all walk the Target table. A page is only ' +
				'ever removed by the target delete cascade, so a target that disappears without it (a raw-table ' +
				'delete, a render result that lands after its target was retired) strands its pages: never ' +
				're-rendered, never reclaimed, and replicated in full to every node. Measured on one deployment: ' +
				'14% of all pages, ~19 GB per node.\n\n' +
				'A page is deleted only when this node owns its URL, it was cached at least `minAge` ago, it is no ' +
				'longer servable (past expiresAt + page.swrTtl), no Target owns its URL and no render of it is in ' +
				'flight — re-checked inside the delete transaction. So a deletion never changes what a crawler is ' +
				'served beyond `stale` -> `miss`.\n\n' +
				'MANUAL ONLY and dry-run by default, like the other destructive sweeps. Node-scoped: each node ' +
				'sweeps the pages whose URL it owns, so run it on every node. Deletes replicate.',
			{
				minAge: option(
					21 * DAY,
					'How long ago a page must have been cached to be a candidate. Keep it well above the longest ' +
						'render cadence plus swrTtl, so a page a live rotation maintains can never qualify.',
					{ unit: 'ms', min: DAY }
				),
				maxDeletes: option(
					100000,
					'Ceiling on pages DELETED per pass. The walk still runs to the end, so `orphaned` is the true ' +
						'population; re-run until `truncated` is false.',
					{ min: 1 }
				),
				batchSize: option(
					100,
					'Pages deleted per transaction. The binding cost of a bulk delete is the number of commits on ' +
						'page_cache, so a batch is one commit — and, with confirmReplication, one confirmation round.',
					{ min: 1, max: 1000 }
				),
				ratePerSecond: option(100, 'Ceiling on pages deleted per second.', { min: 1 }),
				confirmReplication: option(
					true,
					'Hold each batch until every peer has confirmed it. This is the backpressure: a peer that ' +
						'cannot keep up stalls the sweep instead of letting it run ahead of replication.'
				),
				dryRun: option(true, 'Count and report without deleting anything. Defaults ON, so a bare start is a census.'),
			}
		),

		orphanSweep: group(
			'Deletion of targets orphaned by a CACHE-KEY RULE CHANGE — targets whose stored url is no ' +
				'longer what that url canonicalizes to, so no request can produce their key.\n\n' +
				'They are invisible to every other repair path: a sitemap refresh creates the target under ' +
				'the new key and only UNLINKS the old one (`sitemapUrl -> null`), which leaves its schedule ' +
				'rows due on the normal cadence; and the canonical verdict cannot retire them, because with ' +
				'the rule applied on both sides the renderer folds the job url and the declared canonical ' +
				'alike and calls it `self`. So they render forever into keys nothing reads. Measured after ' +
				'enabling `cacheKey.plusIsSpace` on a ~38k-url catalog corpus: ~20,200 urls re-keyed, ' +
				'~40,400 schedule rows. Sizing that needs care: `nextRenderTime` is stamped at COMPLETION, ' +
				'so a row rendered `L` behind its due time next renders `interval` after that — the realized ' +
				'cycle is `interval + L`, not `interval`. At the 8.2h lag observed there, those orphans ran a ' +
				'~14h cycle (~2,900 renders/hr, ~4% of the throughput ceiling) — but ~8% of the work the ' +
				'fleet was actually completing, which is the number that matters while it is saturated.\n\n' +
				'MANUAL ONLY, BY DESIGN — there is no timer. This deletes corpus, and the population it ' +
				'targets is created by an operator changing a `cacheKey` option, so it should run when ' +
				'someone decides to run it (POST /prerender_admin/sweep-orphans) rather than on a schedule ' +
				'that could act on a config change nobody meant to make permanent. Run it with `dryRun` ' +
				'first and reconcile the count against what you expect the rule change to have re-keyed.\n\n' +
				'Node-scoped: each node sweeps only the keys it owns, because the in-flight check reads ' +
				'this node’s lease buffer. Every node must be swept to cover the keyspace.',
			{
				maxDeletes: option(
					5000,
					'Ceiling on targets DELETED per sweep. The scan always runs to completion, so the reported ' +
						'`orphaned` count is the true size of the population even when only this many were removed ' +
						'— a rule change can orphan a large slice of the keyspace at once, and deleting millions of ' +
						'rows in one pass would be its own outage. Re-run until `truncated` is false.',
					{ min: 1 }
				),
				dryRun: option(
					true,
					'Count and report without deleting anything. Defaults ON: the safe direction for a ' +
						'destructive sweep is that an operator who triggers it without reading this gets a census, ' +
						'not a deletion. A run always reports which mode it was in.'
				),
			}
		),
	}),

	scan: group(
		'Bounded registry walks. Harper ends a transaction that stays open too long: with writes pending ' +
			'it is ABORTED and poisoned (422 "split long-running work into smaller transactions"), and ' +
			'read-only it is committed and its clock reset. So every walk over a large table collects while ' +
			'reading and writes only after the cursor closes, in drained batches.',
		{
			collectCap: option(
				100000,
				'Max rows buffered from one scan; the scan still completes and reports the true count.',
				{ min: 1 }
			),
			batchSize: option(100, 'Writes issued (and fully awaited) per batch once the cursor is closed.', {
				min: 1,
			}),
			yieldEvery: option(200, 'Rows scanned between event-loop yields.', { min: 1 }),
		}
	),

	sitemap: group('Sitemap ingestion: the refresh schedule, filtering, and crawler identity.', {
		refreshTime: option(
			'12:00',
			'Local time-of-day ("HH:MM") the refresh grid is anchored on. With the default 24h ' +
				'`refreshInterval` this is simply the daily refresh time; at any shorter interval it is the ' +
				'slot the others are spaced around.',
			{ nonEmpty: true }
		),
		timezone: option('America/New_York', 'IANA timezone `refreshTime` is interpreted in.', { nonEmpty: true }),
		refreshInterval: option(
			24 * HOUR,
			'How often the scheduled refresh runs, as slots spaced this far apart and phase-anchored on ' +
				'`refreshTime` (6h with a 12:00 anchor runs at 00:00/06:00/12:00/18:00 local). The default of ' +
				'24h leaves exactly one slot a day, on the anchor.\n\n' +
				'WHAT A SHORTER INTERVAL BUYS: the sitemap is the only source that attributes a URL to a ' +
				'sitemap, gives it a `changefreq`-derived render interval, and puts it in the sitemap lane ' +
				'that `queue.priority.sitemapBoost` ranks above discovered rows. Until a refresh sees it, a ' +
				'newly-published URL either does not exist here or exists only as a request-path discovery. ' +
				'Halving the interval halves that worst-case wait.\n\n' +
				'WHAT IT COSTS, AND WHY IT IS LESS THAN IT LOOKS: a pass re-fetches every child sitemap and ' +
				'scans the `sitemapUrl` index once per child, but it WRITES ONLY THE DIFF — on a real ~830k ' +
				'entry corpus 99% of entries resolve to `skipped` with no write, and the created/reattached/' +
				'removed counts are catalog churn, so a shorter interval splits the same daily total into ' +
				'smaller passes rather than repeating it. Measured there, a full walk of 31 sitemaps takes ' +
				'~2 minutes of one worker.\n\n' +
				'The real reason not to set this very low is the prune scan\u2019s read cursor: scan-seconds ' +
				'scale linearly with frequency, and long-held snapshots are what retain dead versions. The ' +
				'returns flatten long before the cost does \u2014 a few passes a day is the useful range.\n\n' +
				'Passes CANNOT overlap regardless of what is set here: the pinned worker refuses a second ' +
				'concurrent run, and each root is claimed for the length of its walk (see `staleRunMs`). An ' +
				'interval shorter than a walk therefore skips a slot and logs it rather than running two ' +
				'walks at once.',
			{ unit: 'ms', min: 1 * MINUTE }
		),
		filteredWarnPercent: option(
			50,
			'A sitemap lists every indexable URL on the site, which is routinely a superset of the paths ' +
				'the CDN forwards here — so entries that are not a prerender route are counted and dropped ' +
				'rather than scheduled. Past this share of one sitemap, that is reported as an ERROR instead of ' +
				'an info line: filtering most of a sitemap is far more likely to mean `ingress.routes` is ' +
				'incomplete than that the sitemap is wrong, and a silent filter looks exactly like a healthy ' +
				'refresh.',
			{ unit: 'percent', min: 0, max: 100 }
		),
		node: option(
			'',
			'Pin the periodic sitemap refresh to this node (hostname). Empty disables the scheduled ' +
				'refresh entirely (manual refresh still works).'
		),
		workerIndex: option(0, 'Worker index (on `node`) that runs the scheduled refresh.', { min: 0 }),
		background: option(
			true,
			'Run `POST /Sitemap/<url>` as a background walk and answer immediately with a handle, instead ' +
				'of holding the request open for the whole traversal. A sitemap index is not an ' +
				'HTTP-request-sized unit of work — a real one fans out to tens of children and over a million ' +
				'target writes, so the client (or any proxy between it and Harper) times out long before the ' +
				'walk finishes, leaving the operator with no result, no error, and no way to tell whether ' +
				'anything was written. Progress is persisted to `SitemapRefresh` under the root URL; ' +
				'`GET /SitemapRefresh/<root-url>` reports it. `POST ... {"background": false}` restores the ' +
				'blocking behaviour for a small sitemap or a test.'
		),
		staleRunMs: option(
			10 * MINUTE,
			'How long a progress row may go un-updated before a new refresh treats the run that wrote it ' +
				'as dead and starts over. Guards against a worker restart mid-walk leaving a `running` row that ' +
				'blocks every later refresh of that root.',
			{ unit: 'ms', min: 1 }
		),
		removedSampleCap: option(
			20,
			'Max unlinked-target samples carried back in a refresh result (counts stay exact; only the ' +
				'samples are capped).',
			{ min: 0 }
		),
		failedCap: option(100, 'Max failed-entry samples carried back in a refresh result.', { min: 0 }),
		newTargets: group(
			'How soon a URL the sitemap has just DECLARED gets its first render.\n\n' +
				'Without this, a newly created target takes `getInitialRenderTime`, which jitters the first ' +
				'render across the target’s WHOLE render interval — `hash(url) % interval`. That jitter ' +
				'exists for a real reason (the first ingest of a large sitemap must not stampede the queue), ' +
				'but it is sized for bulk population and applies just as hard to the handful of genuinely new ' +
				'URLs a mature corpus gains each day: on a 48h cadence a product published this morning can ' +
				'wait two days to be rendered once, while the sitemap has been telling us about it the whole ' +
				'time. A declaration is the strongest signal a site gives that a URL matters.\n\n' +
				'So the first render is jittered across `window` instead of the interval, and only for the ' +
				'first `maxPerRun` creates in a walk. The cap is what keeps the bulk case safe: a first ' +
				'ingest creating hundreds of thousands of targets exceeds it immediately and everything past ' +
				'it falls back to full-interval jitter, which is exactly the old behaviour. Steady-state ' +
				'churn (tens to hundreds a day on a real corpus) never comes close to the cap.\n\n' +
				'Only the FIRST render moves. The target’s cadence is untouched — `effectiveInterval` is ' +
				'still the route/stored interval, so every render after this one is on the normal schedule.',
			{
				window: option(
					15 * MINUTE,
					'Jitter window for a newly declared target’s first render. Small values approximate ' +
						'"immediately" while still spreading a batch across minutes rather than firing it into ' +
						'one. `0` disables the fast path entirely and restores full-interval jitter.\n\n' +
						'BELOW ~2 MINUTES IT STOPS SPREADING. `getInitialRenderTime` floors to the minute, so a ' +
						'window under 60,000ms collapses every create in a walk onto ONE minute — the stampede ' +
						'this is jittered to avoid, arrived at by asking for less jitter. Capped at 2147483647 ' +
						'for the same reason `sweepInterval` is: a larger delay is not "effectively never", it ' +
						'overflows the signed 32-bit timer and fires immediately.\n\n' +
						'A window WIDER than the route’s own `renderInterval` is ignored — the fast path would be ' +
						'slower than the jitter it replaces — and does not count as `createdSoon`.',
					{ unit: 'ms', min: 0, max: 2147483647 }
				),
				maxPerRun: option(
					5000,
					'Creates per walk that may take the fast path. Past this, new targets fall back to ' +
						'full-interval jitter — the bulk-population guard.\n\n' +
						'A discovered target\u2019s FIRST listing (a URL minted from traffic that no walk has listed ' +
						'or unlinked) shares this cap: it is filed due now — or, when a canonical-mismatch or ' +
						'noindex verdict parked it, its recheck is — and counted `listedSoon` on the refresh result. ' +
						'A gone-suppressed one is left to `render.suppression.gone.reopen`.',
					{ min: 0 }
				),
			}
		),
		conditional: group(
			'Conditional sitemap fetching: send `If-Modified-Since` and skip the whole reconcile for a ' +
				'document the origin answers 304 to.\n\n' +
				'WHAT IT BUYS. A pass re-fetches every child and scans the `sitemapUrl` index once per ' +
				'child, and it is that prune scan — a held read cursor, whose seconds scale linearly with ' +
				'refresh frequency — that sets the real cost of refreshing often. A 304 skips the body, the ' +
				'parse, the scan and every write, so an unchanged pass costs one request per document and ' +
				'no database work at all. That is what makes polling for a change affordable instead of ' +
				'merely possible: a deployment whose sitemaps rebuild once a night can check every few ' +
				'minutes and pay for the walk only on the pass that finds the rebuild.\n\n' +
				'USE `Last-Modified`, NOT `ETag`, AND DO NOT ASSUME EITHER. Measured on one production ' +
				'edge: `If-Modified-Since` returned a clean 304, while `If-None-Match` sent back the exact ' +
				'ETag the same edge had just served and got 200 with the full multi-megabyte body. An ' +
				'origin that advertises a validator is not promising to honour it, which is why the ' +
				'`not_modified` counter is worth watching — a steady zero here means every pass is doing ' +
				'full work and the frequency should come back down.\n\n' +
				'AN INDEX IS STILL DESCENDED on a 304: that only says the CHILD LIST is unchanged, not the ' +
				'children, and on a real corpus the children rebuild on a different schedule from the index ' +
				'that lists them. Each child then makes its own conditional decision.',
			{
				enabled: option(true, 'Send `If-Modified-Since` when a stored validator is available.'),
				fullPassInterval: option(
					24 * HOUR,
					'Force an UNCONDITIONAL fetch of a document whose entries have not been ingested in this ' +
						'long. This is the repair net and it is why the feature is safe to leave on: a 304 skips ' +
						'the reconcile, and the reconcile is also what re-CREATES targets lost to anything else — ' +
						'a bad purge, a half-applied delete, a botched migration. Without a periodic full pass a ' +
						'corpus could drift for as long as the origin left its sitemaps untouched and nothing ' +
						'would notice. Set it to 0 to make every fetch unconditional (the pre-0.69.0 behaviour).',
					{ unit: 'ms', min: 0 }
				),
			}
		),
		shrinkGuard: group(
			'A circuit breaker on a sitemap that arrives much shorter than the one last accepted — the ' +
				'partial but well-formed document: a generator that died mid-build and still closed its root, ' +
				'an edge serving a stale partial object, an index that left out a child it failed to build. (A ' +
				'body cut off mid-document is refused earlier, by the parse: its root is never closed.) Accepted, ' +
				'such a document presents every URL it lost as departed — hard-expired and re-rendered on an armed ' +
				'departure check — and every one of them rejoins, and renders again, when the origin recovers.\n\n' +
				'THREE CHECKS, ALL ON WHAT THE ORIGIN SENT, NONE ON WHAT MOVED: (1) a urlset whose entry count fell ' +
				'below `(1 - maxRatio)` of its stored `entryCount`, by at least `minUrls`; (2) a child its index ' +
				'stopped listing that still holds, AFTER the walk, at least `minUrls` URLs listed nowhere else and ' +
				'more than `maxRatio` of what it held; (3) an index whose dropped children together hold that much ' +
				'of everything its children held. URLs that merely move — forward shear across fixed-size children, ' +
				'a cache-key rule re-keying a child, children renamed each build — are never counted: (2) and (3) ' +
				'measure URLs listed nowhere after the walk, not child names.\n\n' +
				'A refused document or dropped child is a FAILED child: its row and its targets stay exactly as the ' +
				'last good fetch left them, and the held URLs on its routes are held back rather than departed ' +
				'(`departure_relinked`). Refusals count `shrink_refused`.\n\n' +
				'ACCEPTED ONLY ONCE IT OUTLIVES A REBUILD. A refused shorter document is believed when it has been ' +
				'refused at least `acceptAfter` times AND it survived a NEW origin version (a changed `Last-Modified` ' +
				'or content — for a dropped child, its index\u2019s) arriving at least `newVersionAfter` after the ' +
				'first refusal, or `acceptAge` has passed since it was first refused. Counting walks alone accepted a ' +
				'bad nightly build after a few walks of the same day, before the next rebuild could fix it. An ' +
				'acceptance is logged at error and counted `shrink_accepted`; what it departs is metered like every ' +
				'other departure, by `sitemap.departure.maxPerWalk`. `maxRatio: 1` disables the guard.',
			{
				maxRatio: option(
					0.5,
					'Largest share of what it last held a document may lose in one fetch. 1 disables the guard. 0.5 ' +
						'because real churn is nowhere near it — a mature catalog child gains and loses a few percent a ' +
						'day — while a truncated or partial document typically loses most of itself.',
					{ min: 0, max: 1 }
				),
				minUrls: option(
					1000,
					'Nothing smaller than this many lost URLs is refused, by any of the three checks — so a small ' +
						'child or index the site legitimately empties is never held back. Sized well above real ' +
						'per-child churn (tens a day on a mature catalog) and well below what a truncated or missing ' +
						'product child loses (tens of thousands).',
					{ min: 0 }
				),
				acceptAfter: option(
					2,
					'Refusals of a shorter document before it may be accepted at all — the floor under `acceptAge` ' +
						'and the new-version rule, so one odd fetch (an edge answering with a different ' +
						'`Last-Modified` for the same object) is never mistaken for a rebuild.',
					{ min: 1 }
				),
				acceptAge: option(
					48 * HOUR,
					'Accept a refused shorter document that has stayed refused this long since its first refusal, ' +
						'even if the origin never published a new version of it. 48h: past two nightly rebuilds, so a ' +
						'generator that failed one build has had two chances to fix it; a shrink still there is real.',
					{ unit: 'ms', min: 0 }
				),
				newVersionAfter: option(
					20 * HOUR,
					'How long after the first refusal a NEW origin version must arrive to count as the rebuild that ' +
						'confirms a shrink. A touch or re-publish of the same bad build bumps `Last-Modified` within ' +
						'hours, and a partial that varies from fetch to fetch changes its digest every walk; neither is ' +
						'the next build. 20h: past the same day\u2019s walks, short of a nightly rebuild.',
					{ unit: 'ms', min: 0 }
				),
			}
		),
		departure: group(
			'What a refresh does about URLs that LEAVE a sitemap, beyond unlinking them. The action is ' +
				'declared PER ROUTE (`ingress.routes[].departureAction`); this group bounds and observes it, ' +
				'and nothing here does anything until at least one route opts in.\n\n' +
				'THE CHECK RUNS AFTER THE WHOLE WALK, not at prune time, and that is not an optimisation. A ' +
				'paginated corpus shears across child boundaries: children are walked in order, so a URL that ' +
				'moves to an EARLIER child is re-attached before the child it left is pruned and never looks ' +
				'departed — but one that moves to a LATER child is pruned first and looks departed until the ' +
				'child that now claims it is reached. Acting at prune time would fire on every URL that shifted ' +
				'forward, which on a fixed-size paginated sitemap is every URL after an insertion. Candidates ' +
				'are re-read once the walk ends and anything that picked up an attribution is dropped.',
			{
				enabled: option(
					true,
					'Master switch for the post-walk departure check. Routes still have to opt in, so leaving ' +
						'this on costs nothing until one does; it exists so an operator can stop the behaviour ' +
						'during an incident without editing the route list.'
				),
				dryRun: option(
					true,
					'Decide and report, write nothing. The default, because the useful thing to know first is ' +
						'HOW MANY URLs a real walk would act on — a number no deployment has until it has ' +
						'looked, and one that decides whether `maxActions` is a ceiling or a no-op. The result ' +
						'and the progress row carry the outcome tally either way.'
				),
				// -1 is "no ceiling" for both caps below, and it is -1 rather than `null` or `Infinity` on
				// purpose. `null` already means "no value" in every layer — the merge skips it and keeps the
				// default, an override write refuses it, and the console's number field reports it for an
				// emptied box — so making it mean "uncapped" would turn a blank `maxActions:` in config.yaml
				// from the default into no guard at all, silently and in the dangerous direction. `Infinity`
				// cannot cross JSON, so no override row or console edit could ever carry it. -1 is a plain
				// number every layer already validates and transports, and nobody types it by accident.
				// 0 keeps its meaning — act on / collect nothing — because 0 is also how a walk with no
				// opted-in route switches collection off. Read them through `departureLimit`.
				maxActions: option(
					5000,
					'Ceiling on departed URLs ACTED ON in one walk, or -1 for no ceiling. Skipped candidates ' +
						'(re-attached, suppressed, route opted out) do not count against it.\n\n' +
						'WHAT IT GUARDS AGAINST: a child sitemap that fetches truncated but still parses as valid ' +
						'XML presents every URL it no longer lists as departed, and without a ceiling that one bad ' +
						'fetch would expire a large slice of the cache.\n\n' +
						'OVERFLOW IS DROPPED FOR GOOD, not deferred. By the time the check runs the walk has already ' +
						'unlinked the URL from its sitemap, and a later walk only looks for departures among URLs ' +
						'still linked to one — so a URL counted as `capped` is never offered again (unless it ' +
						're-enters a sitemap and departs a second time). It keeps its target, its render cadence ' +
						'and its cached page; it just never gets its route’s departure action. Read `capped` as ' +
						'departures lost, not postponed.\n\n' +
						'-1 removes the ceiling: every departed URL gets its action and nothing is ever counted as ' +
						'`capped`. That gives up the guard above, so read a `dryRun` tally first. 0 acts on ' +
						'nothing — every candidate is still decided and reported.',
					{ min: -1 }
				),
				maxPerWalk: option(
					5000,
					'Most departures one walk may DECIDE, across every child sitemap at once, or -1 for no ceiling. ' +
						'Past it, departed URLs are DEFERRED, not dropped: each is put back on the child that unlinked ' +
						'it, whose validator is cleared so the next walk re-prunes it and offers them again ' +
						'(`departure_deferred`, and a `budget` entry in the progress row\u2019s `holdBack`).\n\n' +
						'WHY. `sitemap.shrinkGuard` refuses a document that lost more than `maxRatio` of itself; a ' +
						'well-formed partial build that lost less — in one child or in all of them — is not refused, ' +
						'and without this every URL it dropped would depart in one walk and rejoin, all of it, when the ' +
						'origin recovered. Metered, a mass event spreads over several walks, and a recovery inside that ' +
						'time turns the deferred URLs back into listed ones that never departed. Only URLs still ' +
						'unattributed once the walk is over count: shear the walk already re-attached never does.\n\n' +
						'HOW IT DIFFERS FROM `maxActions`: that cap is lossy — its overflow never gets its departure ' +
						'action — and bounds how many actions run; this one is lossless and bounds how fast departures ' +
						'are believed. Only HELD URLs can be deferred, so it needs `maxCandidates` at least as large. ' +
						'5000: comfortably above a mature catalog\u2019s daily departures spread over its walks, and a ' +
						'small fraction of what a missing or half-built product child sheds. The budget goes ROUND-ROBIN across ' +
						'the children that unlinked them, so one child\u2019s mass event cannot hold every other child\u2019s ' +
						'departures back. The deferral re-links for real even under `dryRun` — it undoes the walk\u2019s own ' +
						'unlink, as the failed-child re-link does.',
					{ min: -1 }
				),
				maxCandidates: option(
					50000,
					'Ceiling on departed URLs HELD for the post-walk check, or -1 for no ceiling. Separate from ' +
						'`maxActions` because this one bounds memory: it is a list of URLs retained across a walk ' +
						'that can prune millions. Uncapped, the list is bounded by the URLs that walk actually ' +
						'unlinks — at most `scan.collectCap` per child sitemap — so it grows with how much of the ' +
						'corpus departs at once, which is exactly what a truncated child sitemap inflates. A capped ' +
						'list is reported as such (`departures.capped` on the result and the progress row), so a ' +
						'short list is never presented as "few departed".\n\n' +
						'Overflow is DROPPED FOR GOOD, for the same reason as `maxActions` overflow: the URL is ' +
						'already unlinked, so no later walk offers it again. It is never decided and never appears ' +
						'in the outcome tally; `removed` minus `departures.considered` is how many were lost. -1 ' +
						'removes the ceiling and never reports `capped`; 0 collects nothing.\n\n' +
						'The same list is what a walk with a FAILED child draws on to re-link (`departure_relinked`) ' +
						'the URLs that could have moved into it — those on a route it held at its last parse — ' +
						'instead of departing them, so it also bounds that, and an arrival-only deployment holds up ' +
						'to this many for the re-link alone.',
					{ min: -1 }
				),
			}
		),
		arrival: group(
			'What a refresh does about a URL that REJOINS a sitemap — re-attributed by a walk after an ' +
				'EARLIER walk unlinked it. The action is declared PER ROUTE (`ingress.routes[].arrivalAction`); ' +
				'this group bounds and observes it, and nothing here does anything until at least one route ' +
				'opts in. The mirror of `sitemap.departure`, with its own switches so arming one never arms ' +
				'the other.\n\n' +
				'SHEAR IS KEPT OUT BY A STAMP, NOT BY WAITING. A walk that unlinks a target stamps ' +
				'`Target.unlistedAt` with the walk\u2019s own START, and the re-attach compares against the ' +
				'current walk\u2019s start: a URL that moved to a later child of a paginated index is unlinked ' +
				'and re-attached inside one walk, so its stamp is this walk\u2019s start and it is not a rejoin. ' +
				'Rejoins are therefore known the moment they are re-attached; they are still ACTED on after the ' +
				'walk, by the same executor as departures.\n\n' +
				'WHAT IT DOES NOT SEE: targets unlinked before v0.89.0 (no stamp — they re-render on their ' +
				'cadence, as before); rejoins on a `revalidate: true` walk (which files every listed URL due ' +
				'now anyway). A URL that moves between two ROOT sitemaps looks like a departure in the first ' +
				'root\u2019s walk and a rejoin in the second\u2019s — the departure check has the same limitation, ' +
				'and the cost is one render per such URL, inside the ceilings.\n\n' +
				'Reported as `arrivals` on the refresh result and the progress row (`considered`, `capped`, and ' +
				'an outcome tally: `render`, or `would-render` under `dryRun`, for actions; `route-opted-out`, ' +
				'`suppressed`, `unlinked`, `target-gone` and `capped` for the candidates nothing happened to) and ' +
				'in the walk\u2019s log — not as a metric series.',
			{
				enabled: option(
					true,
					'Master switch for the arrival action. Routes still have to opt in, so leaving this on costs ' +
						'nothing until one does; it exists so an operator can stop the behaviour during an incident ' +
						'without editing the route list.'
				),
				dryRun: option(
					true,
					'Decide and report, write nothing. SEPARATE from `sitemap.departure.dryRun` on purpose: a ' +
						'deployment that has already armed departures and then opts a route into arrivals must still ' +
						'get a measured walk first, because the number that matters — how many rejoins one walk ' +
						'produces, and in particular the burst when a truncated child sitemap recovers and every URL ' +
						'it had dropped rejoins at once — is not one anybody has until they have looked. Inheriting ' +
						'the departure switch would act on the very first walk.'
				),
				// -1 = no ceiling on both, for the reasons `sitemap.departure` spells out; read through
				// `departureLimit`.
				maxActions: option(
					5000,
					'Ceiling on rejoined URLs ACTED ON in one walk, or -1 for no ceiling. Skipped candidates do not ' +
						'count against it.\n\n' +
						'WHAT IT GUARDS AGAINST: the rejoin burst. A child sitemap that fetched truncated in one walk ' +
						'unlinked everything it dropped; when it recovers, every one of those URLs rejoins in the same ' +
						'walk, and without a ceiling that would expire and re-render all of them at once.\n\n' +
						'OVERFLOW IS DROPPED FOR GOOD, like a capped departure: the re-attach has already cleared the ' +
						'stamp, so no later walk sees the URL as a rejoin. It keeps its target, attribution and ' +
						'cadence; it just never gets its route\u2019s arrival action. -1 removes the ceiling; 0 acts on ' +
						'nothing (every candidate is still decided and reported).',
					{ min: -1 }
				),
				maxCandidates: option(
					50000,
					'Ceiling on rejoined URLs HELD for the post-walk action, or -1 for no ceiling. Bounds memory, as ' +
						'`sitemap.departure.maxCandidates` does. Overflow is DROPPED FOR GOOD and reported as ' +
						'`arrivals.capped`. -1 removes the ceiling; 0 collects nothing.',
					{ min: -1 }
				),
			}
		),
		userAgent: option(
			'HarperSitemapCrawler/1.0',
			'User-Agent for Harper’s sitemap crawler fetch. Unlike the proxy fetch UAs, a sitemap fetch ' +
				'isn’t a device render, so it sends a single self-identifying UA rather than a spoofed browser ' +
				'one — makes Harper’s sitemap traffic obvious in origin/CDN logs and separable from the proxy ' +
				'traffic.',
			{ movedFrom: 'sitemapUserAgent' }
		),
	}),

	queue: group('Render-queue mechanics between the plugin and the render fleet.', {
		jobLeaseTime: option(
			10 * MINUTE,
			'How long a claimed job is leased before the queue will grant it to another renderer.\n\n' +
				'The lease is NOT stored in the schedule row — it lives in a node-local shared buffer, so it is ' +
				'lost when a worker generation is replaced. That is correct, not a bug: the schedule row was ' +
				'never moved, so a lost lease simply means the job is granted again (which does mean a restart ' +
				'produces a short duplicate-render burst for whatever was in flight).\n\n' +
				'It is also the retry pacing for the fast-retry lane (`render.failureRetry`), which deliberately ' +
				'holds the lease: a render that fails is retried when its lease expires.\n\n' +
				'The minimum is two minutes because the render fleet DISCARDS any granted job with under 30 ' +
				'seconds of lease left. Below roughly 90s the fleet skips 100% of granted jobs and the queue ' +
				'live-locks: claims keep succeeding, nothing ever renders, and the plugin sees only healthy ' +
				'claims.',
			{
				unit: 'ms',
				min: 2 * MINUTE,
			}
		),
		statusSyncInterval: option(
			MINUTE,
			'How often each node re-resolves queue state on worker 0. The recompute scans nothing — ' +
				'empty/queued/unready comes from the queue keeper. This interval governs how fast a ' +
				'replicated pause/resume intent (QueueControl) converges onto a node, how often the QueueStatus ' +
				'row is broadcast, and how often the lease gauge is reconciled. At most 2147483647 (~24.8 days), ' +
				'Node’s timer ceiling: past it a timer fires every millisecond rather than never.',
			{
				unit: 'ms',
				min: SECOND,
				max: 2147483647,
			}
		),
		maxClaimLimit: option(
			25,
			'Hard ceiling on jobs granted per claim, regardless of what a consumer asks for, so one greedy or ' +
				'misconfigured renderer cannot take a burst other renderers should share.',
			{ min: 1 }
		),
		maxLeases: option(
			4096,
			'Lease slots in the node-local shared buffer that records which keys are currently being ' +
				'rendered.\n\n' +
				'Sizing: a 10-minute lease at 12,000 renders/hour is about 2,000 leases in flight fleet-wide, ' +
				'so ~500 per node on four nodes; 4,096 slots × 32 bytes is 128KB. A claim that cannot record ' +
				'a lease does NOT grant the job (a granted-but-unrecorded job is a double render), so an ' +
				'undersized table shows up as claims granting fewer jobs than asked, with a warning naming the ' +
				'occupancy.\n\n' +
				'Restart-scoped: the buffer is sized once by the first allocation in the process, so a live ' +
				'change would give workers within one generation differently-sized views of the same named ' +
				'buffer. It is read at FIRST USE (the first claim or lease operation) rather than at module ' +
				'load, which is what makes a restart actually honour it.',
			{ min: 1, scope: 'restart' }
		),
		ready: group(
			'THE READY SET — the best of the due rows, in claim order, in shared memory. The queue keeper ' +
				'publishes it every `queue.keeper.publishInterval`; claims on every worker pop from it.\n\n' +
				'The order is relative lateness (lateness over cadence, times `sitemapBoost` for a sitemap-sourced ' +
				'row), because absolute due time treats a 1h-TTL homepage 3h overdue exactly like a 48h-TTL ' +
				'product page 3h overdue — 300% stale against 6% (prerender-plugin#80). Ordering only: total ' +
				'render volume cannot change, since every row it reorders is already due.',
			{
				capacity: option(
					5000,
					'Entries the ready set holds. The keeper republishes every second, so this only needs to ' +
						'cover the claims between publishes with room for leased rows it skips; at ~5 jobs a second ' +
						'per node the default is far more than that.\n\n' +
						'Costs `capacity x ~276 x 2` bytes of shared memory — two slots, so ~2.8MB at the default. ' +
						'Keys are packed end to end, so a long key does not need a slot of its own size.\n\n' +
						'Restart-scoped: a named shared buffer is sized by its first allocation, so a live change ' +
						'would give workers in one generation differently-sized views of the same buffer. A ' +
						'mismatch is logged and the smaller size honoured.',
					{ min: 1, scope: 'restart' }
				),
				sitemapBoost: option(
					2,
					'How much a sitemap-sourced row outranks a discovered one at the same overdue ratio. `1` ' +
						'disables the preference and orders on overdue ratio alone.\n\n' +
						'A MULTIPLIER, not a tier, so it cannot starve discovered URLs: an unserved row\u2019s ' +
						'lateness grows without bound while the boost stays constant, so a discovered row wins as ' +
						'soon as its ratio passes `sitemapBoost x` the highest sitemap ratio in the set. With ' +
						'sitemap pages held ~1.2 cadences late, a discovered page is served within ~2.4 cadences ' +
						'of its own interval at the default.',
					{ min: 1 }
				),
				changedHeadStart: option(
					1,
					'How far ahead a page the change probe found changed starts, in cadences: its row ranks as if ' +
						'it were already this many of its own intervals late. The probe hard-expires such a page and ' +
						'files its render at the current minute, so without a head start it would enter at lateness ' +
						'zero, behind every overdue row, while bots are served the origin for as long as it waits.\n\n' +
						'IN BOOSTED UNITS (since v0.97.0): the head start is multiplied by `sitemapBoost`, as a sitemap ' +
						'row’s lateness is, so a page found changed a minute ago outranks every routine row less than ' +
						'this many cadences late, sitemap-listed or not (a discovered one, less than this times the ' +
						'boost). Unboosted, a sitemap row half a cadence late already outranked it at the default boost.\n\n' +
						'ADDITIVE, and bounded: a routine row still wins once it is more than `changedHeadStart` ' +
						'cadences later than the changed rows being held, so a large change wave takes the fleet for ' +
						'a while, never indefinitely. `0` ranks changed pages like any other due row.',
					{ min: 0 }
				),
				urgentHeadStart: option(
					0.5,
					'The same kind of head start, for a row filed due now by a SINGLE ASK rather than a detected ' +
						'change: a render-now, an admin revalidate or rejoin of one URL, the destination of a permanent ' +
						'redirect whose source was just retired, a URL a sitemap lists for the first time ' +
						'(`RenderSchedule.urgentAt`). Filed at the current minute such a row is zero cadences late, so ' +
						'without this it ranked behind every overdue row — and past `capacity` routine rows, was not ' +
						'published at all. Bulk re-files (a revalidate over a collection, a sitemap walk with ' +
						'`revalidate: true`) are not asks and are not marked.\n\n' +
						'HALF OF `changedHeadStart` BY DEFAULT, on purpose. A changed page is hard-expired and answered ' +
						'from the origin while it waits; an asked-for page is usually still served from the cache. So a ' +
						'change must outrank an ask of the same lateness — and at 0.5 against 1 it does, and outranks ' +
						'any ask filed less than half a cadence before it — while an ask still outranks routine rows ' +
						'less than half a cadence late (sitemap-listed; a discovered one, less than half a cadence times ' +
						'the boost). Keep it below `changedHeadStart`: at equal values an ask filed two hours before a ' +
						'change outranks it. In boosted units and bounded exactly as `changedHeadStart` is. A row that ' +
						'is also marked changed takes `changedHeadStart`; the two are not added. `0` ranks such rows ' +
						'like any other due row, which is the pre-0.97.0 behaviour.',
					{ min: 0 }
				),
				changedDemand: option(
					true,
					'Order changed pages by how often bots ask for them: a changed row\u2019s wait is counted in the ' +
						'page\u2019s visit periods, as the demand tracker (`demand.*`) estimated them when the change was ' +
						'acted on, instead of in its cadence. A changed page is expired, so each visit while it waits ' +
						'is served from the origin, and counted this way the score is those visits: the pages asked ' +
						'for most render first. Counted in cadence, every changed product page shares one divisor and ' +
						'a change wave renders in the order the probe found it.\n\n' +
						'`changedHeadStart` still applies, and so does its bound, now in visits. A changed page nobody ' +
						'asks for gains slowly and yields to routine rows at the same score — they are still served ' +
						'from the cache, it is not asked for. Demand that is unknown (tracker off, still loading, or ' +
						'past `demand.maxFalsePositive`) leaves a row ordered by cadence, as with this off. The estimate ' +
						'is stamped on the row (`RenderSchedule.demandPeriod`) whether or not this is on, so switching ' +
						'it applies to pages already waiting.'
				),
			}
		),
		keeper: group(
			'The queue keeper (v0.93.0): worker 0 holds every schedule row this node owns in memory, ' +
				'kept current by a subscription on the schedule table, and is the queue — `RenderSchedule` is ' +
				'its durable side. It publishes the ready set claims are served from, serves queue state ' +
				'(`GET /prerender_admin/queue-state`) and feeds the backlog snapshot. See prerender-plugin#215.\n\n' +
				'Each ready-set entry is checked against its durable row before it is granted, the head of each ' +
				'publish is re-read and repaired, and a periodic verification walk (`verifyInterval`) repairs ' +
				'anything it missed. Costs about 200 bytes of heap per row on worker 0 (about 50MB at 250k ' +
				'rows), and a load by primary key at start: about 1s per 250k rows on a fresh store, expected ' +
				'tens of seconds on a churned one — SERVED WHILE IT RUNS: the ready set is published from the ' +
				'first chunk, so a restarted node grants claims within about a publish interval. Once live it is ' +
				'never reloaded: a route or default-interval change reclassifies rows in memory, and a membership ' +
				'change drops the rows this node no longer owns and walks the table for the ones it gained, all ' +
				'while serving. Until its first publish the node reports `unready` and grants nothing. A node ' +
				'whose `system.hdb_nodes` names another node first waits (up to two minutes) to see one, since ' +
				'residency ownership is not knowable before the node list is; a single node does not wait.',
			{
				publishInterval: option(
					1000,
					'How often worker 0 republishes the ready set from the keeper, and the longest a row that comes ' +
						'due waits before it can be claimed. A publish is skipped when nothing it depends on changed ' +
						'(forced every 10s regardless). A keeper not heard from in ten intervals (never under 30s) is ' +
						'reported stale but still served from — every entry is checked against its row — until its ' +
						'last set drains; then the node reports `unready`.',
					{ unit: 'ms', min: 100, max: 2147483647 }
				),
				verifyInterval: option(
					60 * MINUTE,
					'How often worker 0 walks the whole table and checks the keeper against it: every row it ' +
						'owns must be held at the same due minute and class, and every row held must still exist. ' +
						'Anything wrong is repaired from the table and counted (`queue_health` `keeper_repaired`); ' +
						'expect 0, since the subscription delivers every write. This bounds a missed write to one ' +
						'interval. A full primary-key walk, yielding every 200 rows: tens of seconds on a churned ' +
						'production store. `0` disables it.',
					{ unit: 'ms', min: 0, max: 2147483647 }
				),
				stateInterval: option(
					5000,
					'How often worker 0 recomputes queue state for `GET /prerender_admin/queue-state` and the ' +
						'backlog snapshot. Walks every occupied minute of every class, so it runs apart from the ' +
						'publish, which only takes the head of the queue.',
					{ unit: 'ms', min: 1000, max: 2147483647 }
				),
			}
		),
		dueNowForward: group(
			'FORWARD A "RENDER THIS NOW" TO THE ROW’S OWNER (v0.97.0). Every render-now, revalidate, admin ' +
				'rejoin and change-probe filing goes through one write that must never DEMOTE a row: a row ' +
				'already due keeps its due time, and a change mark keeps its first instant. That needs the row, ' +
				'and the row lives only on its residency owner — on any other node (about three in four on a ' +
				'four-node cluster) the local read sees nothing, and the whole-row write that replicates to the ' +
				'owner REPLACED its row: an overdue row pushed back to the current minute, its change mark and ' +
				'demand estimate wiped.\n\n' +
				'So a node that does not own the row asks the owner to file it (`POST /prerender_peer/due-now`), ' +
				'where the read is authoritative, and writes nothing itself. The owner never forwards onward. ' +
				'If the owner refuses or cannot be reached, the write is made locally exactly as before — never ' +
				'worse than without this — and that owner is not asked again for 30 seconds, so a peer that is ' +
				'down costs a bulk revalidate one timeout, not one per row. A SLOW answer is not a refusal: the ' +
				'owner may have filed it, and a local write landing after that filing would wipe what it kept. ' +
				'So a plain ask that times out is left to the owner (the worst case is one ask lost to a lost ' +
				'request), and only one carrying a change mark — whose loss leaves a page known wrong on the ' +
				'origin for a cadence — is written locally. Counted as `prerender_ops` `due_now_forward`.\n\n' +
				'REQUIRES `peerRescue.token` and `peerRescue.header` (the shared cluster secret the peer ' +
				'endpoints already use). With either unset this is inert and the endpoint answers 404.',
			{
				enabled: option(true, 'Forward when the peer token is configured. Off files every row locally, as before.'),
				timeoutMs: option(
					1000,
					'Deadline for one forwarded filing. Past it, an ask carrying a change mark is filed locally and ' +
						'any other is left to the owner (see above). Short, because a render-now waits on it: the bot ' +
						'is held for the render, and this sits in front of it. Capped at the 32-bit signed maximum ' +
						'because it reaches `setTimeout`.',
					{ unit: 'ms', min: 1, max: 2147483647 }
				),
			}
		),
	}),

	analytics: group(
		'Bot-request analytics. `bots` is the registry that gives crawlers a stable display name — ' +
			'remove an entry to stop tracking that bot under it. A UA the registry misses is not necessarily ' +
			"'other': with `deriveUnknownBots` on, a self-identifying crawler UA is labeled with the name it " +
			'declares, so a crawler the CDN starts forwarding before it’s registered still shows up in ' +
			'analytics under a usable name — promote recurring derived names into the registry to pin their ' +
			'display name. Only a UA that doesn’t self-identify at all becomes ‘other’, and ' +
			'`recordUnmatched` governs whether those are recorded.',
		{
			enabled: option(true, 'Record bot_request analytics at all.'),
			recordUnmatched: option(true, "Record requests whose UA yielded no name at all (as 'other')."),
			deriveUnknownBots: option(true, 'Label unregistered crawlers with the name their UA declares.'),
			bots: option(
				[
					// Entries must match the HTTP *request* User-Agent, not a robots.txt token.
					// Some crawler names exist only in robots.txt and never appear in a request UA
					// (Googlebot-News, Google-Extended, Applebot-Extended…) — an entry for one of
					// those never matches anything and just misleads readers of this list.
					//
					// Search engines
					{ name: 'Googlebot-Image', match: 'googlebot-image' },
					{ name: 'Googlebot-Video', match: 'googlebot-video' },
					{ name: 'Google InspectionTool', match: 'google-inspectiontool' },
					// the -Image/-Video variants need their own entries: the matcher requires a
					// boundary after the match, so bare `googleother` can't cross the hyphen
					{ name: 'GoogleOther-Image', match: 'googleother-image' },
					{ name: 'GoogleOther-Video', match: 'googleother-video' },
					{ name: 'GoogleOther', match: 'googleother' },
					{ name: 'Storebot-Google', match: 'storebot-google' },
					{ name: 'AdsBot-Google', match: 'adsbot-google' },
					{ name: 'Googlebot', match: 'googlebot' },
					{ name: 'Bingbot', match: 'bingbot' },
					{ name: 'DuckDuckBot', match: 'duckduckbot-https' },
					{ name: 'DuckDuckBot', match: 'duckduckbot' },
					{ name: 'Applebot', match: 'applebot' },
					{ name: 'YandexBot', match: 'yandexbot' },
					{ name: 'Baidu Spider', match: 'baiduspider' },
					{ name: 'SeznamBot', match: 'seznambot' },
					{ name: 'Naver Yeti', match: 'yeti' },
					{ name: 'Sogou Spider', match: 'sogou' },
					{ name: 'PetalBot', match: 'petalbot' },
					// AI crawlers & assistants
					{ name: 'GPTBot', match: 'gptbot' },
					{ name: 'OAI-SearchBot', match: 'oai-searchbot' },
					{ name: 'ChatGPT-User', match: 'chatgpt-user' },
					{ name: 'ClaudeBot', match: 'claudebot' },
					{ name: 'Claude-User', match: 'claude-user' },
					{ name: 'Claude-SearchBot', match: 'claude-searchbot' },
					{ name: 'PerplexityBot', match: 'perplexitybot' },
					{ name: 'Google-CloudVertexBot', match: 'google-cloudvertexbot' },
					{ name: 'Perplexity-User', match: 'perplexity-user' },
					{ name: 'CCBot', match: 'ccbot' },
					{ name: 'Bytespider', match: 'bytespider' },
					{ name: 'Meta-ExternalAgent', match: 'meta-externalagent' },
					{ name: 'Meta-ExternalFetcher', match: 'meta-externalfetcher' },
					{ name: 'FacebookBot', match: 'facebookbot' },
					{ name: 'Amazonbot', match: 'amazonbot' },
					{ name: 'DuckAssistBot', match: 'duckassistbot' },
					{ name: 'MistralAI-User', match: 'mistralai-user' },
					// SEO / site-audit tools
					{ name: 'AhrefsBot', match: 'ahrefsbot' },
					{ name: 'SemrushBot', match: 'semrushbot' },
					{ name: 'MJ12bot', match: 'mj12bot' },
					{ name: 'Rogerbot', match: 'rogerbot' },
					{ name: 'DotBot', match: 'dotbot' },
					{ name: 'Screaming Frog', match: 'screaming frog seo spider' },
					{ name: 'Botify', match: 'botify' },
					{ name: 'Deepcrawl', match: 'deepcrawl' },
					{ name: 'OnCrawl', match: 'oncrawl' },
					{ name: 'Sitebulb', match: 'sitebulb' },
				],
				'Crawler registry: { name, match } entries, where `match` is a case-insensitive substring of ' +
					'the User-Agent; longer matches win over shorter ones (e.g. `googlebot-image` before ' +
					'`googlebot`).',
				{ itemType: 'object' }
			),
		}
	),

	entities: group(
		'THE ENTITY REGISTRY (util/entity.js, issue #166): one `Entity` row per entity a route declares with ' +
			'`ingress.routes[].entityPrefix` (a product), keyed by the entity prefix, holding the entity\u2019s ' +
			'current canonical URL. Written by observations of the origin only — every fetch that says which URL is ' +
			'the canonical: the change probe\u2019s mapped `canonical` slot, a render\u2019s declared canonical (a ' +
			'stored page\u2019s, or a canonical verdict\u2019s), a serve-time check, and a document proxied from the ' +
			'origin on an `entityServe` route — the newer of two disagreeing observations winning, and only when ' +
			'the canonical moves. Replicated, not residency-pinned. Read by `entities.adopt` and the entity serve ' +
			'(`ingress.entityServe`). Observations on `prerender_ops` / `entity_canonical`.',
		{
			enabled: option(
				true,
				'Keep the registry. ON by default, and inert for any route without an `ingress.routes[].entityPrefix`: ' +
					'that prefix is the opt-in. On a route with one, the first probe pass writes one row per probed ' +
					'entity (paced by the probe) and renders fill in the rest; after that it writes only when a canonical ' +
					'moves. Nothing a crawler sees changes with it alone: adoption is dry run by default ' +
					'(`entities.adopt.dryRun`), and the entity serve needs its own opt-in. Off removes every registry ' +
					'read and write, and the entity serve then has no `moved` veto and no tie-break.'
			),
			adopt: group(
				'ADOPT A CANONICAL NO TARGET HOLDS (util/entity.js `resolveCanonical`, issue #166). When an observation ' +
					'names a canonical that is ANOTHER URL of the same entity than the one observed, and no target holds ' +
					'it in rotation (in any spelling: `%27` and an apostrophe are one document), its target is filed due ' +
					'now and urgent, as redirect adoption does. A target suppressed as a canonical verdict ' +
					'(`canonical-mismatch`, `canonical-variant`) is reactivated the same way; one suppressed for any other ' +
					'reason is left alone. The change probe observes through a rule that maps `canonical` in ' +
					'`pageCheck.fields` (an endpoint field holding the canonical path or URL, e.g. ' +
					'`{ slot: 6, fact: canonical, compare: path }`).\n\n' +
					'WHY: a product whose slug changes while it is out of stock is not in the sitemap, so its new ' +
					'canonical arrives only by traffic discovery, whose first render is jittered across the route\u2019s ' +
					'interval; measured, every spelling of such a product then missed for one to four days. The ' +
					'observations are the origin\u2019s own answers for the entity, so a crawler-invented spelling ' +
					'cannot make one invent a canonical. Outcomes on `prerender_ops` / `canonical_adopt`.',
				{
					enabled: option(
						true,
						'Switch. Files nothing while `dryRun` is on, and nothing at all with the registry off.'
					),
					dryRun: option(
						true,
						'Count `would-adopt` and file nothing. The default, because the number to know first is how many ' +
							'canonicals arming would file: `would-adopt` plus `capped`. A dry run remembers each entity it ' +
							'would have adopted, so a repeat inside `retryAfter` reads `recent` as it would armed, and counts ' +
							'against its own lane of the hourly budget, never an armed node\u2019s real slots. A change-probe ' +
							'pass run as a dry run \u2014 the probe\u2019s own `dryRun`, or an operator\u2019s measure-only ' +
							'sweep \u2014 files nothing either.'
					),
					maxPerHour: option(
						60,
						'Most targets adopted per hour on this node, across every worker thread and every observer. ' +
							'Measured on one deployment, products re-slug ~100 times a day cluster-wide; a site-wide ' +
							're-spelling would name every product\u2019s new canonical at once, so past this the rest count ' +
							'`capped` and wait for the next observation of them.',
						{ min: 0 }
					),
					retryAfter: option(
						7 * DAY,
						'An entity adopted once is not adopted again for this long, whichever canonical is named then: a ' +
							'canonical that did not take (it 404s, or its page names another canonical after all) costs one ' +
							'render per window, not one per observation, and two spellings that name each other cannot ' +
							'reactivate each other in turn.',
						{ unit: 'ms', min: HOUR }
					),
				}
			),
		}
	),

	demand: group(
		'The DEMAND TRACKER: which URLs bots actually ask for, and how often — measured, never acted on ' +
			'here. Every visit from a `bots` crawler to a URL in the render rotation sets bits in a ring of ' +
			'Bloom slices (`slices` x `sliceMs`, 4 days at the defaults) that replicate, so any node can ' +
			'answer for the cluster. A URL\u2019s DEMAND is how many of those slices saw a visit, 0 to ' +
			'`slices`, and its estimated visit period is the window divided by that count.\n\n' +
			'CONSUMERS decide what demand is worth, each with its own settings: the cadence ladder ' +
			'(`render.demand`) moves a target between render intervals, and `queue.ready.changedDemand` ' +
			'orders changed pages by how often they are asked for. Neither can act while this is off.\n\n' +
			'WHAT IT CANNOT SEE. Presence is per slice: one visit and a thousand in the same 6 hours read ' +
			'the same, so demand resolves periods from one slice up to the window and nothing faster. And ' +
			'false positives only ever ADD demand (there are no false negatives), which is why a saturated ' +
			'ring is the failure to watch — see `bitsPerSlice` and `maxFalsePositive`.\n\n' +
			'Moved from `render.demand` in v0.95.0, without an alias: a stored override on an old path ' +
			'reports as an unknown key until it is re-saved here.',
		{
			enabled: option(
				false,
				'Record bot visits at all. Off = nothing is recorded, every consumer reads demand as unknown ' +
					'and behaves as if it were off: the cadence ladder rests every target at its route cadence, ' +
					'and changed pages order by cadence.'
			),
			bots: option(
				['*'],
				'Bots whose visits count as demand, by the bot name the analytics registry resolves ' +
					"(analytics.bots / derived names / the literal 'other'), compared case-insensitively. " +
					"['*'] (default) counts every bot; [] counts none, so every target rests at its route " +
					'cadence; a list counts exactly those. Same shape and matching rules as ' +
					'`ingress.discoveryBots`, and worth setting for a related reason: every consumer spends ' +
					'render budget on what this counts (cadence, the order changed pages render in), and a third-party ' +
					'crawler walking the corpus breadth-first promotes pages no search engine asked for. ' +
					'It is also the first lever on ring saturation — see `bitsPerSlice`.',
				{ itemType: 'string' }
			),
			sliceMs: option(
				6 * HOUR,
				'Time resolution of the visit ring. Cannot be coarser than the fastest rung or that rung ' +
					'can never be evaluated.',
				{ unit: 'ms', min: 1 }
			),
			slices: option(
				16,
				'Ring length. Must cover promoteWindows x the slowest rung, so the promotion test for the ' +
					'top rung can see far enough back.',
				{ min: 2 }
			),
			bitsPerSlice: option(
				1 << 20,
				'Bloom filter bits per ring slice, rounded UP to a power of two at use (byte sizing and ' +
					'probe spread both require it). ~1M bits holds ~100k distinct URLs per slice at ~1% ' +
					'false positives. There are no false negatives, so a visited page is never demoted for ' +
					'lack of evidence.\n\n' +
					'SIZE THIS AGAINST THE DISTINCT-URL RATE, and treat overshoot as a correctness problem ' +
					'rather than a cost one. A slice holding n distinct URLs fills to `1 - e^(-kn/m)`, and ' +
					'the false-positive rate is `fill^k` — so it degrades not gradually but off a cliff: at ' +
					'the default k=7 and m=1M, 100k URLs fills to 0.49 (~0.7% false), 320k to 0.88 (~41%), ' +
					'640k to 0.986 (~91%). Past that the ring answers "visited" for essentially everything, ' +
					'the cadence ladder promotes the whole corpus to its floor, and nothing about the ' +
					'failure is loud — the cadence just stops being demand-driven (`maxFalsePositive` ' +
					'stops the newer consumers acting on such a ring; the ladder still does). Watch `demand_fill` at its PEAK, ' +
					'not its mean (it is a sawtooth that resets each slice).\n\n' +
					'WHAT A LARGER RING COSTS (v0.95.1: one copy per node, not per worker). Replicated bytes: ' +
					'the row is `bitsPerSlice / 8` bytes and replicates on every store (`flushInterval`) that ' +
					'changed it — the per-worker version of this write once produced a transaction log two ' +
					'orders of magnitude larger than the state it carried. Memory: `slices` x the row per node ' +
					'for the union, plus about two live slices. Reads: each `mergeInterval` one worker scans ' +
					'the ring’s row versions and fetches only the rows that changed — the current slice from ' +
					'each node — plus one local read of this node\u2019s own row per store. Size to the peak distinct URLs per slice with room: bits = `k n / -ln(1 - f)` ' +
					'for fill f, and f = `maxFalsePositive^(1/k)` (0.652 for 5% at k = 7). Cut what goes in ' +
					'too — `bots` above, and the rotation gate in `recordDemand` — since a URL no consumer can ' +
					'ever act on is pure fill.',
				{ min: 1024 }
			),
			hashes: option(
				7,
				'Bloom hash count (k). The false-positive rate is `fill^k`, and fill itself rises with k ' +
					'(`1 - e^(-kn/m)`), so the best k for a slice holding n distinct URLs in m bits is ' +
					'`(m/n) ln 2` — 7 suits ~100k URLs in the default 1M bits. A ring running far past its sizing ' +
					'is better served by more bits than by a smaller k: at 3.7 URLs per 10 bits, k = 7 reads ~53% ' +
					'false and k = 2 still ~25%.',
				{ min: 1, max: 32 }
			),
			flushInterval: option(
				5 * MINUTE,
				'How often this node\u2019s live slice is stored to its replicated row, by whichever worker ' +
					'holds the interval\u2019s turn (every worker sets its bits in the same shared slice). Only ' +
					'the current slice changes, so the replicated volume is about one `bitsPerSlice / 8` row ' +
					'per node per interval — the other half of the bytes question `bitsPerSlice` raises, and ' +
					'the lever for it: a visit reaches the other nodes up to one interval late, against a ' +
					'`sliceMs` slice.',
				{ unit: 'ms', min: SECOND, max: 2147483647 }
			),
			mergeInterval: option(
				5 * MINUTE,
				'How often the node\u2019s shared union of every node\u2019s rows is brought up to date — by one ' +
					'worker, incrementally: it reads the ring\u2019s row versions and fetches only the rows that ' +
					'changed. The reschedule path runs ~20x/s and cannot pay a read per job result, so every ' +
					'worker answers from the shared union, this stale at most. `demand_fill` and ' +
					'`demand_false_positive` are emitted at each refresh, once per node.',
				{ unit: 'ms', min: SECOND, max: 2147483647 }
			),
			maxFalsePositive: option(
				0.05,
				'The false-positive rate above which demand is UNKNOWN rather than a number. Measured at every ' +
					're-union as the worst full slice\u2019s `fill^k`; while it is exceeded, `queue.ready.changedDemand` ' +
					'falls back to cadence ordering.\n\n' +
					'Why a threshold rather than a correction: a URL nobody visits reads about `slices x rate` ' +
					'slices of demand from noise alone — at 0.05 over 16 slices that is 0.8, under one slice, so ' +
					'a real visit still outranks the noise. At 0.5 it is 8 of 16, and every URL reads as visited ' +
					'every 12 hours whether anyone asked for it or not.\n\n' +
					'The cadence ladder does NOT consult this: its decisions predate the tracker and are pinned ' +
					'as they were. A saturated ring still promotes the ladder\u2019s whole corpus to its floor.',
				{ min: 0, max: 1 }
			),
		}
	),
	crawlStats: group(
		'Crawl breadth: distinct URLs crawled per bot per UTC day, via per-thread HyperLogLog ' +
			'sketches flushed to crawl_stats.CrawlSketch. Read merged through ' +
			'GET /prerender_admin/crawl-breadth. Recording is additionally gated by the analytics ' +
			'gate (no bot name → nothing to attribute a sketch to).',
		{
			enabled: option(true, 'Record crawl-breadth sketches at all.'),
			flushInterval: option(
				5 * MINUTE,
				'Per-thread sketch persistence cadence — the maximum sketch data lost on a crash.',
				{ unit: 'ms', min: SECOND }
			),
			retentionDays: option(90, 'Sketch rows older than this are swept at day rollover.', { min: 1 }),
			precision: option(
				14,
				'HyperLogLog precision `p`. Sets both the accuracy and the SIZE of every sketch row: the ' +
					'sketch is 2^p registers of one byte, so p = 14 is 16 KB with a standard error of ' +
					'~1.04/sqrt(2^p) ≈ 0.8%, p = 12 is 4 KB at ~1.6%, and p = 10 is 1 KB at ~3.3%.\n\n' +
					'This is the lever for the WRITE side, not just for memory. Rows are replicated and ' +
					'rewritten on every flush, so halving p halves the transaction-log volume this table ' +
					'generates — and crawl breadth is a reporting number where a couple of percent of ' +
					'error is immaterial, which makes a lower p unusually cheap. Weigh it against what the ' +
					'estimate is used for before moving it.\n\n' +
					'CHANGING IT RESHAPES EVERY SKETCH. A row written at a different p describes a ' +
					'different register space and cannot be merged with one written at this p, so ' +
					'mismatched rows are ignored rather than merged: expect that day to undercount for ' +
					'the bots involved (and, during a staggered rollout, to ignore shards from nodes ' +
					'still on the old value) until the next UTC day rollover starts every sketch fresh. ' +
					'Nothing is corrupted and nothing needs migrating; one day of breadth numbers is ' +
					'soft. Prefer changing it at a day boundary. The crawl-breadth response reports the ' +
					'shards it had to ignore as `mismatchedShards`, so that undercount is a number an ' +
					'operator can see rather than a smaller-looking day.',
				{ min: 8, max: 16 }
			),
			maxBotsPerThread: option(
				64,
				'Sketches are 16 KB each; this caps a UA-derivation flood from minting unbounded per-thread ' +
					"sketches. Overflow bots share one '~overflow' bucket for the day.",
				{ min: 1 }
			),
		}
	),

	sampling: group(
		'REQUEST SAMPLING: a log of sampled bot requests for questions no counter answers — above all, how ' +
			'often each crawler comes back to a page, per page type and device. Each sampler in `samplers` ' +
			'matches requests, samples them, and records a fixed set of fields. Each worker appends its records ' +
			'to its own gzipped NDJSON file per sampler per UTC day, in `directory` on this node, read back ' +
			'through `GET /prerender_admin/samples` on each node. Everything but `directory` is live: add, ' +
			'change or switch off a sampler with an override row and it takes effect within a second, no ' +
			'restart.\n\n' +
			'COST. Off, or with no sampler for a request\u2019s route and bot, a request pays a null check or ' +
			'two map lookups. A sampled request writes into a preallocated per-worker ring and never waits on ' +
			'storage. Records still in a worker\u2019s ring when it stops are lost (at most one `flushInterval`).',
		{
			enabled: option(
				false,
				'Run the samplers. Off: nothing is matched or recorded, the ring is released, and records already ' +
					'taken are written out. Old files are still deleted on schedule.'
			),
			directory: option(
				'',
				'Where this node writes sample files, as an absolute path; one subdirectory per sampler. Empty ' +
					'(default): `prerender-sampling` under Harper\u2019s root. It must be persistent and outside the ' +
					'component directory, which a deploy replaces. A relative path is refused and nothing is ' +
					'recorded.',
				// FILE-ONLY: a path the plugin writes, reads back through the admin API and deletes from is not
				// something to repoint from the console.
				{ uiEditable: false }
			),
			keepDays: option(
				14,
				'Days of sample files kept. Worker 0 deletes older files (by the day in the file name) every ' +
					'hour, for every sampler directory, including samplers no longer configured.',
				{ min: 1, max: 90 }
			),
			flushInterval: option(
				60_000,
				'How often each worker appends its records. A ring half full flushes at once whatever this says. ' +
					'Longer means fewer appends and more records at risk when a worker stops.',
				{ unit: 'ms', min: 5_000, max: HOUR }
			),
			ringSize: option(
				4096,
				'Records each worker can hold between flushes, preallocated while sampling is on (~270 bytes a ' +
					'slot, twice over: a flush swaps in a second array). A full ring drops new records and counts ' +
					'them (`dropped`): raise this, or shorten `flushInterval`, if that number is not zero.',
				{ min: 64, max: 32_768 }
			),
			samplers: option(
				[],
				'The samplers, each an object:\n\n' +
					'- `name` (required): letters, digits, `.`, `-`, `_`, at most 64. Its directory, and the key its ' +
					'records are read under; unique.\n' +
					'- `enabled` (default true).\n' +
					"- `match`: every key narrows, and an absent key means any. Lists of strings, where `['*']` " +
					'also means any: `routes` (a route\u2019s `path`, or a route class: `prerender`, `passthrough`, ' +
					'`unclassified`), `bots` (names as the analytics registry resolves them, case-insensitive), ' +
					'`devices`, `methods`, `cacheStatuses`, `sources`. And `statuses` (numbers; the status sent, ' +
					'304s and the handler\u2019s own 500s included), `urls` (exact URLs as the cache key spells them, ' +
					'at most 10,000) and `urlPattern` (a regular expression on that URL).\n' +
					'- `sample`: `by` (`url`, the default: a URL is in or out by a hash of the URL and `salt`, so ' +
					'every request for a sampled URL is recorded, from every bot, for as long as the sampler runs ' +
					'\u2014 the shape for revisit questions; `request`: each request independently), `rate` (above 0, ' +
					'at most 1; default 0.01) and `salt` (default the name). Under `by: url`, raising `rate` keeps ' +
					'every URL already in and adds more; changing `salt` picks a different set. A URL is in when ' +
					"`fnv1a32(salt + '\\n' + url) < rate * 2^32`, so an analysis can recompute the set.\n" +
					'- `fields`: what to record, from `ts` (always), `url`, `cacheKey`, `route`, `routeClass`, ' +
					'`bot`, `device`, `method`, `status`, `cacheStatus`, `source`, `ageMs` (age of the copy served), ' +
					'`entityUrl`, `renderNow`, `conditional` (the request carried validators), `node`, `worker`, ' +
					'and two read once per distinct URL when the batch is written, never on the request: `target` ' +
					'(active, suppressed, null for none, or unknown when the read failed) and `sitemap` ' +
					'(sitemap-listed). Default: ts, url, route, bot, device, method, status, cacheStatus, source, ' +
					'ageMs.\n' +
					'- `headers`: request headers to record, by name, at most 8. Credentials are always refused: ' +
					'any name containing cookie, auth, token, secret, password, session or api-key, and the headers ' +
					'this plugin authenticates on (`origin.securityToken.header`, `renderNow.header`, ' +
					'`peerRescue.header`). No client address is recorded unless a header carrying one is listed.\n' +
					'- `maxPerMinute` (default 120, at most 6000): per worker. Picks over it are counted (`capped`), ' +
					'not recorded.\n\n' +
					'COMPLETENESS. Picks not recorded \u2014 `capped`, `dropped` (ring full) and `lost` (an append that ' +
					'failed) \u2014 are written into the same file as a line `{"ts":\u2026,"counters":{\u2026}}`, so a ' +
					'URL-stable sample is complete for any window whose counters lines sum to zero.\n\n' +
					'An invalid entry is dropped, not the list, and an override that would drop one is refused. ' +
					'Unknown keys make an entry invalid: every key narrows the match, so a misspelled one would ' +
					'otherwise widen it silently.',
				{ itemType: 'object' }
			),
		}
	),
});

const clone = (value) => {
	if (Array.isArray(value)) return value.map(clone);
	if (value && typeof value === 'object') {
		const out = {};
		for (const [key, inner] of Object.entries(value)) out[key] = clone(inner);
		return out;
	}
	return value;
};

/** Fresh defaults derived from the schema (deep-cloned, safe to mutate). */
export const defaultConfig = () => {
	const build = (node) => {
		if (isOption(node)) return clone(node.default);
		const out = {};
		for (const [key, child] of Object.entries(node.children)) out[key] = build(child);
		return out;
	};
	return build(configSchema);
};

/**
 * Walk every option in the schema, calling `visit(path, node, inheritedScope)` with the
 * dotted path (no `prerender.` prefix) and the option's effective scope.
 */
/**
 * Visit every option in the schema as `(dottedPath, node, scope)`, depth-first in declaration
 * order. Public because config.js walks it to build the per-option layer/provenance view.
 */
export const walkOptions = (visit) => {
	const walk = (node, path, inheritedScope) => {
		const scope = node.scope ?? inheritedScope;
		if (isOption(node)) return visit(path, node, scope);
		for (const [key, child] of Object.entries(node.children)) {
			walk(child, path ? `${path}.${key}` : key, scope);
		}
	};
	walk(configSchema, '', 'live');
};

/** Dotted paths of secret options (drives redaction). */
export const secretPaths = () => {
	const paths = [];
	walkOptions((path, node) => {
		if (node.secret) paths.push(path);
	});
	return paths;
};

/** Dotted paths of restart-scoped options (drives pending-restart detection). */
export const restartPaths = () => {
	const paths = [];
	walkOptions((path, node, scope) => {
		if (scope === 'restart') paths.push(path);
	});
	return paths;
};

/**
 * Map of legacy dotted path -> current dotted path, from `movedFrom` markers (a marker
 * on a group covers its whole subtree).
 */
export const aliasPaths = () => {
	const aliases = {};
	const walk = (node, path) => {
		if (node.movedFrom) aliases[node.movedFrom] = path;
		if (isGroup(node)) {
			for (const [key, child] of Object.entries(node.children)) walk(child, path ? `${path}.${key}` : key);
		}
	};
	walk(configSchema, '');
	return aliases;
};

const typeOf = (defaultValue) => (Array.isArray(defaultValue) ? 'array' : typeof defaultValue);

/**
 * JSON-serializable schema description for the management API / admin UI. Groups become
 * { kind: 'group', description, scope?, children }; options become
 * { kind: 'option', type, description, scope, default, ...validation/display hints }.
 * Secret defaults are all empty strings, so defaults are safe to serve as-is.
 */
export const describeConfigSchema = () => {
	const describe = (node, inheritedScope, inheritedEditable) => {
		const scope = node.scope ?? inheritedScope;
		// `uiEditable` inherits downward exactly like `scope`, so marking a group file-only covers
		// every option inside it without repeating the marker (and without a later addition to that
		// group silently becoming editable).
		const groupEditable = node.uiEditable ?? inheritedEditable;
		if (isOption(node)) {
			const out = { kind: 'option', type: typeOf(node.default), description: node.description, scope };
			out.default = clone(node.default);
			for (const key of [
				'enum',
				'itemEnum',
				'items',
				'unit',
				'min',
				'max',
				'nonEmpty',
				'itemType',
				'secret',
				'movedFrom',
			]) {
				if (node[key] !== undefined) out[key] = node[key];
			}
			// Resolved rather than raw: the console renders a control from this, so it must not have to
			// re-derive the secret rule or walk back up for an ancestor's marker.
			out.uiEditable = groupEditable !== false && !node.secret;
			return out;
		}
		const children = {};
		for (const [key, child] of Object.entries(node.children)) {
			children[key] = describe(child, scope, groupEditable);
		}
		const out = { kind: 'group', description: node.description, children };
		if (node.scope) out.scope = node.scope;
		if (node.uiEditable === false) out.uiEditable = false;
		if (node.movedFrom) out.movedFrom = node.movedFrom;
		return out;
	};
	return describe(configSchema, 'live', true);
};

/**
 * The entries of a list that break the option's `items` rule; empty when all pass or there is no
 * rule. Shared by the apply-time constraint pass and the override door, so the two cannot disagree.
 */
export const invalidItems = (node, list) => {
	const rule = node?.items;
	if (!rule || !Array.isArray(list)) return [];
	return list.filter(
		(entry) =>
			typeof entry !== 'number' ||
			!Number.isFinite(entry) ||
			(rule.integer && !Number.isInteger(entry)) ||
			(rule.min !== undefined && entry < rule.min) ||
			(rule.max !== undefined && entry > rule.max) ||
			(Array.isArray(rule.not) && rule.not.includes(entry))
	);
};

/** An `items` rule as the reason a refusal gives. */
export const describeItemRule = (rule) =>
	[
		rule.integer ? 'an integer' : 'a number',
		rule.min !== undefined && rule.max !== undefined
			? `from ${rule.min} to ${rule.max}`
			: rule.min !== undefined
				? `>= ${rule.min}`
				: rule.max !== undefined
					? `<= ${rule.max}`
					: null,
		Array.isArray(rule.not) && rule.not.length ? `other than ${rule.not.join(', ')}` : null,
	]
		.filter(Boolean)
		.join(' ');

/**
 * May the console write this path, and if not, why not?
 *
 * The refusal reason is returned rather than logged because it is shown to the operator who tried:
 * "that is a secret, set the environment variable" and "that option is deliberately file-only" are
 * different problems with different fixes, and both are different from a typo'd path.
 *
 * @param {string} path dotted option path
 * @returns {{ ok: true, node: object } | { ok: false, reason: string }}
 */
export const checkUiEditable = (path) => {
	let node = configSchema;
	let editable = configSchema.uiEditable ?? true;
	for (const segment of String(path ?? '').split('.')) {
		// Own-key check for the same reason as `schemaNodeAt`: `children['constructor']` is truthy and
		// is not an option, and answering a refusal is only correct if the walk cannot be fooled.
		if (!isGroup(node) || !Object.hasOwn(node.children, segment)) {
			return { ok: false, reason: `${path} is not a configuration option` };
		}
		node = node.children[segment];
		if (!node) return { ok: false, reason: `${path} is not a configuration option` };
		if (node.uiEditable === false) editable = false;
	}
	if (!isOption(node)) {
		return { ok: false, reason: `${path} is a group of options, not a single option` };
	}
	if (node.secret) {
		return {
			ok: false,
			reason: `${path} is a secret — set it through its environment variable, not from the console`,
		};
	}
	if (!editable) {
		return { ok: false, reason: `${path} is deliberately not editable from the console` };
	}
	return { ok: true, node };
};

/** Look up the schema node (option or group) at a dotted path, or undefined. */
export const schemaNodeAt = (path) => {
	// Coerced and own-key-checked because callers feed this paths that came from a database row. A
	// bare `children[segment]` lookup answers `__proto__` and `constructor` from the prototype chain
	// — truthy values that are not schema nodes — and a non-string path would throw on `.split`.
	// Anything that is not an actual declared node is simply not an option.
	let node = configSchema;
	for (const segment of String(path ?? '').split('.')) {
		if (!isGroup(node) || !Object.hasOwn(node.children, segment)) return undefined;
		node = node.children[segment];
		if (!node) return undefined;
	}
	return node;
};

export { SECOND, MINUTE, HOUR, DAY };