fix: require genuine live hosting evidence

config/compatibility/fixtures.json

@@ -0,0 +1,63 @@
+{
+  "schemaVersion": 1,
+  "families": {
+    "api": {
+      "additive": {
+        "before": { "required": ["id"], "properties": { "id": {} } },
+        "after": {
+          "required": ["id"],
+          "properties": { "id": {}, "displayName": {} }
+        }
+      },
+      "breaking": {
+        "before": { "required": ["id"], "properties": { "id": {} } },
+        "after": {
+          "required": ["id", "name"],
+          "properties": { "id": {}, "name": {} }
+        }
+      }
+    },
+    "config": {
+      "additive": {
+        "before": { "required": ["APP_ENV"], "properties": { "APP_ENV": {} } },
+        "after": {
+          "required": ["APP_ENV"],
+          "properties": { "APP_ENV": {}, "OPTIONAL_FLAG": {} }
+        }
+      },
+      "breaking": {
+        "before": { "required": ["APP_ENV"], "properties": { "APP_ENV": {} } },
+        "after": {
+          "required": ["APP_ENV", "NEW_REQUIRED"],
+          "properties": { "APP_ENV": {}, "NEW_REQUIRED": {} }
+        }
+      }
+    },
+    "storage": {
+      "additive": {
+        "before": { "properties": { "theme": {} } },
+        "after": { "properties": { "theme": {}, "contrast": {} } }
+      },
+      "breaking": {
+        "before": { "properties": { "theme": {} } },
+        "after": { "properties": {} }
+      }
+    },
+    "release": {
+      "additive": {
+        "before": { "required": ["buildId"], "properties": { "buildId": {} } },
+        "after": {
+          "required": ["buildId"],
+          "properties": { "buildId": {}, "builtAt": {} }
+        }
+      },
+      "breaking": {
+        "before": { "required": ["buildId"], "properties": { "buildId": {} } },
+        "after": {
+          "required": ["buildId", "assetManifestHash"],
+          "properties": { "buildId": {}, "assetManifestHash": {} }
+        }
+      }
+    }
+  }
+}

config/contracts/registry-governance.json

@@ -0,0 +1,116 @@
+{
+  "schemaVersion": 1,
+  "registries": [
+    {
+      "registryId": "FE-REG-ROUTE",
+      "path": "src/contracts/routes.js",
+      "exportName": "ROUTE_REGISTRY",
+      "owner": "feature-routing-navigation-guard-contract",
+      "requiredFields": [
+        "routeId",
+        "path",
+        "paramsSchema",
+        "searchSchema",
+        "access",
+        "loadingSurface",
+        "errorSurface",
+        "chunkId"
+      ]
+    },
+    {
+      "registryId": "FE-REG-API",
+      "path": "src/contracts/api-operations.js",
+      "exportName": "API_OPERATIONS",
+      "owner": "feature-api-client-response-envelope-contract",
+      "requiredFields": [
+        "method",
+        "path",
+        "operationId",
+        "auth",
+        "timeoutMs",
+        "idempotency",
+        "requestSchema",
+        "responseSchema",
+        "owner"
+      ]
+    },
+    {
+      "registryId": "FE-REG-ENV",
+      "path": "src/contracts/env.js",
+      "exportName": "ENV_REGISTRY",
+      "owner": "feature-frontend-env-runtime-config-contract",
+      "requiredFields": ["phase", "classification", "required", "defaultValue"]
+    },
+    {
+      "registryId": "FE-REG-STORAGE",
+      "path": "src/contracts/storage-keys.js",
+      "exportName": "STORAGE_REGISTRY",
+      "owner": "feature-frontend-storage-registry-contract",
+      "requiredFields": [
+        "logicalName",
+        "physicalKey",
+        "backend",
+        "classification",
+        "schemaVersion",
+        "ttl",
+        "migration",
+        "quotaFallback"
+      ]
+    },
+    {
+      "registryId": "FE-REG-ERROR",
+      "path": "src/contracts/errors.js",
+      "exportName": "ERROR_REGISTRY",
+      "owner": "feature-frontend-error-classification-boundary-contract",
+      "requiredFields": [
+        "kind",
+        "defaultRetryable",
+        "severity",
+        "userMessageKey",
+        "action",
+        "telemetryEvent",
+        "redaction"
+      ]
+    },
+    {
+      "registryId": "FE-REG-QUERY",
+      "path": "src/contracts/query-keys.js",
+      "exportName": "QUERY_REGISTRY",
+      "owner": "feature-server-state-caching-contract",
+      "requiredFields": [
+        "namespace",
+        "serialization",
+        "identity",
+        "invalidation",
+        "version",
+        "persistence"
+      ]
+    },
+    {
+      "registryId": "FE-REG-TELEMETRY",
+      "path": "src/contracts/telemetry.js",
+      "exportName": "TELEMETRY_REGISTRY",
+      "owner": "feature-frontend-observability-logging-trace-contract",
+      "requiredFields": [
+        "eventName",
+        "trigger",
+        "requiredAttributes",
+        "optionalAttributes",
+        "forbiddenAttributes",
+        "sampling",
+        "delivery"
+      ]
+    },
+    {
+      "registryId": "FE-REG-RELEASE",
+      "path": "src/contracts/release-tokens.js",
+      "exportName": "RELEASE_TOKEN_REGISTRY",
+      "owner": "feature-frontend-release-cache-rollback-contract",
+      "requiredFields": ["token", "source", "compatibilityRole"]
+    }
+  ],
+  "compatibilityImpact": {
+    "allowed": ["none", "additive", "behavior-change", "breaking"],
+    "current": "additive"
+  }
+}

config/hosting/cache-policy.json

