@tokenoftrust/storefront-runner 2.0.15 → 2.0.17

package/apps/storefront/src/lib/apps/routeParams.ts

@@ -0,0 +1,45 @@
+/**
+ * operationParam — resolve the managed-analytics v1 `[operation]` path param
+ * robustly on BOTH admin surfaces.
+ *
+ * On the host-routed surface Astro populates `context.params.operation` normally.
+ * On the TENANT surface (`/<domain>/api/…`) the middleware selects the tenant by
+ * path prefix and rewrites via `next(renderPath)` — and across that rewrite this
+ * flat dynamic route comes back with an EMPTY `context.params` too (mirrors the
+ * identical rewrite defect `changeIdParam` solves for the change routes;
+ * `[operation].ts` is single-segment, so it has no nested-route case to worry
+ * about).
+ *
+ * Fallback: parse the operation from the pathname tail, which is stable on both
+ * surfaces and both sides of the rewrite (`request.url` is the original request,
+ * unaffected by the rewrite — see tenantPreview.ts's `stripBasePath`). No static
+ * sibling reaches this handler — Astro matches static routes first — so the tail
+ * capture is unambiguous wherever this helper runs.
+ */
+import type { APIContext } from "astro";
+
+const TAIL = /\/api\/integrations\/v1\/([^/]+)\/?$/;
+
+function fromPathname(pathname: string | undefined): string | undefined {
+  if (!pathname) return undefined;
+  const m = pathname.match(TAIL);
+  if (!m?.[1]) return undefined;
+  let id: string = m[1];
+  try {
+    id = decodeURIComponent(id);
+  } catch {
+    // keep the raw segment — the allowlist lookup downstream will refuse garbage
+  }
+  const trimmed = id.trim();
+  return trimmed || undefined;
+}
+
+export function operationParam(context: APIContext): string | undefined {
+  const fromParams = context.params.operation?.trim();
+  if (fromParams) return fromParams;
+  try {
+    return fromPathname(new URL(context.request.url).pathname);
+  } catch {
+    return undefined;
+  }
+}

package/apps/storefront/src/lib/blog/collection.ts

