@certrev/cert-block 2.0.0 → 2.0.2

package/src/builder/contract-card.tsx

@@ -21,7 +21,18 @@
  *    injected. Only the block that prints the runtime's tag loads it (`cardCarriesAssets`). The server's HTML carries
  *    the same tag in that block's wrapper, which the parser runs; the runtime's init is idempotent, so it starts once.
  * Both run in a layout effect, before the browser paints the inserted card, so a client-mounted card never shows an
- * empty frame.
+ * empty frame; the roots are checked after every commit of the block, whatever React wrote. React writes the card only
+ * when its HTML changes: the `dangerouslySetInnerHTML` object is kept per string, since React 19 rewrites `innerHTML`
+ * for every new object (2.0.0 on React 19 rebuilt the card on each re-render, and the hosted runtime re-attached it).
+ *
+ * NO CONSOLE NOISE (2.0.1). In a browser that parses declarative roots, the HTML React itself writes names each
+ * template's mode `data-certrev-shadowrootmode` instead of `shadowrootmode` (`clientCardHtml`): Chrome warns ("Found
+ * declarative shadowrootmode attribute on a template, but declarative Shadow DOM is not being parsed") for every such
+ * template `innerHTML` meets, and the layout effect re-parses the card's exact bytes anyway. The wrapper carries
+ * `suppressHydrationWarning` (React never prints it): the server's wrapper holds attached roots where React expects
+ * templates, which React's development build reported as a hydration mismatch on every page. React does not patch a
+ * hydrated element's HTML, so the server's card stays as the parser built it. A server, and a DOM without declarative
+ * roots (jsdom, an old browser), print the card's bytes unchanged.
  *
  * ONE BUILDER RULE, for the sidebar card only. The card's rail is a right float that the article's copy flows around
  * (the Appearance preview's layout, and every other CMS's). On a Builder page the block sits in Builder's own wrapper,
@@ -34,7 +45,9 @@
  */
 
 import * as React from 'react'
+import { maybeSendBrowserHealth } from './card-beacon.js'
 import { type CardDocumentV1, type CardPartName, cardCarriesAssets, cardHtml } from './card-contract.js'
+import { afterPageSettles, applyCardPlacement } from './card-placement.js'
 import { SEED_ATTRIBUTE } from './ssr-seed.js'
 
 /** The global the hosted runtime sets once it has started (`Symbol.for('certrev.card-runtime')` on `document`). */
@@ -45,18 +58,36 @@ const INJECTED_RUNTIME_ATTRIBUTE = 'data-certrev-card-runtime'
 /** A layout effect in a browser; nothing on a server (where React would only warn about it). */
 const useBrowserLayoutEffect = typeof document === 'undefined' ? () => {} : React.useLayoutEffect
 
