feat(plugin): every fetch from the origin resolves the entity's canonical, and the entity serve trusts the newest word; v0.102.0

The registry now learns from renders (a canonical verdict's declared canonical included), serve-time
checks and proxied origin documents as well as the nightly probe, and adopts a canonical no target holds
from any of them. The entity serve answers spellings suppressed as canonical verdicts, refuses a page the
registry has since heard re-slugged (moved), lets the registry break a tie, refuses query strings, and
times each evaluation. Console 0.26.0 charts the registry and the new outcomes.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: trial

package-lock.json

@@ -1,6 +1,6 @@
 {
 	"name": "@harperfast/prerender-console",
-	"version": "0.25.0",
+	"version": "0.26.0",
 	"type": "module",
 	"description": "Standalone Harper component serving the prerender management console UI, proxying to a prerender deployment's /prerender_admin API",
 	"license": "Apache-2.0",

packages/console/package.json

@@ -186,6 +186,7 @@ export function render(ctx) {
 		rawCache(ctx, data, filter),
 		negativeCache(ctx, data, filter),
 		entityServe(ctx, data, filter),
+		entityRegistry(ctx, data),
 		breadth(ctx, filter),
 		el('div', { cls: 'scan-foot' }, [scanFooter(data)]),
 		knobs,
@@ -2310,14 +2311,16 @@ function negativeCache(ctx, data, filter) {
 // Why an entity serve fell through (plugin `prerender_ops` / `entity_serve`), with what each one means.
 const ENTITY_FALL_THROUGHS = [
 	['unconfirmed', 'canonical not rendered or checked since the anchor'],
-	['has-target', 'the spelling has a target of its own'],
+	['has-target', 'the spelling has a target the render path keeps'],
+	['moved', 'the registry heard a re-slug since'],
 	['no-page', 'no page for this device'],
 	['stale', 'past its expiry'],
 	['not-indexable', 'not a 200, or not indexable'],
 	['invalidated', 'predates an invalidation'],
-	['ambiguous', 'more than one candidate'],
+	['ambiguous', 'more than one candidate, none named by the registry'],
 	['no-sibling', 'no other target in rotation'],
 	['not-self-canonical', 'its canonical does not name it'],
+	['has-query', 'a query string'],
 	['unreadable', 'body unreadable'],
 	['no-prefix', 'no entity prefix'],
 	['error', 'read failed'],
@@ -2338,10 +2341,13 @@ function entityServe(ctx, data, filter) {
 		(entry) => entry && typeof entry === 'object' && entry.entityServe === true
 	);
 	const served = sumCount(pick(data, 'bot_serve', (s) => s.method === 'entity' && keepBot(filter, s.type)));
+	// Each evaluation's duration (plugin v0.102.0): what an opted-in route adds to a miss it does not answer.
+	const timings = pick(data, 'prerender_ops', (s) => s.path === 'entity_serve_ms');
 	const help = [
-		'A miss for a spelling with no page and no target of its own (an old or invented slug), answered from the ',
-		'cached render of its entity’s canonical: a fresh, indexable page that names itself, whose canonical was ',
-		'rendered or checked against the origin since the anchor. Switches: ',
+		'A miss for a spelling with no page and no target the render path keeps (an old or invented slug, or one ',
+		'suppressed because its page names its canonical elsewhere), answered from the cached render of its ',
+		'entity’s canonical: a fresh, indexable page that names itself, whose canonical was rendered or checked ',
+		'against the origin since the anchor, and not heard re-slugged since by the entity registry. Switches: ',
 		el('code', { text: 'ingress.entityServe' }),
 		' and ',
 		el('code', { text: 'entityServe' }),
@@ -2403,12 +2409,120 @@ function entityServe(ctx, data, filter) {
 						.join(' · ') || 'none',
 					{ warn: ev('error') + ev('unreadable') > 0 }
 				),
+				timings.length > 0 &&
+					stat(
+						'Cost per evaluation',
+						fmtMs(weighted(timings, 'median')),
+						`median · p95 ≈ ${fmtMs(weighted(timings, 'p95'))} · added to a miss it does not answer`
+					),
 			]),
 			!events.length && el('div', { cls: 'empty', text: 'No entity-serve evaluations in this range.' }),
 		],
 	});
 }
 
