@tokenoftrust/storefront-runner 1.3.4-rc.4 → 1.4.0

package/packages/public-runtime/src/compliance/evaluate.ts

@@ -0,0 +1,265 @@
+/**
+ * Cart compliance EVALUATOR — the single enforcement authority. Given a cart's
+ * regulated lines, a ship-to destination, and a verification state, it returns a
+ * structured decision on whether checkout may COMPLETE. This is the "not just a
+ * notice" core: the notices render the same facts, but this function DECIDES.
+ *
+ * Checkout completion + order creation are EXTERNAL (managed cart). So this
+ * evaluator is consumed at two real fail-closed seams:
+ *   1. the checkout PREFLIGHT (`/api/compliance/preflight`) — the storefront must
+ *      clear the cart here before handing off to the managed cart;
+ *   2. the evidence PROMOTE gate — a regulated tenant is only promotable when its
+ *      enforcement wiring resolves (see `evidence-signals.ts`).
+ *
+ * Fail-closed everywhere: a regulated cart with no resolvable ruleset, an
+ * unconfigured verification provider, or an unsatisfied excise obligation BLOCKS.
+ * Pure + edge-safe.
+ */
+import type { ComplianceRuleset } from "./ruleset.js";
+import { stateRuleFor, effectivePerOrderLimit } from "./ruleset.js";
+import type { ProductComplianceProfile } from "./profile.js";
+import { isRegulatedProfile } from "./profile.js";
+import type { VerificationState } from "./verification.js";
+import { resolveVerificationDecision } from "./verification.js";
+
+export interface CartComplianceLine {
+  sku: string;
+  quantity: number;
+  profile: ProductComplianceProfile;
+  /** Display name for block messages. */
+  title?: string;
+}
+
+export interface ShipDestination {
+  /** State/province code, e.g. "MA". */
+  region: string;
+  /** ISO country code, e.g. "US". */
+  country: string;
+  postalCode?: string;
+}
+
+export interface CartComplianceInput {
+  /** Resolved ruleset, or null when it could NOT be resolved for a regulated tenant. */
+  ruleset: ComplianceRuleset | null;
+  /**
+   * True when the tenant is regulated (age/nicotine). Drives fail-closed when the
+   * ruleset is null. Independent of the lines so an empty/mis-tagged cart on a
+   * regulated tenant still fails closed rather than sneaking through.
+   */
+  regulated: boolean;
+  lines: CartComplianceLine[];
+  destination: ShipDestination | null;
+  verification: VerificationState | null;
+  /** Soft front-door affirmation (UX only; never a substitute for verification). */
+  ageAffirmed?: boolean;
+}
+
+export type ComplianceBlockCode =
+  | "ruleset_unavailable"
+  | "verification_unconfigured"
+  | "verification_required"
+  | "verification_failed"
+  | "destination_required"
+  | "region_prohibited"
+  | "flavored_prohibited"
+  | "purchase_limit_exceeded"
+  | "excise_unavailable";
+
+export interface ComplianceBlock {
+  code: ComplianceBlockCode;
+  message: string;
+  region?: string;
+  sku?: string;
+  /** True when this block is a fail-closed safety default, not a real violation. */
+  failedClosed?: boolean;
+}
+
+export interface CartComplianceRequirements {
+  ageVerification: "satisfied" | "required" | "blocked" | "not_required";
+  /** Adult signature on delivery required (PACT baseline and/or a state rule). */
+  adultSignature: boolean;
+  exciseHandling: "managed-cart" | "provider" | "unavailable" | "not_required";
+  destination: "provided" | "required" | "not_required";
+}
+
+export interface CartComplianceDecision {
+  /**
+   * - "clear"          — may hand off to checkout.
+   * - "action_required" — a shopper step remains (verify, choose ship-to state).
+   * - "blocked"        — a hard prohibition or fail-closed safety default.
+   */
+  status: "clear" | "action_required" | "blocked";
+  blocks: ComplianceBlock[];
+  requirements: CartComplianceRequirements;
+  purchaseLimit: {
+    region?: string;
+    limit: number;
+    units: number;
+    exceeded: boolean;
+  } | null;
+  /** True when any block is a fail-closed safety default. */
+  failedClosed: boolean;
+}
+
+/** Codes that are HARD stops (vs. actionable steps the shopper can still complete). */
+const HARD_BLOCK_CODES: ReadonlySet<ComplianceBlockCode> = new Set([
+  "ruleset_unavailable",
+  "verification_unconfigured",
+  "verification_failed",
+  "region_prohibited",
+  "flavored_prohibited",
+  "purchase_limit_exceeded",
+  "excise_unavailable",
+]);
+
+export function evaluateCartCompliance(
+  input: CartComplianceInput,
+): CartComplianceDecision {
+  const blocks: ComplianceBlock[] = [];
+  const regulatedLines = input.lines.filter((l) => isRegulatedProfile(l.profile));
+  const hasRegulatedGoods = regulatedLines.length > 0;
+
+  const requirements: CartComplianceRequirements = {
+    ageVerification: "not_required",
+    adultSignature: false,
+    exciseHandling: "not_required",
+    destination: "not_required",
+  };
+
+  // 1. Fail closed: a regulated tenant with no resolvable ruleset cannot be evaluated.
+  if (input.regulated && !input.ruleset) {
+    blocks.push({
+      code: "ruleset_unavailable",
+      failedClosed: true,
+      message:
+        "Compliance ruleset could not be resolved for this regulated tenant. " +
+        "Checkout is blocked (safe default = BLOCK).",
+    });
+    return finalize(blocks, requirements, null);
+  }
+
+  const ruleset = input.ruleset;
+  if (!ruleset || (!input.regulated && !hasRegulatedGoods)) {
+    // Unregulated tenant, no regulated goods → nothing to enforce.
+    return finalize(blocks, requirements, null);
+  }
+
+  // 2. Verification gate (fail-closed when required + no provider).
+  const vDecision = resolveVerificationDecision(
+    ruleset.verification,
+    input.verification,
+  );
+  requirements.ageVerification = vDecision.status;
+  if (vDecision.status === "blocked") {
+    blocks.push({
+      code: vDecision.failedClosed
+        ? "verification_unconfigured"
+        : "verification_failed",
+      failedClosed: vDecision.failedClosed,
+      message: vDecision.reason ?? "Age/identity verification failed.",
+    });
+  } else if (vDecision.status === "required") {
+    blocks.push({
+      code: "verification_required",
+      message: vDecision.reason ?? "Age/identity verification required.",
+    });
+  }
+
+  // 3. Excise obligation (fail-closed when required + unavailable).
+  if (ruleset.excise.required) {
+    requirements.exciseHandling = ruleset.excise.handling;
+    if (ruleset.excise.handling === "unavailable") {
+      blocks.push({
+        code: "excise_unavailable",
+        failedClosed: true,
+        message:
+          "Excise tax is required for these products but no excise path is wired. " +
+          "Checkout is blocked (safe default = BLOCK).",
+      });
+    }
+  }
+
+  // 4. Adult signature (PACT baseline; a state rule can also require it).
+  requirements.adultSignature =
+    ruleset.pactAct.enabled && ruleset.pactAct.adultSignatureRequired;
+
+  // 5. Destination-dependent rules. If regulated goods but no ship-to state, the
+  //    cart cannot clear — the state must be known to apply jurisdiction rules.
+  if (hasRegulatedGoods) {
+    if (!input.destination) {
+      requirements.destination = "required";
+      blocks.push({
+        code: "destination_required",
+        message:
+          "A ship-to state is required to confirm this order can be legally shipped.",
+      });
+    } else {
+      requirements.destination = "provided";
+      const region = input.destination.region.trim().toUpperCase();
+      const stateRule = stateRuleFor(ruleset, region);
+      if (stateRule?.adultSignatureRequired) requirements.adultSignature = true;
+
+      for (const line of regulatedLines) {
+        // Per-product ToT-synced restriction (data-driven per SKU).
+        const perProductBanned = line.profile.restrictedRegions.includes(region);
+        if (stateRule?.banAll || perProductBanned) {
+          blocks.push({
+            code: "region_prohibited",
+            region,
+            sku: line.sku,
+            message: `${line.title ?? line.sku} cannot be shipped to ${region}${
+              stateRule?.note ? ` (${stateRule.note})` : ""
+            }.`,
+          });
+          continue;
+        }
+        if (stateRule?.banFlavored && line.profile.isFlavored) {
+          blocks.push({
+            code: "flavored_prohibited",
+            region,
+            sku: line.sku,
+            message: `Flavored ${line.title ?? line.sku} cannot be shipped to ${region}${
+              stateRule?.note ? ` (${stateRule.note})` : ""
+            }.`,
+          });
+        }
+      }
+    }
+  }
+
+  // 6. Purchase limit (per-order regulated-unit cap for the destination region).
+  let purchaseLimit: CartComplianceDecision["purchaseLimit"] = null;
+  if (hasRegulatedGoods && input.destination) {
+    const region = input.destination.region.trim().toUpperCase();
+    const limit = effectivePerOrderLimit(ruleset, region);
+    if (limit != null && Number.isFinite(limit)) {
+      const units = regulatedLines.reduce((n, l) => n + Math.max(0, l.quantity), 0);
+      const exceeded = units > limit;
+      purchaseLimit = { region, limit, units, exceeded };
+      if (exceeded) {
+        blocks.push({
+          code: "purchase_limit_exceeded",
+          region,
+          message: `This order (${units} units) exceeds the ${limit}-unit per-order limit for ${region}.`,
+        });
+      }
+    }
+  }
+
+  return finalize(blocks, requirements, purchaseLimit);
+}
+
+function finalize(
+  blocks: ComplianceBlock[],
+  requirements: CartComplianceRequirements,
+  purchaseLimit: CartComplianceDecision["purchaseLimit"],
+): CartComplianceDecision {
+  const failedClosed = blocks.some((b) => b.failedClosed === true);
+  const hasHardBlock = blocks.some((b) => HARD_BLOCK_CODES.has(b.code));
+  const status: CartComplianceDecision["status"] = hasHardBlock
+    ? "blocked"
+    : blocks.length > 0
+      ? "action_required"
+      : "clear";
+  return { status, blocks, requirements, purchaseLimit, failedClosed };
+}