+/** What a client render prints in place of a template's `shadowrootmode` (the header comment). */
+export const INERT_MODE_ATTRIBUTE = 'data-certrev-shadowrootmode'
+
+/** Whether this DOM parses declarative shadow roots (a browser does; a server and jsdom do not). */
+function parsesDeclarativeRoots(): boolean {
+	return typeof HTMLTemplateElement === 'function' && 'shadowRootMode' in HTMLTemplateElement.prototype
+}
+
+/** The card's HTML as React writes it in such a browser: each template's mode under `INERT_MODE_ATTRIBUTE`. */
+export function clientCardHtml(html: string): string {
+	return html.replace(/<template\b([^>]*?)\sshadowrootmode=/gi, `<template$1 ${INERT_MODE_ATTRIBUTE}=`)
+}
+
+/** The template's declared mode, under either name. */
+function declaredMode(template: Element): string | null {
+	return template.getAttribute('shadowrootmode') ?? template.getAttribute(INERT_MODE_ATTRIBUTE)
+}
+
 /** Whether this host still holds an unattached declarative root. */
 function pendingTemplate(host: Element): HTMLTemplateElement | null {
 	if ((host as HTMLElement).shadowRoot) return null
 	for (const child of Array.from(host.children)) {
-		if (child instanceof HTMLTemplateElement && child.hasAttribute('shadowrootmode')) return child
+		if (child instanceof HTMLTemplateElement && declaredMode(child) !== null) return child
 	}
 	return null
 }
 
 /** Attach one host's root from its template, as the parser would have: its mode, its options, its content. */
 function attachFromTemplate(host: HTMLElement, template: HTMLTemplateElement): void {
-	const mode = template.getAttribute('shadowrootmode') === 'closed' ? 'closed' : 'open'
+	const mode = declaredMode(template) === 'closed' ? 'closed' : 'open'
 	const init: ShadowRootInit & { clonable?: boolean; serializable?: boolean } = {
 		mode,
 		delegatesFocus: template.hasAttribute('shadowrootdelegatesfocus'),
@@ -119,22 +150,47 @@ export const BUILDER_CARD_FLOW_CSS =
 	'.builder-blocks > .builder-block > [data-certrev-face="card"]:has(> certrev-card[data-certrev-part="rail"]){display:block !important}' +
 	'}'
 
+/** One object for the flow rule's element, so React 19 never rewrites it on a re-render. */
+const BUILDER_CARD_FLOW_HTML = { __html: BUILDER_CARD_FLOW_CSS }
+
 export function ContractCardFace(props: {
 	readonly card: CardDocumentV1
 	readonly names: readonly CardPartName[]
 	/** The record that names this card (`ssr-seed.ts`): the browser repaints it from here with no read. */
 	readonly seed: string
+	/** 2.0.1: the delivery origin the block read, where its sampled health beacon goes (`card-beacon.ts`). */
+	readonly origin?: string
 }) {
 	const ref = React.useRef<HTMLDivElement>(null)
 	const html = cardHtml(props.card, props.names)
+	const printed = typeof document !== 'undefined' && parsesDeclarativeRoots() ? clientCardHtml(html) : html
+	// One object per printed string: React 19 rewrites `innerHTML` whenever this prop is a new object (React 18 compared
+	// the strings), which would replace the attached card on every re-render.
+	const inner = React.useMemo(() => ({ __html: printed }), [printed])
 	const { card } = props
 	const carriesAssets = cardCarriesAssets(card, props.names)
+	// After every commit of this block (a no-op while every root is attached): whatever React wrote, the card has its roots
+	// before the browser paints.
+	useBrowserLayoutEffect(() => {
+		if (ref.current) attachCardRoots(ref.current, html)
+	})
 	useBrowserLayoutEffect(() => {
+		if (ref.current && carriesAssets) injectCardRuntime(card)
+	}, [card, carriesAssets])
+	const { origin } = props
+	React.useEffect(() => {
+		maybeSendBrowserHealth(origin, card.subject.externalId)
+	}, [origin, card])
+	// 2.0.1: the document's placement hints, once the page has settled (`card-placement.ts`). Keyed on the printed HTML,
+	// which the document and the parts decide, so a re-render that prints the same card moves nothing again.
+	const placing = React.useRef({ card, names: props.names })
+	placing.current = { card, names: props.names }
+	// biome-ignore lint/correctness/useExhaustiveDependencies: `html` is the trigger on purpose; the document and parts are read from the ref
+	React.useEffect(() => {
 		const wrapper = ref.current
 		if (!wrapper) return
-		attachCardRoots(wrapper, html)
-		if (carriesAssets) injectCardRuntime(card)
-	}, [html, card, carriesAssets])
+		return afterPageSettles(() => applyCardPlacement(wrapper, placing.current.card, placing.current.names))
+	}, [html])
 	const wrapper = (
 		<div
 			ref={ref}
@@ -144,8 +200,9 @@ export function ContractCardFace(props: {
 			data-certrev-contract={String(props.card.contract)}
 			data-certrev-def-version={props.card.defVersion}
 			{...{ [SEED_ATTRIBUTE]: props.seed }}
+			suppressHydrationWarning
 			// biome-ignore lint/security/noDangerouslySetInnerHtml: CertREV's card document, printed only after it hashes to the digest the verified envelope signs
-			dangerouslySetInnerHTML={{ __html: html }}
+			dangerouslySetInnerHTML={inner}
 		/>
 	)
 	if (!props.names.includes('rail')) return wrapper
@@ -153,7 +210,7 @@ export function ContractCardFace(props: {
 		<>
 			{wrapper}
 			{/* biome-ignore lint/security/noDangerouslySetInnerHtml: a package constant; React would escape the `>` and `"` of its selectors */}
-			<style data-certrev-builder-flow="" dangerouslySetInnerHTML={{ __html: BUILDER_CARD_FLOW_CSS }} />
+			<style data-certrev-builder-flow="" dangerouslySetInnerHTML={BUILDER_CARD_FLOW_HTML} />
 		</>
 	)
 }

package/src/builder/delivery-runtime.ts

@@ -14,6 +14,10 @@
  * A revocation still lands on the first render after its refresh does. The tests' runtime gets
  * the same cache shape, so they exercise what production runs.
  *
+ * 2.0.2: a server render waits at most `CARD_SERVER_WAIT_MS` (300 ms) for a cold read, never joins another request's read
+ * in flight, and a failure is remembered `CARD_DELIVERY_FAILURE_MS` (60 s) per placement, so a hanging CertREV costs a
+ * brand's page at most one short wait per placement per minute (2.0.1: 8 s, every 5 s).
+ *
  * 2.0.0: the trust root is a key SET (`verify/key-set.ts`). `resolveKid` is still the baked set (today
  * `cert-issuer-1`), and the card verifies with `resolveKidFor(baseUrl)`: a baked kid resolves as before, any other kid
  * makes one read of the delivery origin's published key set, accepted only when a baked kid signs it. A rotation then
@@ -24,16 +28,44 @@ import type { ResolvePublicKeyByKid } from '../contract/kernel.js'
 import { TtlCache } from '../verify/cache.js'
 import type { CachedDelivery } from '../verify/get-verified-delivery.js'
 import { forgetKeySetsForTests, keySetResolver } from '../verify/key-set.js'
+import { setCardBeaconForTests } from './card-beacon.js'
 import { forgetCardDigestsForTests } from './card-contract.js'
 import { forgetCardReportsForTests } from './card-report.js'
 import { forgetFaceHashesForTests } from './delivered-face.js'
 import { CERT_ISSUER_KID, CERT_ISSUER_PUBLIC_KEY_PEM } from './issuer-key.js'
 import { forgetPageSeedsForTests } from './ssr-seed.js'
 
-/** The card's server read deadline. A brand's server waits this long once per cold placement. */
+/**
+ * The card's fetch deadline: how long a read of the Delivery API may run (2.0.2: in the background, past the render; a
+ * browser read under `clientRead`). Not how long a server render waits: that is `CARD_SERVER_WAIT_MS`.
+ */
 export const CARD_DELIVERY_TIMEOUT_MS = 8_000
-/** How long past its 60s TTL a certificate may still paint while it is refreshed or CertREV is down. */
-export const CARD_DELIVERY_STALE_MS = 300_000
+/**
+ * 2.0.2: the longest a SERVER render waits for a placement's read (2.0.1 waited the whole `CARD_DELIVERY_TIMEOUT_MS`,
+ * 8 s). Past it the render prints nothing (`delivery_unreachable`), the placement's failure is remembered
+ * (`CARD_DELIVERY_FAILURE_MS`), and the read runs on: when it lands it is cached for the next render. 300 ms covers the
+ * Delivery API's p90 function time (221 ms over 30 days of production, n = 21,368 CDN misses; 93% <= 300 ms) and a
+ * cached edge answer (~50 ms) plus a round trip; see the CHANGELOG.
+ */
+export const CARD_SERVER_WAIT_MS = 300
+/**
+ * 2.0.2: how long a placement's failure (a timeout, a network error, a 5xx, a render that stopped waiting) is
+ * remembered per process. Inside it, no read of the placement starts: a render with no cached card prints nothing at
+ * once, and a stale card paints without a refresh. So an ongoing outage costs at most one short wait per placement per
+ * minute. (2.0.1: a failure was remembered 5 s.)
+ */
+export const CARD_DELIVERY_FAILURE_MS = 60_000
+/**
+ * 2.0.1: how long a verified answer is fresh. With the stale window below, a card adds at most one minute to the Delivery
+ * API's own cache (`max-age=60, stale-while-revalidate=240`), so a revoked card is gone within ADR 0001 §7's five to
+ * six minutes (2.0.0's 60 s + 300 s here stacked to about twelve).
+ */
+export const CARD_DELIVERY_TTL_MS = 30_000
+/**
+ * How long past its TTL a certificate may still paint while it is refreshed or CertREV is down (2.0.1: 30 s; 2.0.0:
+ * 300 s). Never longer: past it, a read that cannot reach CertREV prints nothing.
+ */
+export const CARD_DELIVERY_STALE_MS = 30_000
 
 export interface CardDeliveryRuntime {
 	/** The baked kids: the package's own trust root (and the only keys that may sign a published key set). */
@@ -47,6 +79,8 @@ export interface CardDeliveryRuntime {
 	readonly cache: TtlCache<CachedDelivery>
 	readonly now: () => number
 	readonly timeoutMs?: number
+	/** 2.0.2: the longest a server render waits for a read (`CARD_SERVER_WAIT_MS`). */
+	readonly serverWaitMs?: number
 }
 
 const bakedResolveKid: ResolvePublicKeyByKid = (kid) =>
@@ -54,9 +88,11 @@ const bakedResolveKid: ResolvePublicKeyByKid = (kid) =>
 
 function newCardCache(now?: () => number): TtlCache<CachedDelivery> {
 	return new TtlCache<CachedDelivery>({
-		ttlMs: 60_000,
+		ttlMs: CARD_DELIVERY_TTL_MS,
 		negativeTtlMs: 5_000,
 		staleMs: CARD_DELIVERY_STALE_MS,
+		// 2.0.2: on a server only. A browser read (`clientRead`) holds no page, and keeps 2.0.1's 5 s (break-it B1).
+		...(typeof document === 'undefined' ? { failureTtlMs: CARD_DELIVERY_FAILURE_MS } : {}),
 		// A refresh the host runtime abandoned (workerd cancels a finished request's I/O) never
 		// settles; after the deadline plus a margin, the next render starts a new one.
 		inflightMaxMs: CARD_DELIVERY_TIMEOUT_MS + 2_000,
@@ -71,6 +107,7 @@ function defaultRuntime(): CardDeliveryRuntime {
 		cache: newCardCache(),
 		now: Date.now,
 		timeoutMs: CARD_DELIVERY_TIMEOUT_MS,
+		serverWaitMs: CARD_SERVER_WAIT_MS,
 	}
 }
 
@@ -94,7 +131,8 @@ export function cardResolveKidFor(rt: CardDeliveryRuntime, baseUrl: string): Res
 /**
  * Test seam: replace parts of the runtime (a fresh cache unless one is given) and forget the page's envelope seeds
  * (a fresh runtime is a fresh page), (1.3.0) every delivered face's memoized hashes and (2.0.0) every card
- * document's digest and every published key set. Returns a restore.
+ * document's digest and every published key set. 2.0.1: beacons go nowhere (a test that wants them sets its own
+ * transport with `setCardBeaconForTests` after this). Returns a restore.
  */
 export function setCardDeliveryRuntimeForTests(overrides: Partial<CardDeliveryRuntime>): () => void {
 	forgetPageSeedsForTests()
@@ -102,6 +140,7 @@ export function setCardDeliveryRuntimeForTests(overrides: Partial<CardDeliveryRu
 	forgetCardDigestsForTests()
 	forgetKeySetsForTests()
 	forgetCardReportsForTests()
+	const restoreBeacon = setCardBeaconForTests()
 	const previous = runtime
 	const now = overrides.now ?? previous.now
 	runtime = {
@@ -111,5 +150,6 @@ export function setCardDeliveryRuntimeForTests(overrides: Partial<CardDeliveryRu
 	}
 	return () => {
 		runtime = previous
+		restoreBeacon()
 	}
 }

package/src/builder/index.tsx

@@ -31,10 +31,10 @@
  * (`face: { html, css }`, unsigned) and the verified envelope signs that face's sha256 digests for the
  * def version served (`content.faceDigest`), an unpinned whole-card block paints that face instead;
  * markup that does not hash to the signed digest is never painted. A revoked, expired, unverifiable or unreachable cert, a marker that
- * is not exactly that shape, or a missing entry id renders nothing. A block WITHOUT the marker
- * (every entry exported before 1.1.0) renders from its options exactly as 1.0.3 did, so the
- * paragraph above still describes it: an editor who deletes the marker gets the options face back,
- * which is the 1.0.3 trust boundary, not a new one.
+ * is not exactly that shape, or a missing entry id renders nothing. 2.0.1: a block WITHOUT the marker
+ * (every entry exported before 1.1.0) renders nothing too, and reports `no_marker`: through 2.0.0 it
+ * painted its options as 1.0.3 did, unsigned export-time claims an editor could change. So deleting the
+ * marker no longer brings any face back.
  *
  * Three things the card DOES enforce, and they are the limit of it: no chrome at all without a
  * `reviewerName` and a `verifyUrl`; a credential renders only welded to its dated verification

package/src/builder/ssr-seed.ts

@@ -41,9 +41,10 @@
  * page carried for another version.
  *
  * WHEN THE SERVER HAD NO ENVELOPE TO PAINT (1.2.0) the same attribute carries a fallback record instead of a seed:
- * `{ v: 1, baseUrl, externalId, design?, face }`, where `face` is `'options'` (CertREV could not be reached, so the
- * server painted the block's own options face) or `'none'` (the server painted nothing: revoked, expired, unverifiable,
- * for another entry). A browser that renders the card again (hydration, or React's client re-render after a hydration
+ * `{ v: 1, baseUrl, externalId, design?, face, reason? }`, where `face` is `'none'` (the server painted nothing:
+ * revoked, expired, unverifiable, for another entry, or, 2.0.1, CertREV not reached, with `reason` naming why) or, on a
+ * page a 2.0.0 server rendered, `'options'` (CertREV could not be reached and that server painted the block's options
+ * face; 2.0.1 prints nothing for it). A browser that renders the card again (hydration, or React's client re-render after a hydration
  * error elsewhere on the page) paints what the record says, so it neither reads the Delivery API nor shows a card the
  * server withheld. A record holds no payload, so `parseSeed` never takes one for a seed. A `'none'` record sits on a
  * `hidden` element with nothing in it.
@@ -114,7 +115,7 @@ export interface PageSeed {
 	readonly raw: string
 }
 
-/** What the server painted with no verified envelope: the block's options face, or nothing. */
+/** What the server painted with no verified envelope: nothing (2.0.1 never writes `'options'`; a 2.0.0 page may hold one). */
 export type FallbackFace = 'options' | 'none'
 
 /** The record a server writes where it had no envelope to paint (the file header). */

package/src/builder/version.ts

@@ -0,0 +1,2 @@
+/** This package's version, as its beacon reports it (held to `package.json` by `version.test.ts`). */
+export const CERT_BLOCK_VERSION = '2.0.2'

package/src/verify/cache.ts

@@ -18,6 +18,12 @@
  *      down costs the page nothing it already had. A definitive answer (a revocation, say)
  *      replaces the entry the moment the refresh lands. With the default `staleMs` of 0 an
  *      expired entry is gone, exactly as before 1.2.0.
+ *   5. (2.0.2, opt-in through `failureTtlMs`) FAILURE MEMORY: a transient result (`isTransient`: the origin was not
+ *      reached) is remembered in a slot of its own for `failureTtlMs`, beside a positive entry and never over it. While
+ *      it is remembered nothing loads for the key: a read with no servable entry gets the failure at once, and a stale
+ *      entry is served without starting a refresh. A definitive answer clears it. So an ongoing outage costs a caller at
+ *      most one load per key per failure window. `markFailed` lets a caller that stopped waiting (a render deadline)
+ *      remember one before the load itself settles. Without `failureTtlMs` the cache behaves exactly as 2.0.1's.
  *
  * It is deliberately tiny + dependency-free (a Map + timestamps) so it runs in any server
  * runtime (Node, edge, workerd). For multi-instance deployments this is per-instance L1 and
@@ -44,6 +50,11 @@ export interface TtlCacheOptions {
 	 * it and none would ever refresh again.
 	 */
 	readonly inflightMaxMs?: number
+	/**
+	 * 2.0.2: how long a transient result (`isTransient`) is remembered, in a slot of its own (default: none, and a transient
+	 * result is cached as a negative entry as before). See the module header, point 5.
+	 */
+	readonly failureTtlMs?: number
 	/** Injectable clock for deterministic tests. */
 	readonly now?: () => number
 }
@@ -57,16 +68,19 @@ interface Entry<V> {
 interface Inflight<V> {
 	readonly promise: Promise<V>
 	readonly startedAt: number
+	readonly token: object
 }
 
 export class TtlCache<V> {
 	private readonly store = new Map<string, Entry<V>>()
 	private readonly inflight = new Map<string, Inflight<V>>()
+	private readonly failures = new Map<string, { readonly value: V; readonly until: number }>()
 	private readonly ttlMs: number
 	private readonly negativeTtlMs: number
 	private readonly maxEntries: number
 	private readonly staleMs: number
 	private readonly inflightMaxMs: number
+	private readonly failureTtlMs: number
 	private readonly now: () => number
 
 	constructor(opts: TtlCacheOptions = {}) {
@@ -75,6 +89,7 @@ export class TtlCache<V> {
 		this.maxEntries = opts.maxEntries ?? 1000
 		this.staleMs = opts.staleMs !== undefined && opts.staleMs > 0 ? opts.staleMs : 0
 		this.inflightMaxMs = opts.inflightMaxMs ?? Number.POSITIVE_INFINITY
+		this.failureTtlMs = opts.failureTtlMs !== undefined && opts.failureTtlMs > 0 ? opts.failureTtlMs : 0
 		this.now = opts.now ?? Date.now
 	}
 
@@ -89,10 +104,20 @@ export class TtlCache<V> {
 		return undefined
 	}
 
+	/** 2.0.2: the remembered failure while it lasts (only with `failureTtlMs`); prunes it past that. */
+	private failure(key: string): { readonly value: V } | undefined {
+		const f = this.failures.get(key)
+		if (!f) return undefined
+		if (f.until > this.now()) return f
+		this.failures.delete(key)
+		return undefined
+	}
+
 	/** Read a live (non-expired) entry, or undefined. Never serves a stale one; prunes an entry past its stale window. */
 	peek(key: string): V | undefined {
 		const e = this.servable(key)
-		return e && e.expiresAt > this.now() ? e.value : undefined
+		if (e && e.expiresAt > this.now()) return e.value
+		return this.failure(key)?.value
 	}
 
 	/**
@@ -109,8 +134,10 @@ export class TtlCache<V> {
 		isTransient?: (v: V) => boolean,
 	): V | undefined {
 		const e = this.servable(key)
-		if (!e) return undefined
-		if (e.expiresAt <= this.now()) {
+		const failed = this.failure(key)
+		if (!e) return failed?.value
+		// 2.0.2: no refresh while a failure is remembered; the stale value is still served.
+		if (e.expiresAt <= this.now() && !failed) {
 			this.load(key, loader, isNegative, positiveTtlMs, isTransient).catch(() => undefined)
 		}
 		return e.value
@@ -158,9 +185,20 @@ export class TtlCache<V> {
 		const existing = this.inflight.get(key)
 		if (existing && this.now() - existing.startedAt < this.inflightMaxMs) return existing.promise
 
+		const token = {}
 		const promise: Promise<V> = (async () => {
 			const value = await loader()
-			if (isTransient?.(value)) {
+			// 2.0.2: a load that was replaced (abandoned past `inflightMaxMs`) never writes: its answer may be older than
+			// the replacement's, and a late verified read must never overwrite a newer revocation.
+			if (this.inflight.get(key)?.token !== token) return value
+			if (this.failureTtlMs > 0) {
+				if (isTransient?.(value)) {
+					this.markFailed(key, value)
+					const kept = this.servable(key)
+					return kept && !kept.negative ? kept.value : value
+				}
+				this.failures.delete(key)
+			} else if (isTransient?.(value)) {
 				const kept = this.servable(key)
 				if (kept && !kept.negative) return kept.value
 			}
@@ -169,10 +207,10 @@ export class TtlCache<V> {
 			return value
 		})().finally(() => {
 			// Only this load's own slot: a newer load that replaced an abandoned one keeps its place.
-			if (this.inflight.get(key)?.promise === promise) this.inflight.delete(key)
+			if (this.inflight.get(key)?.token === token) this.inflight.delete(key)
 		})
 
-		this.inflight.set(key, { promise, startedAt: this.now() })
+		this.inflight.set(key, { promise, startedAt: this.now(), token })
 		return promise
 	}
 
@@ -189,9 +227,39 @@ export class TtlCache<V> {
 		this.store.set(key, { value, expiresAt: this.now() + ttl, negative })
 	}
 
+	/** 2.0.2: whether a load for `key` is running (and still joinable, younger than `inflightMaxMs`). */
+	loading(key: string): boolean {
+		const existing = this.inflight.get(key)
+		return existing !== undefined && this.now() - existing.startedAt < this.inflightMaxMs
+	}
+
+	/**
+	 * 2.0.2: remember a transient failure for `key` for `failureTtlMs` from now (a caller that stopped waiting for a load, or
+	 * a load that settled on one), beside the key's entry: it never touches a positive entry. Without `failureTtlMs` it is
+	 * a negative entry for the negative TTL, as a transient result was before 2.0.2, and like any `set` it replaces the
+	 * key's entry.
+	 */
+	markFailed(key: string, value: V): void {
+		if (this.failureTtlMs <= 0) {
+			this.set(key, value, true)
+			return
+		}
+		// Bounded like the store (break-it B3): past `maxEntries`, drop the expired failures, then the oldest.
+		if (this.failures.size >= this.maxEntries && !this.failures.has(key)) {
+			const now = this.now()
+			for (const [k, f] of this.failures) if (f.until <= now) this.failures.delete(k)
+			if (this.failures.size >= this.maxEntries) {
+				const oldest = this.failures.keys().next().value
+				if (oldest !== undefined) this.failures.delete(oldest)
+			}
+		}
+		this.failures.set(key, { value, until: this.now() + this.failureTtlMs })
+	}
+
 	/** Drop a key (e.g. on a known revocation push). */
 	delete(key: string): void {
 		this.store.delete(key)
+		this.failures.delete(key)
 	}
 
 	/**
@@ -205,11 +273,15 @@ export class TtlCache<V> {
 		for (const key of this.store.keys()) {
 			if (key.startsWith(prefix)) this.store.delete(key)
 		}
+		for (const key of this.failures.keys()) {
+			if (key.startsWith(prefix)) this.failures.delete(key)
+		}
 	}
 
 	clear(): void {
 		this.store.clear()
 		this.inflight.clear()
+		this.failures.clear()
 	}
 
 	get size(): number {

package/src/verify/get-verified-delivery.ts

@@ -106,6 +106,8 @@ export type CachedDelivery =
 			readonly reason: CertSuppressReason
 			/** 1.2.0: true when CertREV was not reached (no answer about the credential); see the module header. */
 			readonly unreachable?: true
+			/** 2.0.1: the HTTP status, when CertREV answered with a non-OK status other than 404/410. */
+			readonly status?: number
 	  }
 
 /** The answer for one render: the verdict AT THIS RENDER'S CLOCK, and the def to paint it with. */
@@ -117,6 +119,8 @@ export interface VerifiedDelivery {
 	readonly signature?: CertSignature
 	/** 1.2.0: on a suppress verdict, true when CertREV was not reached; else undefined. */
 	readonly unreachable?: true
+	/** 2.0.1: with `unreachable`, the HTTP status when CertREV answered with one (a 5xx, a 429, ...); else undefined. */
+	readonly status?: number
 	/**
 	 * 1.3.0: on a `render` verdict, the server-rendered face served beside the artifact, when the response carried a
 	 * well-formed one; else undefined (never on a suppress verdict). UNVERIFIED: see `DeliveredFace`.
@@ -175,8 +179,13 @@ function suppressed(reason: CertSuppressReason): CachedDelivery {
 }
 
 /** A read that did not reach CertREV: the same least-wrong reason as before 1.2.0, marked `unreachable`. */
-function unreachable(): CachedDelivery {
-	return { kind: 'suppressed', reason: 'unsupported_contract_version', unreachable: true }
+function unreachable(status?: number): CachedDelivery {
+	return {
+		kind: 'suppressed',
+		reason: 'unsupported_contract_version',
+		unreachable: true,
+		...(status === undefined ? {} : { status }),
+	}
 }
 
 const isUnreachable = (v: CachedDelivery): boolean => v.kind === 'suppressed' && v.unreachable === true
@@ -312,7 +321,7 @@ async function loadDelivery(opts: GetVerifiedDeliveryOptions): Promise<CachedDel
 	// Nothing served for this placement: never certified, or withdrawn. A LIVE revocation is a 200
 	// tombstone, so a 4xx here genuinely means "no credential for this subject".
 	if (res.status === 404 || res.status === 410) return suppressed('subject_mismatch')
-	if (!res.ok) return unreachable()
+	if (!res.ok) return unreachable(res.status)
 	let body: unknown
 	try {
 		body = await res.json()
@@ -356,6 +365,7 @@ export function settleDelivery(cached: CachedDelivery, context: RenderContext):
 			verdict: { decision: 'suppress', reason: cached.reason },
 			renderDef: null,
 			...(cached.unreachable ? { unreachable: true as const } : {}),
+			...(cached.unreachable && cached.status !== undefined ? { status: cached.status } : {}),
 		}
 	}
 	const verdict = renderVerdict(cached.payload, context)
@@ -417,6 +427,33 @@ export function peekVerifiedDelivery(
 	return cached === undefined ? undefined : settleDelivery(cached, opts.context)
 }
 
+/**
+ * 2.0.2: the settled answer for "CertREV was not reached in time": what a server render prints when it stops waiting
+ * (its deadline passed, or another request's read of the placement is in flight). Nothing, reported as
+ * `delivery_unreachable`, exactly as for a read that failed.
+ */
+export function unreachableDelivery(): VerifiedDelivery {
+	return settleDelivery(unreachable(), { platform: 'builder', externalId: '', now: new Date(0) })
+}
+
+/**
+ * 2.0.2: remember that a read of one placement did not reach CertREV in time (a render stopped waiting for it), so the
+ * cache answers the placement at once for its failure window. A no-op on a cache with no failure window beyond 2.0.1's
+ * negative entry. Never touches a verified entry.
+ */
+export function rememberDeliveryUnreachable(
+	opts: Pick<GetVerifiedDeliveryOptions, 'baseUrl' | 'platform' | 'externalId' | 'context' | 'cache' | 'design'>,
+): void {
+	;(opts.cache ?? sharedDeliveryCache).markFailed(deliveryCacheKey(opts), unreachable())
+}
+
+/** 2.0.2: whether a read of one placement is already running in `cache` (a render's, or a background refresh). */
+export function deliveryLoading(
+	opts: Pick<GetVerifiedDeliveryOptions, 'baseUrl' | 'platform' | 'externalId' | 'context' | 'cache' | 'design'>,
+): boolean {
+	return (opts.cache ?? sharedDeliveryCache).loading(deliveryCacheKey(opts))
+}
+
 /** Drop the cached read for one placement (e.g. from a revocation webhook); with `design`, that pinned read. */
 export function invalidateDelivery(
 	opts: Pick<GetVerifiedDeliveryOptions, 'baseUrl' | 'platform' | 'externalId' | 'context' | 'design'>,