create-ailk 0.24.0 → 0.26.0

package/templates/apps/api/src/services/abandon-email.ts

@@ -1,336 +0,0 @@
-/**
- * @file abandon-email.ts
- * @description The abandon-email sweep service (#3962 D4).
- *
- * `runAbandonEmailSweep` is the one entry point: select partial `FlowSession`
- * rows past their flow's configured delay, dispatch per the flow's send
- * policy (dark → audit-only stamp; enabled → send + stamp), and record the
- * outcome on the session row (D5's idempotency + audit guarantee). Invoked
- * by the CLI entry (`src/bin/abandon-sweep.ts`) on an operator-supplied
- * cadence — this service itself is stateless and has no timer of its own
- * (D1: no queue/cron infrastructure).
- *
- * Mirrors the lead-routing/flow-engine house shape: type-result returns,
- * mocked-dep tests, PII-safe logging via @working-theory/observability
- * (siteId/flowSlug/sessionId/mode/outcome only — never email/state values).
- */
-
-import { sendAbandonEmail } from "@working-theory/email";
-import { logger } from "@working-theory/observability";
-import {
-  flowConfigSchema,
-  type AbandonEmailConfig,
-} from "@working-theory/validation";
-
-import { prisma } from "../lib/prisma.js";
-
-// ─── Types ────────────────────────────────────────────────────────────────────
-
-export type AbandonEmailSweepSummary = {
-  scanned: number;
-  selected: number;
-  sent: number;
-  dark: number;
-  failed: number;
-  skipped: number;
-};
-
-export type AbandonEmailSweepError = {
-  kind: "flows_not_configured" | "unexpected_error";
-  message: string;
-};
-
-export type AbandonEmailSweepResult =
-  | { ok: true; summary: AbandonEmailSweepSummary }
-  | { ok: false; error: AbandonEmailSweepError };
-
-export type RunAbandonEmailSweepOptions = {
-  siteId?: string;
-  now?: Date;
-};
-
-type FlowDefinitionRow = {
-  id: string;
-  siteId: string;
-  slug: string;
-  config: unknown;
-};
-
-type AbandonCandidateRow = {
-  id: string;
-  siteId: string;
-  flowSlug: string;
-  email: string | null;
-  locale: string | null;
-};
-
-// ─── DB-required guard (mirrors flow-engine.ts's requireDb) ────────────────────
-
-const FLOWS_NOT_CONFIGURED_ERROR = {
-  kind: "flows_not_configured" as const,
-  message: "Flows are not configured.",
-};
-
-function requireDb(): AbandonEmailSweepError | null {
-  if (!process.env.DATABASE_URL) return FLOWS_NOT_CONFIGURED_ERROR;
-  return null;
-}
-
-// ─── PII-safe outcome logging ───────────────────────────────────────────────────
-
-type AbandonOutcome = "dark" | "skipped" | "sent" | "failed";
-
-const OUTCOME_MESSAGE: Record<AbandonOutcome, string> = {
-  dark: "[abandon-email] session selected — dark mode, audit-only",
-  skipped: "[abandon-email] enabled candidate skipped — no from-address configured",
-  sent: "[abandon-email] session selected — sent",
-  failed: "[abandon-email] session selected — send failed",
-};
-
-/**
- * The one shape every outcome logs (siteId/flowSlug/sessionId/mode/outcome —
- * never email/state values, per this file's PII boundary).
- */
-function logOutcome(
-  session: AbandonCandidateRow,
-  mode: AbandonEmailConfig["mode"],
-  outcome: AbandonOutcome,
-): void {
-  logger.info(
-    {
-      siteId: session.siteId,
-      flowSlug: session.flowSlug,
-      sessionId: session.id,
-      mode,
-      outcome,
-    },
-    OUTCOME_MESSAGE[outcome],
-  );
-}
-
-// ─── Copy resolution (D6) ───────────────────────────────────────────────────────
-
-/**
- * `copy[session.locale ?? liveConfig.defaultLocale] ?? copy[liveConfig.defaultLocale]`
- * (D6). `defaultLocale` is a required key on every LocalizedString the
- * `abandonEmailSchema` superRefine walk enforces, so the final fallback is
- * always resolvable for a schema-valid config.
- */
-function resolveCopy(
-  copy: Record<string, string>,
-  sessionLocale: string | null,
-  defaultLocale: string,
-): string {
-  const locale = sessionLocale ?? defaultLocale;
-  return copy[locale] ?? copy[defaultLocale] ?? "";
-}
-
-/** Link = resumeUrl + '?fs=' + sessionId — no other session data (D7, no PII). */
-function buildResumeLink(
-  resumeUrl: string | undefined,
-  sessionId: string,
-): string | undefined {
-  if (!resumeUrl) return undefined;
-  return `${resumeUrl}?fs=${sessionId}`;
-}
-
-// ─── Candidate paging (#9249) ───────────────────────────────────────────────────
-
-/**
- * How many candidates one run reads per flow definition. A flow with more
- * past-delay sessions than this processes one page and leaves the rest —
- * still `abandonEmailStatus: null` — for the next run. Same page as
- * `STANDARD_SEED_PAGE` (lib/tenant-db.ts), this app's other background page.
- */
-export const ABANDON_CANDIDATE_PAGE_SIZE = 500;
-
-// ─── The sweep ──────────────────────────────────────────────────────────────────
-
-/**
- * The unguarded sweep body — mutates `summary` in place as it goes, so a
- * mid-loop throw still leaves the caller's catch block able to log how far
- * it got (code-review finding on #3962's acceptance PR: an unhandled
- * rejection mid-sweep should degrade to a structured error with the partial
- * progress visible, not vanish).
- */
-async function sweepAllDefinitions(
-  opts: RunAbandonEmailSweepOptions,
-  now: Date,
-  fromAddress: string | undefined,
-  summary: AbandonEmailSweepSummary,
-): Promise<void> {
-  const definitions = (await prisma.flowDefinition.findMany({
-    ...(opts.siteId !== undefined && { where: { siteId: opts.siteId } }),
-    select: { id: true, siteId: true, slug: true, config: true },
-  })) as FlowDefinitionRow[];
-
-  for (const definition of definitions) {
-    const parsedConfig = flowConfigSchema.safeParse(definition.config);
-    if (!parsedConfig.success) {
-      // Surface, do not swallow (code-review finding on #3962's acceptance
-      // PR) — every sibling path in this feature area (serveFlow /
-      // upsertFlowDefinition in flow-engine.ts) returns an explicit error on
-      // a config-parse failure; a stored config that has drifted from the
-      // schema must not silently stop that flow's abandon-email policy from
-      // ever running again with no operator-visible signal.
-      logger.warn(
-        {
-          siteId: definition.siteId,
-          flowSlug: definition.slug,
-          zodIssue: parsedConfig.error.issues[0]?.message,
-        },
-        "[abandon-email] skipping flow — stored config failed schema validation",
-      );
-      continue;
-    }
-    const config = parsedConfig.data;
-    const policy: AbandonEmailConfig | undefined = config.abandonEmail;
-    // Block absent = abandon email OFF for this flow — never selected (D2).
-    if (!policy) continue;
-
-    const cutoff = new Date(now.getTime() - policy.delayMinutes * 60_000);
-
-    // The #3956 D2 partial-lead query (email != null AND completedAt == null)
-    // plus the not-yet-processed and delay-window terms (D4/D5).
-    const candidates = (await prisma.flowSession.findMany({
-      where: {
-        flowId: definition.id,
-        email: { not: null },
-        completedAt: null,
-        abandonEmailStatus: null,
-        updatedAt: { lte: cutoff },
-      },
-      select: {
-        id: true,
-        siteId: true,
-        flowSlug: true,
-        email: true,
-        locale: true,
-      },
-      // #9249 — oldest-updated first, so the page is deterministic (the same
-      // reason flow-aggregate.ts orders its capped read).
-      orderBy: { updatedAt: "asc" },
-      take: ABANDON_CANDIDATE_PAGE_SIZE,
-    })) as AbandonCandidateRow[];
-
-    summary.scanned += candidates.length;
-
-    const darkIds: string[] = [];
-
-    for (const session of candidates) {
-      summary.selected += 1;
-
-      if (policy.mode === "dark") {
-        darkIds.push(session.id);
-        logOutcome(session, policy.mode, "dark");
-        continue;
-      }
-
-      // mode:'enabled' — an env gap must not consume the one send: leave the
-      // candidate UNSTAMPED so a later configured run still sends it (D4).
-      if (!fromAddress) {
-        summary.skipped += 1;
-        logOutcome(session, policy.mode, "skipped");
-        continue;
-      }
-
-      const subject = resolveCopy(
-        policy.copy.subject,
-        session.locale,
-        config.defaultLocale,
-      );
-      const body = resolveCopy(
-        policy.copy.body,
-        session.locale,
-        config.defaultLocale,
-      );
-      const cta = policy.copy.cta
-        ? resolveCopy(policy.copy.cta, session.locale, config.defaultLocale)
-        : undefined;
-      const resumeLink = buildResumeLink(policy.resumeUrl, session.id);
-
-      const sendResult = await sendAbandonEmail({
-        // `email: { not: null }` in the WHERE clause above guarantees this.
-        to: session.email as string,
-        fromAddress,
-        subject,
-        body,
-        ...(cta !== undefined && { cta }),
-        ...(resumeLink !== undefined && { resumeLink }),
-      });
-
-      if (sendResult.ok) {
-        await prisma.flowSession.update({
-          where: { id: session.id },
-          data: { abandonEmailStatus: "sent", abandonEmailAt: now },
-        });
-        summary.sent += 1;
-        logOutcome(session, policy.mode, "sent");
-      } else {
-        // Terminal to the sweep — no auto-retry (D5); clearing the stamp is
-        // the deliberate operator retry.
-        await prisma.flowSession.update({
-          where: { id: session.id },
-          data: { abandonEmailStatus: "failed", abandonEmailAt: now },
-        });
-        summary.failed += 1;
-        logOutcome(session, policy.mode, "failed");
-      }
-    }
-
-    // #9249 — one stamp for the whole dark-mode page, not one per row. The
-    // `abandonEmailStatus: null` guard is the candidate read's own term, so a
-    // row an overlapping run stamped meanwhile keeps what that run wrote.
-    if (darkIds.length > 0) {
-      await prisma.flowSession.updateMany({
-        where: { id: { in: darkIds }, abandonEmailStatus: null },
-        data: { abandonEmailStatus: "dark", abandonEmailAt: now },
-      });
-      summary.dark += darkIds.length;
-    }
-  }
-}
-
-export async function runAbandonEmailSweep(
-  opts: RunAbandonEmailSweepOptions = {},
-): Promise<AbandonEmailSweepResult> {
-  const dbError = requireDb();
-  if (dbError) return { ok: false, error: dbError };
-
-  const now = opts.now ?? new Date();
-  // #4740: `||`, not `??` — an accidentally-set empty-string override
-  // (AILK_ABANDON_EMAIL_FROM="") is an env GAP, not a sender, so it falls
-  // through to the owner-wide default; both empty resolves to `undefined` and
-  // the `!fromAddress` guard leaves the candidate unstamped. The same shape
-  // is applied identically in waitlist-followup.ts's sibling sweep.
-  const fromAddress =
-    process.env.AILK_ABANDON_EMAIL_FROM ||
-    process.env.AILK_LEAD_NOTIFICATION_FROM ||
-    undefined;
-
-  const summary: AbandonEmailSweepSummary = {
-    scanned: 0,
-    selected: 0,
-    sent: 0,
-    dark: 0,
-    failed: 0,
-    skipped: 0,
-  };
-
-  try {
-    await sweepAllDefinitions(opts, now, fromAddress, summary);
-  } catch (err) {
-    // An unexpected DB/network failure mid-loop must degrade to a
-    // structured error, not an unhandled rejection (code-review finding on
-    // #3962's acceptance PR) — the CLI entry's own try/catch expects this
-    // shape. Progress already stamped on session rows before the throw is
-    // NOT lost (D5's idempotency means a re-run picks up where this one
-    // stopped); the partial in-memory summary is logged so it is not
-    // silently discarded.
-    const message = err instanceof Error ? err.message : "Unknown error";
-    logger.error({ partialSummary: summary, err: message }, "[abandon-email] sweep failed mid-run");
-    return { ok: false, error: { kind: "unexpected_error", message } };
-  }
-
-  return { ok: true, summary };
-}

