@tokenoftrust/cli 2.5.5 → 2.5.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.5.5",
+  "version": "2.5.7",
   "description": "Token of Trust developer CLI — clone a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",

package/src/commands/report.mjs

@@ -39,7 +39,7 @@ export const USAGE = `tot report go-live — the go-live readiness report for yo
 
 Save each page's JSON from the devkit page checks into <dir> first, e.g.
   validate-page.sh <base> / > <dir>/home.json
-  validate-page-browser.mjs <base> / --provider cloudflare > <dir>/home.browser.json
+  validate-page-browser.mjs <base> / --store . --provider cloudflare > <dir>/home.browser.json
 
 ${TEASER}`;
 
@@ -147,9 +147,9 @@ export function storeConfigCheck(lint) {
 /**
  * Everything the report needs, from a page-results directory. A site-wide run's summary is used as
  * is; otherwise the checks are derived here from the single-page results.
- * @param {{ pagesDir: string, stylePath?: string|null, lint?: any }} input
+ * @param {{ pagesDir: string, stylePath?: string|null, lint?: any, config?: Record<string, any>|null }} input the store checkout's lint and `.tot/config.json`
  */
-export function evidenceFromDir({ pagesDir, stylePath = null, lint = null }) {
+export function evidenceFromDir({ pagesDir, stylePath = null, lint = null, config = null }) {
   const summary = readJson(join(pagesDir, "site-summary.json"));
   const styleJson = readJson(stylePath ?? join(pagesDir, "style.json"));
   const browserDir = join(pagesDir, "browser");
@@ -177,6 +177,7 @@ export function evidenceFromDir({ pagesDir, stylePath = null, lint = null }) {
             aggregate: { ...summary, totals: { ...summary.totals, issues: summary.totals?.issues ?? { lowRiskOpen: 0 } } },
             styleJson: styleJson ?? (summary.style?.gates ? { gates: summary.style.gates } : null),
             args: { manifest: summary.manifest ?? "(none supplied to the style-concept audit)" },
+            config,
           }),
         ];
     return {
@@ -195,6 +196,7 @@ export function evidenceFromDir({ pagesDir, stylePath = null, lint = null }) {
       aggregate: { pages: results, totals: { issues: { lowRiskOpen: 0 } } },
       styleJson,
       args: { manifest: "(none supplied to the style-concept audit)" },
+      config,
     }).filter((c) => c.area !== "Low-risk fix loop"),
   ];
   const failing = results.filter((r) => Object.values(r.gates).some((v) => v === false)).length;
@@ -288,7 +290,8 @@ export function run(argv, ctx, io = {}) {
     return 2;
   }
   const lint = storeExists ? validateTenant(store, { tenantId: tenant, mode: args.workspace ? "workspace" : "monorepo" }) : null;
