@tokenoftrust/storefront-runner 2.0.16 → 2.0.18

package/apps/storefront/src/lib/fixtures/ws3-readonly-clone-preflight/index.ts

@@ -0,0 +1,495 @@
+/**
+ * Fixture-only WS3 clone-read preflight.
+ *
+ * This is a pure conformance boundary over caller-supplied synthetic metadata.
+ * It intentionally has no imports and no execution seam: it cannot resolve,
+ * create, update, reconcile, or otherwise operate a clone. WS3 remains the owner
+ * of clone execution and public contract publication.
+ */
+
+export const WS3_CLONE_READ_PREFLIGHT_SCHEMA = "ws3-clone-read-preflight.v1" as const;
+
+const READ_CAPABILITIES = ["read:metadata", "read:manifest", "read:invariants"] as const;
+type ReadCapability = (typeof READ_CAPABILITIES)[number];
+
+export interface SyntheticCloneReadMetadata {
+  schemaVersion: typeof WS3_CLONE_READ_PREFLIGHT_SCHEMA;
+  fixtureId: string;
+  synthetic: true;
+  tenant: {
+    tenantId: string;
+    tenantTier: "regulated-commerce";
+  };
+  clone: {
+    cloneId: string;
+    snapshotReference: string;
+    sourceRevision: string;
+    capturedAt: string;
+  };
+  requestedCapabilities: ReadCapability[];
+  readFacts: {
+    manifestPresent: boolean;
+    catalogRecordCount: number;
+    orderRecordCount: number;
+    integrationReferenceCount: number;
+  };
+}
+
+export type CloneReadPreflightBlockerCode =
+  | "invalid-shape"
+  | "not-explicitly-synthetic"
+  | "live-looking-identity"
+  | "unsafe-field"
+  | "live-endpoint"
+  | "mutation-capability-refused"
+  | "unsupported-capability"
+  | "manifest-missing";
+
+export interface CloneReadPreflightBlocker {
+  code: CloneReadPreflightBlockerCode;
+  path: string;
+  message: string;
+}
+
+export interface CloneReadPreflightInvariant {
+  id:
+    | "synthetic-identities-only"
+    | "read-capabilities-only"
+    | "sanitized-offline-snapshot"
+    | "manifest-observed";
+  passed: boolean;
+}
+
+export interface CloneReadPreflightResult {
+  schemaVersion: typeof WS3_CLONE_READ_PREFLIGHT_SCHEMA;
+  ready: boolean;
+  blockers: CloneReadPreflightBlocker[];
+  invariants: CloneReadPreflightInvariant[];
+  observed: {
+    fixtureId: string | null;
+    tenantId: string | null;
+    cloneId: string | null;
+    snapshotReference: string | null;
+    requestedCapabilities: ReadCapability[];
+    readFacts: SyntheticCloneReadMetadata["readFacts"] | null;
+  };
+}
+
+const MUTATION_CAPABILITY = /(^|:)(create|update|execute|write|delete|mutate|reconcile|promote|deploy)(:|$)/i;
+const UNSAFE_KEY = /(authorization|credential|secret|password|api[-_]?key|access[-_]?token|refresh[-_]?token|private[-_]?key|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])/;
+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_ENDPOINT = /\b(?:https?|wss?):\/\//i;
+const CODE_VALUE = /(?:<\/?script\b|javascript:|\{\{|=>|\bfunction\s*\(|\b(?:window|document)\.|\bdataLayer\b|\bGTM-[A-Z0-9-]+\b)/i;
+const SHA = /^[a-f0-9]{40}$/;
+const ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+// Local fixture identities stay deliberately closed until WS3 publishes a public read contract.
+const FIXTURE_ID = /^synthetic-ws3-regulated-clone-read-v1$/;
+const TENANT_ID = /^synthetic-regulated-source\.test$/;
+const CLONE_LABEL = /^synthetic-risk-read-\d{3}$/;
+const SNAPSHOT_REFERENCE = /^fixture:\/\/synthetic-ws3-clone\/snapshot-\d{3}$/;
+const MAX_SYNTHETIC_READ_COUNT = 999_999;
+
+function record(value: unknown): Record<string, unknown> | null {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function ownDataValue(value: Record<string, unknown> | null, key: string): unknown {
+  if (!value) return undefined;
+  const descriptor = Object.getOwnPropertyDescriptor(value, key);
+  return descriptor && descriptor.enumerable && Object.hasOwn(descriptor, "value")
+    ? descriptor.value
+    : undefined;
+}
+
+function text(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function isSanitizedText(value: string): boolean {
+  return !(
+    CREDENTIAL_VALUE.test(value) ||
+    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) ||
+    LIVE_ENDPOINT.test(value) ||
+    CODE_VALUE.test(value)
+  );
+}
+
+function exactKeys(
+  value: Record<string, unknown>,
+  expected: readonly string[],
+  path: string,
+  block: (code: CloneReadPreflightBlockerCode, path: string, message: string) => void,
+): void {
+  const allowed = new Set(expected);
+  for (const key of Reflect.ownKeys(value)) {
+    if (typeof key !== "string" || !allowed.has(key)) {
+      block("invalid-shape", path, "contains an unexpected field");
+      continue;
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor || !descriptor.enumerable || !Object.hasOwn(descriptor, "value")) {
+      block("invalid-shape", `${path}.${key}`, "must be an enumerable data field");
+    }
+  }
+  for (const key of expected) {
+    if (ownDataValue(value, key) === undefined) {
+      block("invalid-shape", `${path}.${key}`, "required data field is missing");
+    }
+  }
+}
+
+function arrayDataValues(
+  value: unknown,
+  path: string,
+  block: (code: CloneReadPreflightBlockerCode, path: string, message: string) => void,
+): unknown[] | null {
+  if (!Array.isArray(value)) return null;
+  const lengthDescriptor = Object.getOwnPropertyDescriptor(value, "length");
+  const length = lengthDescriptor && Object.hasOwn(lengthDescriptor, "value")
+    ? lengthDescriptor.value
+    : -1;
+  if (!Number.isSafeInteger(length) || (length as number) < 0) {
+    block("invalid-shape", path, "array length is invalid");
+    return [];
+  }
+  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")) {
+      block("invalid-shape", `${path}[${index}]`, "must be an enumerable data item");
+      result.push(undefined);
+    } else {
+      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)) {
+      block("invalid-shape", path, "array contains unexpected metadata");
+    }
+  }
+  return result;
+}
+
+function findUnsafeData(
+  value: unknown,
+  block: (code: CloneReadPreflightBlockerCode, path: string, message: string) => void,
+  path = "metadata",
+): void {
+  if (typeof value === "string") {
+    if (CREDENTIAL_VALUE.test(value)) block("unsafe-field", 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)
+    ) {
+      block("unsafe-field", path, "PII-shaped value is forbidden");
+    }
+    if (LIVE_ENDPOINT.test(value)) block("live-endpoint", path, "network endpoint values are forbidden");
+    if (CODE_VALUE.test(value)) block("unsafe-field", path, "code-bearing value is forbidden");
+    return;
+  }
+  if (Array.isArray(value)) {
+    const entries = arrayDataValues(value, path, block) ?? [];
+    entries.forEach((entry, index) => findUnsafeData(entry, block, `${path}[${index}]`));
+    return;
+  }
+  const object = record(value);
+  if (!object) {
+    if (value !== null && typeof value === "object") {
+      block("invalid-shape", path, "must be a plain own-data object");
+    }
+    return;
+  }
+  for (const key of Reflect.ownKeys(object)) {
+    if (typeof key !== "string") {
+      block("invalid-shape", path, "contains a non-JSON field");
+      continue;
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(object, key);
+    if (!descriptor || !descriptor.enumerable || !Object.hasOwn(descriptor, "value")) {
+      block("invalid-shape", path, "contains a non-data field");
+      continue;
+    }
+    if (UNSAFE_KEY.test(key)) block("unsafe-field", path, "contains a PII/secret-shaped field");
+    // Caller-controlled keys never become blocker paths or messages.
+    findUnsafeData(descriptor.value, block, path);
+  }
+}
+
+function syntheticReadCount(value: unknown): value is number {
+  return Number.isSafeInteger(value) && (value as number) >= 0 && (value as number) <= MAX_SYNTHETIC_READ_COUNT;
+}
+
+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;
+}
+
+/**
+ * Assess synthetic clone-read metadata without invoking any clone or I/O seam.
+ * Invalid input is represented as blockers so callers get a complete, stable
+ * conformance report rather than a partial execution attempt.
+ */
+function assessSyntheticCloneRead(metadata: unknown): Readonly<CloneReadPreflightResult> {
+  const blockers: CloneReadPreflightBlocker[] = [];
+  const seen = new Set<string>();
+  const block = (code: CloneReadPreflightBlockerCode, path: string, message: string): void => {
+    const key = `${code}:${path}:${message}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      blockers.push({ code, path, message });
+    }
+  };
+
+  findUnsafeData(metadata, block);
+  const root = record(metadata);
+  if (!root) {
+    block("invalid-shape", "metadata", "expected an object");
+  } else {
+    exactKeys(
+      root,
+      ["schemaVersion", "fixtureId", "synthetic", "tenant", "clone", "requestedCapabilities", "readFacts"],
+      "metadata",
+      block,
+    );
+  }
+
+  const schemaVersion = ownDataValue(root, "schemaVersion");
+  const synthetic = ownDataValue(root, "synthetic");
+  const fixtureIdCandidate = text(ownDataValue(root, "fixtureId"));
+  const fixtureId =
+    synthetic === true &&
+    fixtureIdCandidate &&
+    FIXTURE_ID.test(fixtureIdCandidate) &&
+    isSanitizedText(fixtureIdCandidate)
+      ? fixtureIdCandidate
+      : null;
+  if (schemaVersion !== WS3_CLONE_READ_PREFLIGHT_SCHEMA) {
+    block("invalid-shape", "metadata.schemaVersion", `expected ${WS3_CLONE_READ_PREFLIGHT_SCHEMA}`);
+  }
+  if (!fixtureId) {
+    block("not-explicitly-synthetic", "metadata", "explicit synthetic metadata and a closed fixture-id format are required");
+  }
+
+  const tenant = record(ownDataValue(root, "tenant"));
+  if (!tenant) {
+    block("invalid-shape", "metadata.tenant", "expected an object");
+  } else {
+    exactKeys(tenant, ["tenantId", "tenantTier"], "metadata.tenant", block);
+  }
+  const tenantIdCandidate = text(ownDataValue(tenant, "tenantId"));
+  const tenantId =
+    tenantIdCandidate && TENANT_ID.test(tenantIdCandidate) && isSanitizedText(tenantIdCandidate)
+      ? tenantIdCandidate
+      : null;
+  if (!tenantId) {
+    block("live-looking-identity", "metadata.tenant.tenantId", "tenantId must use the closed synthetic format");
+  }
+  if (ownDataValue(tenant, "tenantTier") !== "regulated-commerce") {
+    block("invalid-shape", "metadata.tenant.tenantTier", "expected regulated-commerce");
+  }
+
+  const clone = record(ownDataValue(root, "clone"));
+  if (!clone) {
+    block("invalid-shape", "metadata.clone", "expected an object");
+  } else {
+    exactKeys(clone, ["cloneId", "snapshotReference", "sourceRevision", "capturedAt"], "metadata.clone", block);
+  }
+  const cloneIdCandidate = text(ownDataValue(clone, "cloneId"));
+  const cloneParts = cloneIdCandidate?.split("~clone~") ?? [];
+  const cloneLabel = cloneParts.length === 2 ? cloneParts[1] : null;
+  const cloneId =
+    tenantId &&
+    cloneIdCandidate &&
+    cloneParts[0] === tenantId &&
+    cloneLabel &&
+    cloneLabel.length <= 72 &&
+    CLONE_LABEL.test(cloneLabel) &&
+    isSanitizedText(cloneIdCandidate)
+      ? cloneIdCandidate
+      : null;
+  if (!cloneId) {
+    block(
+      "live-looking-identity",
+      "metadata.clone.cloneId",
+      "cloneId must belong to the synthetic tenant and use a synthetic- clone label",
+    );
+  }
+  const snapshotCandidate = text(ownDataValue(clone, "snapshotReference"));
+  const snapshotReference =
+    snapshotCandidate && SNAPSHOT_REFERENCE.test(snapshotCandidate) && isSanitizedText(snapshotCandidate)
+      ? snapshotCandidate
+      : null;
+  if (!snapshotReference) {
+    block("live-endpoint", "metadata.clone.snapshotReference", "only the closed offline fixture-reference format is allowed");
+  }
+  if (!text(ownDataValue(clone, "sourceRevision"))?.match(SHA)) {
+    block("invalid-shape", "metadata.clone.sourceRevision", "expected a fixed 40-character revision");
+  }
+  const capturedAt = text(ownDataValue(clone, "capturedAt"));
+  if (!capturedAt?.match(ISO_UTC) || Number.isNaN(Date.parse(capturedAt))) {
+    block("invalid-shape", "metadata.clone.capturedAt", "expected a canonical UTC timestamp");
+  }
+
+  const requestedCapabilityInput = ownDataValue(root, "requestedCapabilities");
+  const capabilityData = arrayDataValues(requestedCapabilityInput, "metadata.requestedCapabilities", block);
+  const capabilities = capabilityData ?? [];
+  if (!capabilityData) {
+    block("invalid-shape", "metadata.requestedCapabilities", "expected an array");
+  }
+  if (capabilities.length === 0) {
+    block("invalid-shape", "metadata.requestedCapabilities", "at least one read capability is required");
+  }
+  const requestedCapabilities: ReadCapability[] = [];
+  capabilities.forEach((capability, index) => {
+    const path = `metadata.requestedCapabilities[${index}]`;
+    if (typeof capability !== "string") {
+      block("invalid-shape", path, "expected a string");
+      return;
+    }
+    if (MUTATION_CAPABILITY.test(capability)) {
+      block("mutation-capability-refused", path, "mutation capability is not read-only");
+    } else if (!READ_CAPABILITIES.includes(capability as ReadCapability)) {
+      block("unsupported-capability", path, "capability is outside the local fixture contract");
+    } else {
+      requestedCapabilities.push(capability as ReadCapability);
+    }
+  });
+
+  const facts = record(ownDataValue(root, "readFacts"));
+  if (!facts) {
+    block("invalid-shape", "metadata.readFacts", "expected an object");
+  } else {
+    exactKeys(
+      facts,
+      ["manifestPresent", "catalogRecordCount", "orderRecordCount", "integrationReferenceCount"],
+      "metadata.readFacts",
+      block,
+    );
+  }
+  const manifestPresent = ownDataValue(facts, "manifestPresent");
+  const catalogRecordCount = ownDataValue(facts, "catalogRecordCount");
+  const orderRecordCount = ownDataValue(facts, "orderRecordCount");
+  const integrationReferenceCount = ownDataValue(facts, "integrationReferenceCount");
+  if (typeof manifestPresent !== "boolean") {
+    block("invalid-shape", "metadata.readFacts.manifestPresent", "expected a boolean");
+  } else if (!manifestPresent) {
+    block("manifest-missing", "metadata.readFacts.manifestPresent", "read snapshot has no manifest");
+  }
+  if (!syntheticReadCount(catalogRecordCount)) {
+    block("invalid-shape", "metadata.readFacts.catalogRecordCount", "expected an integer from 0 through 999999");
+  }
+  if (!syntheticReadCount(orderRecordCount)) {
+    block("invalid-shape", "metadata.readFacts.orderRecordCount", "expected an integer from 0 through 999999");
+  }
+  if (!syntheticReadCount(integrationReferenceCount)) {
+    block("invalid-shape", "metadata.readFacts.integrationReferenceCount", "expected an integer from 0 through 999999");
+  }
+
+  const hasBlocker = (...codes: CloneReadPreflightBlockerCode[]): boolean =>
+    blockers.some(({ code }) => codes.includes(code));
+  // A skipped accessor, sparse array item, or other malformed data surface means
+  // none of the cross-field security claims can be proven from the whole input.
+  const shapeInspectable = !hasBlocker("invalid-shape");
+  const invariants: CloneReadPreflightInvariant[] = [
+    {
+      id: "synthetic-identities-only",
+      passed: shapeInspectable && !hasBlocker("not-explicitly-synthetic", "live-looking-identity"),
+    },
+    {
+      id: "read-capabilities-only",
+      passed: shapeInspectable && !hasBlocker("mutation-capability-refused", "unsupported-capability"),
+    },
+    {
+      id: "sanitized-offline-snapshot",
+      passed: shapeInspectable && !hasBlocker("unsafe-field", "live-endpoint"),
+    },
+    {
+      id: "manifest-observed",
+      passed: shapeInspectable && !hasBlocker("manifest-missing") && manifestPresent === true,
+    },
+  ];
+
+  const readFacts =
+    facts &&
+    typeof manifestPresent === "boolean" &&
+    syntheticReadCount(catalogRecordCount) &&
+    syntheticReadCount(orderRecordCount) &&
+    syntheticReadCount(integrationReferenceCount)
+      ? {
+          manifestPresent,
+          catalogRecordCount,
+          orderRecordCount,
+          integrationReferenceCount,
+        }
+      : null;
+
+  return deepFreeze({
+    schemaVersion: WS3_CLONE_READ_PREFLIGHT_SCHEMA,
+    ready: blockers.length === 0 && invariants.every(({ passed }) => passed),
+    blockers,
+    invariants,
+    observed: {
+      fixtureId,
+      tenantId,
+      cloneId,
+      snapshotReference,
+      requestedCapabilities,
+      readFacts,
+    },
+  });
+}
+
+function inspectionFailure(): Readonly<CloneReadPreflightResult> {
+  return deepFreeze({
+    schemaVersion: WS3_CLONE_READ_PREFLIGHT_SCHEMA,
+    ready: false,
+    blockers: [{ code: "invalid-shape", path: "metadata", message: "input could not be safely inspected" }],
+    invariants: [
+      { id: "synthetic-identities-only", passed: false },
+      { id: "read-capabilities-only", passed: false },
+      { id: "sanitized-offline-snapshot", passed: false },
+      { id: "manifest-observed", passed: false },
+    ],
+    observed: {
+      fixtureId: null,
+      tenantId: null,
+      cloneId: null,
+      snapshotReference: null,
+      requestedCapabilities: [],
+      readFacts: null,
+    },
+  });
+}
+
+export function preflightSyntheticCloneRead(metadata: unknown): Readonly<CloneReadPreflightResult> {
+  try {
+    return assessSyntheticCloneRead(metadata);
+  } catch {
+    // Proxy traps and other caller-controlled inspection failures are contained;
+    // their thrown text is never copied into the stable conformance result.
+    return inspectionFailure();
+  }
+}

package/apps/storefront/src/lib/integration/tenantAnalyticsDeclarations.ts

@@ -0,0 +1,198 @@
+/**
+ * Tenant-owned analytics declaration surface (TIER 1).
+ *
+ * Today a tenant cannot declare a measurement destination from its OWN tree: the
+ * declaration lives in `tenant.integrations` (apps/storefront/src/config/tenants.ts),
+ * which is platform code a tenant may not touch (customization golden rule #1). So a
+ * merchant must file a request for what should be a self-serve, versioned, publishable
+ * edit — exactly like `theme.json` or `content/*`.
+ *
+ * This module is the tenant-tree producer that closes that gap. A tenant commits an
+ * `analytics.json` in its own tree (the tenant-owned surface, `tenants/<id>/**`), and
+ * this materializes it into the SAME already-consumed declaration seam
+ * ({@link IntegrationDeclarationInput}[], read by
+ * {@link loadTenantIntegrationDeclarations} and merged into the render plan by the
+ * interim bridge). It adds NO new runtime: it is a THIRD producer into an existing
+ * consumer, alongside the platform-authored `tenant.integrations` and the D1-backed
+ * managed installs.
+ *
+ * The heavy validation is NOT hand-rolled — each declared destination is built by the
+ * shipped, reviewed {@link buildPlatformAdapterDeclaration}, which fail-closes on an
+ * unknown adapter, a missing/invalid live id, an invalid per-stage id, or a non-live
+ * stage that reuses the live id. That is the whole point: a tenant supplies only public
+ * per-stage destination ids and gets a working, consent-gated, CSP-clean, non-live-safe
+ * measurement integration with no renderer change.
+ *
+ * Two callers, one core:
+ *   - PUBLISH validation — {@link materializeTenantAnalyticsDeclarations} returns
+ *     structured {@link ContractViolation}s so the ship/customization pipeline can
+ *     REFUSE an invalid `analytics.json` with an actionable, per-field message, exactly
+ *     as it refuses an invalid `theme.json`.
+ *   - RUNTIME materialization — {@link loadTenantAnalyticsDeclarations} is fail-closed:
+ *     a missing or (defensively) invalid file yields the empty set, never a throw, so an
+ *     undeclared tenant resolves the environment-only plan and a byte-identical page.
+ */
+import {
+  buildPlatformAdapterDeclaration,
+  ENVIRONMENT_SCHEMA_VERSION,
+  Violations,
+  isPlainObject,
+  rejectUnknownKeys,
+  type BrowserEnvironment,
+  type ContractViolation,
+  type IntegrationDeclarationInput,
+} from "@tot/public-runtime";
+
+/** The tenant-owned file that declares measurement destinations, in the tenant tree. */
+export const TENANT_ANALYTICS_FILE = "analytics.json";
+
+/** The current `analytics.json` contract version. */
+export const TENANT_ANALYTICS_SCHEMA_VERSION = 1 as const;
+
+/** One declared measurement destination: a first-class adapter + its per-stage public ids. */
+export interface TenantAnalyticsDestination {
+  /** The first-class platform adapter id, e.g. `platform.google-measurement`. */
+  adapter: string;
+  /** Public per-stage destination ids. `live` is required; non-live stages take SEPARATE test ids. */
+  ids: Record<string, unknown>;
+}
+
+/** The result of materializing a tenant's `analytics.json` into declarations. */
+export interface TenantAnalyticsMaterialization {
+  /** True only when EVERY declared destination validated; false surfaces `violations`. */
+  ok: boolean;
+  /** The materialized declarations, in declared order. Empty whenever `ok` is false. */
+  declarations: readonly IntegrationDeclarationInput[];
+  /** Per-field violations for the publish surface. Empty whenever `ok` is true. */
+  violations: readonly ContractViolation[];
+}
+
+/**
+ * The fixed environment the declaration is CONSTRUCTED against. A first-class adapter
+ * declaration is environment-INDEPENDENT in content — its per-stage ids are all baked
+ * into `publicConfig` and the client picks the current stage at render time — so the
+ * environment here only satisfies {@link buildPlatformAdapterDeclaration}'s validation
+ * and its (discarded) plan resolution. `canonicalHost` is a fixed placeholder, never the
+ * tenant id, so a clone id (which is not a legal hostname) can never fail construction.
+ */
+const CONSTRUCTION_ENVIRONMENT: BrowserEnvironment = {
+  schemaVersion: ENVIRONMENT_SCHEMA_VERSION,
+  siteSurface: "storefront",
+  environment: "live",
+  canonicalHost: "tenant-analytics.invalid",
+  revision: "tenant-analytics-declaration",
+};
+
+const EMPTY: readonly IntegrationDeclarationInput[] = Object.freeze([]);
+
+/** Re-anchor a builder violation path under the declaring `destinations[i]` element. */
+function reanchor(violation: ContractViolation, index: number): ContractViolation {
+  const base = `destinations[${index}]`;
+  const path =
+    violation.path === "(root)" || violation.path === ""
+      ? base
+      : violation.path === "adapterId"
+        ? `${base}.adapter`
+        : violation.path.startsWith("adapterId.")
+          ? `${base}.adapter${violation.path.slice("adapterId".length)}`
+          : `${base}.${violation.path}`;
+  return { path, code: violation.code, message: violation.message };
+}
+
+/** Validate the closed shape of one declared destination before it reaches the builder. */
+function readDestination(
+  raw: unknown,
+  index: number,
+  v: Violations,
+): TenantAnalyticsDestination | undefined {
+  const base = `destinations[${index}]`;
+  if (!isPlainObject(raw)) {
+    v.add(base, "type", "A destination must be an object of { adapter, ids }.");
+    return undefined;
+  }
+  rejectUnknownKeys(raw, ["adapter", "ids"], v, base);
+  const adapter = raw["adapter"];
+  if (typeof adapter !== "string" || adapter.length === 0) {
+    v.add(`${base}.adapter`, "type", "A destination adapter must be a non-empty string.");
+    return undefined;
+  }
+  if (!isPlainObject(raw["ids"])) {
+    v.add(`${base}.ids`, "type", "ids must be an object of { stage: destinationId }.");
+    return undefined;
+  }
+  return { adapter, ids: raw["ids"] };
+}
+
+/**
+ * Parse and materialize a tenant's `analytics.json` content into first-class adapter
+ * declarations. `raw` is the already-parsed JSON value (or `undefined`/`null` when the
+ * tenant declares none). Fail-closed and whole-file: if ANY declared destination is
+ * invalid, NO declaration is produced and the violations name every offending field —
+ * a half-valid analytics file never partially materializes.
+ */
+export function materializeTenantAnalyticsDeclarations(input: {
+  raw: unknown;
+  tenantPublicId: string;
+}): TenantAnalyticsMaterialization {
+  const { raw, tenantPublicId } = input;
+  // An undeclared tenant (no file) is the zero-cost norm, not an error.
+  if (raw === undefined || raw === null) {
+    return { ok: true, declarations: EMPTY, violations: [] };
+  }
+
+  const v = new Violations();
+  if (!isPlainObject(raw)) {
+    v.add("(root)", "type", "analytics.json must be a JSON object with a `destinations` array.");
+    return { ok: false, declarations: EMPTY, violations: v.items };
+  }
+  rejectUnknownKeys(raw, ["schemaVersion", "destinations"], v, "");
+  if ("schemaVersion" in raw && raw["schemaVersion"] !== TENANT_ANALYTICS_SCHEMA_VERSION) {
+    v.add(
+      "schemaVersion",
+      "unsupported_version",
+      `schemaVersion must equal ${TENANT_ANALYTICS_SCHEMA_VERSION}.`,
+    );
+  }
+  const destinationsRaw = raw["destinations"];
+  if (!Array.isArray(destinationsRaw)) {
+    v.add("destinations", "type", "`destinations` must be an array.");
+    return { ok: false, declarations: EMPTY, violations: v.items };
+  }
+
+  const declarations: IntegrationDeclarationInput[] = [];
+  destinationsRaw.forEach((destinationRaw, index) => {
+    const destination = readDestination(destinationRaw, index, v);
+    if (!destination) return;
+    const built = buildPlatformAdapterDeclaration({
+      adapterId: destination.adapter,
+      ids: destination.ids,
+      tenantPublicId,
+      environment: CONSTRUCTION_ENVIRONMENT,
+    });
+    if (!built.ok) {
+      for (const violation of built.violations) v.items.push(reanchor(violation, index));
+      return;
+    }
+    // Namespace the ref so a tenant-declared adapter can never be mistaken for — or
+    // collide with — the same adapter installed through the managed D1 path.
+    declarations.push({ ...built.declaration, ref: `tenant-analytics:${destination.adapter}` });
+  });
+
+  if (!v.ok) return { ok: false, declarations: EMPTY, violations: v.items };
+  return { ok: true, declarations, violations: [] };
+}
+
+/**
+ * Read a tenant's already-materialized analytics declarations for the render hot path,
+ * fail-closed: a missing OR invalid file yields the empty set (never throws), so an
+ * undeclared tenant resolves the environment-only plan and a defensively-invalid file
+ * darks its own analytics rather than the page. Publish validation
+ * ({@link materializeTenantAnalyticsDeclarations}) is what keeps an invalid file from
+ * ever reaching here.
+ */
+export function loadTenantAnalyticsDeclarations(
+  raw: unknown,
+  tenantPublicId: string,
+): readonly IntegrationDeclarationInput[] {
+  return materializeTenantAnalyticsDeclarations({ raw, tenantPublicId }).declarations;
+}