@@ -0,0 +1,35 @@
+{
+  "schemaVersion": 1,
+  "surfaces": {
+    "index": {
+      "path": "/",
+      "cacheControl": "no-cache",
+      "contentTypes": ["text/html"],
+      "securityHeaders": true
+    },
+    "runtimeConfig": {
+      "path": "/config.json",
+      "cacheControl": "no-store",
+      "contentTypes": ["application/json"],
+      "securityHeaders": true
+    },
+    "releaseManifest": {
+      "path": "/release-manifest.json",
+      "cacheControl": "no-store",
+      "contentTypes": ["application/json"],
+      "securityHeaders": true
+    },
+    "hashedAsset": {
+      "pathPattern": "/assets/*",
+      "cacheControl": "public, max-age=31536000, immutable",
+      "contentTypes": ["text/javascript", "application/javascript"],
+      "securityHeaders": false
+    },
+    "sourceMap": {
+      "public": false
+    },
+    "serviceWorker": {
+      "enabled": false
+    }
+  }
+}

config/hosting/response-headers.fixture.json

@@ -0,0 +1,39 @@
+{
+  "schemaVersion": 1,
+  "responses": {
+    "index": {
+      "cache-control": "no-cache",
+      "content-type": "text/html; charset=utf-8",
+      "content-security-policy": "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; form-action 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self' https:; font-src 'self'; upgrade-insecure-requests",
+      "strict-transport-security": "max-age=31536000; includeSubDomains",
+      "x-frame-options": "DENY",
+      "referrer-policy": "strict-origin-when-cross-origin",
+      "x-content-type-options": "nosniff",
+      "permissions-policy": "camera=(), microphone=(), geolocation=()"
+    },
+    "runtimeConfig": {
+      "cache-control": "no-store",
+      "content-type": "application/json; charset=utf-8",
+      "content-security-policy": "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; form-action 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self' https:; font-src 'self'; upgrade-insecure-requests",
+      "strict-transport-security": "max-age=31536000; includeSubDomains",
+      "x-frame-options": "DENY",
+      "referrer-policy": "strict-origin-when-cross-origin",
+      "x-content-type-options": "nosniff",
+      "permissions-policy": "camera=(), microphone=(), geolocation=()"
+    },
+    "releaseManifest": {
+      "cache-control": "no-store",
+      "content-type": "application/json; charset=utf-8",
+      "content-security-policy": "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; form-action 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self' https:; font-src 'self'; upgrade-insecure-requests",
+      "strict-transport-security": "max-age=31536000; includeSubDomains",
+      "x-frame-options": "DENY",
+      "referrer-policy": "strict-origin-when-cross-origin",
+      "x-content-type-options": "nosniff",
+      "permissions-policy": "camera=(), microphone=(), geolocation=()"
+    },
+    "hashedAsset": {
+      "cache-control": "public, max-age=31536000, immutable",
+      "content-type": "text/javascript; charset=utf-8"
+    }
+  }
+}

config/release/coherence-fixtures.json

@@ -0,0 +1,77 @@
+{
+  "schemaVersion": 1,
+  "fixtures": [
+    {
+      "name": "coherent-release",
+      "expectedCompatible": true,
+      "frontend": {
+        "buildId": "build-a",
+        "configSchemaVersion": "1.0",
+        "apiContractVersion": "1.0",
+        "assetManifestHash": "assets-a",
+        "releaseId": "release-a"
+      },
+      "runtime": {
+        "buildId": "build-a",
+        "configSchemaVersion": "1.1",
+        "apiContractVersion": "1.2",
+        "assetManifestHash": "assets-a",
+        "releaseId": "release-a"
+      }
+    },
+    {
+      "name": "mixed-html-and-assets",
+      "expectedCompatible": false,
+      "frontend": {
+        "buildId": "build-a",
+        "configSchemaVersion": "1.0",
+        "apiContractVersion": "1.0",
+        "assetManifestHash": "assets-a",
+        "releaseId": "release-a"
+      },
+      "runtime": {
+        "buildId": "build-b",
+        "configSchemaVersion": "1.0",
+        "apiContractVersion": "1.0",
+        "assetManifestHash": "assets-b",
+        "releaseId": "release-b"
+      }
+    },
+    {
+      "name": "incompatible-runtime-config",
+      "expectedCompatible": false,
+      "frontend": {
+        "buildId": "build-a",
+        "configSchemaVersion": "1.0",
+        "apiContractVersion": "1.0",
+        "assetManifestHash": "assets-a",
+        "releaseId": "release-a"
+      },
+      "runtime": {
+        "buildId": "build-a",
+        "configSchemaVersion": "2.0",
+        "apiContractVersion": "1.0",
+        "assetManifestHash": "assets-a",
+        "releaseId": "release-a"
+      }
+    },
+    {
+      "name": "incompatible-api-contract",
+      "expectedCompatible": false,
+      "frontend": {
+        "buildId": "build-a",
+        "configSchemaVersion": "1.0",
+        "apiContractVersion": "1.0",
+        "assetManifestHash": "assets-a",
+        "releaseId": "release-a"
+      },
+      "runtime": {
+        "buildId": "build-a",
+        "configSchemaVersion": "1.0",
+        "apiContractVersion": "2.0",
+        "assetManifestHash": "assets-a",
+        "releaseId": "release-a"
+      }
+    }
+  ]
+}

config/schemas/release-verification.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "ART-FE-003@1",
+  "type": "object",
+  "required": ["schemaVersion", "generatedAt", "artifact", "fixtures", "passed"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "artifact": {
+      "type": "object",
+      "required": ["checked", "compatible", "mismatches"]
+    },
+    "fixtures": { "type": "array", "minItems": 2 },
+    "passed": { "type": "boolean" }
+  },
+  "additionalProperties": false
+}

