create-ailk 0.1.0 → 0.2.0

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

@@ -0,0 +1,288 @@
+/**
+ * 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 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,
+    },
+  };
+}

package/templates/apps/api/src/services/answer-distributions.ts

@@ -0,0 +1,138 @@
+/**
+ * @file answer-distributions.ts
+ * @description Shared per-question answer bucketing (#4771 D4).
+ *
+ * Extracted from `waitlist-dashboard.ts`'s `computeMetricRow` (the original
+ * inline `distributions` body) — moved verbatim, not rewritten, so
+ * `waitlist-dashboard.test.ts` stays green with NO edits to that file (the
+ * AC 7 regression floor).
+ *
+ * Takes already-flattened answer maps, not rows: `waitlist-dashboard.ts`
+ * passes `leads.map((l) => l.payload)`; `flow-aggregate.ts` passes
+ * `sessions.map((s) => flattenSessionState(s.state))`. That is what lets one
+ * implementation serve two different row types without either service
+ * knowing about the other's.
+ *
+ * Hosted as a THIRD, neutral module rather than inside `flow-aggregate.ts`
+ * (the issue's own `## Scope` names only that file) — a deliberate scope
+ * extension per `rules/worker-contract.md` § Mid-task scope expansion:
+ * hosting the shared helper in `flow-aggregate.ts` would make the operator
+ * dashboard import from the flow-aggregate service, an import direction no
+ * reader would predict from the names.
+ */
+
+import { logger } from "@working-theory/observability";
+import type { WaitlistAnswerType } from "@working-theory/validation";
+
+/**
+ * Defensive upper bound on an aggregation read (Medium finding, PR #4687
+ * security review). Caps the raw row count any SINGLE scoped read can
+ * return, so a `kind:"all"` aggregation spanning many sites (or a flow with
+ * many completed sessions) cannot load an unbounded result set into memory.
+ * Generous enough that no real deployment should hit it yet measured — if
+ * one does, the affected read undercounts rather than growing unbounded,
+ * and `logAggregationCapHit` below leaves a signal to act on (measure, then
+ * follow up with a real bound or DB-side aggregation).
+ */
+export const MAX_AGGREGATION_ROWS = 20_000;
+
+export function logAggregationCapHit(where: string, rowCount: number): void {
+  if (rowCount < MAX_AGGREGATION_ROWS) return;
+  logger.warn(
+    { where, rowCount, cap: MAX_AGGREGATION_ROWS },
+    "[answer-distributions] aggregation read hit its row cap — results may undercount",
+  );
+}
+
+/** A question's declared option set + the two fields the bucketer needs. */
+export type AnswerDistributionQuestion = {
+  id: string;
+  answerType: WaitlistAnswerType;
+  // `| undefined` (not just `?`) — the repo's `exactOptionalPropertyTypes`
+  // distinguishes "key absent" from "key present with value undefined", and
+  // both `WaitlistQuestion.options` and `WaitlistExperimentConfig`'s own
+  // `.optional()`-inferred fields are of the latter, wider shape.
+  options?: readonly { value: string }[] | undefined;
+};
+
+export type AnswerDistributionOption = {
+  value: string;
+  count: number;
+  share: number;
+};
+
+export type AnswerDistribution = {
+  questionId: string;
+  answerType: WaitlistAnswerType;
+  answered: number;
+  options: AnswerDistributionOption[];
+};
+
+/**
+ * Read one question's answer out of an already-flattened answer map — moved
+ * verbatim from `waitlist-dashboard.ts`'s (formerly local) `readPayloadAnswer`.
+ */
+export function readPayloadAnswer(
+  payload: unknown,
+  questionId: string,
+): string | string[] | undefined {
+  if (typeof payload !== "object" || payload === null) return undefined;
+  const value = (payload as Record<string, unknown>)[questionId];
+  if (typeof value === "string" && value.length > 0) return value;
+  if (Array.isArray(value)) {
+    const strings = value.filter((v): v is string => typeof v === "string");
+    return strings.length > 0 ? strings : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Bucket every declared question's answers across a set of already-flattened
+ * answer maps — moved verbatim from `computeMetricRow`'s inline
+ * `distributions` body. A value outside a question's declared options is
+ * counted under `"(other)"`; `text` / `email` / `url` questions are never
+ * charted (empty `options`, `answered` still populated).
+ */
+export function computeAnswerDistributions(
+  questions: readonly AnswerDistributionQuestion[],
+  answerSets: readonly unknown[],
+): AnswerDistribution[] {
+  return questions.map((q) => {
+    const answeredSets = answerSets.filter(
+      (payload) => readPayloadAnswer(payload, q.id) !== undefined,
+    );
+    const answered = answeredSets.length;
+    if (
+      q.answerType === "text" ||
+      q.answerType === "email" ||
+      q.answerType === "url"
+    ) {
+      return {
+        questionId: q.id,
+        answerType: q.answerType,
+        answered,
+        options: [],
+      };
+    }
+    const declared = new Set((q.options ?? []).map((o) => o.value));
+    const counts = new Map<string, number>();
+    for (const payload of answeredSets) {
+      const value = readPayloadAnswer(payload, q.id);
+      const values = Array.isArray(value)
+        ? value
+        : value !== undefined
+          ? [value]
+          : [];
+      for (const v of values) {
+        const bucket = declared.has(v) ? v : "(other)";
+        counts.set(bucket, (counts.get(bucket) ?? 0) + 1);
+      }
+    }
+    const options = [...counts.entries()].map(([value, count]) => ({
+      value,
+      count,
+      share: answered > 0 ? count / answered : 0,
+    }));
+    return { questionId: q.id, answerType: q.answerType, answered, options };
+  });
+}

package/templates/apps/api/src/services/consent.ts

@@ -0,0 +1,236 @@
+/**
+ * @file consent.ts
+ * @description The consent-grant writer (#5275 Part B) — `recordConsent`,
+ * the one function that turns a person's answers to a site's consent
+ * purposes into `ConsentGrant` rows, plus `recordLegacyConsent`, the D11
+ * path for a caller that could only say `consent: true`.
+ *
+ * SURFACE-AGNOSTIC BY DESIGN (D10). A grant's subject is a `subjectType` +
+ * `subjectId` pair of plain scalars with no relation into any other table
+ * (ADR 0009 invariant 1), so a new surface — the newsletter subscribe path
+ * is the named follow-up — adopts consent by adding ONE call here and NO
+ * migration. Nothing in this module knows what a project listing is.
+ *
+ * THE EVIDENCE RULE (spec §5.2): no row is ever written with statement text
+ * the system did not actually render to that person. Two consequences:
+ *
+ *   - `recordConsent` resolves each statement from the SAME registry and the
+ *     SAME `resolveConsentStatement` the renderer used (D7), so the recorded
+ *     wording and the rendered wording are one string by construction, and a
+ *     request body never carries wording at all. A purpose id the registry
+ *     does not know is skipped, not written: no statement was rendered for it.
+ *   - A grant whose wording cannot be proven — a legacy `consent: true` body,
+ *     or the migration backfill — carries `UNRECOVERABLE_CONSENT_STATEMENT`,
+ *     never today's default text. Stamping current wording onto a grant
+ *     nobody read would fabricate evidence (D11).
+ *
+ * APPEND-ONLY (D9): every write is a `createMany`; this module never
+ * updates or upserts, so a later withdrawal sits beside the earlier grant
+ * rather than replacing it. Declines are written as `granted: false` (D8).
+ */
+
+import { createHash } from "node:crypto";
+
+import { logger } from "@working-theory/observability";
+import {
+  consentPurposeById,
+  resolveConsentStatement,
+  SITE_CONSENT_CONFIG_DEFAULTS,
+  type SiteConsentConfig,
+} from "@working-theory/validation";
+
+import { prisma } from "../lib/prisma.js";
+
+/**
+ * The one delegate this module writes through — the shape of `prisma` AND of
+ * the `tx` client an interactive `$transaction` hands out, so a caller that
+ * creates the subject row can write the grant in the SAME transaction (the
+ * listing's `start` does): either the row and its evidence both land, or
+ * neither does.
+ */
+export interface ConsentWriteClient {
+  consentGrant: {
+    createMany(args: { data: ConsentGrantRow[] }): Promise<{ count: number }>;
+  };
+}
+
+interface ConsentGrantRow {
+  siteId: string;
+  subjectType: string;
+  subjectId: string;
+  purposeId: string;
+  granted: boolean;
+  locale: string;
+  statement: string;
+  statementHash: string;
+}
+
+/**
+ * The most keys a `consents` map may carry on an anonymous request. Any real
+ * registry is a handful of purposes; the cap bounds the per-request work an
+ * unbounded map could buy (security review, Low 3).
+ */
+export const MAX_CONSENT_KEYS = 64;
+
+/**
+ * The statement sentinel for a grant whose wording cannot be proven — a row
+ * carrying it records THAT a person consented (and when), not WHAT they read.
+ * Written on exactly two paths: `recordLegacyConsent` (a body carrying only
+ * the legacy `consent: true` literal, D11) and the consent_grants migration's
+ * backfill of pre-existing listings, which must carry this exact literal.
+ * It is never a substitute for real wording: a caller that rendered a
+ * statement records it through `recordConsent`.
+ */
+export const UNRECOVERABLE_CONSENT_STATEMENT =
+  "[unrecoverable: no statement was rendered by this system for this grant]";
+
+/** BCP-47 `und` — the locale of a statement nobody read. */
+export const UNRECOVERABLE_CONSENT_LOCALE = "und";
+
+/** sha256 hex of a statement — the `statementHash` that groups identical wordings. */
+export function consentStatementHash(statement: string): string {
+  return createHash("sha256").update(statement).digest("hex");
+}
+
+/**
+ * The site's consent registry.
+ *
+ * There is no per-site consent config ROW yet (spec §4 deliberately adds
+ * none), so every site resolves to `SITE_CONSENT_CONFIG_DEFAULTS`. This
+ * function is the single seam a `SiteConsentConfig` row wires into later
+ * (the `listingConfigFor` shape: read the blob, `consentConfigFor(blob)`).
+ * The RENDERER (`packages/ui`) resolves its statements from the same
+ * `SITE_CONSENT_CONFIG_DEFAULTS`, which is what keeps the recorded statement
+ * identical to the rendered one until a config row exists — at which point
+ * both sides must read the same row.
+ */
+export async function consentConfigForSite(
+  _siteId: string,
+): Promise<SiteConsentConfig> {
+  return SITE_CONSENT_CONFIG_DEFAULTS;
+}
+
+/**
+ * The id of the first REQUIRED registry purpose `consents` does not GRANT —
+ * declined (`false`) or simply absent — or `undefined` when every required
+ * purpose is `true`. Absence counts as unmet on purpose (security review,
+ * Medium 1): a body carrying `consents: {}` beside `consent: true` would
+ * otherwise create the subject with no grant row at all, which is a worse
+ * record than the legacy sentinel. A surface whose subject cannot exist
+ * without the required purposes (the listing: the row goes on to publish the
+ * founder's address) checks this before creating the subject.
+ */
+export function requiredConsentUnmet(
+  config: SiteConsentConfig,
+  consents: Record<string, boolean>,
+): string | undefined {
+  for (const purpose of config.purposes) {
+    if (purpose.required && consents[purpose.id] !== true) return purpose.id;
+  }
+  return undefined;
+}
+
+export interface RecordConsentInput {
+  siteId: string;
+  /** e.g. `project_listing`, `subscriber` — a plain scalar, no relation (D10). */
+  subjectType: string;
+  subjectId: string;
+  /** The locale the statements were RENDERED in; the served locale is what gets recorded. */
+  locale: string;
+  config: SiteConsentConfig;
+  /** purposeId → the person's answer. `false` is a stored decline (D8). */
+  consents: Record<string, boolean>;
+}
+
+/**
+ * Write one `ConsentGrant` row per answered purpose in one `createMany`.
+ * Returns the number of rows written. Append-only — never update/upsert.
+ * `db` defaults to the shared client; pass a `$transaction` client to land
+ * the grant atomically with the subject row it belongs to.
+ */
+export async function recordConsent(
+  input: RecordConsentInput,
+  db: ConsentWriteClient = prisma,
+): Promise<number> {
+  const rows: ConsentGrantRow[] = [];
+  const unknown: string[] = [];
+
+  for (const [purposeId, granted] of Object.entries(input.consents)) {
+    const purpose = consentPurposeById(input.config, purposeId);
+    if (!purpose) {
+      // Not in the registry ⇒ no statement was rendered for it ⇒ nothing to
+      // record (the evidence rule). Collected and logged ONCE per call below,
+      // because a client naming a purpose the site does not declare is a
+      // drift someone should see — and a map full of junk keys must not buy
+      // a log line each.
+      unknown.push(purposeId);
+      continue;
+    }
+    const { statement, locale } = resolveConsentStatement(purpose, input.locale);
+    rows.push({
+      siteId: input.siteId,
+      subjectType: input.subjectType,
+      subjectId: input.subjectId,
+      purposeId,
+      granted,
+      locale,
+      statement,
+      statementHash: consentStatementHash(statement),
+    });
+  }
+
+  if (unknown.length > 0) {
+    logger.warn(
+      {
+        siteId: input.siteId,
+        subjectType: input.subjectType,
+        unknownCount: unknown.length,
+        sample: unknown.slice(0, 5),
+      },
+      "[consent] skipping unknown purpose ids — not in the site's consent registry, no statement was rendered for them",
+    );
+  }
+
+  if (rows.length === 0) return 0;
+  const result = await db.consentGrant.createMany({ data: rows });
+  return result.count;
+}
+
+export interface RecordLegacyConsentInput {
+  siteId: string;
+  subjectType: string;
+  subjectId: string;
+  config: SiteConsentConfig;
+}
+
+/**
+ * The D11 path: a body that carried only the legacy `consent: true` literal.
+ * Writes ONE grant against the site's first `required` purpose (falling back
+ * to its first purpose), `granted: true`, with the statement marked
+ * unrecoverable — the caller affirmed, but this system rendered it no
+ * wording to affirm.
+ */
+export async function recordLegacyConsent(
+  input: RecordLegacyConsentInput,
+  db: ConsentWriteClient = prisma,
+): Promise<number> {
+  const purpose =
+    input.config.purposes.find((p) => p.required) ?? input.config.purposes[0];
+  if (!purpose) return 0;
+
+  const result = await db.consentGrant.createMany({
+    data: [
+      {
+        siteId: input.siteId,
+        subjectType: input.subjectType,
+        subjectId: input.subjectId,
+        purposeId: purpose.id,
+        granted: true,
+        locale: UNRECOVERABLE_CONSENT_LOCALE,
+        statement: UNRECOVERABLE_CONSENT_STATEMENT,
+        statementHash: consentStatementHash(UNRECOVERABLE_CONSENT_STATEMENT),
+      },
+    ],
+  });
+  return result.count;
+}