@tokenoftrust/storefront-runner 2.0.17 → 2.0.18

package/packages/public-runtime/schemas/publication-space/v1/ref.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tokenoftrust.com/schemas/publication-space/v1/ref.schema.json",
+  "title": "PublicationSpaceRefV1",
+  "type": "object",
+  "patternProperties": { "^\\$(?:schema|comment|id)$": {} },
+  "additionalProperties": false,
+  "required": ["version", "tenant", "spaceId"],
+  "properties": {
+    "version": { "const": 1 },
+    "tenant": {
+      "type": "string",
+      "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$"
+    },
+    "spaceId": {
+      "type": "string",
+      "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$"
+    }
+  }
+}

package/packages/public-runtime/schemas/publication-version/v1/pointer.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tokenoftrust.com/schemas/publication-version/v1/pointer.schema.json",
+  "title": "PublicationChannelPointerV1",
+  "type": "object",
+  "patternProperties": { "^\\$(?:schema|comment|id)$": {} },
+  "additionalProperties": false,
+  "required": ["schemaVersion", "tenant", "spaceId", "channel", "revision", "versionId", "sourceSha", "artifactDigest", "updatedAt"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "tenant": { "$ref": "#/$defs/identifier" },
+    "spaceId": { "$ref": "#/$defs/identifier" },
+    "channel": { "enum": ["preview", "live"] },
+    "revision": { "type": "integer", "minimum": 1 },
+    "versionId": { "$ref": "#/$defs/versionId" },
+    "sourceSha": { "$ref": "#/$defs/sha40" },
+    "artifactDigest": { "$ref": "#/$defs/sha256" },
+    "updatedAt": { "$ref": "#/$defs/instant" }
+  },
+  "$defs": {
+    "identifier": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$" },
+    "opaqueId": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9._:-]{6,126}[a-z0-9])$" },
+    "versionId": { "type": "string", "pattern": "^pv_[a-z0-9](?:[a-z0-9._:-]{4,122}[a-z0-9])$" },
+    "sha40": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+    "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "instant": { "type": "string", "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$" }
+  }
+}

package/packages/public-runtime/schemas/publication-version/v1/transition-request.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tokenoftrust.com/schemas/publication-version/v1/transition-request.schema.json",
+  "title": "PublicationTransitionRequestV1",
+  "type": "object",
+  "patternProperties": { "^\\$(?:schema|comment|id)$": {} },
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "transitionId",
+    "operation",
+    "tenant",
+    "spaceId",
+    "channel",
+    "targetVersionId",
+    "expectedSourceSha",
+    "expectedArtifactDigest",
+    "expectedRevision",
+    "principal",
+    "occurredAt"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "transitionId": { "$ref": "#/$defs/opaqueId" },
+    "operation": { "enum": ["activate", "rollback"] },
+    "tenant": { "$ref": "#/$defs/identifier" },
+    "spaceId": { "$ref": "#/$defs/identifier" },
+    "channel": { "enum": ["preview", "live"] },
+    "targetVersionId": { "$ref": "#/$defs/versionId" },
+    "expectedSourceSha": { "$ref": "#/$defs/sha40" },
+    "expectedArtifactDigest": { "$ref": "#/$defs/sha256" },
+    "expectedRevision": { "type": "integer", "minimum": 0 },
+    "principal": { "$ref": "#/$defs/opaqueId" },
+    "occurredAt": { "$ref": "#/$defs/instant" }
+  },
+  "$defs": {
+    "identifier": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$" },
+    "opaqueId": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9._:-]{6,126}[a-z0-9])$" },
+    "versionId": { "type": "string", "pattern": "^pv_[a-z0-9](?:[a-z0-9._:-]{4,122}[a-z0-9])$" },
+    "sha40": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+    "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "instant": { "type": "string", "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$" }
+  }
+}