docs/contracts/compatibility.md

@@ -0,0 +1,11 @@
+# Contract compatibility and rollback rules
+
+The blocking tuple is `(buildId, configSchemaVersion, apiContractVersion,
+assetManifestHash, releaseId)`. Versions are parsed numerically.
+
+1. additive changes preserve current required fields
+2. breaking changes require a major version bump
+3. persisted cache is discarded unless an explicit tested migration exists
+4. an incompatible config or API contract blocks product mount
+5. rollback restores HTML, assets, runtime config, API compatibility, and
+   release manifest as one coherent set

docs/operations/release-cache-rollback.md

@@ -0,0 +1,32 @@
+# Release, cache, and rollback contract
+
+Each deployment is an immutable `releases/<releaseId>/` artifact set. The
+provider adapter must upload assets, release manifest, runtime config, and
+verify asset reachability before atomically switching the active HTML pointer.
+The post-switch boot, route, API, telemetry, and reload-loop smoke checks close
+the deployment.
+
+Rollback selects a prior release tuple, confirms its assets and runtime/API
+compatibility, atomically switches the complete set, performs the provider
+cache action, and repeats the smoke checks. Rebuilding an old commit, replacing
+HTML alone, or declaring recovery from cache-purge completion is prohibited.
+Recovery is established by old/new reachability probes.
+
+The provider-independent cache defaults are:
+
+- hashed assets: `public, max-age=31536000, immutable`
+- HTML: `no-cache`
+- runtime config and release manifest: `no-store`
+- public source maps: disabled
+- service worker/offline cache: disabled
+
+HTML, JSON config/manifest, and hashed JavaScript MIME types are also compared
+to the declared allowlist; a cache-correct response with a mismatched
+`Content-Type` still fails the hosting gate.
+
+`corepack pnpm verify:hosting-headers` uses a deterministic fixture locally.
+Set `HOSTING_BASE_URL` to probe deployed responses; production promotion
+requires the artifact to report `mode: "live"`. The live target must be its
+canonical, non-loopback HTTPS root URL. Each required surface must return HTTP
+200 without leaving that origin before its cache, content-type, and security
+headers can count as deployment evidence.

package.json

@@ -29,7 +29,11 @@
     "verify:lockfile": "corepack pnpm install --frozen-lockfile",
     "generate:supply-chain": "node scripts/generate-supply-chain.mjs",
     "scan:security": "node scripts/security-scan.mjs",
-    "check:browser-security": "node scripts/check-browser-security.mjs"
+    "check:browser-security": "node scripts/check-browser-security.mjs",
+    "check:registries": "node scripts/check-registries.mjs",
+    "verify:compatibility": "node scripts/check-compatibility.mjs",
+    "verify:release": "node scripts/verify-release.mjs",
+    "verify:hosting-headers": "node scripts/verify-hosting-headers.mjs"
   },
   "dependencies": {
     "@tanstack/react-query": "5.101.4",

public/release-manifest.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "appVersion": "0.1.0",
+  "buildId": "local-build",
+  "commitSha": "local",
+  "configSchemaVersion": "1",
+  "apiContractVersion": "1",
+  "assetManifestHash": "generated-during-build",
+  "releaseId": "local-release",
+  "builtAt": "1970-01-01T00:00:00.000Z"
+}

schemas/artifacts/registry-snapshot.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "generatedAt",
+    "compatibilityImpact",
+    "failures",
+    "registries"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "compatibilityImpact": {
+      "enum": ["none", "additive", "behavior-change", "breaking"]
+    },
+    "failures": { "type": "array", "maxItems": 0 },
+    "registries": {
+      "type": "array",
+      "minItems": 8,
+      "maxItems": 8,
+      "items": {
+        "type": "object",
+        "required": ["registryId", "owner", "source", "rowCount", "rows"]
+      }
+    }
+  },
+  "additionalProperties": false
+}

scripts/check-compatibility.mjs

@@ -0,0 +1,43 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+
+import { classifyObjectSchemaChange } from "../src/application/policies/compatibility.js";
+
+const fixtures = JSON.parse(
+  await readFile("config/compatibility/fixtures.json", "utf8"),
+);
+const results = [];
+
+for (const [family, cases] of Object.entries(fixtures.families)) {
+  for (const expected of ["additive", "breaking"]) {
+    const fixture = cases[expected];
+    const actual = classifyObjectSchemaChange(fixture.before, fixture.after);
+    results.push({ family, expected, actual, passed: actual === expected });
+  }
+}
+
+await mkdir("artifacts/release", { recursive: true });
+await writeFile(
+  "artifacts/release/compatibility.json",
+  `${JSON.stringify(
+    {
+      schemaVersion: 1,
+      generatedAt: new Date().toISOString(),
+      rules: [
+        "additive changes preserve required fields",
+        "breaking changes require version bump and migration, discard, fallback, or rollback",
+        "config and API major versions must match",
+        "incompatible persisted cache is discarded by default",
+        "rollback uses a coherent compatibility tuple",
+      ],
+      results,
+    },
+    null,
+    2,
+  )}\n`,
+);
+
+if (results.some((result) => !result.passed)) {
+  process.stderr.write("Compatibility fixture classification failed.\n");
+  process.exit(1);
+}
+process.stdout.write("Compatibility fixtures: PASS\n");

scripts/check-registries.mjs