-  const evidence = evidenceFromDir({ pagesDir, stylePath: args.style ? resolve(args.style) : null, lint });
+  const config = storeExists ? readJson(join(store, ".tot", "config.json")) : null;
+  const evidence = evidenceFromDir({ pagesDir, stylePath: args.style ? resolve(args.style) : null, lint, config });
   if (!evidence.measured) {
     err(`${fail(
       `no page-check results under ${pagesDir}`,

package/src/declared-config.d.mts

@@ -32,10 +32,21 @@ export function declarationFindings(
   current: Record<string, unknown> | null | undefined,
   previous: Record<string, unknown> | null | undefined,
 ): string[];
+export interface DeclaredObligation {
+  id: string;
+  surface: string;
+}
+export const COMPLIANCE_OBLIGATIONS: readonly Readonly<{ id: string; surface: string; keys: string[] }>[];
+export function declaredObligations(compliance: object | null | undefined): DeclaredObligation[];
 export function isRegulatedCompliance(compliance: object | null | undefined): boolean;
+export const COHERENCE_CHECK_IDS: readonly ("age_gate" | "excise" | "jurisdiction")[];
+export const OBLIGATION_EVIDENCE_CHECK: Readonly<Record<string, "age_gate" | "excise" | "jurisdiction" | null>>;
+export function isRegulatedObligationSet(obligations: readonly DeclaredObligation[]): boolean;
+export function coherenceChecksFor(obligations: readonly DeclaredObligation[]): ("age_gate" | "excise" | "jurisdiction")[];
 export function declaresJurisdictionNotice(compliance: object | null | undefined): boolean;
 export function complianceCoherenceFailures(
   compliance: object | null | undefined,
+  obligations?: readonly DeclaredObligation[],
 ): Partial<Record<"age_gate" | "excise" | "jurisdiction", { field: string; detail: string; hint: string }>>;
 export function complianceFindings(config: Record<string, unknown>, file?: string): DeclaredConfigFinding[];
 export function validateDeclaredConfig(config: Record<string, unknown>, file?: string): DeclaredConfigFinding[];
@@ -59,7 +70,10 @@ export const NICOTINE_WARNING_TEXT: string;
 export const CONSPICUITY_FLOOR: Readonly<{ contrast: number; fontSizePx: number; fontWeight: number }>;
 export const DEFAULT_NICOTINE_WARNING_PRESET: string;
 export const NICOTINE_WARNING_PRESETS: Readonly<Record<string, Readonly<NicotineWarningPresentation>>>;
+export const NICOTINE_WARNING_KEYS: readonly string[];
 export const NICOTINE_WARNING_STYLE_KEYS: readonly string[];
+export const NICOTINE_WARNING_CHECK_WIDTH_BOUNDS: Readonly<{ min: number; max: number }>;
+export function nicotineWarningCheckWidths(declaration: unknown): { widths: number[]; problems: string[] };
 export function contrastRatio(a: string, b: string): number;
 export function conspicuityProblems(p: NicotineWarningPresentation): string[];
 export function resolveNicotineWarning(declaration: unknown): ResolvedNicotineWarning;

package/src/declared-config.mjs

@@ -12,7 +12,9 @@
  *
  * Mirrors packages/public-runtime/src/declared-tenant-config.mjs (this package ships
  * to npm on its own); test/declared-config-parity.test.mjs pins the two together.
- * Dependency-free: the storefront runner copies this file as-is.
+ * Dependency-free: the storefront runner copies this file as-is, and the devkit page checks carry
+ * a byte-identical copy (docs/devkit-staging/tools/lib/declared-config.mjs, pinned by
+ * test/declared-config-devkit-copy.test.mjs) so their gates read a store's declaration the same way.
  */
 
 export const TOT_CONFIG_KEYS = [
@@ -184,8 +186,43 @@ export const MANDATED_NOTICE_KEYS = [
 
 const ERROR = "error";
 const WARN = "warn";
+/** @type {(v: unknown) => v is Record<string, any>} */
 const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 
+/**
+ * The platform's compliance obligations — the registry in
+ * packages/public-runtime/src/compliance-obligations.ts, mirrored here because this file
+ * is dependency-free: each duty's id, its compliance-authority surface, and the declared
+ * `compliance.*` keys that switch it on. packages/private-controlplane/tests/
+ * compliance-obligation-checks.test.ts pins this list to the registry, key for key.
+ */
+export const COMPLIANCE_OBLIGATIONS = Object.freeze([
+  { id: "age_gate", surface: "regulated", keys: ["minAge"] },
+  { id: "excise", surface: "regulated", keys: ["nicotineWarning", "exciseTax"] },
+  { id: "nicotine_warning", surface: "regulated", keys: ["nicotineWarning"] },
+  { id: "pact_act", surface: "regulated", keys: ["pactAct"] },
+  { id: "adult_signature", surface: "regulated", keys: ["adultSignature"] },
+  { id: "prop65", surface: "commerce", keys: ["prop65"] },
+  { id: "jurisdiction", surface: "commerce", keys: ["stateEligibility", "shippingRestriction"] },
+]);
+
+/**
+ * The obligations a declared compliance block switches on, as `resolveObligations` returns
+ * them (id + surface), in registry order.
+ * @param {Record<string, any> | null | undefined} compliance
+ * @returns {{ id: string, surface: string }[]}
+ */
+export function declaredObligations(compliance) {
+  return COMPLIANCE_OBLIGATIONS
+    .filter((o) => o.keys.some((key) => !!compliance?.[key]))
+    .map(({ id, surface }) => ({ id, surface }));
+}
+
+/** True when the declared block puts the store on the regulated surface. */
+export function isRegulatedCompliance(compliance) {
+  return isRegulatedObligationSet(declaredObligations(compliance));
+}
+
 /**
  * Compliance coherence — the declared-config half of the hosted preview's `age_gate`,
  * `excise` and `jurisdiction` evidence checks, so `tot validate` fails locally on
@@ -193,9 +230,42 @@ const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v)
  * packages/public-runtime/src/compliance-coherence.mjs (the platform's single source);
  * test/declared-config-parity.test.mjs pins the two together.
  */
-export function isRegulatedCompliance(compliance) {
-  const minAge = compliance?.minAge;
-  return (typeof minAge === "number" && minAge > 0) || !!compliance?.nicotineWarning;
+export const COHERENCE_CHECK_IDS = Object.freeze(/** @type {const} */ (["age_gate", "excise", "jurisdiction"]));
+
+export const OBLIGATION_EVIDENCE_CHECK = Object.freeze({
+  age_gate: "age_gate",
+  excise: "excise",
+  nicotine_warning: "excise",
+  pact_act: "jurisdiction",
+  adult_signature: "jurisdiction",
+  jurisdiction: "jurisdiction",
+  prop65: null,
+});
+
+/** @param {readonly { id: string, surface: string }[]} obligations */
+export function isRegulatedObligationSet(obligations) {
+  return obligations.some((o) => o.surface === "regulated");
+}
+
+/**
+ * @param {readonly { id: string, surface: string }[]} obligations
+ * @returns {("age_gate" | "excise" | "jurisdiction")[]}
+ */
+export function coherenceChecksFor(obligations) {
+  const out = new Set();
+  if (isRegulatedObligationSet(obligations)) {
+    out.add("age_gate");
+    out.add("jurisdiction");
+  }
+  for (const { id } of obligations) {
+    if (!Object.hasOwn(OBLIGATION_EVIDENCE_CHECK, id)) {
+      for (const check of COHERENCE_CHECK_IDS) out.add(check);
+      continue;
+    }
+    const check = OBLIGATION_EVIDENCE_CHECK[/** @type {keyof typeof OBLIGATION_EVIDENCE_CHECK} */ (id)];
+    if (check) out.add(check);
+  }
+  return COHERENCE_CHECK_IDS.filter((c) => out.has(c));
 }
 
 export function declaresJurisdictionNotice(compliance) {
@@ -203,19 +273,48 @@ export function declaresJurisdictionNotice(compliance) {
   return compliance?.pactAct === true || (typeof text === "string" && text.trim().length > 0);
 }
 
+/** @param {unknown} declaration */
+function stateEligibilityHasContent(declaration) {
+  if (declaration === null || typeof declaration !== "object" || Array.isArray(declaration)) return false;
+  const d = /** @type {Record<string, unknown>} */ (declaration);
+  const listed = (v) => Array.isArray(v) && v.some((s) => typeof s === "string" && s.trim().length > 0);
+  return listed(d.restrictedStates) || listed(d.eligibleStates) || (typeof d.note === "string" && d.note.trim().length > 0);
+}
+
+const REGULATED_KEY_FOR = Object.freeze({
+  age_gate: "minAge",
+  excise: "exciseTax",
+  nicotine_warning: "nicotineWarning",
+  pact_act: "pactAct",
+  adult_signature: "adultSignature",
+});
+
+function regulatedBy(compliance, obligations) {
+  const keys = new Set();
+  for (const o of obligations) {
+    if (o.surface !== "regulated") continue;
+    const key = REGULATED_KEY_FOR[/** @type {keyof typeof REGULATED_KEY_FOR} */ (o.id)];
+    if (o.id === "excise" && !compliance?.exciseTax) continue;
+    if (key) keys.add(key);
+  }
+  return [...keys].map((k) => `\`compliance.${k}\``).join(", ") || "a regulated obligation";
+}
+
 /**
  * @param {Record<string, any> | null | undefined} compliance
+ * @param {readonly { id: string, surface: string }[]} [obligations] defaults to what the block declares
  * @returns {Partial<Record<"age_gate" | "excise" | "jurisdiction", { field: string, detail: string, hint: string }>>}
  */
