@tokenoftrust/storefront-runner 2.0.17 → 2.0.19

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

@@ -0,0 +1,195 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tokenoftrust.com/schemas/publication-space/v1/manifest.schema.json",
+  "title": "PublicationSpaceManifestV1",
+  "$comment": "This schema provides portable structural and lexical validation, including literal reserved mounts. validatePublicationSpaceManifestV1 enforces the same policy after path normalization.",
+  "type": "object",
+  "patternProperties": { "^\\$(?:schema|comment|id)$": {} },
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "id",
+    "tenant",
+    "source",
+    "routes",
+    "visibility",
+    "authorization",
+    "discovery",
+    "assets",
+    "renderer"
+  ],
+  "properties": {
+    "version": { "const": 1 },
+    "id": { "$ref": "#/$defs/identifier" },
+    "tenant": { "$ref": "#/$defs/identifier" },
+    "source": {
+      "type": "object",
+      "patternProperties": { "^\\$(?:schema|comment|id)$": {} },
+      "additionalProperties": false,
+      "required": ["forge", "repo", "defaultBranch"],
+      "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])?$"
+        },
+        "defaultBranch": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "pattern": "^(?![-/.])(?!HEAD$)(?!.*(?:/\\.|\\.\\.|@\\{|\\\\|\\s|~|\\^|:|\\?|\\*|\\[|//))(?!.*(?:^|/)[^/]*\\.lock(?:/|$))(?!.*[/.]$)[A-Za-z0-9._/-]+$"
+        }
+      }
+    },
+    "routes": {
+      "type": "object",
+      "patternProperties": { "^\\$(?:schema|comment|id)$": {} },
+      "additionalProperties": false,
+      "required": ["canonicalMount"],
+      "properties": {
+        "canonicalMount": { "$ref": "#/$defs/mountPath" },
+        "aliases": {
+          "type": "array",
+          "items": {
+            "oneOf": [
+              {
+                "type": "object",
+                "patternProperties": { "^\\$(?:schema|comment|id)$": {} },
+                "additionalProperties": false,
+                "required": ["from", "behavior"],
+                "properties": {
+                  "from": { "$ref": "#/$defs/aliasPath" },
+                  "behavior": { "const": "render" }
+                }
+              },
+              {
+                "type": "object",
+                "patternProperties": { "^\\$(?:schema|comment|id)$": {} },
+                "additionalProperties": false,
+                "required": ["from", "behavior", "to"],
+                "properties": {
+                  "from": { "$ref": "#/$defs/aliasPath" },
+                  "behavior": { "const": "redirect-308" },
+                  "to": { "$ref": "#/$defs/path" }
+                }
+              }
+            ]
+          }
+        }
+      }
+    },
+    "visibility": { "enum": ["public", "internal"] },
+    "authorization": {
+      "oneOf": [
+        {
+          "type": "object",
+          "patternProperties": { "^\\$(?:schema|comment|id)$": {} },
+          "additionalProperties": false,
+          "required": ["policy"],
+          "properties": { "policy": { "const": "public" } }
+        },
+        {
+          "type": "object",
+          "patternProperties": { "^\\$(?:schema|comment|id)$": {} },
+          "additionalProperties": false,
+          "required": ["policy", "capability"],
+          "properties": {
+            "policy": { "const": "capability" },
+            "capability": { "const": "internal-content-reader" }
+          }
+        }
+      ]
+    },
+    "discovery": {
+      "type": "object",
+      "patternProperties": { "^\\$(?:schema|comment|id)$": {} },
+      "additionalProperties": false,
+      "required": ["sitemap", "feeds", "publicSearch", "llms"],
+      "properties": {
+        "sitemap": { "type": "boolean" },
+        "feeds": { "type": "boolean" },
+        "publicSearch": { "type": "boolean" },
+        "llms": { "type": "boolean" }
+      }
+    },
+    "assets": {
+      "type": "object",
+      "patternProperties": { "^\\$(?:schema|comment|id)$": {} },
+      "additionalProperties": false,
+      "required": ["namespace", "access"],
+      "properties": {
+        "namespace": { "$ref": "#/$defs/identifier" },
+        "access": { "enum": ["public", "authorized"] }
+      }
+    },
+    "renderer": {
+      "type": "object",
+      "patternProperties": { "^\\$(?:schema|comment|id)$": {} },
+      "additionalProperties": false,
+      "required": ["contractVersion", "themeContractVersion"],
+      "properties": {
+        "contractVersion": { "type": "string", "minLength": 1 },
+        "themeContractVersion": { "type": "string", "minLength": 1 }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": { "type": "object", "properties": { "visibility": { "const": "public" } } },
+      "then": {
+        "type": "object",
+        "properties": {
+          "authorization": { "type": "object", "properties": { "policy": { "const": "public" } } },
+          "assets": { "type": "object", "properties": { "access": { "const": "public" } } }
+        }
+      }
+    },
+    {
+      "if": { "type": "object", "properties": { "visibility": { "const": "internal" } } },
+      "then": {
+        "type": "object",
+        "properties": {
+          "authorization": { "type": "object", "properties": { "policy": { "const": "capability" } } },
+          "assets": { "type": "object", "properties": { "access": { "const": "authorized" } } },
+          "discovery": {
+            "type": "object",
+            "properties": {
+              "sitemap": { "const": false },
+              "feeds": { "const": false },
+              "publicSearch": { "const": false },
+              "llms": { "const": false }
+            }
+          }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "identifier": {
+      "type": "string",
+      "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$"
+    },
+    "path": {
+      "type": "string",
+      "not": {
+        "type": "string",
+        "pattern": "^/(?:(?:%25(?:2|%32)(?:[Ee]|%45|%65))){1,2}(?:/|$)"
+      },
+      "pattern": "^/(?!(?:(?:\\.|%2[eE])){1,2}(?:/|$))(?!.*/(?:(?:\\.|%2[eE])){1,2}(?:/|$))(?!.*%(?:2[fF]|5[cC]))(?!.*%25(?:(?:0|%30|1|%31)(?:[0-9A-Fa-f]|%3[0-9]|%4[1-6]|%6[1-6])|(?:2|%32)(?:[Ff]|%46|%66)|(?:5|%35)(?:[Cc]|%43|%63)|(?:7|%37)(?:[Ff]|%46|%66)))(?!.*\/(?:(?:%25(?:2|%32)(?:[Ee]|%45|%65))){1,2}(?:/|$))(?!.*[?#\\\\\\u0000-\\u001F\\u007F\\uD800-\\uDFFF])(?:[^%?#\\\\\\u0000-\\u001F\\u007F\\uD800-\\uDFFF]|%(?:2[0-9A-Ea-e]|[34][0-9A-Fa-f]|5[0-9A-Ba-bD-Fd-f]|6[0-9A-Fa-f]|7[0-9A-Ea-e])|%(?:[Cc][2-9A-Fa-f]|[Dd][0-9A-Fa-f])%(?:[89AaBb][0-9A-Fa-f])|%[Ee]0%(?:[AaBb][0-9A-Fa-f])%(?:[89AaBb][0-9A-Fa-f])|%[Ee][1-9A-Ca-cEFef]%(?:[89AaBb][0-9A-Fa-f])%(?:[89AaBb][0-9A-Fa-f])|%[Ee][Dd]%(?:[89][0-9A-Fa-f])%(?:[89AaBb][0-9A-Fa-f])|%[Ff]0%(?:[9AaBb][0-9A-Fa-f])%(?:[89AaBb][0-9A-Fa-f])%(?:[89AaBb][0-9A-Fa-f])|%[Ff][1-3]%(?:[89AaBb][0-9A-Fa-f])%(?:[89AaBb][0-9A-Fa-f])%(?:[89AaBb][0-9A-Fa-f])|%[Ff]4%8[0-9A-Fa-f]%(?:[89AaBb][0-9A-Fa-f])%(?:[89AaBb][0-9A-Fa-f]))*$"
+    },
+    "mountPath": {
+      "allOf": [
+        { "$ref": "#/$defs/path" },
+        { "type": "string", "pattern": "^/(?!(?:\\.well-known|__evidence|__preview|_astro|_style-guide|admin|api|apps|assets|auth|brand|capabilities|cockpit|collections|dashboard|dev|favicon\\.svg|health|js|llms\\.txt|platform|preview|products|robots\\.txt|saved|search|shared|sitemap\\.xml|style-guide|tenants)(?:/|$))" }
+      ]
+    },
+    "aliasPath": {
+      "allOf": [
+        { "$ref": "#/$defs/mountPath" },
+        { "type": "string", "pattern": "^/.+" }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tokenoftrust.com/schemas/publication-space/v1/normalized-mount.schema.json",
+  "title": "NormalizedPublicationMountEntryV1",
+  "$comment": "This schema provides portable structural and lexical validation. Cross-property equality/inequality and Unicode NFC are enforced by validateNormalizedPublicationMountEntryV1 because JSON Schema 2020-12 cannot compare property values or normalize Unicode.",
+  "type": "object",
+  "patternProperties": { "^\\$(?:schema|comment|id)$": {} },
+  "additionalProperties": false,
+  "required": ["version", "tenant", "spaceId", "kind", "mount", "canonicalMount", "behavior"],
+  "properties": {
+    "version": { "const": 1 },
+    "tenant": { "$ref": "#/$defs/identifier" },
+    "spaceId": { "$ref": "#/$defs/identifier" },
+    "kind": { "enum": ["canonical", "alias"] },
+    "mount": { "$ref": "#/$defs/mountPath" },
+    "canonicalMount": { "$ref": "#/$defs/mountPath" },
+    "behavior": { "enum": ["render", "redirect-308"] },
+    "redirectTo": { "$ref": "#/$defs/normalizedPath" }
+  },
+  "allOf": [
+    {
+      "if": { "type": "object", "properties": { "kind": { "const": "canonical" } } },
+      "then": {
+        "type": "object",
+        "properties": { "behavior": { "const": "render" } },
+        "not": {
+          "type": "object",
+          "properties": { "redirectTo": {} },
+          "required": ["redirectTo"]
+        }
+      }
+    },
+    {
+      "if": { "type": "object", "properties": { "kind": { "const": "alias" } } },
+      "then": { "type": "object", "properties": { "mount": { "$ref": "#/$defs/aliasPath" } } }
+    },
+    {
+      "if": { "type": "object", "properties": { "behavior": { "const": "render" } } },
+      "then": {
+        "type": "object",
+        "not": {
+          "type": "object",
+          "properties": { "redirectTo": {} },
+          "required": ["redirectTo"]
+        }
+      }
+    },
+    {
+      "if": { "type": "object", "properties": { "behavior": { "const": "redirect-308" } } },
+      "then": {
+        "type": "object",
+        "properties": { "kind": { "const": "alias" } },
+        "required": ["redirectTo"]
+      }
+    }
+  ],
+  "$defs": {
+    "identifier": {
+      "type": "string",
+      "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$"
+    },
+    "normalizedPath": {
+      "type": "string",
+      "not": { "type": "string", "pattern": "^/(?:%252[Ee]){1,2}(?:/|$)" },
+      "pattern": "^/(?!(?:\\.{1,2})(?:/|$))(?!.*/\\.{1,2}(?:/|$))(?!.*%25(?:0[0-9A-Fa-f]|1[0-9A-Fa-f]|2[Ff]|5[Cc]|7[Ff]))(?!.*\/(?:%252[Ee]){1,2}(?:/|$))(?:(?:[A-Za-z0-9._!~*'()-]|%(?:20|2[2-6BC]|3[A-F]|40|5[BDE]|60|7[B-D])|%(?:C[2-9A-F]|D[0-9A-F])%(?:[89AB][0-9A-F])|%E0%(?:[AB][0-9A-F])%(?:[89AB][0-9A-F])|%E[1-9A-CEF]%(?:[89AB][0-9A-F])%(?:[89AB][0-9A-F])|%ED%(?:[89][0-9A-F])%(?:[89AB][0-9A-F])|%F0%(?:[9AB][0-9A-F])%(?:[89AB][0-9A-F])%(?:[89AB][0-9A-F])|%F[1-3]%(?:[89AB][0-9A-F])%(?:[89AB][0-9A-F])%(?:[89AB][0-9A-F])|%F4%8[0-9A-F]%(?:[89AB][0-9A-F])%(?:[89AB][0-9A-F]))+(?:/(?:[A-Za-z0-9._!~*'()-]|%(?:20|2[2-6BC]|3[A-F]|40|5[BDE]|60|7[B-D])|%(?:C[2-9A-F]|D[0-9A-F])%(?:[89AB][0-9A-F])|%E0%(?:[AB][0-9A-F])%(?:[89AB][0-9A-F])|%E[1-9A-CEF]%(?:[89AB][0-9A-F])%(?:[89AB][0-9A-F])|%ED%(?:[89][0-9A-F])%(?:[89AB][0-9A-F])|%F0%(?:[9AB][0-9A-F])%(?:[89AB][0-9A-F])%(?:[89AB][0-9A-F])|%F[1-3]%(?:[89AB][0-9A-F])%(?:[89AB][0-9A-F])%(?:[89AB][0-9A-F])|%F4%8[0-9A-F]%(?:[89AB][0-9A-F])%(?:[89AB][0-9A-F]))+)*)?$"
+    },
+    "mountPath": {
+      "allOf": [
+        { "$ref": "#/$defs/normalizedPath" },
+        { "type": "string", "pattern": "^/(?!(?:\\.well-known|__evidence|__preview|_astro|_style-guide|admin|api|apps|assets|auth|brand|capabilities|cockpit|collections|dashboard|dev|favicon\\.svg|health|js|llms\\.txt|platform|preview|products|robots\\.txt|saved|search|shared|sitemap\\.xml|style-guide|tenants)(?:/|$))" }
+      ]
+    },
+    "aliasPath": {
+      "allOf": [
+        { "$ref": "#/$defs/mountPath" },
+        { "type": "string", "pattern": "^/.+" }
+      ]
+    }
+  }
+}

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,14 @@
 // 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-routing.js";
+export * from "./publication-version.js";
+export * from "./publication-artifact.js";
+export * from "./publication-reader.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 +59,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";