@@ -0,0 +1,112 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const governance = JSON.parse(
+  await readFile("config/contracts/registry-governance.json", "utf8"),
+);
+const failures = [];
+const owners = new Map();
+const snapshots = [];
+
+for (const specification of governance.registries) {
+  if (owners.has(specification.registryId)) {
+    failures.push(`duplicate owner for ${specification.registryId}`);
+  }
+  owners.set(specification.registryId, specification.owner);
+
+  let rows = specification.declaredRows;
+  try {
+    await access(specification.path);
+    const module = await import(
+      `${pathToFileURL(path.resolve(specification.path)).href}?registry-check=${Date.now()}`
+    );
+    rows = module[specification.exportName];
+  } catch {
+    if (!rows) failures.push(`missing registry source ${specification.path}`);
+  }
+
+  if (!rows || typeof rows !== "object" || Array.isArray(rows)) {
+    failures.push(`${specification.registryId} is not an object registry`);
+    continue;
+  }
+
+  for (const [rowName, row] of Object.entries(rows)) {
+    if (!row || typeof row !== "object" || Array.isArray(row)) {
+      failures.push(`${specification.registryId}.${rowName} is not an object`);
+      continue;
+    }
+    for (const field of specification.requiredFields) {
+      if (!(field in row)) {
+        failures.push(`${specification.registryId}.${rowName} missing ${field}`);
+      }
+    }
+  }
+
+  snapshots.push({
+    registryId: specification.registryId,
+    owner: specification.owner,
+    source: specification.path,
+    rowCount: Object.keys(rows).length,
+    rows,
+  });
+}
+
+const sourceFiles = [
+  "src/application",
+  "src/presentation",
+  "src/domain",
+];
+const adHocPatterns = [
+  { name: "direct fetch", expression: /\bfetch\s*\(/ },
+  { name: "direct localStorage", expression: /\blocalStorage\.(?:get|set|remove)Item/ },
+  { name: "direct import.meta.env", expression: /\bimport\.meta\.env\./ },
+  { name: "raw API path", expression: /["']\/api\// },
+];
+
+/** @param {string} directory */
+async function scanDirectory(directory) {
+  const entries = await import("node:fs/promises").then(({ readdir }) =>
+    readdir(directory, { withFileTypes: true }),
+  );
+  for (const entry of entries) {
+    const target = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      await scanDirectory(target);
+      continue;
+    }
+    if (!/\.(js|jsx|mjs)$/.test(entry.name)) continue;
+    const content = await readFile(target, "utf8");
+    for (const pattern of adHocPatterns) {
+      if (pattern.expression.test(content)) {
+        failures.push(`ad-hoc ${pattern.name} in ${target}`);
+      }
+    }
+  }
+}
+
+for (const sourceDirectory of sourceFiles) {
+  await scanDirectory(sourceDirectory);
+}
+
+await mkdir("artifacts/quality", { recursive: true });
+await writeFile(
+  "artifacts/quality/registries.json",
+  `${JSON.stringify(
+    {
+      schemaVersion: 1,
+      generatedAt: new Date().toISOString(),
+      compatibilityImpact: governance.compatibilityImpact.current,
+      failures,
+      registries: snapshots,
+    },
+    null,
+    2,
+  )}\n`,
+);
+
+if (failures.length > 0) {
+  process.stderr.write(`Registry governance failed:\n${failures.join("\n")}\n`);
+  process.exit(1);
+}
+process.stdout.write(`Registry governance: ${snapshots.length} registries PASS\n`);

scripts/generate-build-manifest.mjs

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import process from "node:process";
 
@@ -5,13 +6,23 @@ const packageJson = JSON.parse(await readFile("package.json", "utf8"));
 const packageManagerVersion = packageJson.packageManager.split("@").at(-1);
 const buildId = process.env.VITE_BUILD_ID ?? "local-build";
 const commitSha = process.env.VITE_COMMIT_SHA ?? "local";
+const releaseId = process.env.RELEASE_ID ?? "local-release";
 const runnerImage = process.env.CI_RUNNER_IMAGE ?? `${process.platform}-${process.arch}`;
+const builtAt = new Date().toISOString();
+const viteManifest = await readFile("dist/.vite/manifest.json");
+const assetManifestHash = createHash("sha256")
+  .update(viteManifest)
+  .digest("hex");
+const runtimeConfig = JSON.parse(await readFile("dist/config.json", "utf8"));
+
+runtimeConfig.BUILD_ID = buildId;
+runtimeConfig.RELEASE_ID = releaseId;
 
 const manifest = {
   schemaVersion: 1,
   buildId,
   commitSha,
-  generatedAt: new Date().toISOString(),
+  generatedAt: builtAt,
   buildContext: {
     nodeVersion: process.version,
     packageManagerVersion,
@@ -23,7 +34,24 @@ const manifest = {
   },
 };
 
+const releaseManifest = {
+  schemaVersion: 1,
+  appVersion: packageJson.version,
+  buildId,
+  commitSha,
+  configSchemaVersion: runtimeConfig.CONFIG_SCHEMA_VERSION,
+  apiContractVersion: runtimeConfig.API_CONTRACT_VERSION,
+  assetManifestHash,
+  releaseId,
+  builtAt,
+};
+
 await mkdir("artifacts/release", { recursive: true });
+await writeFile("dist/config.json", `${JSON.stringify(runtimeConfig, null, 2)}\n`);
+await writeFile(
+  "dist/release-manifest.json",
+  `${JSON.stringify(releaseManifest, null, 2)}\n`,
+);
 await writeFile(
   "artifacts/release/build-manifest.json",
   `${JSON.stringify(manifest, null, 2)}\n`,

scripts/lib/hosting-probe.mjs

@@ -0,0 +1,68 @@
+const LOOPBACK_IPV4 = /^127(?:\.\d{1,3}){3}$/;
+
+/**
+ * A release gate must not promote a local preview server as live hosting
+ * evidence.
+ *
+ * @param {string} value
+ * @returns {
+ *   | { passed: true; reason: null; url: URL; observedOrigin: string }
+ *   | { passed: false; reason: string; url: URL | null; observedOrigin: string | null }
+ * }
+ */
+export function classifyLiveHostingBaseUrl(value) {
+  /** @type {URL} */
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return {
+      passed: false,
+      reason: "HOSTING_BASE_URL must be an absolute URL",
+      url: null,
+      observedOrigin: null,
+    };
+  }
+
+  const observedOrigin = url.origin;
+  const hostname = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  if (url.protocol !== "https:") {
+    return {
+      passed: false,
+      reason: "live hosting evidence requires HTTPS",
+      url,
+      observedOrigin,
+    };
+  }
+  if (url.username || url.password) {
+    return {
+      passed: false,
+      reason: "HOSTING_BASE_URL must not contain credentials",
+      url,
+      observedOrigin,
+    };
+  }
+  if (
+    hostname === "localhost" ||
+    hostname.endsWith(".localhost") ||
+    hostname === "::1" ||
+    hostname === "0.0.0.0" ||
+    LOOPBACK_IPV4.test(hostname)
+  ) {
+    return {
+      passed: false,
+      reason: "local or loopback hosts are not live deployment evidence",
+      url,
+      observedOrigin,
+    };
+  }
+  if (url.pathname !== "/" || url.search || url.hash) {
+    return {
+      passed: false,
+      reason: "HOSTING_BASE_URL must be the canonical root URL",
+      url,
+      observedOrigin,
+    };
+  }
+  return { passed: true, reason: null, url, observedOrigin };
+}

scripts/verify-hosting-headers.mjs

@@ -0,0 +1,183 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+
+import { classifyLiveHostingBaseUrl } from "./lib/hosting-probe.mjs";
+
+const cachePolicy = JSON.parse(
+  await readFile("config/hosting/cache-policy.json", "utf8"),
+);
+const securityPolicy = JSON.parse(
+  await readFile("config/hosting/security-headers.json", "utf8"),
+);
+const baseUrl = process.env.HOSTING_BASE_URL;
+const liveTarget = baseUrl ? classifyLiveHostingBaseUrl(baseUrl) : null;
+const distFiles = (await readdir("dist", { recursive: true })).map(String);
+const publicSourceMaps = distFiles.filter((file) => file.endsWith(".map"));
+const publicServiceWorkers = distFiles.filter((file) =>
+  /(?:^|\/)(?:service-worker|sw)(?:[.-][^/]*)?\.js$/i.test(file),
+);
+
+/** @type {Record<string, Record<string, string>>} */
+let responses = {};
+let mode;
+/** @type {Array<{
+ * surface: string;
+ * header: string;
+ * expected: unknown;
+ * observed: unknown;
+ * reason?: string;
+ * passed: boolean;
+ * }>} */
+const probeResults = [];
+
+if (liveTarget?.passed) {
+  mode = "live";
+  const assets = await readdir("dist/assets");
+  const hashedJavaScript = assets.find((file) => file.endsWith(".js"));
+  if (!hashedJavaScript) throw new Error("No built hashed JavaScript found.");
+  const paths = {
+    index: "/",
+    runtimeConfig: "/config.json",
+    releaseManifest: "/release-manifest.json",
+    hashedAsset: `/assets/${hashedJavaScript}`,
+  };
+  responses = {};
+  for (const [surface, pathname] of Object.entries(paths)) {
+    const requestedUrl = new URL(pathname, liveTarget.url);
+    try {
+      const response = await fetch(requestedUrl, { redirect: "follow" });
+      const finalUrl = new URL(response.url);
+      probeResults.push(
+        {
+          surface,
+          header: "http-status",
+          expected: 200,
+          observed: response.status,
+          passed: response.status === 200,
+        },
+        {
+          surface,
+          header: "final-origin",
+          expected: liveTarget.url.origin,
+          observed: finalUrl.origin,
+          passed: finalUrl.origin === liveTarget.url.origin,
+        },
+      );
+      responses[surface] = Object.fromEntries(
+        [...response.headers.entries()].map(([name, value]) => [
+          name.toLowerCase(),
+          value,
+        ]),
+      );
+    } catch (error) {
+      probeResults.push({
+        surface,
+        header: "transport",
+        expected: "reachable",
+        observed: error instanceof Error ? error.name : "UnknownError",
+        passed: false,
+      });
+    }
+  }
+} else if (liveTarget) {
+  mode = "invalid-live";
+  probeResults.push({
+    surface: "deployment",
+    header: "base-url",
+    expected: "canonical non-loopback HTTPS root URL",
+    observed: liveTarget.observedOrigin,
+    reason: liveTarget.reason,
+    passed: false,
+  });
+} else {
+  mode = "fixture";
+  responses = JSON.parse(
+    await readFile("config/hosting/response-headers.fixture.json", "utf8"),
+  ).responses;
+}
+
+const results = [...probeResults];
+for (const [surface, policy] of Object.entries(cachePolicy.surfaces)) {
+  if (!("cacheControl" in policy)) continue;
+  const observed = responses[surface]?.["cache-control"];
+  results.push({
+    surface,
+    header: "cache-control",
+    expected: policy.cacheControl,
+    observed,
+    passed: observed === policy.cacheControl,
+  });
+  const observedContentType = responses[surface]?.["content-type"];
+  const observedMime = observedContentType
+    ?.split(";", 1)[0]
+    .trim()
+    .toLowerCase();
+  results.push({
+    surface,
+    header: "content-type",
+    expected: policy.contentTypes,
+    observed: observedContentType,
+    passed: policy.contentTypes.includes(observedMime),
+  });
+  if (policy.securityHeaders) {
+    for (const [header, expected] of Object.entries(securityPolicy.headers)) {
+      const observedSecurity = responses[surface]?.[header.toLowerCase()];
+      results.push({
+        surface,
+        header: header.toLowerCase(),
+        expected,
+        observed: observedSecurity,
+        passed: observedSecurity === expected,
+      });
+    }
+  }
+}
+
+results.push({
+  surface: "sourceMap",
+  header: "public",
+  expected: false,
+  observed: publicSourceMaps.length > 0,
+  passed:
+    cachePolicy.surfaces.sourceMap.public === false &&
+    publicSourceMaps.length === 0,
+});
+results.push({
+  surface: "serviceWorker",
+  header: "enabled",
+  expected: false,
+  observed: publicServiceWorkers.length > 0,
+  passed:
+    cachePolicy.surfaces.serviceWorker.enabled === false &&
+    publicServiceWorkers.length === 0,
+});
+
+const passed = results.every((result) => result.passed);
+await mkdir("artifacts/release", { recursive: true });
+await writeFile(
+  "artifacts/release/hosting-headers.json",
+  `${JSON.stringify(
+    {
+      schemaVersion: 1,
+      generatedAt: new Date().toISOString(),
+      mode,
+      baseUrl: liveTarget?.observedOrigin ?? null,
+      providerVerificationRequired: mode !== "live",
+      results,
+      passed,
+    },
+    null,
+    2,
+  )}\n`,
+);
+
+if (!passed) {
+  process.stderr.write(
+    "Hosting cache/content-type/security header verification failed.\n",
+  );
+  process.exit(1);
+}
+process.stdout.write(
+  `Hosting header contract: PASS (${mode}; live verification ${
+    mode === "live" ? "complete" : "required before promotion"
+  })\n`,
+);

scripts/verify-release.mjs

@@ -0,0 +1,98 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+
+import { verifyCompatibilityTuple } from "../src/application/policies/compatibility.js";
+import {
+  compareReleaseToRuntime,
+  RELEASE_TOKEN_REGISTRY,
+} from "../src/contracts/release-tokens.js";
+
+const fixturesDocument =
+  /** @type {{
+   *   fixtures: Array<{
+   *     name: string,
+   *     expectedCompatible: boolean,
+   *     frontend: {
+   *       buildId: string,
+   *       configSchemaVersion: string,
+   *       apiContractVersion: string,
+   *       assetManifestHash: string,
+   *       releaseId: string
+   *     },
+   *     runtime: {
+   *       buildId: string,
+   *       configSchemaVersion: string,
+   *       apiContractVersion: string,
+   *       assetManifestHash: string,
+   *       releaseId: string
+   *     }
+   *   }>
+   * }} */ (
+    JSON.parse(
+      await readFile("config/release/coherence-fixtures.json", "utf8"),
+    )
+  );
+const release = JSON.parse(await readFile("dist/release-manifest.json", "utf8"));
+const runtimeConfig = JSON.parse(await readFile("dist/config.json", "utf8"));
+const viteManifest = await readFile("dist/.vite/manifest.json");
+const actualAssetManifestHash = createHash("sha256")
+  .update(viteManifest)
+  .digest("hex");
+
+const artifactComparison = compareReleaseToRuntime(release, runtimeConfig);
+const artifactMismatches = [...artifactComparison.mismatches];
+for (const token of Object.keys(RELEASE_TOKEN_REGISTRY)) {
+  if (typeof release[token] !== "string" || release[token].length === 0) {
+    artifactMismatches.push(`releaseToken:${token}`);
+  }
+}
+if (!Number.isFinite(Date.parse(release.builtAt))) {
+  artifactMismatches.push("releaseToken:builtAtFormat");
+}
+if (release.assetManifestHash !== actualAssetManifestHash) {
+  artifactMismatches.push("assetManifestContent");
+}
+
+const fixtures = fixturesDocument.fixtures.map((fixture) => {
+  const result = verifyCompatibilityTuple({
+    frontend: fixture.frontend,
+    runtime: fixture.runtime,
+  });
+  return {
+    name: fixture.name,
+    expectedCompatible: fixture.expectedCompatible,
+    actualCompatible: result.compatible,
+    mismatches: result.mismatches,
+    passed: result.compatible === fixture.expectedCompatible,
+  };
+});
+const artifact = {
+  checked: true,
+  compatible: artifactComparison.compatible && artifactMismatches.length === 0,
+  mismatches: artifactMismatches,
+  releaseId: release.releaseId,
+};
+const passed = artifact.compatible && fixtures.every((fixture) => fixture.passed);
+const report = {
+  schemaVersion: 1,
+  generatedAt: new Date().toISOString(),
+  artifact,
+  fixtures,
+  passed,
+};
+
+await mkdir("artifacts/release", { recursive: true });
+await writeFile(
+  "artifacts/release/verification.json",
+  `${JSON.stringify(report, null, 2)}\n`,
+);
+
+if (!passed) {
+  process.stderr.write(
+    `Release coherence failed: ${artifactMismatches.join(", ") || "fixture"}\n`,
+  );
+  process.exit(1);
+}
+process.stdout.write(
+  `Release coherence: PASS (${fixtures.length - 1} mixed fixtures rejected)\n`,
+);

src/application/policies/compatibility.js

@@ -0,0 +1,102 @@
+export const COMPATIBILITY_TUPLE_FIELDS = Object.freeze([
+  "buildId",
+  "configSchemaVersion",
+  "apiContractVersion",
+  "assetManifestHash",
+  "releaseId",
+]);
+
+/** @param {string} version */
+export function parseNumericVersion(version) {
+  const match = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(version);
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2] ?? 0),
+    patch: Number(match[3] ?? 0),
+  };
+}
+
+/** @param {string} supported @param {string} actual */
+export function isVersionCompatible(supported, actual) {
+  const expected = parseNumericVersion(supported);
+  const candidate = parseNumericVersion(actual);
+  if (!expected || !candidate) return false;
+  return (
+    expected.major === candidate.major &&
+    candidate.minor >= expected.minor
+  );
+}
+
+/**
+ * @param {{
+ *   frontend: {
+ *     buildId: string,
+ *     configSchemaVersion: string,
+ *     apiContractVersion: string,
+ *     assetManifestHash: string,
+ *     releaseId: string
+ *   },
+ *   runtime: {
+ *     buildId: string,
+ *     configSchemaVersion: string,
+ *     apiContractVersion: string,
+ *     assetManifestHash: string,
+ *     releaseId: string
+ *   }
+ * }} input
+ */
+export function verifyCompatibilityTuple(input) {
+  const mismatches = [];
+  if (input.frontend.buildId !== input.runtime.buildId) mismatches.push("buildId");
+  if (
+    !isVersionCompatible(
+      input.frontend.configSchemaVersion,
+      input.runtime.configSchemaVersion,
+    )
+  ) {
+    mismatches.push("configSchemaVersion");
+  }
+  if (
+    !isVersionCompatible(
+      input.frontend.apiContractVersion,
+      input.runtime.apiContractVersion,
+    )
+  ) {
+    mismatches.push("apiContractVersion");
+  }
+  if (input.frontend.assetManifestHash !== input.runtime.assetManifestHash) {
+    mismatches.push("assetManifestHash");
+  }
+
+  const releaseWarning =
+    input.frontend.releaseId === input.runtime.releaseId
+      ? null
+      : "releaseId";
+  return Object.freeze({
+    compatible: mismatches.length === 0,
+    mismatches: Object.freeze(mismatches),
+    warnings: Object.freeze(releaseWarning ? [releaseWarning] : []),
+  });
+}
+
+/**
+ * @param {{ required?: string[], properties?: Record<string, unknown> }} before
+ * @param {{ required?: string[], properties?: Record<string, unknown> }} after
+ */
+export function classifyObjectSchemaChange(before, after) {
+  const beforeRequired = new Set(before.required ?? []);
+  const afterRequired = new Set(after.required ?? []);
+  const removedProperties = Object.keys(before.properties ?? {}).filter(
+    (key) => !(key in (after.properties ?? {})),
+  );
+  const addedRequired = [...afterRequired].filter(
+    (key) => !beforeRequired.has(key),
+  );
+  if (removedProperties.length > 0 || addedRequired.length > 0) return "breaking";
+
+  const addedProperties = Object.keys(after.properties ?? {}).filter(
+    (key) => !(key in (before.properties ?? {})),
+  );
+  return addedProperties.length > 0 ? "additive" : "none";
+}