@@ -156,6 +156,9 @@ function toSummary(p: BlogPost): BlogPostSummary {
     tags: p.tags,
     status: p.status,
     ...(p.scheduledAt ? { scheduledAt: p.scheduledAt } : {}),
+    // Carried, not dropped: a listing renders the entitlement badge off this,
+    // so omitting it makes a members-only post read as public in every listing.
+    ...(p.access ? { access: p.access } : {}),
     ...(p.featuredImage ? { featuredImage: p.featuredImage } : {}),
     ...(p.canonicalUrl ? { canonicalUrl: p.canonicalUrl } : {}),
     ...(p.inLanguage ? { inLanguage: p.inLanguage } : {}),

package/apps/storefront/src/lib/blog/provider.ts

@@ -1,12 +1,17 @@
 // The live WordPress `/blog` deliberately keeps reading its committed, curated
 // index.json (its order is hand-maintained and SEO-load-bearing). The generic
 // derived engine lives in ./collection.ts and powers `the-build` + any new
-// collection; switching `/blog` onto it is a later migration once order is
+// collection, and backs `/blog` whenever that curated index is unusable;
+// switching `/blog` onto it outright is a later migration once order is
 // encoded as data (see B0.1 §"/blog migration caution").
 import { tenantDirSegment } from "@tot/public-runtime";
+import { listPosts } from "./collection.js";
 import type { BlogPost, BlogPostSummary } from "./types.js";
 import type { ContentProvider } from "../storyblok/provider.js";
 
+/** The collection id `/blog` reads — the derived fallback's second argument. */
+const BLOG_COLLECTION = "blog";
+
 type ArtifactSource = Pick<ContentProvider, "readArtifact" | "listArtifactPaths">;
 
 function canReadArtifacts(value: ArtifactSource | undefined): value is ArtifactSource {
@@ -43,25 +48,54 @@ function tenantKey(keys: string[], tenantId: string, suffix: string): string | u
   return keys.find((key) => key.includes(segment) && key.endsWith(suffix));
 }
 
-export async function listBlogPosts(
+/** A curated index is usable only if it parses AND is the array shape it claims. */
+function parseCuratedIndex(raw: string): BlogPostSummary[] | null {
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    return Array.isArray(parsed) ? (parsed as BlogPostSummary[]) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The curated `index.json` for this tenant, or null when it is absent, malformed,
+ * or not an array. Null is "cannot use the curated order", never "no posts".
+ */
+async function readCuratedIndex(
   tenantId: string,
   source?: ArtifactSource,
-): Promise<BlogPostSummary[]> {
+): Promise<BlogPostSummary[] | null> {
   if (canReadArtifacts(source)) {
-    const paths = await source.listArtifactPaths("blog/");
     const raw = await source.readArtifact("blog/index.json");
-    if (raw) {
-      try {
-        return JSON.parse(raw) as BlogPostSummary[];
-      } catch {
-        return [];
-      }
-    }
-    if (paths !== null) return [];
+    if (raw) return parseCuratedIndex(raw);
   }
   const key = tenantKey(Object.keys(indexGlobs), tenantId, "/index.json")
     ?? Object.keys(indexGlobs).find((candidate) => candidate.includes(`${tenantDirSegment(tenantId)}content/blog/index.json`));
-  return key ? indexGlobs[key]!() : [];
+  return key ? (await indexGlobs[key]!()) ?? null : null;
+}
+
+/**
+ * The curated index stays the preferred source — its order is hand-maintained
+ * and SEO-load-bearing — but it must never be the blog's single point of
+ * failure. One malformed byte in `content/blog/index.json` makes the reconcile's
+ * JSON validator advisory-skip it, and the whole surface (index, taxonomy pages,
+ * RSS, sitemap entries) then reads as an empty collection and hard-404s while
+ * every `posts/*.json` sits materialized beside it.
+ *
+ * So an unusable curated index falls back to the derived index over
+ * `blog/posts/*.json` (./collection.ts): newest-first rather than curated order,
+ * and every article still reachable and listed. Whether the curated index is
+ * authoritative or derived, the runtime/build-time source selection is identical
+ * — `listPosts` applies the same "artifact paths, else build-time globs" rule.
+ */
+export async function listBlogPosts(
+  tenantId: string,
+  source?: ArtifactSource,
+): Promise<BlogPostSummary[]> {
+  const curated = await readCuratedIndex(tenantId, source);
+  if (curated && curated.length > 0) return curated;
+  return listPosts(tenantId, BLOG_COLLECTION, { content: source });
 }
 
 export async function getBlogPost(

package/apps/storefront/src/lib/fixtures/regulated-commerce-truth/index.ts

@@ -0,0 +1,540 @@
+/**
+ * Synthetic regulated-commerce truth used by cross-workstream conformance tests.
+ *
+ * This module is deliberately fixture-only. It does not call an integration API,
+ * deliver an order, import a report, or mutate a tenant. Consumers receive a
+ * validated, detached snapshot whose identifiers can never name a live tenant or
+ * destination.
+ */
+
+export const REGULATED_COMMERCE_TRUTH_SCHEMA = "regulated-commerce-truth.v1" as const;
+
+export type ExpectedInvariant =
+  | { disposition: "allow"; violations: [] }
+  | { disposition: "closed-failure"; violations: ["age-verification-required"] };
+
+export interface RegulatedCommerceTruthFixture {
+  schemaVersion: typeof REGULATED_COMMERCE_TRUTH_SCHEMA;
+  fixtureId: string;
+  synthetic: true;
+  capturedAt: string;
+  tenant: {
+    tenantId: string;
+    /** Canonical public-runtime TenantTier vocabulary. */
+    tenantTier: "regulated-commerce";
+    jurisdiction: string;
+    minimumAge: number;
+    ageVerificationRequired: true;
+  };
+  integrations: Array<{
+    reference: string;
+    kind: "order-risk";
+    destination: string;
+    enabled: boolean;
+  }>;
+  orders: Array<{
+    orderReference: string;
+    integrationReference: string;
+    occurredAt: string;
+    status: "paid" | "closed";
+    currency: "USD";
+    totalMinor: number;
+    destinationCountry: "US";
+    regulatedItems: Array<{
+      sku: string;
+      category: "age-restricted";
+      quantity: number;
+      unitPriceMinor: number;
+    }>;
+    compliance: {
+      ageVerification: "passed" | "missing";
+      consentRecorded: boolean;
+      taxCollectedMinor: number;
+    };
+    expectedInvariant: ExpectedInvariant;
+  }>;
+}
+
+const FIXTURE_SOURCE = {
+  schemaVersion: REGULATED_COMMERCE_TRUTH_SCHEMA,
+  fixtureId: "synthetic-regulated-commerce-risk-v1",
+  synthetic: true,
+  capturedAt: "2026-08-29T12:00:00.000Z",
+  tenant: {
+    tenantId: "synthetic-regulated-merchant.test",
+    tenantTier: "regulated-commerce",
+    jurisdiction: "US-MN",
+    minimumAge: 21,
+    ageVerificationRequired: true,
+  },
+  integrations: [
+    {
+      reference: "integration:synthetic:order-risk-v1",
+      kind: "order-risk",
+      destination: "fake://synthetic-order-risk/deliveries",
+      enabled: true,
+    },
+  ],
+  orders: [
+    {
+      orderReference: "order:synthetic:verified-001",
+      integrationReference: "integration:synthetic:order-risk-v1",
+      occurredAt: "2026-08-29T12:01:00.000Z",
+      status: "paid",
+      currency: "USD",
+      totalMinor: 6499,
+      destinationCountry: "US",
+      regulatedItems: [
+        {
+          sku: "SYNTH-AGE-21-001",
+          category: "age-restricted",
+          quantity: 1,
+          unitPriceMinor: 5999,
+        },
+      ],
+      compliance: {
+        ageVerification: "passed",
+        consentRecorded: true,
+        taxCollectedMinor: 500,
+      },
+      expectedInvariant: { disposition: "allow", violations: [] },
+    },
+    {
+      orderReference: "order:synthetic:closed-002",
+      integrationReference: "integration:synthetic:order-risk-v1",
+      occurredAt: "2026-08-29T12:02:00.000Z",
+      status: "closed",
+      currency: "USD",
+      totalMinor: 3299,
+      destinationCountry: "US",
+      regulatedItems: [
+        {
+          sku: "SYNTH-AGE-21-002",
+          category: "age-restricted",
+          quantity: 1,
+          unitPriceMinor: 2999,
+        },
+      ],
+      compliance: {
+        ageVerification: "missing",
+        consentRecorded: false,
+        taxCollectedMinor: 300,
+      },
+      expectedInvariant: {
+        disposition: "closed-failure",
+        violations: ["age-verification-required"],
+      },
+    },
+  ],
+} satisfies RegulatedCommerceTruthFixture;
+
+const UNSAFE_KEY = /(authorization|credential|secret|password|api[-_]?key|access[-_]?token|refresh[-_]?token|email|phone|address|(?:^|[-_])name(?:$|[-_]))/i;
+const CREDENTIAL_VALUE = /(-----BEGIN [A-Z ]*PRIVATE KEY-----|\bBearer\s+[A-Za-z0-9._~-]+|\bAKIA[0-9A-Z]{16}\b)/;
+const EMAIL_VALUE = /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i;
+const PHONE_VALUE = /\b(?:\+?\d{1,3}[-. ]?)?(?:\(\d{3}\)|\d{3})[-. ]\d{3}[-. ]\d{4}\b/;
+const PAYMENT_VALUE = /(?:^|[^0-9])(?:\d{4}[- ]?){3}\d{4}(?:$|[^0-9])|(?:^|[^0-9])\d{13,19}(?:$|[^0-9])/;
+/** US SSN/EIN-like nine-digit identifiers, contiguous or in their common hyphenated forms. */
+const GOVERNMENT_ID_VALUE = /(?:^|[^0-9])(?:\d{3}-\d{2}-\d{4}|\d{2}-\d{7}|\d{9})(?:$|[^0-9])/;
+const ADDRESS_VALUE = /\b\d{1,6}(?:[- ]+[A-Za-z][A-Za-z0-9.']*){1,5}[- ]+(?:street|st|avenue|ave|road|rd|boulevard|blvd|lane|ln|drive|dr|court|ct|way)\b/i;
+const PERSON_NAME_VALUE = /\b(?:[A-Z][a-z]{1,30}\s+[A-Z][a-z]{1,30}|(?:jane|john)[-_ ]doe)\b/i;
+const LIVE_URL_VALUE = /\b(?:https?|wss?):\/\//i;
+const CODE_VALUE = /(?:<\/?script\b|javascript:|\{\{|=>|\bfunction\s*\(|\b(?:window|document)\.|\bdataLayer\b|\bGTM-[A-Z0-9-]+\b)/i;
+
+// This is one local golden fixture, not a public extensible identity contract.
+const FIXTURE_ID = /^synthetic-regulated-commerce-risk-v1$/;
+const TENANT_ID = /^synthetic-regulated-merchant\.test$/;
+const JURISDICTION = /^US-MN$/;
+const INTEGRATION_REFERENCE = /^integration:synthetic:order-risk-v1$/;
+const FAKE_DESTINATION = /^fake:\/\/synthetic-order-risk\/deliveries$/;
+const ORDER_REFERENCE = /^order:synthetic:(?:verified|closed)-\d{3}$/;
+const SYNTHETIC_SKU = /^SYNTH-AGE-21-\d{3}$/;
+const MAX_MINIMUM_AGE = 125;
+const MAX_ITEM_QUANTITY = 10_000;
+const MAX_MINOR_AMOUNT = 99_999_999;
+
+class FixtureValidationError extends Error {}
+const VALIDATION_ERRORS = new WeakSet<object>();
+
+function fail(path: string, message: string): never {
+  const error = new FixtureValidationError(`Invalid regulated-commerce truth at ${path}: ${message}`);
+  VALIDATION_ERRORS.add(error);
+  throw Object.freeze(error);
+}
+
+function record(value: unknown, path: string): Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    fail(path, "expected a plain data object");
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) fail(path, "expected a plain data object");
+  return value as Record<string, unknown>;
+}
+
+function ownDataValue(value: Record<string, unknown>, key: string): unknown {
+  const descriptor = Object.getOwnPropertyDescriptor(value, key);
+  return descriptor && descriptor.enumerable && Object.hasOwn(descriptor, "value")
+    ? descriptor.value
+    : undefined;
+}
+
+function arrayDataValues(value: unknown, path: string): unknown[] {
+  if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype) {
+    fail(path, "expected an ordinary data array");
+  }
+  const lengthDescriptor = Object.getOwnPropertyDescriptor(value, "length");
+  const length = lengthDescriptor && Object.hasOwn(lengthDescriptor, "value")
+    ? lengthDescriptor.value
+    : -1;
+  if (!Number.isSafeInteger(length) || (length as number) < 0) fail(path, "array length is invalid");
+  const result: unknown[] = [];
+  for (let index = 0; index < (length as number); index += 1) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+    if (!descriptor || !descriptor.enumerable || !Object.hasOwn(descriptor, "value")) {
+      fail(`${path}[${index}]`, "expected an own enumerable data item");
+    }
+    result.push(descriptor.value);
+  }
+  for (const key of Reflect.ownKeys(value)) {
+    if (key === "length") continue;
+    if (typeof key !== "string" || !/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= (length as number)) {
+      fail(path, "array contains unexpected metadata");
+    }
+  }
+  return result;
+}
+
+function string(value: unknown, path: string): string {
+  if (typeof value !== "string" || value.length === 0) fail(path, "expected a non-empty string");
+  return value;
+}
+
+function boundedInteger(value: unknown, path: string, minimum: number, maximum: number): number {
+  if (!Number.isSafeInteger(value) || (value as number) < minimum || (value as number) > maximum) {
+    fail(path, `expected an integer from ${minimum} through ${maximum}`);
+  }
+  return value as number;
+}
+
+function exactKeys(value: Record<string, unknown>, keys: string[], path: string): void {
+  const expected = new Set(keys);
+  for (const key of Reflect.ownKeys(value)) {
+    if (typeof key !== "string" || !expected.has(key)) fail(path, "contains an unexpected field");
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor || !descriptor.enumerable || !Object.hasOwn(descriptor, "value")) {
+      fail(`${path}.${key}`, "must be an own enumerable data field");
+    }
+  }
+  for (const key of keys) {
+    if (ownDataValue(value, key) === undefined) fail(`${path}.${key}`, "required data field is missing");
+  }
+}
+
+function literal<T extends string | boolean>(value: unknown, expected: T, path: string): T {
+  if (value !== expected) fail(path, `expected ${JSON.stringify(expected)}`);
+  return expected;
+}
+
+function oneOf<T extends string>(value: unknown, allowed: readonly T[], path: string): T {
+  if (typeof value !== "string" || !allowed.includes(value as T)) {
+    fail(path, `expected one of ${allowed.join(", ")}`);
+  }
+  return value as T;
+}
+
+function isoTimestamp(value: unknown, path: string): string {
+  const parsed = string(value, path);
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(parsed) || Number.isNaN(Date.parse(parsed))) {
+    fail(path, "expected a canonical UTC timestamp");
+  }
+  return parsed;
+}
+
+function assertSanitized(value: unknown, path = "fixture"): void {
+  if (typeof value === "string") {
+    if (CREDENTIAL_VALUE.test(value)) fail(path, "credential-shaped value is forbidden");
+    if (
+      EMAIL_VALUE.test(value) ||
+      PHONE_VALUE.test(value) ||
+      PAYMENT_VALUE.test(value) ||
+      GOVERNMENT_ID_VALUE.test(value) ||
+      ADDRESS_VALUE.test(value) ||
+      PERSON_NAME_VALUE.test(value)
+    ) {
+      fail(path, "PII-shaped value is forbidden");
+    }
+    if (LIVE_URL_VALUE.test(value)) fail(path, "live URL value is forbidden");
+    if (CODE_VALUE.test(value)) fail(path, "code-bearing value is forbidden");
+    return;
+  }
+  if (Array.isArray(value)) {
+    const entries = arrayDataValues(value, path);
+    for (let index = 0; index < entries.length; index += 1) {
+      assertSanitized(entries[index], `${path}[${index}]`);
+    }
+    return;
+  }
+  if (value !== null && typeof value === "object") {
+    const object = record(value, path);
+    for (const key of Reflect.ownKeys(object)) {
+      if (typeof key !== "string") fail(path, "contains a non-JSON field");
+      const descriptor = Object.getOwnPropertyDescriptor(object, key);
+      if (!descriptor || !descriptor.enumerable || !Object.hasOwn(descriptor, "value")) {
+        fail(path, "contains a non-data field");
+      }
+      if (UNSAFE_KEY.test(key)) fail(path, "contains a PII/secret-shaped field");
+      // Do not include caller-controlled property names in diagnostics.
+      assertSanitized(descriptor.value, path);
+    }
+  }
+}
+
+function parseTenant(value: unknown): RegulatedCommerceTruthFixture["tenant"] {
+  const input = record(value, "fixture.tenant");
+  exactKeys(
+    input,
+    ["tenantId", "tenantTier", "jurisdiction", "minimumAge", "ageVerificationRequired"],
+    "fixture.tenant",
+  );
+  const tenantId = string(ownDataValue(input, "tenantId"), "fixture.tenant.tenantId");
+  if (!TENANT_ID.test(tenantId)) {
+    fail("fixture.tenant.tenantId", "must use the closed synthetic tenant-id format");
+  }
+  const jurisdiction = string(ownDataValue(input, "jurisdiction"), "fixture.tenant.jurisdiction");
+  if (!JURISDICTION.test(jurisdiction)) {
+    fail("fixture.tenant.jurisdiction", "must use the closed jurisdiction format");
+  }
+  return {
+    tenantId,
+    tenantTier: literal(ownDataValue(input, "tenantTier"), "regulated-commerce", "fixture.tenant.tenantTier"),
+    jurisdiction,
+    minimumAge: boundedInteger(
+      ownDataValue(input, "minimumAge"),
+      "fixture.tenant.minimumAge",
+      18,
+      MAX_MINIMUM_AGE,
+    ),
+    ageVerificationRequired: literal(
+      ownDataValue(input, "ageVerificationRequired"),
+      true,
+      "fixture.tenant.ageVerificationRequired",
+    ),
+  };
+}
+
+function parseIntegrations(value: unknown): RegulatedCommerceTruthFixture["integrations"] {
+  const inputs = arrayDataValues(value, "fixture.integrations");
+  if (inputs.length === 0) fail("fixture.integrations", "at least one integration reference is required");
+  const integrations: RegulatedCommerceTruthFixture["integrations"] = [];
+  for (let index = 0; index < inputs.length; index += 1) {
+    const path = `fixture.integrations[${index}]`;
+    const input = record(inputs[index], path);
+    exactKeys(input, ["reference", "kind", "destination", "enabled"], path);
+    const reference = string(ownDataValue(input, "reference"), `${path}.reference`);
+    if (!INTEGRATION_REFERENCE.test(reference)) {
+      fail(`${path}.reference`, "must use the closed synthetic integration-reference format");
+    }
+    const destination = string(ownDataValue(input, "destination"), `${path}.destination`);
+    if (!FAKE_DESTINATION.test(destination)) {
+      fail(`${path}.destination`, "must use the closed fake destination format");
+    }
+    const enabled = ownDataValue(input, "enabled");
+    if (typeof enabled !== "boolean") fail(`${path}.enabled`, "expected a boolean");
+    integrations.push({
+      reference,
+      kind: literal(ownDataValue(input, "kind"), "order-risk", `${path}.kind`),
+      destination,
+      enabled,
+    });
+  }
+  return integrations;
+}
+
+function parseExpectedInvariant(value: unknown, path: string): ExpectedInvariant {
+  const input = record(value, path);
+  exactKeys(input, ["disposition", "violations"], path);
+  const disposition = oneOf(
+    ownDataValue(input, "disposition"),
+    ["allow", "closed-failure"] as const,
+    `${path}.disposition`,
+  );
+  const violationInputs = arrayDataValues(ownDataValue(input, "violations"), `${path}.violations`);
+  const violations: Array<"age-verification-required"> = [];
+  for (let index = 0; index < violationInputs.length; index += 1) {
+    violations.push(
+      literal(violationInputs[index], "age-verification-required", `${path}.violations[${index}]`),
+    );
+  }
+  if (disposition === "allow") {
+    if (violations.length !== 0) fail(`${path}.violations`, "allow must have no violations");
+    return { disposition, violations: [] };
+  }
+  if (violations.length !== 1) {
+    fail(`${path}.violations`, "closed-failure must contain the age-verification-required violation");
+  }
+  return { disposition, violations: ["age-verification-required"] };
+}
+
+function parseOrders(
+  value: unknown,
+  integrations: RegulatedCommerceTruthFixture["integrations"],
+): RegulatedCommerceTruthFixture["orders"] {
+  const inputs = arrayDataValues(value, "fixture.orders");
+  if (inputs.length === 0) fail("fixture.orders", "at least one truth order is required");
+  const integrationReferences = new Set<string>();
+  for (const integration of integrations) integrationReferences.add(integration.reference);
+  const orders: RegulatedCommerceTruthFixture["orders"] = [];
+  for (let index = 0; index < inputs.length; index += 1) {
+    const path = `fixture.orders[${index}]`;
+    const input = record(inputs[index], path);
+    exactKeys(
+      input,
+      [
+        "orderReference",
+        "integrationReference",
+        "occurredAt",
+        "status",
+        "currency",
+        "totalMinor",
+        "destinationCountry",
+        "regulatedItems",
+        "compliance",
+        "expectedInvariant",
+      ],
+      path,
+    );
+    const orderReference = string(ownDataValue(input, "orderReference"), `${path}.orderReference`);
+    if (!ORDER_REFERENCE.test(orderReference)) {
+      fail(`${path}.orderReference`, "must use the closed synthetic order-reference format");
+    }
+    const integrationReference = string(
+      ownDataValue(input, "integrationReference"),
+      `${path}.integrationReference`,
+    );
+    if (!integrationReferences.has(integrationReference)) {
+      fail(`${path}.integrationReference`, "does not reference a declared integration");
+    }
+    const itemInputs = arrayDataValues(ownDataValue(input, "regulatedItems"), `${path}.regulatedItems`);
+    if (itemInputs.length === 0) fail(`${path}.regulatedItems`, "at least one regulated item is required");
+    const regulatedItems: RegulatedCommerceTruthFixture["orders"][number]["regulatedItems"] = [];
+    for (let itemIndex = 0; itemIndex < itemInputs.length; itemIndex += 1) {
+      const itemPath = `${path}.regulatedItems[${itemIndex}]`;
+      const item = record(itemInputs[itemIndex], itemPath);
+      exactKeys(item, ["sku", "category", "quantity", "unitPriceMinor"], itemPath);
+      const sku = string(ownDataValue(item, "sku"), `${itemPath}.sku`);
+      if (!SYNTHETIC_SKU.test(sku)) fail(`${itemPath}.sku`, "must use the closed synthetic SKU format");
+      regulatedItems.push({
+        sku,
+        category: literal(ownDataValue(item, "category"), "age-restricted", `${itemPath}.category`),
+        quantity: boundedInteger(
+          ownDataValue(item, "quantity"),
+          `${itemPath}.quantity`,
+          1,
+          MAX_ITEM_QUANTITY,
+        ),
+        unitPriceMinor: boundedInteger(
+          ownDataValue(item, "unitPriceMinor"),
+          `${itemPath}.unitPriceMinor`,
+          1,
+          MAX_MINOR_AMOUNT,
+        ),
+      });
+    }
+    const complianceInput = record(ownDataValue(input, "compliance"), `${path}.compliance`);
+    exactKeys(complianceInput, ["ageVerification", "consentRecorded", "taxCollectedMinor"], `${path}.compliance`);
+    const consentRecorded = ownDataValue(complianceInput, "consentRecorded");
+    if (typeof consentRecorded !== "boolean") {
+      fail(`${path}.compliance.consentRecorded`, "expected a boolean");
+    }
+    const compliance = {
+      ageVerification: oneOf(
+        ownDataValue(complianceInput, "ageVerification"),
+        ["passed", "missing"] as const,
+        `${path}.compliance.ageVerification`,
+      ),
+      consentRecorded,
+      taxCollectedMinor: boundedInteger(
+        ownDataValue(complianceInput, "taxCollectedMinor"),
+        `${path}.compliance.taxCollectedMinor`,
+        0,
+        MAX_MINOR_AMOUNT,
+      ),
+    };
+    const status = oneOf(ownDataValue(input, "status"), ["paid", "closed"] as const, `${path}.status`);
+    const expectedInvariant = parseExpectedInvariant(
+      ownDataValue(input, "expectedInvariant"),
+      `${path}.expectedInvariant`,
+    );
+    const shouldFailClosed = status === "closed" || compliance.ageVerification !== "passed";
+    if (shouldFailClosed !== (expectedInvariant.disposition === "closed-failure")) {
+      fail(`${path}.expectedInvariant`, "does not match the fixture's regulated-commerce facts");
+    }
+    orders.push({
+      orderReference,
+      integrationReference,
+      occurredAt: isoTimestamp(ownDataValue(input, "occurredAt"), `${path}.occurredAt`),
+      status,
+      currency: literal(ownDataValue(input, "currency"), "USD", `${path}.currency`),
+      totalMinor: boundedInteger(
+        ownDataValue(input, "totalMinor"),
+        `${path}.totalMinor`,
+        1,
+        MAX_MINOR_AMOUNT,
+      ),
+      destinationCountry: literal(
+        ownDataValue(input, "destinationCountry"),
+        "US",
+        `${path}.destinationCountry`,
+      ),
+      regulatedItems,
+      compliance,
+      expectedInvariant,
+    });
+  }
+  return orders;
+}
+
+function deepFreeze<T>(value: T): T {
+  if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) deepFreeze(child);
+  }
+  return value;
+}
+
+function parseRegulatedCommerceTruth(value: unknown): Readonly<RegulatedCommerceTruthFixture> {
+  assertSanitized(value);
+  const input = record(value, "fixture");
+  exactKeys(input, ["schemaVersion", "fixtureId", "synthetic", "capturedAt", "tenant", "integrations", "orders"], "fixture");
+  const fixtureId = string(ownDataValue(input, "fixtureId"), "fixture.fixtureId");
+  if (!FIXTURE_ID.test(fixtureId)) fail("fixture.fixtureId", "must use the closed synthetic fixture-id format");
+  const integrations = parseIntegrations(ownDataValue(input, "integrations"));
+  const parsed: RegulatedCommerceTruthFixture = {
+    schemaVersion: literal(
+      ownDataValue(input, "schemaVersion"),
+      REGULATED_COMMERCE_TRUTH_SCHEMA,
+      "fixture.schemaVersion",
+    ),
+    fixtureId,
+    synthetic: literal(ownDataValue(input, "synthetic"), true, "fixture.synthetic"),
+    capturedAt: isoTimestamp(ownDataValue(input, "capturedAt"), "fixture.capturedAt"),
+    tenant: parseTenant(ownDataValue(input, "tenant")),
+    integrations,
+    orders: parseOrders(ownDataValue(input, "orders"), integrations),
+  };
+  return deepFreeze(parsed);
+}
+
+/** Validate unknown fixture input and return a detached, immutable truth snapshot. */
+export function loadRegulatedCommerceTruth(value: unknown): Readonly<RegulatedCommerceTruthFixture> {
+  try {
+    return parseRegulatedCommerceTruth(value);
+  } catch (error) {
+    if (error !== null && typeof error === "object" && VALIDATION_ERRORS.has(error)) throw error;
+    throw new FixtureValidationError("Invalid regulated-commerce truth: input could not be safely inspected");
+  }
+}
+
+/** Load the repository's canonical deterministic fixture as a fresh snapshot. */
+export function loadSyntheticRegulatedCommerceTruth(): Readonly<RegulatedCommerceTruthFixture> {
+  return loadRegulatedCommerceTruth(FIXTURE_SOURCE);
+}