+// Who told the entity registry (plugin `entity_canonical` / `canonical_adopt` context), in the order a re-slug is
+// usually seen: the origin documents crawlers pull, the renders, the serve-time checks, the nightly probe.
+const ENTITY_OBSERVERS = [
+	['origin', 'proxied origin documents'],
+	['render', 'renders'],
+	['check', 'serve-time checks'],
+	['probe', 'the nightly probe'],
+];
+
+/**
+ * The entity registry (plugin v0.101.0, `entities`): each product's current canonical, learned from every fetch
+ * from the origin. `entity_canonical` is every observation by what it did (`moved` is a re-slug seen, by the
+ * observer that saw it first); `canonical_adopt` is what was done about a canonical no target held. In an
+ * adoption dry run, `would-adopt` plus `capped` is what arming files.
+ */
+function entityRegistry(ctx, data) {
+	const observed = pick(data, 'prerender_ops', (s) => s.path === 'entity_canonical');
+	const adoptions = pick(data, 'prerender_ops', (s) => s.path === 'canonical_adopt');
+	const options = optionIndex(configState(ctx).payload);
+	const enabled = options.get('entities.enabled')?.effective === true;
+	const adoptOn = options.get('entities.adopt.enabled')?.effective !== false;
+	const adoptDry = options.get('entities.adopt.dryRun')?.effective !== false;
+	const help = [
+		'One row per product holding its current canonical, written by every fetch from the origin that names it: ',
+		'proxied misses, renders, serve-time checks and the nightly probe. A canonical no target holds is filed due ',
+		'now (adoption). Switches: ',
+		el('code', { text: 'entities' }),
+		' (',
+		link('Config →', () => ctx.go('config')),
+		').',
+	];
+	if (!enabled && !observed.length && !adoptions.length) {
+		return card('Entity registry', {
+			head: [spacer(), pill('off', '')],
+			help,
+			body: [el('div', { cls: 'empty', text: 'Off.' })],
+		});
+	}
+	const tally = (combos) => {
+		const by = new Map();
+		for (const s of combos) {
+			const key = `${s.method ?? 'unknown'}|${s.type ?? 'unknown'}`;
+			by.set(key, (by.get(key) ?? 0) + s.count);
+		}
+		return (outcome, from = null) =>
+			from === null
+				? [...by].filter(([key]) => key.startsWith(`${outcome}|`)).reduce((acc, [, n]) => acc + n, 0)
+				: (by.get(`${outcome}|${from}`) ?? 0);
+	};
+	const seen = tally(observed);
+	const did = tally(adoptions);
+	const filed = did('adopted') + did('reactivated');
+	const wouldFile = did('would-adopt');
+	const byObserver = (count) =>
+		ENTITY_OBSERVERS.map(([from, label]) => [label, count(from)])
+			.filter(([, n]) => n > 0)
+			.map(([label, n]) => `${num(n)} ${label}`)
+			.join(' · ') || 'none';
+
+	return card(`Entity registry — ${scopeLabel(data)}`, {
+		head: [
+			enabled ? pill('on', 'ok') : pill('off', 'warn'),
+			adoptOn ? (adoptDry ? pill('adoption dry run', 'info') : pill('adoption armed', 'ok')) : pill('adoption off', ''),
+			spacer(),
+		],
+		help,
+		body: [
+			stats([
+				stat(
+					'Re-slugs seen',
+					fmtCount(seen('moved')),
+					byObserver((from) => seen('moved', from))
+				),
+				stat('New entities', fmtCount(seen('new')), 'first observation of a product'),
+				adoptDry
+					? stat(
+							'Would adopt',
+							fmtCount(wouldFile + did('capped')),
+							`${num(wouldFile)} under the hourly budget · ${num(did('capped'))} past it`,
+							{ warn: did('capped') > 0 }
+						)
+					: stat(
+							'Adopted',
+							fmtCount(filed),
+							byObserver((from) => did('adopted', from) + did('reactivated', from)),
+							{
+								warn: did('capped') > 0,
+							}
+						),
+				stat(
+					'Not adopted',
+					fmtCount(did('exists') + did('suppressed') + did('recent') + did('refused') + did('error')),
+					`${num(did('exists'))} already held · ${num(did('recent'))} recent · ${num(did('suppressed'))} suppressed` +
+						(did('error') ? ` · ${num(did('error'))} errors` : ''),
+					{ warn: did('error') > 0 }
+				),
+			]),
+			!observed.length && !adoptions.length && el('div', { cls: 'empty', text: 'No registry activity in this range.' }),
+		],
+	});
+}
+
 /** Days of crawl sketch one breadth read covers — the Crawl breadth panel's trend and the miss recurrence. */
 const BREADTH_DAYS = 7;
 

