@certrev/cert-block 2.0.1 → 2.1.0

package/src/components/render-def.ts

@@ -141,6 +141,30 @@ export const COMPENSATED_EXPERT_CUE = 'Compensated expert'
 export const CERT_SCOPE_LINE =
 	'Independent editorial review of this article’s text and sources. Not a product endorsement, nor medical advice.'
 
+/**
+ * 2.1.0: the scope line for an article whose review covered its TEXT only (no references or sources section). Byte-verbatim
+ * copy of the portal's `FTC_DISCLOSURE_LINE_TEXT_ONLY` (`src/lib/embed/ftc-disclosure.ts`; Owen, Console decision
+ * af5b0db5, 2026-10-30: the review line says what the expert actually reviewed). Same curly apostrophe, same contract
+ * status as `CERT_SCOPE_LINE`: never re-word here.
+ */
+export const CERT_SCOPE_LINE_TEXT_ONLY =
+	'Independent editorial review of this article’s text. Not a product endorsement, nor medical advice.'
+
+/**
+ * 2.1.0: what the review covered, the portal's signed `content.expert.reviewScope`. ABSENT means `text_and_sources`: every
+ * envelope signed before the field existed prints exactly as 2.0.2 printed it.
+ */
+export type CertReviewScope = 'text' | 'text_and_sources'
+
+/**
+ * The scope line for a review scope, the ONE rule every face of this package prints by: only an exact `'text'` is the
+ * text-only line; anything else (absent, null, `'text_and_sources'`, a value this version has never heard of) is the full
+ * `CERT_SCOPE_LINE`. The portal's `scopeLineFor` decides the same way.
+ */
+export function certScopeLineFor(reviewScope: unknown): typeof CERT_SCOPE_LINE | typeof CERT_SCOPE_LINE_TEXT_ONLY {
+	return reviewScope === 'text' ? CERT_SCOPE_LINE_TEXT_ONLY : CERT_SCOPE_LINE
+}
+
 /**
  * The delivered display-string EDITION, stamped as `data-certrev-strings-version`
  * so the crawl monitor can assert which verbatim strings a live face should carry.

package/src/modal/cert-modal-view.ts

@@ -29,7 +29,7 @@
 
 import { asText, escapeHtml } from './escape.js'
 import { resizeAvatarUrl } from './avatar-resize.js'
-import { CERT_SCOPE_LINE, formatCertDisplayDate } from './display-strings.js'
+import { formatCertDisplayDate, scopeLineForReview } from './display-strings.js'
 import { checkIcon, chevronMark, verifiedStamp } from './certrev-cert-modal.styles.js'
 
 export interface CertModalCredential {
@@ -48,6 +48,9 @@ export interface CertModalExpert {
 	/** The pre-composed material-connection label ('Compensated expert') or null/absent for
 	 *  a pro-bono reviewer. Present → the disclosure footer renders the label; null/absent → label omitted. */
 	compensationCue?: string | null
+	/** 2.1.0: what the review covered (`'text'` | `'text_and_sources'`, absent = text and sources). Picks the locked
+	 *  scope line the footer prints, never its words. */
+	reviewScope?: string | null
 }
 
 /** The subset of the signed `payload.content` the modals read (structural). */