package/templates/apps/api/src/services/aeo-score.ts

@@ -1,325 +0,0 @@
-/**
- * Instant AEO score service (#4666 D3/D4).
- *
- * Productizes the existing pure `@working-theory/aeo` scorer behind the
- * SSRF-guarded external-URL crawler at `@working-theory/aeo/fetch`. The
- * rule set, severity table, and `identityMode`/`locale` defaults are
- * declared ONCE, here.
- */
-import {
-  runAudit,
-  schemaCoverage,
-  jsonldValidity,
-  entityMarkup,
-  faqHowtoIncentive,
-  EXAMPLE_SCORE_CRAWL,
-  EXAMPLE_SCORE_META,
-  EXAMPLE_SCORE_ANNOTATIONS,
-  type Rule,
-  type AuditReport,
-  type PerRuleResult,
-} from "@working-theory/aeo";
-import {
-  assertUrlSafe,
-  crawlSite,
-  buildAuditPayload,
-  type CrawlResult,
-  type FetchImpl,
-  type Resolver,
-  type SkippedEntry,
-} from "@working-theory/aeo/fetch";
-import type {
-  AeoDimension,
-  AeoDimensionId,
-  AeoScoreResult,
-} from "@working-theory/validation";
-
-/**
- * The readiness rules (#5949) are deliberately NOT in this set. They grade
- * frontmatter and site-set facts (`AuditInput.readiness`); `buildAuditPayload`
- * produces no frontmatter, so on a crawl input all three pass vacuously
- * (packages/aeo FR5). Adding them would put three always-100 dimensions into a
- * closed four-member public enum. `/v1/aeo/score` has no MCP twin
- * (apps/api/CLAUDE.md § API ↔ MCP parity), so this is not a parity divergence.
- */
-export const AEO_SCORE_EXCLUDED_READINESS_RULES = [
-  "policies-present",
-  "offer-on-priced-page",
-  "tax-code-when-stripe-tax",
-] as const;
-
-/** The service's fixed rule set — the four content rules only (§ 2.1 FR4). */
-export const AEO_SCORE_RULES: Rule[] = [
-  schemaCoverage,
-  jsonldValidity,
-  entityMarkup,
-  faqHowtoIncentive,
-];
-
-/** Severity table, verbatim from prospect-audit-site's "Compose the score-led sales report". */
-export const AEO_DIMENSION_SEVERITY: Record<
-  AeoDimensionId,
-  "high" | "medium" | "low"
-> = {
-  "schema-coverage": "high",
-  "entity-markup": "high",
-  "jsonld-validity": "medium",
-  "faq-howto-incentive": "low",
-};
-
-const AEO_DIMENSION_LABELS: Record<AeoDimensionId, string> = {
-  "schema-coverage": "Schema Coverage",
-  "jsonld-validity": "JSON-LD Validity",
-  "entity-markup": "Entity Markup",
-  "faq-howto-incentive": "FAQ / HowTo Incentive",
-};
-
-/** D5 — the route's default + the configured-budget cap, both declared once. */
-export const AEO_SCORE_DEFAULT_BUDGET_MS = 6000;
-export const AEO_SCORE_MAX_BUDGET_MS = 15000;
-
-/**
- * Resolve `AEO_SCORE_BUDGET_MS` for the route. A missing/unparseable/
- * non-positive value falls back to the default silently (nothing to warn
- * about — the env var is simply unset in dev). A value above the 15 000 ms
- * cap is logged and falls back to the default (D5) — raising it beyond the
- * crawler's own 15 s per-fetch bound would collide with the handler's 25 s
- * request guard once cold start is added. Re-checked on EVERY request, not
- * once at process startup — a serverless deployment has no persistent
- * startup phase to check this at.
- */
-export function resolveScoreBudgetMs(
-  rawEnv: string | undefined,
-  log?: { warn: (msg: string) => void },
-): number {
-  if (!rawEnv) return AEO_SCORE_DEFAULT_BUDGET_MS;
-  const parsed = Number(rawEnv);
-  if (!Number.isFinite(parsed) || parsed <= 0)
-    return AEO_SCORE_DEFAULT_BUDGET_MS;
-  if (parsed > AEO_SCORE_MAX_BUDGET_MS) {
-    log?.warn(
-      `AEO_SCORE_BUDGET_MS=${rawEnv} exceeds the ${AEO_SCORE_MAX_BUDGET_MS}ms cap; falling back to the ${AEO_SCORE_DEFAULT_BUDGET_MS}ms default.`,
-    );
-    return AEO_SCORE_DEFAULT_BUDGET_MS;
-  }
-  return parsed;
-}
-
-const SEVERITY_RANK: Record<"high" | "medium" | "low", number> = {
-  high: 0,
-  medium: 1,
-  low: 2,
-};
-
-/** `lowestTwo` ordering (D4): score asc, then severity high>medium>low, then weight desc. */
-function compareDimensions(a: AeoDimension, b: AeoDimension): number {
-  if (a.score !== b.score) return a.score - b.score;
-  const severityDiff = SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
-  if (severityDiff !== 0) return severityDiff;
-  return b.weight - a.weight;
-}
-
-const FAQ_HOWTO_INCENTIVE_ID: AeoDimensionId = "faq-howto-incentive";
-
-/** The fixed opportunity sentence for the incentive dimension (D4) — its per-page results carry no evidence. */
-function faqHowtoOpportunityFinding(slug: string): string {
-  return `${slug}: no FAQPage or HowTo structured data (a visibility opportunity, not a defect)`;
-}
-
-function buildDimension(
-  ruleId: AeoDimensionId,
-  report: AuditReport,
-): AeoDimension {
-  const perRule = report.perRule.find((r) => r.id === ruleId) as PerRuleResult;
-  const perPage = perRule.perPage ?? [];
-  const fraction = perRule.score ?? (perRule.pass ? 1 : 0);
-  const score = Math.round(fraction * 100);
-
-  let finding: string | null;
-  let pagesPassing: number;
-  const pagesTotal = perPage.length > 0 ? perPage.length : 1;
-
-  if (ruleId === FAQ_HOWTO_INCENTIVE_ID) {
-    pagesPassing = perPage.filter((p) => p.bonus === true).length;
-    const firstMissing = perPage.find((p) => p.bonus !== true);
-    finding = firstMissing
-      ? faqHowtoOpportunityFinding(firstMissing.slug)
-      : null;
-  } else {
-    pagesPassing =
-      perPage.length > 0
-        ? perPage.filter((p) => p.pass).length
-        : perRule.pass
-          ? 1
-          : 0;
-    const firstFailing = perPage.find((p) => !p.pass);
-    finding = firstFailing
-      ? (firstFailing.evidence ?? perRule.evidence ?? null)
-      : null;
-  }
-
-  return {
-    id: ruleId,
-    label: AEO_DIMENSION_LABELS[ruleId],
-    weight: perRule.weight,
-    score,
-    severity: AEO_DIMENSION_SEVERITY[ruleId],
-    finding,
-    pagesPassing,
-    pagesTotal,
-  };
-}
-
-/**
- * `assertUrlSafe`'s per-path rejection text (`packages/aeo/src/fetch/ssrf.ts`)
- * can disclose which internal host/IP a crawl target resolved to — an
- * anonymous-endpoint recon primitive (AILK #5110, mirroring the #4707 fix
- * already applied to `scoreUrl`'s top-level `unavailable`/`ssrf_blocked`
- * check below). `crawlSite` re-checks every path individually (DNS-rebinding
- * defense) and writes the raw `assertUrlSafe` text straight into
- * `SkippedEntry.reason` (`packages/aeo/src/fetch/crawl.ts:125`) — deliberately
- * so, per that file's own test
- * (`packages/aeo/__tests__/fetch/crawl.test.ts:47-49`), so the redaction
- * happens HERE instead, at the boundary where a `ready` result's
- * `meta.skipped` is assembled. Every `assertUrlSafe` rejection message has
- * one of these six fixed prefixes; `crawlSite`'s other `SkippedEntry.reason`
- * producers (`"budget_exceeded"`, a `fetchPage` HTTP/redirect/fetch-failure
- * message) never do.
- */
-const SSRF_GUARD_REASON_PATTERN =
-  /^(Not a valid URL:|Only http\(s\) URLs allowed,|Blocked host \(internal\/loopback\/metadata\):|DNS resolution failed for|No DNS addresses resolved for|Host .+ resolves to a blocked address:)/;
-
-/**
- * `meta.skipped[]` boundary serializer (#5110). A per-path SSRF-guard
- * rejection is logged server-side (the specific host/IP detail, for operator
- * diagnosis) and replaced on the wire with the same generic `"ssrf_blocked"`
- * sentinel `scoreUrl`'s top-level check already returns (below) — never the
- * raw text. Any other skip reason passes through unchanged.
- */
-function toClientSkippedEntry(entry: SkippedEntry): SkippedEntry {
-  if (!SSRF_GUARD_REASON_PATTERN.test(entry.reason)) return entry;
-  console.warn(
-    "aeo-score: per-path SSRF-guard rejection (redacted on the wire)",
-    {
-      path: entry.path,
-      url: entry.url,
-      reason: entry.reason,
-    },
-  );
-  return { ...entry, reason: "ssrf_blocked" };
-}
-
-/** Pure: crawl payload → runAudit → dimensions (D3/D4). Never throws on an empty crawl — the caller checks first. */
-export function scoreCrawl(
-  crawl: CrawlResult,
-  opts?: { now?: () => Date },
-): AeoScoreResult {
-  if (crawl.pages.length === 0) {
-    return {
-      status: "unavailable",
-      reason: "no_pages_fetched",
-      message: "No pages were fetched.",
-    };
-  }
-
-  const payload = buildAuditPayload(crawl.pages);
-  const report = runAudit(
-    { ...payload, locale: "en", identityMode: "organization" },
-    AEO_SCORE_RULES,
-  );
-
-  const dimensions = AEO_SCORE_RULES.map((rule) =>
-    buildDimension(rule.id as AeoDimensionId, report),
-  );
-  const lowestTwo = [...dimensions].sort(compareDimensions).slice(0, 2);
-  const partial = crawl.skipped.some((s) => s.reason === "budget_exceeded");
-  const now = opts?.now ? opts.now() : new Date();
-
-  return {
-    status: "ready",
-    score: Math.round(report.fractionalScore ?? report.score),
-    dimensions,
-    lowestTwo,
-    meta: {
-      auditedAt: now.toISOString(),
-      pagesAudited: crawl.pages.length,
-      partial,
-      skipped: crawl.skipped.map(toClientSkippedEntry),
-      schemaVersion: report.meta.schemaVersion,
-      registryVersion: report.meta.registryVersion,
-    },
-  };
-}
-
-export interface ScoreUrlDeps {
-  fetchImpl?: FetchImpl;
-  resolver?: Resolver;
-  budgetMs?: number;
-}
-
-/** `assertUrlSafe` → `crawlSite` → `scoreCrawl` (D3). */
-export async function scoreUrl(
-  url: string,
-  deps: ScoreUrlDeps = {},
-): Promise<AeoScoreResult> {
-  const safe = await assertUrlSafe(url, {
-    ...(deps.resolver !== undefined && { resolver: deps.resolver }),
-  });
-  if (!safe.ok) {
-    return {
-      status: "unavailable",
-      reason: "ssrf_blocked",
-      message: safe.reason,
-    };
-  }
-
-  const budgetMs = deps.budgetMs ?? AEO_SCORE_DEFAULT_BUDGET_MS;
-  try {
-    const crawl = await crawlSite(url, {
-      ...(deps.fetchImpl !== undefined && { fetchImpl: deps.fetchImpl }),
-      ...(deps.resolver !== undefined && { resolver: deps.resolver }),
-      deadline: Date.now() + budgetMs,
-    });
-    if (crawl.pages.length === 0) {
-      return {
-        status: "unavailable",
-        reason: "no_pages_fetched",
-        message: "No pages were fetched within the crawl budget.",
-      };
-    }
-    return scoreCrawl(crawl);
-  } catch (e) {
-    const message = e instanceof Error ? e.message : String(e);
-    return { status: "unavailable", reason: "crawl_failed", message };
-  }
-}
-
-/** The bundled pre-launch example — no runtime `fs` read (D6). */
-export function loadExampleScore(): AeoScoreResult {
-  const result = scoreCrawl(EXAMPLE_SCORE_CRAWL);
-  if (result.status !== "ready") {
-    // The fixture is committed and known-good; this should never happen.
-    throw new Error("Example score fixture failed to score.");
-  }
-  const annotate = (d: AeoDimension): AeoDimension => ({
-    ...d,
-    annotation: EXAMPLE_SCORE_ANNOTATIONS[d.id],
-  });
-  return {
-    ...result,
-    dimensions: result.dimensions.map(annotate),
-    lowestTwo: result.lowestTwo.map(annotate),
-    meta: {
-      ...result.meta,
-      example: true,
-      sourceUrl: EXAMPLE_SCORE_META.sourceUrl,
-      generatedAt: EXAMPLE_SCORE_META.generatedAt,
-      // Wire-visible disclosure (acceptance-review finding, #4666): whether
-      // the crawl data is a genuine fetch of `sourceUrl` or a hand-authored
-      // representative dataset. Sourced from EXAMPLE_SCORE_META itself, not
-      // hardcoded here, so regenerating the fixture from a real crawl flips
-      // this automatically.
-      illustrative: EXAMPLE_SCORE_META.illustrative,
-    },
-  };
-}