package/packages/public-runtime/schemas/publication-version/v1/transition.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tokenoftrust.com/schemas/publication-version/v1/transition.schema.json",
+  "title": "PublicationPointerTransitionV1",
+  "type": "object",
+  "patternProperties": { "^\\$(?:schema|comment|id)$": {} },
+  "additionalProperties": false,
+  "required": ["schemaVersion", "transitionId", "operation", "tenant", "spaceId", "channel", "previous", "next", "principal", "occurredAt"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "transitionId": { "$ref": "#/$defs/opaqueId" },
+    "operation": { "enum": ["activate", "rollback"] },
+    "tenant": { "$ref": "#/$defs/identifier" },
+    "spaceId": { "$ref": "#/$defs/identifier" },
+    "channel": { "enum": ["preview", "live"] },
+    "previous": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/snapshot" }] },
+    "next": { "$ref": "#/$defs/snapshot" },
+    "principal": { "$ref": "#/$defs/opaqueId" },
+    "occurredAt": { "$ref": "#/$defs/instant" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "operation": { "const": "rollback" } }, "required": ["operation"] },
+      "then": { "properties": { "previous": { "$ref": "#/$defs/snapshot" } } }
+    }
+  ],
+  "$defs": {
+    "identifier": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$" },
+    "opaqueId": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9._:-]{6,126}[a-z0-9])$" },
+    "versionId": { "type": "string", "pattern": "^pv_[a-z0-9](?:[a-z0-9._:-]{4,122}[a-z0-9])$" },
+    "sha40": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+    "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "instant": { "type": "string", "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$" },
+    "snapshot": {
+      "type": "object",
+      "patternProperties": { "^\\$(?:schema|comment|id)$": {} },
+      "additionalProperties": false,
+      "required": ["revision", "versionId", "sourceSha", "artifactDigest"],
+      "properties": {
+        "revision": { "type": "integer", "minimum": 1 },
+        "versionId": { "$ref": "#/$defs/versionId" },
+        "sourceSha": { "$ref": "#/$defs/sha40" },
+        "artifactDigest": { "$ref": "#/$defs/sha256" }
+      }
+    }
+  }
+}

package/packages/public-runtime/schemas/publication-version/v1/version.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tokenoftrust.com/schemas/publication-version/v1/version.schema.json",
+  "title": "PublicationVersionV1",
+  "type": "object",
+  "patternProperties": { "^\\$(?:schema|comment|id)$": {} },
+  "additionalProperties": false,
+  "required": ["schemaVersion", "versionId", "tenant", "spaceId", "source", "renderer", "artifactDigest", "createdAt", "metadata"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "versionId": { "$ref": "#/$defs/versionId" },
+    "tenant": { "$ref": "#/$defs/identifier" },
+    "spaceId": { "$ref": "#/$defs/identifier" },
+    "source": {
+      "type": "object",
+      "patternProperties": { "^\\$(?:schema|comment|id)$": {} },
+      "additionalProperties": false,
+      "required": ["forge", "repo", "commitSha"],
+      "properties": {
+        "forge": { "enum": ["gitea", "github", "fixture"] },
+        "repo": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "pattern": "^(?!.*\\.\\.)(?!.*//)[A-Za-z0-9](?:[A-Za-z0-9._/-]{0,254}[A-Za-z0-9])?$"
+        },
+        "commitSha": { "$ref": "#/$defs/sha40" }
+      }
+    },
+    "renderer": {
+      "type": "object",
+      "patternProperties": { "^\\$(?:schema|comment|id)$": {} },
+      "additionalProperties": false,
+      "required": ["contractVersion", "themeContractVersion"],
+      "properties": {
+        "contractVersion": { "type": "string", "minLength": 1 },
+        "themeContractVersion": { "type": "string", "minLength": 1 }
+      }
+    },
+    "artifactDigest": { "$ref": "#/$defs/sha256" },
+    "createdAt": { "$ref": "#/$defs/instant" },
+    "metadata": {
+      "type": "object",
+      "patternProperties": { "^\\$(?:schema|comment|id)$": {} },
+      "additionalProperties": false,
+      "required": ["buildId"],
+      "properties": { "buildId": { "$ref": "#/$defs/opaqueId" } }
+    }
+  },
+  "$defs": {
+    "identifier": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$" },
+    "opaqueId": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9._:-]{6,126}[a-z0-9])$" },
+    "versionId": { "type": "string", "pattern": "^pv_[a-z0-9](?:[a-z0-9._:-]{4,122}[a-z0-9])$" },
+    "sha40": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+    "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "instant": { "type": "string", "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$" }
+  }
+}

package/packages/public-runtime/src/activity/catalog.ts