src/contracts/release-tokens.js

@@ -0,0 +1,65 @@
+import { verifyCompatibilityTuple } from "../application/policies/compatibility.js";
+
+export const RELEASE_TOKEN_REGISTRY = Object.freeze({
+  appVersion: token("appVersion", "manifest", "human release label"),
+  buildId: token("buildId", "CI build", "asset and HTML coherence"),
+  commitSha: token("commitSha", "VCS", "source traceability"),
+  configSchemaVersion: token(
+    "configSchemaVersion",
+    "runtime config schema",
+    "boot compatibility",
+  ),
+  apiContractVersion: token(
+    "apiContractVersion",
+    "frontend/backend agreement",
+    "schema compatibility",
+  ),
+  assetManifestHash: token(
+    "assetManifestHash",
+    "build output",
+    "chunk integrity and mismatch detection",
+  ),
+  releaseId: token("releaseId", "deploy system", "rollback target"),
+  builtAt: token("builtAt", "CI", "diagnostics only; never cache identity"),
+});
+
+/**
+ * @param {string} name
+ * @param {string} source
+ * @param {string} compatibilityRole
+ */
+function token(name, source, compatibilityRole) {
+  return Object.freeze({ token: name, source, compatibilityRole });
+}
+
+/**
+ * Compare a release manifest and runtime configuration structurally. Version
+ * fields are delegated to the numeric compatibility policy, never compared
+ * lexically.
+ *
+ * @param {{
+ *   buildId: string,
+ *   configSchemaVersion: string,
+ *   apiContractVersion: string,
+ *   assetManifestHash: string,
+ *   releaseId: string
+ * }} release
+ * @param {{
+ *   BUILD_ID: string,
+ *   CONFIG_SCHEMA_VERSION: string,
+ *   API_CONTRACT_VERSION: string,
+ *   RELEASE_ID: string
+ * }} runtimeConfig
+ */
+export function compareReleaseToRuntime(release, runtimeConfig) {
+  return verifyCompatibilityTuple({
+    frontend: release,
+    runtime: {
+      buildId: runtimeConfig.BUILD_ID,
+      configSchemaVersion: runtimeConfig.CONFIG_SCHEMA_VERSION,
+      apiContractVersion: runtimeConfig.API_CONTRACT_VERSION,
+      assetManifestHash: release.assetManifestHash,
+      releaseId: runtimeConfig.RELEASE_ID,
+    },
+  });
+}