package/packages/public-runtime/src/compliance/evidence-signals.ts

@@ -0,0 +1,81 @@
+/**
+ * Enforcement → EVIDENCE signal bridge. The evidence document's compliance-critical
+ * checks (`age_gate`, `excise`, `jurisdiction`) gate whether a tenant is
+ * PROMOTABLE. Before this unit those checks asserted only config COHERENCE (the
+ * tenant declared a minAge / warning / restriction string). That is not
+ * enforcement — a store could declare "21+" and still ship untaxed to a banned
+ * state. This bridge reports whether real enforcement is WIRED, so `promotable`
+ * reflects enforcement, not just declared intent.
+ *
+ * The signal is intentionally per-tenant (not per-cart): it answers "can this
+ * regulated tenant enforce?", which is exactly the promote question. Fail-closed:
+ * a regulated tenant with no resolvable ruleset reports every signal false → not
+ * promotable.
+ *
+ * Pure + edge-safe.
+ */
+import type { ComplianceRuleset } from "./ruleset.js";
+
+export interface EnforcementEvidenceSignals {
+  /** A data-driven ruleset resolved for this (regulated) tenant. */
+  rulesetPresent: boolean;
+  /** The ruleset carries jurisdiction rules (state bans/limits) — not an empty list. */
+  jurisdictionRulesPresent: boolean;
+  /** Verification is satisfiable: a live provider is wired, OR it isn't required. */
+  verificationWired: boolean;
+  /** Excise obligation has a real handling path (not "unavailable"), OR not required. */
+  exciseWired: boolean;
+  /** PACT per-order reporting capture is wired when required. */
+  reportingWired: boolean;
+}
+
+export interface EnforcementSignalInput {
+  /** True when the tenant is regulated (age/nicotine). */
+  regulated: boolean;
+  /** Whether the PACT per-order reporting capture sink is wired in this deployment. */
+  reportingCaptureWired: boolean;
+}
+
+/**
+ * Derive the enforcement evidence signals for a tenant from its resolved ruleset.
+ * Unregulated tenants pass vacuously. A regulated tenant with no ruleset fails
+ * every signal (fail-closed → blocks promote).
+ */
+export function enforcementSignals(
+  ruleset: ComplianceRuleset | null,
+  input: EnforcementSignalInput,
+): EnforcementEvidenceSignals {
+  if (!input.regulated) {
+    return {
+      rulesetPresent: true,
+      jurisdictionRulesPresent: true,
+      verificationWired: true,
+      exciseWired: true,
+      reportingWired: true,
+    };
+  }
+  if (!ruleset) {
+    return {
+      rulesetPresent: false,
+      jurisdictionRulesPresent: false,
+      verificationWired: false,
+      exciseWired: false,
+      reportingWired: false,
+    };
+  }
+  const verificationWired =
+    !ruleset.verification.required || !!ruleset.verification.provider;
+  const exciseWired =
+    !ruleset.excise.required || ruleset.excise.handling !== "unavailable";
+  const reportingWired =
+    !ruleset.pactAct.enabled ||
+    !ruleset.pactAct.reportingRequired ||
+    input.reportingCaptureWired;
+  return {
+    rulesetPresent: true,
+    jurisdictionRulesPresent: ruleset.states.length > 0,
+    verificationWired,
+    exciseWired,
+    reportingWired,
+  };
+}