@@ -98,7 +98,7 @@ export const ACTION_CATALOG = {
   },
   "cli.command.result": {
     actors: ["dev", "agent"], source: "cli", sinks: HIGH_VOLUME,
-    argsAllow: ["command", "subcommand", "cliVersion", "exitCode", "durationMs"], renderedAllow: [],
+    argsAllow: ["command", "subcommand", "cliVersion", "exitCode", "durationMs", "diagnosticId"], renderedAllow: [],
     desc: "A `tot` CLI command finished (exit code + duration).",
   },
   "cli.obstacle.reported": {

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

@@ -122,6 +122,12 @@ export interface ReviewEnvironment {
    * surfaced in the PR review console. Absent/empty ⇒ validated clean.
    */
   findings?: PreviewStateFinding[];
+  /**
+   * Artifact paths this candidate's reconcile DROPPED from the version it published.
+   * Non-empty on a `ready` candidate means the preview renders the tenant's content
+   * MINUS these files; `lastError` names them in prose. Absent/empty ⇒ published clean.
+   */
+  droppedArtifacts?: string[];
   /** Auditable safety-block override applied to this candidate (who/why), if any. */
   overriddenBy?: PreviewStateOverride | null;
   /**

package/packages/public-runtime/src/customization-reconcile.ts

@@ -76,6 +76,14 @@ export interface PreviewState {
    * Absent/empty ⇒ the tenant's files validated clean. Written by `reconcilePreview`.
    */
   findings?: PreviewStateFinding[];
+  /**
+   * Artifact paths the last reconcile DROPPED from the version it published. A
+   * non-empty list on a SUCCESSFUL reconcile means the site is serving the tenant's
+   * content MINUS these files — they exist in the repo and are absent from the live
+   * version. Absent/empty ⇒ everything mapped was published. `lastError` names the
+   * same paths in prose. Written by `reconcilePreview`.
+   */
+  droppedArtifacts?: string[];
   /**
    * The auditable safety-block override applied to this reconcile (who/why), when a
    * blocking-safety finding was materialized past. Absent/null ⇒ no override.

package/packages/public-runtime/src/html-cache-policy.ts

@@ -0,0 +1,57 @@
+/**
+ * Route-document HTML cache policy (ADR 0013 — `serving.htmlCachePolicy`).
+ *
+ * The browser/shared TTLs a tenant's ROUTE DOCUMENTS (HTML) are served with are a
+ * declared property of the TENANT, read by BOTH public-serving substrates (the
+ * Cloudflare Worker+R2 pointer plane and the AWS S3/CloudFront plane), so moving
+ * substrate never silently changes repeat-visit caching. This module is the ONE
+ * place the policy is turned into a `Cache-Control` string, so both planes emit a
+ * byte-identical header from one formatter.
+ */
+
+/** The declared route-document cache TTLs (all in SECONDS). Absent fields fall to {@link DEFAULT_HTML_CACHE_POLICY}. */
+export interface HtmlCachePolicy {
+  /** `max-age` — how long a browser may reuse a route document without revalidating. */
+  browserMaxAge?: number;
+  /** `s-maxage` — how long the shared CDN cache may reuse it. */
+  sharedMaxAge?: number;
+  /** `stale-while-revalidate` — grace window a stale document may still serve while a fresh one is fetched. */
+  staleWhileRevalidate?: number;
+}
+
+/**
+ * The route-document default when a tenant declares no `serving.htmlCachePolicy`.
+ * A 5-minute browser+shared TTL with a 1-day SWR: fresh-biased because the pointer
+ * flip republishes at a STABLE url and every publish busts the edge (digest-scoped
+ * keys self-invalidate), so a short browser ceiling is safe and the ADR's contract.
+ */
+export const DEFAULT_HTML_CACHE_POLICY: Required<HtmlCachePolicy> = {
+  browserMaxAge: 300,
+  sharedMaxAge: 300,
+  staleWhileRevalidate: 86400,
+};
+
+/**
+ * Render a {@link HtmlCachePolicy} to a `Cache-Control` header value. Each field
+ * falls back to {@link DEFAULT_HTML_CACHE_POLICY} INDEPENDENTLY, so a partial policy
+ * is completed rather than rejected, and `null`/`undefined` yields the full default.
+ * This is the single source of the route-document Cache-Control string for both planes.
+ */
+export function formatHtmlCacheControl(policy?: HtmlCachePolicy | null): string {
+  const browserMaxAge = policy?.browserMaxAge ?? DEFAULT_HTML_CACHE_POLICY.browserMaxAge;
+  const sharedMaxAge = policy?.sharedMaxAge ?? DEFAULT_HTML_CACHE_POLICY.sharedMaxAge;
+  const staleWhileRevalidate =
+    policy?.staleWhileRevalidate ?? DEFAULT_HTML_CACHE_POLICY.staleWhileRevalidate;
+  return `public, max-age=${browserMaxAge}, s-maxage=${sharedMaxAge}, stale-while-revalidate=${staleWhileRevalidate}`;
+}
+
+/**
+ * The internal, MATERIALIZE-ONLY response header the render emits (gated on the
+ * materialize probe request header) so the publish/materialize plane can capture the
+ * tenant's resolved route-document Cache-Control into the bundle manifest — the same
+ * capture pattern as CSP. It is NEVER emitted on a real public response.
+ */
+export const HTML_CACHE_POLICY_CAPTURE_HEADER = "x-tot-html-cache-policy";
+
+/** The request header the materialize probe sends to ask the render to emit {@link HTML_CACHE_POLICY_CAPTURE_HEADER}. */
+export const HTML_CACHE_POLICY_CAPTURE_PROBE = "x-tot-materialize-capture";

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

@@ -15,6 +15,12 @@
 // preview / script types the renderer needs. Read/apply only.
 export * from "./product.js";
 export * from "./tenant.js";
+export * from "./publication-space.js";
+export * from "./publication-version.js";
+export * from "./publication-artifact.js";
+// The ONE route-tier authority: route -> mount -> publication space ->
+// {visibility, authorization} -> an ADR 0013 tier. No consumer derives its own.
+export * from "./route-tier.js";
 export * from "./checkout.js";
 export * from "./membership.js";
 export * from "./checkout-orders.js";
@@ -51,6 +57,7 @@ export * from "./review-trust-proof.js";
 export * from "./compliance/index.js";
 export * from "./tenant-assets.js";
 export * from "./static-bundle.js";
+export * from "./html-cache-policy.js";
 export * from "./binary-path.js";
 export * from "./hot-standby-readiness.js";
 export * from "./hash.js";

package/packages/public-runtime/src/integration/consent-broker.ts

@@ -140,6 +140,33 @@ export function defaultConsentSnapshot(): ConsentSnapshot {
   return makeSnapshot([ESSENTIAL]);
 }
 
+/**
+ * The MATERIALIZE-ONLY request header carrying a tenant's resolved consent snapshot
+ * (ADR 0013). The go-live dispatch resolves the tenant's REAL snapshot from D1 (the
+ * Worker holds that binding) and the bake pipeline sets this header on each render, so
+ * the static render inlines the real snapshot WITHOUT a consent D1 read on the
+ * public/materialize path. Never present on a real public request.
+ */
+export const CONSENT_SNAPSHOT_INPUT_HEADER = "x-tot-consent-snapshot";
+
+/**
+ * The HMAC-SHA256 signature (hex) over the {@link CONSENT_SNAPSHOT_INPUT_HEADER}
+ * value, carried alongside it. The go-live Worker (which holds both the tenant's real
+ * consent D1 and the signing secret) signs the snapshot; the materialize render
+ * VERIFIES it before honoring the input header. Absent/invalid ⇒ the snapshot input is
+ * rejected and consent falls back to the fail-closed default. Together with the
+ * materialize-mode binding gate this makes the input header un-forgeable: the deployed
+ * Worker never reads it at all, and even in materialize mode a snapshot without a valid
+ * signature from the go-live secret is refused.
+ */
+export const CONSENT_SNAPSHOT_SIG_HEADER = "x-tot-consent-snapshot-sig";
+
+/** The Worker secret binding whose value signs/verifies the baked consent snapshot. */
+export const CONSENT_SNAPSHOT_HMAC_SECRET_BINDING = "CONSENT_SNAPSHOT_HMAC_SECRET";
+
+/** The Worker binding that marks a MATERIALIZE-mode render — absent on the deployed Worker. */
+export const MATERIALIZE_MODE_BINDING = "TOT_MATERIALIZE_MODE";
+
 /**
  * Whether a purpose is currently eligible. `essential` is always eligible; an
  * unknown or unapproved-and-ungranted purpose is not — so this both permits
@@ -208,6 +235,94 @@ export function parseConsentSnapshot(raw: unknown): ConsentSnapshot | null {
   return canonical;
 }
 
+// ── Baked-snapshot signature (materialize bake wire) ────────────────────────────
+// The go-live Worker holds the tenant's real consent D1 AND the signing secret; it
+// signs the resolved snapshot, and the materialize render verifies before honoring the
+// input header. Web Crypto only (crypto.subtle) so it runs unchanged on workerd, and
+// verification is constant-time. The signature is TENANT-BOUND — it covers a
+// length-prefixed framing of `tenantId` and `serializedSnapshot`, so neither field's
+// content can shift a byte across the field boundary: a signed snapshot for one tenant
+// can never be replayed as another tenant's baked input, or as a different snapshot for
+// the same tenant.
+
+const consentSigTextEncoder = new TextEncoder();
+
+/**
+ * The exact string the consent snapshot signature covers: each field prefixed by its
+ * own UTF-8 byte length, so no value in either field can be interpreted as a field
+ * separator.
+ */
+function consentSignaturePayload(tenantId: string, serializedSnapshot: string): string {
+  const tenantBytes = consentSigTextEncoder.encode(tenantId).length;
+  const snapshotBytes = consentSigTextEncoder.encode(serializedSnapshot).length;
+  return `${tenantBytes}:${tenantId}${snapshotBytes}:${serializedSnapshot}`;
+}
+
+async function consentHmacKey(secret: string): Promise<CryptoKey> {
+  return crypto.subtle.importKey(
+    "raw",
+    consentSigTextEncoder.encode(secret) as unknown as BufferSource,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign", "verify"],
+  );
+}
+
+function consentSigHexToBytes(hex: string): Uint8Array | null {
+  if (hex.length === 0 || hex.length % 2 !== 0 || /[^0-9a-fA-F]/.test(hex)) return null;
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  return out;
+}
+
+/**
+ * Sign a tenant's serialized consent snapshot: hex HMAC-SHA256 over the length-prefixed
+ * {@link consentSignaturePayload}. The go-live Worker calls this; the materialize render
+ * verifies with the same secret via {@link verifyConsentSnapshotSig}.
+ */
+export async function signConsentSnapshot(
+  secret: string,
+  tenantId: string,
+  serializedSnapshot: string,
+): Promise<string> {
+  const key = await consentHmacKey(secret);
+  const sig = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    consentSigTextEncoder.encode(
+      consentSignaturePayload(tenantId, serializedSnapshot),
+    ) as unknown as BufferSource,
+  );
+  let hex = "";
+  for (const b of new Uint8Array(sig)) hex += b.toString(16).padStart(2, "0");
+  return hex;
+}
+
+/**
+ * Verify a consent snapshot signature (constant-time via `crypto.subtle.verify`). A
+ * malformed / short / absent signature returns false rather than throwing — fail-closed,
+ * so a caller can never smuggle in an unsigned or forged snapshot.
+ */
+export async function verifyConsentSnapshotSig(
+  secret: string,
+  tenantId: string,
+  serializedSnapshot: string,
+  signatureHex: string | null | undefined,
+): Promise<boolean> {
+  if (!signatureHex) return false;
+  const sig = consentSigHexToBytes(signatureHex.trim());
+  if (!sig) return false;
+  const key = await consentHmacKey(secret);
+  return crypto.subtle.verify(
+    "HMAC",
+    key,
+    sig as unknown as BufferSource,
+    consentSigTextEncoder.encode(
+      consentSignaturePayload(tenantId, serializedSnapshot),
+    ) as unknown as BufferSource,
+  );
+}
+
 /** Listener invoked with the new snapshot whenever eligibility changes. */
 export type ConsentListener = (snapshot: ConsentSnapshot) => void;
 

package/packages/public-runtime/src/integration/interim-bridge.ts

@@ -12,13 +12,15 @@
  * with it (the plan carries no vendor runtime, and `planRevision` moves), so a
  * rollback leaves no stale effect.
  *
- * It is deliberately narrow (ADR 0016/0023 Q6): the bridge is enabled ONLY on
- * eligible unregulated-marketing tenants. A regulated tenant is REFUSED with an
- * actionable explanation until a capability-specific certification exists — the
- * regulated shared-runtime floor is non-waivable, and this bridge never opens an
- * escape hatch around it. Promote-time enforcement still runs through the full
- * fail-closed gate (`verifyIntegrationPromotable`); this module is the render-time
- * tenant-eligibility decision that precedes it.
+ * It is deliberately narrow (ADR 0016/0023 Q6): on a regulated tenant the bridge
+ * enables only the declarations the surface × tier matrix permits on the regulated
+ * surface without a certification — reviewed platform-adapter/sandbox/server tiers —
+ * and REFUSES full parent authority (`elevated-parent`) until a capability-specific
+ * certification clears every clause. The regulated shared-runtime floor is
+ * non-waivable, and this bridge never opens an escape hatch around it. Promote-time
+ * enforcement still runs through the full fail-closed gate
+ * (`verifyIntegrationPromotable`); this module is the render-time tenant-eligibility
+ * decision that precedes it.
  */
 import type { BrowserEnvironment } from "./environment.js";
 import type { EffectivePlan } from "./plan.js";
@@ -34,6 +36,13 @@ import {
   isRegulatedParentCertified,
   type RegulatedParentCertification,
 } from "./regulated-parent-cert.js";
+import {
+  allowedTiersForCell,
+  resolveCellAuthority,
+  type CellAuthority,
+  type TenantTier,
+} from "../integration-capabilities.js";
+import type { ExecutionTier } from "./phases.js";
 
 /**
  * Whether an integration's declared consent dependency permits loading its entry
@@ -57,6 +66,11 @@ export interface InterimBridgeRefusal {
   surface: AssuranceSurface;
   /** An operator-facing explanation of the refusal and what unblocks it. */
   message: string;
+  /**
+   * The registered feedback item tracking this gap, so a consumer can route the reader
+   * to live work without parsing the message. See {@link REGULATED_REFUSAL_FEEDBACK_REF}.
+   */
+  feedbackRef: string;
 }
 
 /**
@@ -80,10 +94,11 @@ export interface InterimBridgeInput {
    * G2: the regulated elevated-parent certification artifact for a regulated tenant.
    * The bridge NEVER accepts a raw "certified" boolean — it runs
    * {@link decideRegulatedParentCert} itself (via {@link isRegulatedParentCertified}),
-   * so `certifiedImmutable` has a SINGLE ORIGIN: a regulated tenant is enabled ONLY
-   * when the cert clears every clause (pinned, undrifted from `servedDigest`, every
-   * server-derived obligation proven). Absent/failed ⇒ the decision fails closed and
-   * the tenant stays refused. This is the WS2 forward seam, not a per-tenant bypass.
+   * so `certifiedImmutable` has a SINGLE ORIGIN: a regulated tenant's full-parent
+   * authority (`elevated-parent`) declaration is enabled ONLY when the cert clears
+   * every clause (pinned, undrifted from `servedDigest`, every server-derived
+   * obligation proven). Absent/failed ⇒ the decision fails closed and that declaration
+   * stays refused. This is the WS2 forward seam, not a per-tenant bypass.
    */
   regulatedCertification?: RegulatedParentCertification | null;
   /**
@@ -101,31 +116,71 @@ export interface InterimBridgeInput {
  * set), so an eligible tenant's plan is exactly the kernel plan every mount serves —
  * the bridge adds only the tenant-eligibility gate, not a second plan shape.
  */