tests/unit/compatibility.test.js

@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  classifyObjectSchemaChange,
+  isVersionCompatible,
+  parseNumericVersion,
+  verifyCompatibilityTuple,
+} from "../../src/application/policies/compatibility.js";
+
+describe("contract compatibility", () => {
+  it("uses numeric version parsing rather than lexical comparison", () => {
+    expect(parseNumericVersion("1.10.0")).toEqual({ major: 1, minor: 10, patch: 0 });
+    expect(isVersionCompatible("1.9", "1.10")).toBe(true);
+    expect(isVersionCompatible("1.9", "2.0")).toBe(false);
+    expect(isVersionCompatible("next", "1.0")).toBe(false);
+  });
+
+  it("distinguishes additive and breaking object changes", () => {
+    const base = { required: ["id"], properties: { id: {} } };
+    expect(
+      classifyObjectSchemaChange(base, {
+        required: ["id"],
+        properties: { id: {}, name: {} },
+      }),
+    ).toBe("additive");
+    expect(
+      classifyObjectSchemaChange(base, {
+        required: ["id", "name"],
+        properties: { id: {}, name: {} },
+      }),
+    ).toBe("breaking");
+  });
+
+  it("treats release ID mismatch as a warning when the blocking tuple is coherent", () => {
+    const frontend = {
+      buildId: "build-a",
+      configSchemaVersion: "1.0",
+      apiContractVersion: "1.0",
+      assetManifestHash: "hash-a",
+      releaseId: "release-a",
+    };
+    expect(
+      verifyCompatibilityTuple({
+        frontend,
+        runtime: { ...frontend, releaseId: "release-b" },
+      }),
+    ).toEqual({
+      compatible: true,
+      mismatches: [],
+      warnings: ["releaseId"],
+    });
+  });
+
+  it("blocks mixed build, config, API, or asset tuples", () => {
+    const frontend = {
+      buildId: "build-a",
+      configSchemaVersion: "1.0",
+      apiContractVersion: "1.0",
+      assetManifestHash: "hash-a",
+      releaseId: "release-a",
+    };
+    expect(
+      verifyCompatibilityTuple({
+        frontend,
+        runtime: {
+          ...frontend,
+          buildId: "build-b",
+          configSchemaVersion: "2.0",
+          assetManifestHash: "hash-b",
+        },
+      }),
+    ).toMatchObject({
+      compatible: false,
+      mismatches: ["buildId", "configSchemaVersion", "assetManifestHash"],
+    });
+  });
+});