packages/console/src/admin/views/traffic.js

@@ -297,16 +297,6 @@ test('a metric the plugin emits is charted by the console, or waived with a reas
 			'prerender_ops.entity_gate',
 			'dry-run census; read raw from /prerender_admin/analytics — armed refusals land in discovery_gated',
 		],
-		// The entity registry (plugin v0.101.0) ships off, and its adoption in dry run. Its two series are read
-		// raw from the analytics endpoint during that window; a console panel for them is the follow-up.
-		[
-			'prerender_ops.entity_canonical',
-			'registry ships off; read raw from /prerender_admin/analytics during the dry run — panel follows',
-		],
-		[
-			'prerender_ops.canonical_adopt',
-			'adoption ships in dry run; read raw from /prerender_admin/analytics (would-adopt) — panel follows',
-		],
 		// `render.change_lag_ms` and `prerender_ops.due_now_forward` (plugin v0.97.0) are charted on the Queue
 		// view since console v0.22.0 (Change to cache, Filing).
 	]);

packages/console/test/adminAssets.test.js

@@ -1378,3 +1378,70 @@ test('miss rows fold route and bot per cause, and an unknown cause gets its own
 	// A device outside deviceTypes.default is configuration, not capacity: it never waits on a render.
 	assert.equal(missRows([combo('bot_miss', 'device', '/a', 'googlebot', 1)])[0].family, 'rule');
 });
+
+// ---- the entity registry (plugin entities) ------------------------------------------
+
+test('the entity-serve panel names the newer fall-throughs and what an evaluation costs', async () => {
+	const analytics = {
+		...ANALYTICS,
+		series: [
+			...ANALYTICS.series,
+			combo('prerender_ops', 'entity_serve', 'served', 'bingbot', 500),
+			combo('prerender_ops', 'entity_serve', 'moved', 'bingbot', 30),
+			combo('prerender_ops', 'entity_serve', 'has-query', 'bingbot', 20),
+			combo('prerender_ops', 'entity_serve_ms', null, null, 550, 1.5, 6),
+		],
+	};
+	const config = {
+		...CONFIG,
+		layers: [
+			...CONFIG.layers.filter((layer) => layer.path !== 'ingress.routes'),
+			{ path: 'ingress.routes', effective: [{ match: 'prefix', path: '/product/', entityServe: true }] },
+			{ path: 'ingress.entityServe.dryRun', effective: false },
+		],
+	};
+	const ctx = makeCtx({ analytics, config });
+	await load(ctx);
+	const text = everything(ctx);
+	assert.match(text, /30 the registry heard a re-slug since · 20 a query string/);
+	assert.match(text, /Cost per evaluation/);
+	assert.match(text, /median · p95/);
+});
+
+test('the registry panel: re-slugs seen by the observer that saw them, and the adoption dry-run number', async () => {
+	const analytics = {
+		...ANALYTICS,
+		series: [
+			...ANALYTICS.series,
+			combo('prerender_ops', 'entity_canonical', 'moved', 'origin', 60),
+			combo('prerender_ops', 'entity_canonical', 'moved', 'render', 25),
+			combo('prerender_ops', 'entity_canonical', 'moved', 'probe', 15),
+			combo('prerender_ops', 'entity_canonical', 'new', 'probe', 9000),
+			combo('prerender_ops', 'entity_canonical', 'same', 'probe', 900000),
+			combo('prerender_ops', 'canonical_adopt', 'would-adopt', 'origin', 70),
+			combo('prerender_ops', 'canonical_adopt', 'capped', 'probe', 5),
+			combo('prerender_ops', 'canonical_adopt', 'exists', 'probe', 1200),
+		],
+	};
+	const config = {
+		...CONFIG,
+		layers: [...CONFIG.layers, { path: 'entities.enabled', effective: true }],
+	};
+	const ctx = makeCtx({ analytics, config });
+	await load(ctx);
+	const text = everything(ctx);
+	assert.match(text, /Entity registry/);
+	assert.match(text, /adoption dry run/);
+	assert.match(text, /Re-slugs seen/);
+	assert.match(text, /60 proxied origin documents · 25 renders · 15 the nightly probe/);
+	assert.match(text, /Would adopt/);
+	assert.match(text, /70 under the hourly budget · 5 past it/);
+	assert.match(text, /1,200 already held/);
+});
+
+test('the registry panel is a quiet “off” when the registry is off and silent', async () => {
+	const ctx = makeCtx({ analytics: ANALYTICS });
+	await load(ctx);
+	const text = everything(ctx);
+	assert.match(text, /Entity registry/);
+});