@@ -171,12 +174,13 @@ function certifiedChip(cls: string): string {
  * (`expert.compensationCue`, a FINISHED string off the signed envelope) leads ONLY when the reviewer
  * was compensated; a pro-bono reviewer (null/absent cue) drops the label but keeps the scope line —
  * which makes no compensation claim, so it is true for volunteers too and renders unconditionally.
- * The scope line is the verbatim FTC copy (`CERT_SCOPE_LINE`), never re-assembled here.
+ * The scope line is the verbatim FTC copy (`CERT_SCOPE_LINE`, or 2.1.0's `CERT_SCOPE_LINE_TEXT_ONLY` when the signed
+ * `expert.reviewScope` is `'text'`), never re-assembled here.
  */
 function disclosureFooter(expert: CertModalExpert | null | undefined): string {
 	const cue = asText(expert?.compensationCue).trim()
 	const cueHtml = cue ? `<span class="crm-disclosure__cue">${escapeHtml(cue)}</span> ` : ''
-	return `<div class="crm-disclosure">${cueHtml}${escapeHtml(CERT_SCOPE_LINE)}</div>`
+	return `<div class="crm-disclosure">${cueHtml}${escapeHtml(scopeLineForReview(expert?.reviewScope))}</div>`
 }
 
 /**

package/src/modal/display-strings.ts

@@ -14,7 +14,7 @@
  * never legitimately carry renders nothing (see `formatCertDisplayDate`).
  */
 
-import { FTC_DISCLOSURE_LINE } from "./ftc-disclosure.js";
+import { FTC_DISCLOSURE_LINE, FTC_DISCLOSURE_LINE_TEXT_ONLY } from "./ftc-disclosure.js";
 
 /** The compensation cue (guide "line A"), byte-verbatim from portal `COMPENSATED_EXPERT_CUE`. */
 export const COMPENSATED_EXPERT_CUE = "Compensated expert";
@@ -22,6 +22,19 @@ export const COMPENSATED_EXPERT_CUE = "Compensated expert";
 /** The FTC scope disclaimer, re-exported from the FTC SoT (portal `CERT_SCOPE_LINE = FTC_DISCLOSURE_LINE`). */
 export const CERT_SCOPE_LINE = FTC_DISCLOSURE_LINE;
 
+/** 2.1.0: the text-only scope line (portal `FTC_DISCLOSURE_LINE_TEXT_ONLY`), for a review that covered the text only. */
+export const CERT_SCOPE_LINE_TEXT_ONLY = FTC_DISCLOSURE_LINE_TEXT_ONLY;
+
+/**
+ * 2.1.0: the scope line for the signed `content.expert.reviewScope`. Only an exact `"text"` is the text-only line; absent,
+ * null, `"text_and_sources"` or any other value is `CERT_SCOPE_LINE`, as 2.0.2 printed it. The same rule as
+ * `certScopeLineFor` in `../components/render-def.ts`, repeated because `src/modal/` imports nothing from `src/components/`
+ * (it is bundled standalone into `certrev-cert.js`).
+ */
+export function scopeLineForReview(reviewScope: unknown): typeof CERT_SCOPE_LINE | typeof CERT_SCOPE_LINE_TEXT_ONLY {
+	return reviewScope === "text" ? CERT_SCOPE_LINE_TEXT_ONLY : CERT_SCOPE_LINE;
+}
+
 /**
  * Format a timestamp the way every cert byline renders dates ("Jun 14, 2026", en-US short month,
  * UTC-pinned). Null for an unparseable input — callers treat that as "no date, no byline".

package/src/modal/ftc-disclosure.ts

@@ -15,3 +15,11 @@
 
 export const FTC_DISCLOSURE_LINE =
 	"Independent editorial review of this article’s text and sources. Not a product endorsement, nor medical advice." as const;
+
+/**
+ * 2.1.0: the line for an article whose review covered its TEXT only (no references or sources section): a byte-faithful
+ * copy of the portal's `FTC_DISCLOSURE_LINE_TEXT_ONLY` (Owen, Console decision af5b0db5). Same contract status and curly
+ * apostrophe as `FTC_DISCLOSURE_LINE`.
+ */
+export const FTC_DISCLOSURE_LINE_TEXT_ONLY =
+	"Independent editorial review of this article’s text. Not a product endorsement, nor medical advice." as const;

package/src/reader/render.ts

@@ -49,7 +49,7 @@
  */
 import { asText } from '../components/escape.js'
 import { CERTREV_LINK_REL } from '../components/rel.js'
-import { CERT_SCOPE_LINE, CERT_STRINGS_VERSION, COMPENSATED_EXPERT_CUE } from '../components/render-def.js'
+import { CERT_STRINGS_VERSION, COMPENSATED_EXPERT_CUE, certScopeLineFor } from '../components/render-def.js'
 import type { CertContent } from '../contract/kernel.js'
 import { readerFace } from './face.js'
 import {
@@ -115,6 +115,13 @@ interface Facts {
 	/** The joined credential labels, '' when there are none or the rung shows none (named, minimal). */
 	readonly creds: string
 	readonly hasCue: boolean
+	/**
+	 * The scope sentence, by the signed `expert.reviewScope` (2.1.0, `certScopeLineFor`: `'text'` is the text-only line,
+	 * anything else the full one). It is DIRECT text of the scope element (the demo's `<span class="dg-scope">`), which
+	 * carries the `data-ftc-line` marker itself: no inner span, so the element's `.certrev-r-scope em` cue and the sentence
+	 * are leaves of one element, as the demo paints them. The marker is on exactly one element per render, as before.
+	 */
+	readonly scope: string
 	readonly illus: boolean
 	/** Whether the memo is printed: there is one, and the rung is the memo rung. */
 	readonly hasMemo: boolean
@@ -161,6 +168,7 @@ function readFacts(input: ReaderFaceInput): Facts {
 		showPhoto,
 		creds: rung === 'named' || minimal ? '' : labels.join(', '),
 		hasCue,
+		scope: certScopeLineFor(expert.reviewScope),
 		illus: input.illustrative === true && !hasCue,
 		hasMemo: !isBlank(content.memo) && rung === 'memo',
 		toned: isTonedStyle(style),
@@ -209,13 +217,6 @@ function scopeLead(f: Facts): string {
 	return ''
 }
 
-/**
- * The scope sentence is DIRECT text of the scope element (the demo's `<span class="dg-scope">`), which carries the
- * `data-ftc-line` marker itself: no inner span, so the element's `.certrev-r-scope em` cue and the sentence are leaves of
- * one element, as the demo paints them. The marker is on exactly one element per render, as before.
- */
-const SCOPE = CERT_SCOPE_LINE
-
 /**
  * The muted credential line, empty when the reviewer has no displayed credential (so no "verified" claim prints).
  *
@@ -296,7 +297,7 @@ function bannerCard(f: Facts): string {
 	}
 
 	// POR-9317: the memo card carries the scope line when there is a memo; with none this card is the sole claim face.
-	const scope = scopeOn ? `<div class="certrev-r-scope" data-ftc-disclosure data-ftc-line>${SCOPE}</div>` : ''
+	const scope = scopeOn ? `<div class="certrev-r-scope" data-ftc-disclosure data-ftc-line>${f.scope}</div>` : ''
 
 	return (
 		`${sectionOpen(f, true, f.minimal ? 'Expert reviewed' : credentialAria(f))}\n  <div class="certrev-r-card">\n` +
@@ -324,7 +325,7 @@ function bannerMemo(f: Facts): string {
 		`        <blockquote>${esc(f.content.memo)}</blockquote>${links}</div>\n    </div>\n` +
 		'    <div class="certrev-r-rule"></div>\n    <div class="certrev-r-vfoot">\n' +
 		`      <span class="certrev-r-verified">${readerLogo('mono', 17, '')}Verified by <b>CertREV</b></span>\n` +
-		`      <span class="certrev-r-scope" data-ftc-disclosure data-ftc-line>${scopeLead(f)}${SCOPE}</span>\n    </div>\n  </div>\n</section>`
+		`      <span class="certrev-r-scope" data-ftc-disclosure data-ftc-line>${scopeLead(f)}${f.scope}</span>\n    </div>\n  </div>\n</section>`
 	)
 }
 
@@ -364,7 +365,7 @@ function sidebar(f: Facts): string {
 		`${open}<div class="certrev-r-side-body">\n      <div class="certrev-r-by">${avatar}<div>\n` +
 		`          <b>${esc(f.ename)}${f.creds !== '' ? `<!-- -->, <!-- -->${esc(f.creds)}` : ''}</b>${verifiedLine(f, false)}</div>\n      </div>` +
 		`${fold}${more}` +
-		`<div class="certrev-r-scope" data-ftc-disclosure data-ftc-line>${scopeLead(f)}${SCOPE}</div>\n    </div>` +
+		`<div class="certrev-r-scope" data-ftc-disclosure data-ftc-line>${scopeLead(f)}${f.scope}</div>\n    </div>` +
 		`${links}</div>\n</section>`
 	)
 }

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

@@ -427,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'>,

package/src/webcomponent/render-badge-html.ts

@@ -22,9 +22,9 @@ import {
 } from '../components/format.js'
 import { CERTREV_LINK_REL } from '../components/rel.js'
 import {
-	CERT_SCOPE_LINE,
 	CERT_STRINGS_VERSION,
 	type CertRenderDef,
+	certScopeLineFor,
 	resolveRenderTheme,
 	themeCssVarDeclarations,
 } from '../components/render-def.js'
@@ -88,6 +88,8 @@ function attr(name: string, value: string | null | undefined): string {
 export function renderBadgeHtml(payload: CertPayload, opts: RenderBadgeOptions = {}): string {
 	const content: LooseContent = payload?.content ?? {}
 	const expert = content.expert ?? null
+	// 2.1.0: the locked scope line the signed `expert.reviewScope` picks ('text' is the text-only line).
+	const scopeLine = certScopeLineFor((expert as { readonly reviewScope?: unknown } | null)?.reviewScope)
 	const display = resolveDisplay(content.display ?? undefined, opts.accentColor, opts.renderDef)
 	const theme = resolveRenderTheme(opts.renderDef)
 	const style = badgeFace(opts.badgeStyle ?? display.badgeStyle)
@@ -155,14 +157,15 @@ export function renderBadgeHtml(payload: CertPayload, opts: RenderBadgeOptions =
 	// regardless of a render-def, matching the Shopify/WordPress engine fix. The
 	// cue's "expert" links to the reviewer profile; the whole cue tag-strips to the
 	// byte-verbatim COMPENSATED_EXPERT_CUE. The scope line is byte-verbatim
-	// CERT_SCOPE_LINE (its curly apostrophe U+2019 survives escapeHtml untouched).
+	// CERT_SCOPE_LINE (its curly apostrophe U+2019 survives escapeHtml untouched), or 2.1.0's CERT_SCOPE_LINE_TEXT_ONLY
+	// when the signed `expert.reviewScope` is 'text' (`certScopeLineFor`).
 	const cueInner = profileUrl
 		? `Compensated <a class="${C}__cue-link" href="${escapeAttribute(profileUrl)}" rel="${CERTREV_LINK_REL}">expert</a>`
 		: 'Compensated expert'
 	const disclosure =
 		`<div class="${C}__disclosure">` +
 		`<span class="${C}__compensated-cue">${cueInner}</span>` +
-		`<p class="${C}__ftc" data-ftc-disclosure><span data-ftc-line>${escapeHtml(CERT_SCOPE_LINE)}</span></p>` +
+		`<p class="${C}__ftc" data-ftc-disclosure><span data-ftc-line>${escapeHtml(scopeLine)}</span></p>` +
 		`</div>`
 
 	const verify = verifyUrl