tests/unit/hosting-probe.test.js

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+
+import { classifyLiveHostingBaseUrl } from "../../scripts/lib/hosting-probe.mjs";
+
+describe("live hosting evidence target", () => {
+  it("accepts a canonical production HTTPS root", () => {
+    expect(
+      classifyLiveHostingBaseUrl("https://frontend.example.test/"),
+    ).toMatchObject({
+      passed: true,
+      observedOrigin: "https://frontend.example.test",
+    });
+  });
+
+  it.each([
+    ["http://frontend.example.test/", "requires HTTPS"],
+    ["https://localhost:4173/", "not live deployment evidence"],
+    ["https://127.0.0.1/", "not live deployment evidence"],
+    ["https://frontend.example.test/app/", "canonical root URL"],
+    ["https://user:secret@frontend.example.test/", "must not contain credentials"],
+  ])("rejects %s", (url, reason) => {
+    expect(classifyLiveHostingBaseUrl(url)).toMatchObject({
+      passed: false,
+      reason: expect.stringContaining(reason),
+    });
+  });
+});

tests/unit/registry-governance.test.js

@@ -0,0 +1,21 @@
+import { readFile } from "node:fs/promises";
+import { describe, expect, it } from "vitest";
+
+describe("registry governance manifest", () => {
+  it("declares exactly eight single-owner registries and impact labels", async () => {
+    const governance = JSON.parse(
+      await readFile("config/contracts/registry-governance.json", "utf8"),
+    );
+    expect(governance.registries).toHaveLength(8);
+    expect(new Set(governance.registries.map((entry) => entry.registryId)).size).toBe(
+      8,
+    );
+    expect(governance.registries.every((entry) => entry.owner)).toBe(true);
+    expect(governance.compatibilityImpact.allowed).toEqual([
+      "none",
+      "additive",
+      "behavior-change",
+      "breaking",
+    ]);
+  });
+});