packages/console/test/trafficView.test.js

@@ -189,21 +189,29 @@ Notes that bite:
   traffic is answered that way. `entity_serve` is one emit per evaluation of a true miss on an
   opted-in route, detail = outcome, context = bot: `served`, `would-serve` (every guard passed under
   `ingress.entityServe.dryRun`; the miss path answered it — **the dry-run number**, to read against
-  `bot_serve` `origin`/`miss` on the route), or the guard that fell through: `has-target`,
-  `no-sibling`, `no-page`, `not-indexable`, `stale`, `invalidated`, `ambiguous`, `unconfirmed`,
-  `not-self-canonical`, `unreadable`, `no-prefix`, `error`. Read `has-target` with the entity gate in
-  mind: in a gate dry run every spelling a minting crawler asks for again has a target by then.
-  `unconfirmed` climbs right after the anchor and falls as the pass and the serve-time checks
-  confirm canonicals. If a route stays there, no check compares its `canonical`.
+  `bot_serve` `origin`/`miss` on the route), or the guard that fell through: `has-query`,
+  `has-target`, `no-sibling`, `no-page`, `not-indexable`, `stale`, `invalidated`, `ambiguous`,
+  `unconfirmed`, `moved`, `not-self-canonical`, `unreadable`, `no-prefix`, `error`. Read `has-target`
+  with the entity gate in mind: in a gate dry run every spelling a minting crawler asks for again has
+  a target by then (since v0.102.0 a spelling suppressed as a canonical verdict is answered, not
+  `has-target`). `unconfirmed` climbs right after the anchor and falls as the pass and the serve-time
+  checks confirm canonicals. If a route stays there, no check compares its `canonical`. `moved`
+  (v0.102.0, `entities.enabled`) is a page the registry has since heard re-slugged: it should be rare,
+  and should not persist for an entity, because the observation that moved the registry also adopted
+  the new canonical. `entity_serve_ms` (v0.102.0) is each evaluation's duration, every outcome: a
+  duration, so read its percentiles.
 - **The entity registry is `prerender_ops` / `entity_canonical` and `canonical_adopt`** (v0.101.0,
   `entities.enabled`). `entity_canonical`: one emit per observation of an entity's canonical, detail =
   what it did to the registry (`new`, `moved`, `same`, `older`, `foreign`, `unreadable`, `error`),
-  context = the observer (`probe` or `render`). `moved`/`probe` per day is the re-slug rate; `moved`
-  alternating between `probe` and `render` for the same entities means the endpoint and the page
-  disagree about the canonical. `canonical_adopt` (`entities.adopt`): one emit per adoption decision,
-  made only when an observation names a canonical that is another URL than the one observed: `adopted`,
-  `reactivated`, `would-adopt` (**the dry-run number**), `exists` (every duplicate spelling, nightly),
-  `suppressed`, `recent`, `capped` (past `maxPerHour` on this node), `refused`, `error`.
+  context = the observer: `probe`, `render` (a stored page, or a canonical verdict's declared canonical),
+  `check` (a serve-time check) or `origin` (a proxied origin document on an `entityServe` route; the last
+  two since v0.102.0). `moved` per day is the re-slug rate, and which observer moves it first says how
+  fast a re-slug is seen. `moved` alternating between `probe` and `render` for the same entities means
+  the endpoint and the page disagree about the canonical. `canonical_adopt` (`entities.adopt`): one emit
+  per adoption decision, made only when an observation names a canonical that is another URL than the
+  one observed, context = the observer: `adopted`, `reactivated`, `would-adopt` (**the dry-run
+  number**), `exists` (every duplicate spelling, nightly), `suppressed`, `recent`, `capped` (past
+  `maxPerHour` on this node), `refused`, `error`.
 - **The change probe's `probe_*` series changed shape in v0.97.0, and the table row above predates
   it.** (1) The pass counters are emitted **per probed batch as increments**, not once when a pass
   ends: a nine-hour pass is no longer one row that a dropped analytics window loses whole, and a pass