+/**
+ * Feedback tripwire for the regulated refusal below.
+ *
+ * A tripwire is three coupled parts: a registered feedback item describing an accepted
+ * gap, a reference to it from the message emitted where execution trips over that gap,
+ * and a workstream that owns closing it. Carrying the reference in the refusal itself is
+ * what routes a reader to live work instead of a fresh diagnosis.
+ *
+ * This gate refuses a regulated tenant whose declaration requests full parent
+ * authority (`elevated-parent`) without a {@link RegulatedParentCertification} that
+ * clears every clause — an absent or failed one fails closed. Owned by the
+ * `tot-regulated-integration-certification` workstream.
+ *
+ * See docs/playbooks/feedback-tripwire.md for the generalized recipe — this is the
+ * reference implementation, not a one-off.
+ */
+export const REGULATED_REFUSAL_FEEDBACK_REF = "fb-1788612281954-3q8f1n" as const;
+
 export function resolveInterimBridgePlan(input: InterimBridgeInput): InterimBridgeResult {
   const surface = resolveObligationSurface(input.tenant);
 
   // The certification is the SINGLE ORIGIN of `certifiedImmutable`: derive it from the
-  // decision (never a raw external flag), so a regulated tenant is enabled only when the
-  // cert actually clears every clause. Absent/failed ⇒ false ⇒ refused.
+  // decision (never a raw external flag), so a regulated tenant's full-parent authority
+  // declaration is enabled only when the cert actually clears every clause. Absent/failed
+  // ⇒ false ⇒ that declaration is refused.
   const regulatedCertified = isRegulatedParentCertified(input.regulatedCertification, {
     tenant: input.tenant,
     servedDigest: input.servedDigest,
   });
 
-  if (isRegulated(input.tenant) && !regulatedCertified) {
-    return {
-      ok: false,
-      reason: "regulated-refused",
-      refusal: {
-        code: "regulated-tenant-not-certified",
-        surface,
-        message:
-          `The interim marketing bridge is not enabled for regulated tenants (resolved surface ` +
-          `"${surface}"). A regulated parent tier requires an immutable, version-pinned, ` +
-          `capability-specific certification — a mere acknowledgement cannot waive the ` +
-          `non-waivable regulated shared-runtime floor. Complete WS2 certification to enable it.`,
-      },
-    };
+  // Drive the render-time refusal off the same surface × tier matrix the policy layer
+  // enforces (SURFACE_TENANT_TIER_MATRIX): a regulated tenant is refused only for a
+  // declaration the matrix does not permit on the regulated surface — full parent
+  // authority (`elevated-parent`) without a certification that clears every clause, never
+  // a reviewed platform-adapter/sandbox/server tier the cell already allows. A cert whose
+  // codeForm is `mutable-container`, or that has drifted/is incomplete, never clears the
+  // decision, so mutable parent code on a regulated surface stays refused.
+  // `verifyIntegrationPromotable` remains the authoritative fail-closed backstop at
+  // promote time; this only stops the bridge PRE-refusing a class the policy permits.
+  if (isRegulated(input.tenant)) {
+    const cell = resolveCellAuthority(regulatedTenantTier(input.tenant), "regulated");
+    const refused =
+      !cell ||
+      input.declarations.some((decl) =>
+        isRegulatedDeclarationRefused(decl.manifest.browser.executionTier, cell, regulatedCertified),
+      );
+    if (refused) {
+      return {
+        ok: false,
+        reason: "regulated-refused",
+        refusal: {
+          code: "regulated-tenant-not-certified",
+          surface,
+          message:
+            `This integration needs full-page access to run on your storefront. Because your ` +
+            `store is regulated, that level of access is only available once a compliance ` +
+            `certification confirms it can't reach age-verification or customer data — a ` +
+            `safeguard, not a limitation of your store. Standard analytics and platform ` +
+            `integrations, including Google Analytics 4 (GA4), work normally on a regulated ` +
+            `storefront and can be added today. To proceed, choose a standard, already-supported ` +
+            `integration, or contact support to pursue certification for this one.`,
+          feedbackRef: REGULATED_REFUSAL_FEEDBACK_REF,
+        },
+      };
+    }
   }
 
   const result = resolveEffectivePlan({
@@ -136,3 +191,32 @@ export function resolveInterimBridgePlan(input: InterimBridgeInput): InterimBrid
   if (!result.ok) return { ok: false, reason: "invalid-plan", violations: result.violations };
   return { ok: true, plan: result.value };
 }
+
+/**
+ * The regulated tenant tier for the matrix lookup. Both regulated tiers carry the
+ * identical `regulated` cell (`maxTier: "server"`, `elevatedParent: "cert-required"`),
+ * so the split only tracks the tenant's site type; an unset site type resolves to
+ * `regulated-commerce`, mirroring {@link resolveObligationSurface}'s commerce floor.
+ */
+function regulatedTenantTier(tenant: ObligationTenant): TenantTier {
+  return tenant.siteType === "marketing" ? "regulated-marketing" : "regulated-commerce";
+}
+
+/**
+ * Whether one declaration is refused on the regulated surface, per the cell's authority.
+ * Full parent authority (`elevated-parent`) is gated by the cell's elevated-parent
+ * disposition — `cert-required` enables it only behind a certification that clears every
+ * clause, and any other disposition (`prohibited`/`acknowledge`) never enables it here
+ * (fail closed). Every other tier is permitted when it is within the cell's allowed
+ * non-elevated tiers (`platform-adapter` ≤ `sandbox` ≤ `server`).
+ */
+function isRegulatedDeclarationRefused(
+  tier: ExecutionTier,
+  cell: CellAuthority,
+  regulatedCertified: boolean,
+): boolean {
+  if (tier === "elevated-parent") {
+    return cell.elevatedParent === "cert-required" ? !regulatedCertified : true;
+  }
+  return !allowedTiersForCell(cell).includes(tier);
+}