tests/unit/release-coherence.test.js

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  compareReleaseToRuntime,
+  RELEASE_TOKEN_REGISTRY,
+} from "../../src/contracts/release-tokens.js";
+
+describe("release coherence", () => {
+  it("owns all eight release tokens and keeps builtAt diagnostic-only", () => {
+    expect(Object.keys(RELEASE_TOKEN_REGISTRY)).toHaveLength(8);
+    expect(RELEASE_TOKEN_REGISTRY.builtAt.compatibilityRole).toContain(
+      "never cache identity",
+    );
+  });
+
+  it("compares the runtime config to the release structurally", () => {
+    const release = {
+      buildId: "build-a",
+      configSchemaVersion: "1.0",
+      apiContractVersion: "1.0",
+      assetManifestHash: "assets-a",
+      releaseId: "release-a",
+    };
+    expect(
+      compareReleaseToRuntime(release, {
+        BUILD_ID: "build-a",
+        CONFIG_SCHEMA_VERSION: "1.2",
+        API_CONTRACT_VERSION: "1.1",
+        RELEASE_ID: "release-a",
+      }),
+    ).toMatchObject({ compatible: true, mismatches: [] });
+  });
+
+  it("rejects HTML-only rollback against a newer runtime config", () => {
+    const oldRelease = {
+      buildId: "build-old",
+      configSchemaVersion: "1.0",
+      apiContractVersion: "1.0",
+      assetManifestHash: "assets-old",
+      releaseId: "release-old",
+    };
+    expect(
+      compareReleaseToRuntime(oldRelease, {
+        BUILD_ID: "build-new",
+        CONFIG_SCHEMA_VERSION: "2.0",
+        API_CONTRACT_VERSION: "2.0",
+        RELEASE_ID: "release-new",
+      }),
+    ).toMatchObject({
+      compatible: false,
+      mismatches: ["buildId", "configSchemaVersion", "apiContractVersion"],
+    });
+  });
+});