-export function complianceCoherenceFailures(compliance) {
+export function complianceCoherenceFailures(compliance, obligations = declaredObligations(compliance)) {
   /** @type {Partial<Record<"age_gate" | "excise" | "jurisdiction", { field: string, detail: string, hint: string }>>} */
   const out = {};
-  if (!isRegulatedCompliance(compliance)) return out;
+  const checks = coherenceChecksFor(obligations);
+  const regulated = isRegulatedObligationSet(obligations);
   const minAge = typeof compliance?.minAge === "number" ? compliance.minAge : null;
-  if (minAge == null || minAge < 18) {
+  if (checks.includes("age_gate") && regulated && (minAge == null || minAge < 18)) {
     out.age_gate = {
       field: "compliance.minAge",
-      detail: "Age-restricted/nicotine products require `compliance.minAge` (18 or higher) — none is set.",
+      detail: `Age-restricted products (${regulatedBy(compliance, obligations)}) require \`compliance.minAge\` (18 or higher) — none is set.`,
       hint: "Set `compliance.minAge` (18+) in .tot/config.json.",
     };
   }
@@ -226,16 +325,29 @@ export function complianceCoherenceFailures(compliance) {
       hint: "Set `compliance.minAge` to 21 in .tot/config.json (nicotine requires 21+, not just 18+).",
     };
   }
-  if (!declaresJurisdictionNotice(compliance)) {
-    out.jurisdiction = {
-      field: "compliance.pactAct",
-      detail:
-        "Regulated products require a shipping/jurisdiction notice: set `compliance.pactAct: true` " +
-        "or `compliance.shippingRestriction` — neither is set.",
-      hint:
-        "Set `compliance.pactAct: true` for the platform's PACT Act notice, or " +
-        "`compliance.shippingRestriction` to your own restriction text, in .tot/config.json.",
-    };
+  if (checks.includes("jurisdiction")) {
+    if (regulated && !declaresJurisdictionNotice(compliance)) {
+      out.jurisdiction = {
+        field: "compliance.pactAct",
+        detail:
+          `Regulated products (${regulatedBy(compliance, obligations)}) require a shipping/jurisdiction notice: ` +
+          "set `compliance.pactAct: true` or `compliance.shippingRestriction` — neither is set.",
+        hint:
+          "Set `compliance.pactAct: true` for the platform's PACT Act notice, or " +
+          "`compliance.shippingRestriction` to your own restriction text, in .tot/config.json.",
+      };
+    } else if (!regulated && !declaresJurisdictionNotice(compliance)
+      && !stateEligibilityHasContent(compliance?.stateEligibility)) {
+      const field = compliance?.stateEligibility ? "compliance.stateEligibility" : "compliance.shippingRestriction";
+      out.jurisdiction = {
+        field,
+        detail:
+          `\`${field}\` is declared but gives its shipping/jurisdiction notice nothing to say, so no notice renders.`,
+        hint:
+          "Set `compliance.shippingRestriction` to your restriction text, or give `compliance.stateEligibility` " +
+          "`restrictedStates`, `eligibleStates` or a `note`, in .tot/config.json.",
+      };
+    }
   }
   return out;
 }
@@ -251,27 +363,29 @@ export function complianceCoherenceFailures(compliance) {
  */
 export function complianceFindings(config, file = ".tot/config.json") {
   const compliance = isObject(config?.compliance) ? config.compliance : null;
+  const obligations = declaredObligations(compliance);
+  const owed = new Set(obligations.map((o) => o.id));
   const out = [];
-  for (const [check, failure] of Object.entries(complianceCoherenceFailures(compliance))) {
+  for (const [check, failure] of Object.entries(complianceCoherenceFailures(compliance, obligations))) {
     out.push(mk(ERROR, `compliance-${check.replace("_", "-")}`, `${file} compliance`,
       `${failure.detail} The hosted preview fails its \`${check}\` check on this.`, failure.hint));
   }
   // The hosted reconcile refuses a declaration whose `capabilities` switch off the
   // compliance floor (packages/public-runtime/src/capabilities.ts capabilityFloorViolations).
   const capabilities = isObject(config?.capabilities) ? config.capabilities : {};
-  if (compliance?.minAge && capabilities.ageVerification?.enabled === false) {
+  if (owed.has("age_gate") && capabilities.ageVerification?.enabled === false) {
     out.push(mk(ERROR, "capability-compliance-floor", `${file} capabilities`,
       "`capabilities.ageVerification` cannot be disabled for a store with `compliance.minAge` — the hosted preview refuses this revision.",
       "Remove `capabilities.ageVerification.enabled: false` from .tot/config.json."));
   }
-  if (compliance?.nicotineWarning && capabilities.exciseTax?.enabled === false) {
+  if (owed.has("excise") && capabilities.exciseTax?.enabled === false) {
     out.push(mk(ERROR, "capability-compliance-floor", `${file} capabilities`,
-      "`capabilities.exciseTax` cannot be disabled for a store with `compliance.nicotineWarning` — the hosted preview refuses this revision.",
+      "`capabilities.exciseTax` cannot be disabled for a store with `compliance.nicotineWarning` or `compliance.exciseTax` — the hosted preview refuses this revision.",
       "Remove `capabilities.exciseTax.enabled: false` from .tot/config.json."));
   }
-  if (isRegulatedCompliance(compliance) && !compliance?.ruleProfile) {
+  if (isRegulatedObligationSet(obligations) && !compliance?.ruleProfile) {
     out.push(mk(WARN, "compliance-rule-profile", `${file} compliance`,
-      "This store is regulated (`compliance.minAge`/`compliance.nicotineWarning`) but declares no " +
+      `This store is regulated (${regulatedBy(compliance, obligations)}) but declares no ` +
         "`compliance.ruleProfile`, so no checkout rules resolve: the preview renders, but checkout blocks " +
         "and going live refuses.",
       'Declare `compliance.ruleProfile` (e.g. "vape-nicotine-us") in .tot/config.json.'));
@@ -470,7 +584,13 @@ export function validateDeclaredConfig(config, file = ".tot/config.json") {
     }
   }
   out.push(...complianceFindings(config, file));
-  const warning = resolveNicotineWarning(isObject(config.compliance) ? config.compliance.nicotineWarning : undefined);
+  const declaration = isObject(config.compliance) ? config.compliance.nicotineWarning : undefined;
+  for (const problem of nicotineWarningCheckWidths(declaration).problems) {
+    out.push(mk(ERROR, "config-nicotine-warning-check-widths", `${file} compliance`,
+      `\`compliance.nicotineWarning\`: ${problem}. The page browser gate cannot check the warning at the widths you meant.`,
+      "list the widths where your layout changes (e.g. where your header becomes fixed), or remove `checkWidthsPx`"));
+  }
+  const warning = resolveNicotineWarning(declaration);
   if (warning.enabled && warning.problems.length > 0) {
     out.push(mk(ERROR, "config-nicotine-warning", `${file} compliance`, nicotineWarningProblemMessage(warning.problems),
       'use `true`, `{ "preset": "dark" }` or `{ "preset": "light" }`, or fix the style values named above'));
@@ -504,6 +624,7 @@ export function validateDeclaredConfig(config, file = ".tot/config.json") {
 //   "nicotineWarning": true                                   → the "dark" preset
 //   "nicotineWarning": { "preset": "light" }                  → a validated preset
 //   "nicotineWarning": { "preset": "light", "style": {...} }  → a custom presentation
+//   "nicotineWarning": { "checkWidthsPx": [800] }             → also checked seen at 800px wide
 //
 // Every presentation — preset or custom — must clear CONSPICUITY_FLOOR. A preset needs no
 // review. A custom presentation is a deviation the owner approves at go-live:
@@ -562,6 +683,9 @@ export const NICOTINE_WARNING_PRESETS = Object.freeze({
  * }} NicotineWarningPresentation
  */
 
+/** Every key a `compliance.nicotineWarning` object may declare. */
+export const NICOTINE_WARNING_KEYS = Object.freeze(["preset", "style", "checkWidthsPx"]);
+
 export const NICOTINE_WARNING_STYLE_KEYS = Object.freeze([
   "background", "text", "border", "textTransform", "fontWeight", "fontSizePx",
 ]);
@@ -669,8 +793,9 @@ export function resolveNicotineWarning(declaration) {
   if (!isObject(declaration)) {
     return resolved({ problems: ["must be `true` or an object like { \"preset\": \"light\" }"] });
   }
-  const { preset: presetName = DEFAULT_NICOTINE_WARNING_PRESET, style, ...rest } = /** @type {Record<string, unknown>} */ (declaration);
-  const problems = Object.keys(rest).map((k) => `\`${k}\` is not a nicotineWarning key (allowed: preset, style)`);
+  const { preset: presetName = DEFAULT_NICOTINE_WARNING_PRESET, style, checkWidthsPx: _checkWidths, ...rest } =
+    /** @type {Record<string, unknown>} */ (declaration);
+  const problems = Object.keys(rest).map((k) => `\`${k}\` is not a nicotineWarning key (allowed: ${NICOTINE_WARNING_KEYS.join(", ")})`);
   const base = typeof presetName === "string" ? NICOTINE_WARNING_PRESETS[presetName] : undefined;
   if (!base) {
     problems.push(`\`preset\` must be one of ${Object.keys(NICOTINE_WARNING_PRESETS).map((p) => `"${p}"`).join(", ")}`);
@@ -695,6 +820,35 @@ export function resolveNicotineWarning(declaration) {
   return resolved({ presentation, preset: matching ?? null, custom: !matching });
 }
 
+/** The viewport widths a store may add to the page browser gate's nicotine-warning check. */
+export const NICOTINE_WARNING_CHECK_WIDTH_BOUNDS = Object.freeze({ min: 320, max: 3840 });
+
+/**
+ * The extra viewport widths at which the page browser gate checks the nicotine warning is seen.
+ *
+ * The gate always checks its own phone, tablet, laptop and desktop widths; `checkWidthsPx` adds
+ * the store's own breakpoints (e.g. the width where its header becomes fixed) and never removes
+ * a default. A store that does not declare the warning has no widths; `true` and an object
+ * without `checkWidthsPx` add none.
+ *
+ *   "nicotineWarning": { "preset": "dark", "checkWidthsPx": [800, 1180] }
+ *
+ * `problems` lists why a declared value is unusable, in which case no extra width is used.
+ * @param {unknown} declaration the store's `compliance.nicotineWarning`
+ * @returns {{ widths: number[], problems: string[] }}
+ */
+export function nicotineWarningCheckWidths(declaration) {
+  if (!isObject(declaration)) return { widths: [], problems: [] };
+  const value = /** @type {Record<string, unknown>} */ (declaration).checkWidthsPx;
+  if (value === undefined) return { widths: [], problems: [] };
+  const { min, max } = NICOTINE_WARNING_CHECK_WIDTH_BOUNDS;
+  const usable = (/** @type {unknown} */ w) => Number.isInteger(w) && /** @type {number} */ (w) >= min && /** @type {number} */ (w) <= max;
+  if (!Array.isArray(value) || value.length === 0 || !value.every(usable)) {
+    return { widths: [], problems: [`\`checkWidthsPx\` must be a non-empty array of whole pixel widths from ${min} to ${max}, e.g. [800]`] };
+  }
+  return { widths: [...new Set(/** @type {number[]} */ (value))].sort((a, b) => a - b), problems: [] };
+}
+
 /**
  * The exact, human-readable statement of a custom presentation — what the owner approves.
  * Every resolved value is in it, so two presentations that differ in any value describe
@@ -720,7 +874,8 @@ export function describeNicotineWarningPresentation(p) {
  * fixed or sticky header pinned to the top of the viewport). Raising the warning above page
  * chrome would paint it over the tenant's own open menus and drawers, so occlusion is measured
  * instead: the page browser gate (`validate-page-browser.mjs`, `nicotineWarning`) fails a page
- * whose warning is covered at a phone, tablet or desktop width and names the covering element.
+ * whose warning is covered at a phone, tablet or desktop width, or at a width the store declares
+ * in `checkWidthsPx`, and names the covering element.
  * @param {unknown} declaration the tenant's `compliance.nicotineWarning`
  * @param {"bar" | "block"} variant
  */

package/src/readiness-checks.mjs

@@ -178,8 +178,38 @@ export function ecommerceStyleGuideCheck(styleJson) {
   };
 }
 
-export function buildReadinessChecks({ aggregate, styleJson, args }) {
+/**
+ * The store's declared compliance notices, judged on every page. Only a notice the store declares
+ * is a row, and a page that did not judge it fails: a declared legal notice nobody has seen on the
+ * page is not ready, whatever the page check reported.
+ * @param {{ gates?: Record<string, boolean | null> }[]} results
+ * @param {Record<string, any> | null | undefined} config the store's `.tot/config.json`
+ */
+export function complianceNoticesCheck(results, config) {
+  if (!config?.compliance?.nicotineWarning) return null;
+  const counts = countGate(results, "nicotineWarning");
+  const problem = counts.total === 0
+    ? "No pages were discovered for validation."
+    : counts.fail > 0 || counts.unknown > 0
+      ? `The store declares the FDA nicotine warning: ${counts.fail}/${counts.total} page(s) fail the visibility gate` +
+        `${counts.unknown > 0 ? ` and ${counts.unknown}/${counts.total} were not judged against the declaration` : ""}.`
+      : `The FDA nicotine warning is seen on all ${counts.total} page(s) at every checked width.`;
+  return {
+    area: "Compliance notices",
+    status: counts.total > 0 && counts.fail === 0 && counts.unknown === 0 ? "PASS" : "FAIL",
+    why: "A store that declares the FDA nicotine warning must show it, conspicuously and uncovered, on every page (21 CFR 1143.3).",
+    problem,
+    fix: "Run the browser page checks with --store <your checkout> on every page, then offset any fixed or sticky header the gate names; never restyle or move the warning.",
+  };
+}
+
+/**
+ * @param {{ aggregate: any, styleJson: any, args: { manifest: string }, config?: Record<string, any> | null }} input
+ *   `config` is the store's `.tot/config.json`, which decides the compliance notices row.
+ */
+export function buildReadinessChecks({ aggregate, styleJson, args, config = null }) {
   const results = aggregate.pages;
+  const compliance = complianceNoticesCheck(results, config);
   const render = countGate(results, "render");
   const boundary = countGate(results, "boundary");
   const seo = combineCounts(countGate(results, "seo"), countGate(results, "sitemap"));
@@ -191,6 +221,7 @@ export function buildReadinessChecks({ aggregate, styleJson, args }) {
   const lowRisk = aggregate.totals.issues.lowRiskOpen ?? 0;
 
   return [
+    ...(compliance ? [compliance] : []),
     styleGuideCheck(styleJson, args.manifest),
     ecommerceStyleGuideCheck(styleJson),
     styleQualityCheck(styleJson),

package/src/validate.mjs

@@ -17,7 +17,7 @@
  */
 import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
-import { validateDeclaredConfig } from "./declared-config.mjs";
+import { declaredObligations, isRegulatedCompliance, validateDeclaredConfig } from "./declared-config.mjs";
 import {
   foreignTenantSegments,
   parseMappingTarget,
@@ -291,18 +291,17 @@ function validateEmbedsDoc(doc, file) {
   return out;
 }
 
+// What the obligation registry says this store owes (declared-config.mjs mirrors it).
 function complianceObligations(config) {
-  const compliance = config?.compliance || {};
+  const owed = new Set(declaredObligations(config?.compliance).map((o) => o.id));
   return {
-    ageVerification: !!compliance.minAge,
-    exciseTax: !!compliance.nicotineWarning,
+    ageVerification: owed.has("age_gate"),
+    exciseTax: owed.has("excise"),
   };
 }
 
 function rawHtmlAllowed(config) {
-  const obligations = complianceObligations(config);
-  const regulated = obligations.ageVerification || obligations.exciseTax;
-  return !regulated;
+  return !isRegulatedCompliance(config?.compliance);
 }
 
 function validateCapabilitiesDoc(doc, file, config) {
@@ -325,7 +324,7 @@ function validateCapabilitiesDoc(doc, file, config) {
     out.push(mk(ERROR, "capability-compliance-floor", file, "ageVerification cannot be disabled for a tenant with compliance.minAge"));
   }
   if (obligations.exciseTax && doc.exciseTax?.enabled === false) {
-    out.push(mk(ERROR, "capability-compliance-floor", file, "exciseTax cannot be disabled for a tenant with compliance.nicotineWarning"));
+    out.push(mk(ERROR, "capability-compliance-floor", file, "exciseTax cannot be disabled for a tenant with compliance.nicotineWarning or compliance.exciseTax"));
   }
   return out;
 }