package/packages/public-runtime/src/compliance/index.ts

@@ -0,0 +1,22 @@
+/**
+ * @tot/public-runtime — compliance ENFORCEMENT engine (regulated commerce).
+ *
+ * The pure, edge-safe decision core that turns the compliance NOTICES from
+ * decoration into enforcement. Assembled from:
+ *   - profile.ts          — derive a product's regulated characteristics
+ *   - ruleset.ts          — the data-driven jurisdiction/federal rule model
+ *   - verification.ts     — the fail-closed age/identity verification gate
+ *   - evaluate.ts         — the cart→decision evaluator (the single authority)
+ *   - pact-report.ts      — PACT Act monthly-report per-order capture
+ *   - evidence-signals.ts — enforcement→evidence promote-gate bridge
+ *
+ * The concrete per-tenant rule DATA lives in the app
+ * (`apps/storefront/src/config/compliance/rulesets.ts`); this package owns the
+ * SHAPES + the decision logic so they can be unit-tested in one place.
+ */
+export * from "./profile.js";
+export * from "./ruleset.js";
+export * from "./verification.js";
+export * from "./evaluate.js";
+export * from "./pact-report.js";
+export * from "./evidence-signals.js";

package/packages/public-runtime/src/compliance/pact-report.ts

@@ -0,0 +1,94 @@
+/**
+ * PACT Act monthly-report CAPTURE. The Prevent All Cigarette Trafficking (PACT)
+ * Act requires ENDS sellers to file monthly reports with each state's tobacco tax
+ * administrator listing every shipment into that state. This framework CAPTURES
+ * the per-order data those filings need, in a stable record shape; assembling and
+ * FILING the actual monthly report is the merchant's / their counsel's job.
+ *
+ * The record is a SEPARATE compliance sink from the app-forwarded contract order
+ * (which is `customerHash`-only by the compliance floor) — PACT reporting
+ * legitimately needs buyer name + ship-to address, so it is captured server-side
+ * into a compliance sink, never leaked to installed apps.
+ *
+ * Pure + edge-safe: builds the record from data the caller already holds.
+ */
+import type { ShipDestination } from "./evaluate.js";
+
+export const PACT_REPORT_RECORD_VERSION = 1;
+
+/** One shipped regulated line, as the PACT report enumerates it. */
+export interface PactReportLine {
+  sku: string;
+  productName: string;
+  /** Category for the report (e.g. "e-liquid", "ends"). */
+  category: string;
+  quantity: number;
+  /** Volume in millilitres when known (state reports often want ml of e-liquid). */
+  volumeMl?: number;
+}
+
+/** The buyer identity a PACT filing needs (captured to the compliance sink only). */
+export interface PactReportBuyer {
+  name: string;
+  shipTo: ShipDestination & { line1?: string; line2?: string; city?: string };
+}
+
+export interface PactReportOrderRecord {
+  recordVersion: number;
+  tenantId: string;
+  orderId: string;
+  /** ISO 8601 order placed-at. */
+  placedAt: string;
+  /** Destination state — the report is filed per-state. */
+  region: string;
+  buyer: PactReportBuyer;
+  lines: PactReportLine[];
+  /** Total regulated units shipped. */
+  totalUnits: number;
+  /** Verification evidence reference at time of sale (proves the 21+ check). */
+  verificationEvidenceRef?: string;
+  /** Adult-signature-on-delivery was required for this shipment. */
+  adultSignatureRequired: boolean;
+}
+
+export interface BuildPactReportInput {
+  tenantId: string;
+  orderId: string;
+  placedAt: string;
+  buyer: PactReportBuyer;
+  lines: PactReportLine[];
+  verificationEvidenceRef?: string;
+  adultSignatureRequired: boolean;
+}
+
+/**
+ * Build the per-order PACT report record. Throws if the ship-to state is missing —
+ * a regulated shipment MUST have a filing jurisdiction; capturing it without one
+ * would silently drop it from the monthly report.
+ */
+export function buildPactReportRecord(
+  input: BuildPactReportInput,
+): PactReportOrderRecord {
+  const region = input.buyer.shipTo.region?.trim().toUpperCase();
+  if (!region) {
+    throw new Error(
+      "buildPactReportRecord: ship-to region is required for PACT reporting",
+    );
+  }
+  const totalUnits = input.lines.reduce(
+    (n, l) => n + Math.max(0, l.quantity),
+    0,
+  );
+  return {
+    recordVersion: PACT_REPORT_RECORD_VERSION,
+    tenantId: input.tenantId,
+    orderId: input.orderId,
+    placedAt: input.placedAt,
+    region,
+    buyer: { ...input.buyer, shipTo: { ...input.buyer.shipTo, region } },
+    lines: input.lines,
+    totalUnits,
+    verificationEvidenceRef: input.verificationEvidenceRef,
+    adultSignatureRequired: input.adultSignatureRequired,
+  };
+}

package/packages/public-runtime/src/compliance/profile.ts

@@ -0,0 +1,198 @@
+/**
+ * Product compliance PROFILE — the regulated characteristics an enforcement
+ * decision matches on, derived from the canonical `CatalogProduct` (which carries
+ * NO native compliance attributes — see `product.ts`). The signal sources, in
+ * precedence order, are the ones the ToT catalog sync already populates:
+ *
+ *   1. `metafields[compliance/*]` — ToT-synced per-SKU compliance data
+ *      (`restricted_states` JSON, `product_category`). This is the authoritative,
+ *      data-driven per-product restriction source; it is NOT a hardcoded list.
+ *   2. `product_type` / `tags` — merchant taxonomy (nicotine/vape/e-liquid, the
+ *      `F: <flavor>` tag convention the PDP already reads).
+ *   3. the chosen variant's `option_values` (Flavor, Nicotine strength).
+ *
+ * Pure + edge-safe (no node, no I/O). The storefront resolves a product's profile
+ * once and feeds it to `evaluateCartCompliance`.
+ */
+import type { CatalogProduct, CatalogVariant } from "../product.js";
+
+/** Coarse regulated category. `none` ⇒ not an age/nicotine-restricted product. */
+export type RegulatedCategory =
+  | "ends" // electronic nicotine delivery system (device / pod / disposable)
+  | "e-liquid" // nicotine e-liquid / salts
+  | "other-nicotine"
+  | "accessory" // batteries, coils — regulated-adjacent, no nicotine of its own
+  | "none";
+
+export interface ProductComplianceProfile {
+  /** Carries nicotine / is an ENDS product (the age-gate + excise axis). */
+  containsNicotine: boolean;
+  /**
+   * Has a characterizing flavor beyond tobacco/menthol — the axis several states
+   * ban for ENDS. `false` for tobacco/menthol/unflavored.
+   */
+  isFlavored: boolean;
+  /** Flavor labels found (lowercased), e.g. ["mango", "ice"]. */
+  flavorLabels: string[];
+  /** Derived regulated category. */
+  category: RegulatedCategory;
+  /**
+   * Per-product state/jurisdiction restrictions synced from ToT
+   * (`compliance.restricted_states`), uppercased region codes. The data-driven
+   * per-SKU no-ship list — complements the tenant ruleset's jurisdiction rules.
+   */
+  restrictedRegions: string[];
+}
+
+/** Flavors that do NOT count as "characterizing" for a flavored-ENDS ban. */
+const UNFLAVORED = new Set([
+  "tobacco",
+  "classic tobacco",
+  "menthol",
+  "unflavored",
+  "none",
+  "original",
+  "plain",
+]);
+
+const NICOTINE_HINTS = [
+  "nicotine",
+  "vape",
+  "vapor",
+  "vaping",
+  "e-liquid",
+  "eliquid",
+  "e-juice",
+  "ejuice",
+  "e liquid",
+  "salt nic",
+  "nic salt",
+  "pod",
+  "disposable",
+  "ends",
+  "cig",
+];
+
+const ACCESSORY_HINTS = ["battery", "coil", "charger", "case", "lanyard"];
+
+function readMetafield(
+  product: Pick<CatalogProduct, "metafields">,
+  namespace: string,
+  key: string,
+): string | undefined {
+  const mf = product.metafields.find(
+    (m) => m.namespace === namespace && m.key === key,
+  );
+  return mf?.value?.trim() || undefined;
+}
+
+/** Parse `compliance.restricted_states` — a JSON array OR an object keyed by code. */
+function parseRestrictedRegions(raw: string | undefined): string[] {
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    const codes = Array.isArray(parsed) ? parsed : Object.keys(parsed);
+    return codes
+      .map((c) => String(c).trim().toUpperCase())
+      .filter((c) => c.length > 0);
+  } catch {
+    // Not JSON — tolerate a comma/space separated list.
+    return raw
+      .split(/[,\s]+/)
+      .map((c) => c.trim().toUpperCase())
+      .filter((c) => c.length > 0);
+  }
+}
+
+/** Collect flavor labels from the `F: <flavor>` tag convention + a chosen variant. */
+function collectFlavors(
+  product: Pick<CatalogProduct, "tags">,
+  variant?: Pick<CatalogVariant, "option_values"> | null,
+): string[] {
+  const labels = new Set<string>();
+  for (const tag of product.tags ?? []) {
+    if (tag.startsWith("F: ")) {
+      const v = tag.slice(3).trim().toLowerCase();
+      if (v) labels.add(v);
+    }
+  }
+  const optFlavor = variant?.option_values?.["Flavor"];
+  if (optFlavor) labels.add(optFlavor.trim().toLowerCase());
+  return [...labels];
+}
+
+function containsAny(haystack: string, needles: string[]): boolean {
+  return needles.some((n) => haystack.includes(n));
+}
+
+/**
+ * Derive a product's compliance profile. Optionally pass the chosen `variant` to
+ * refine flavor/nicotine from the selected option values (e.g. a "0mg" variant is
+ * not treated as nicotine-bearing on the nicotine-strength axis).
+ */
+export function deriveProductProfile(
+  product: Pick<
+    CatalogProduct,
+    "metafields" | "tags" | "product_type" | "title"
+  >,
+  variant?: Pick<CatalogVariant, "option_values"> | null,
+): ProductComplianceProfile {
+  const category = readMetafield(product, "compliance", "product_category");
+  const type = (product.product_type ?? category ?? "").toLowerCase();
+  const haystack = [
+    type,
+    (product.title ?? "").toLowerCase(),
+    ...(product.tags ?? []).map((t) => t.toLowerCase()),
+  ].join(" ");
+
+  const restrictedRegions = parseRestrictedRegions(
+    readMetafield(product, "compliance", "restricted_states"),
+  );
+
+  const isAccessory =
+    containsAny(haystack, ACCESSORY_HINTS) &&
+    !containsAny(haystack, ["e-liquid", "eliquid", "juice", "salt"]);
+
+  // Nicotine strength option: a stated non-zero strength is a strong signal; an
+  // explicit "0mg"/"0 mg" variant is NOT treated as nicotine on that axis.
+  const nicStrength = variant?.option_values?.["Nicotine strength"]?.toLowerCase();
+  const nicOptionSaysZero = nicStrength != null && /^0\s*mg\b/.test(nicStrength);
+  const nicOptionSaysNonZero =
+    nicStrength != null && /\d/.test(nicStrength) && !nicOptionSaysZero;
+
+  const containsNicotine =
+    !isAccessory &&
+    (nicOptionSaysNonZero ||
+      (!nicOptionSaysZero && containsAny(haystack, NICOTINE_HINTS)));
+
+  const flavorLabels = collectFlavors(product, variant);
+  const isFlavored =
+    containsNicotine &&
+    flavorLabels.some((f) => !UNFLAVORED.has(f)) &&
+    flavorLabels.length > 0;
+
+  let cat: RegulatedCategory = "none";
+  if (isAccessory) cat = "accessory";
+  else if (containsAny(haystack, ["e-liquid", "eliquid", "juice", "salt"]))
+    cat = "e-liquid";
+  else if (containsNicotine && containsAny(haystack, ["pod", "device", "kit", "disposable", "vape", "ends"]))
+    cat = "ends";
+  else if (containsNicotine) cat = "other-nicotine";
+
+  return {
+    containsNicotine,
+    isFlavored,
+    flavorLabels,
+    category: cat,
+    restrictedRegions,
+  };
+}
+
+/** True when a profile carries ANY regulated characteristic that enforcement covers. */
+export function isRegulatedProfile(p: ProductComplianceProfile): boolean {
+  return (
+    p.containsNicotine ||
+    p.category !== "none" ||
+    p.restrictedRegions.length > 0
+  );
+}