@tokenoftrust/storefront-runner 2.2.89 → 2.2.91

package/apps/storefront/src/middleware/renderChain.ts

@@ -235,11 +235,13 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   // The tenant as it renders in THIS environment: its record with the declared
   // `.tot/config.json` fields applied (compliance, siteType, capabilities,
   // features). Everything below — static bundle, notices, gates, features,
-  // capabilities — reads this, never the bare record.
+  // capabilities — reads this, never the bare record. A candidate-pinned render
+  // takes the candidate version's declaration, so a reviewer sees the notices the
+  // change under review declares.
   const tenant = await withDeclaredTenantConfig(
     tenantRecord,
     kv ? (key: string) => kv.get(key) : async () => null,
-    customization.env,
+    { env: customization.env, ...(candidatePin ? { pinnedVersionId: candidatePin.versionId } : {}) },
   );
   const publicationTimestamp = publicationSource.status === "selected"
     ? publicationSource.publicationTimestamp
@@ -441,16 +443,6 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
     if (hit) return await stampResponseNonce(hit, freshNonce());
   }
 
-  // Catalog source selection (docs/architecture/product-catalog.md).
-  // A store's product source graduates over its life: JSON fixtures (dev default) ->
-  // D1 edge replica (staging) -> hosted ToT catalog (go-live). The read backend is
-  // chosen by the CALLER: the control plane resolves the D1 edge replica when
-  // USE_D1_CATALOG=1; the public branch never does, so `createToTClient` falls back
-  // to the bundled JSON fixture snapshot. The hosted catalog graduates the SAME
-  // canonical records into the D1 read model (emitCatalogSql), so JSON/D1/hosted
-  // render identically — pinned by lib/tot/sourceSelection.test.ts.
-  const tot = await createToTClient(tenant, await input.readCatalogD1?.());
-
   const proto = url.protocol === "http:" ? "http" : "https";
   // Canonical base uses the tenant's canonical domain in prod; for local dev we
   // keep the actual host (plus any /<domain> base path) so links resolve.
@@ -468,7 +460,19 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   // pointer, the artifact is resolved through the immutable site version
   // (channel -> versionId -> manifest -> content). Tenants with no channel
   // pointer fall back to the legacy per-path selection — no behavior change.
-  const kvGet = kv ? (key: string) => kv.get(key) : async () => null;
+  // Request-scoped read memo: every content read resolves the same pointer and
+  // version manifest, and a catalog render reads one artifact per catalog file.
+  const kvReads = new Map<string, Promise<string | null>>();
+  const kvGet = kv
+    ? (key: string) => {
+        let read = kvReads.get(key);
+        if (!read) {
+          read = kv.get(key);
+          kvReads.set(key, read);
+        }
+        return read;
+      }
+    : async () => null;
 
   // Self-heal a DANGLING channel pointer: the pointer for this env's channel may
   // name a version that was never built (or whose manifest was evicted).
@@ -600,7 +604,6 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
       ? await resolveTenantCommerce(tenant)
       : null;
   locals.commerce = commerce ?? undefined;
-  locals.tot = tot;
   // Resolve the shared root adapter first. An opened publication version then
   // becomes authoritative for selected content while a mounted space may still
   // reuse root-owned chrome. Neither source falls through to another space.
@@ -624,6 +627,12 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
       kvGet,
     );
   }
+  // Catalog serving is declared per tenant (`catalog.serving`, ADR 0033 and
+  // docs/architecture/product-catalog.md). The store's own `content/catalog/` files
+  // are read through the SAME content source just resolved, so they follow the
+  // request's selected version exactly as pages and the blog do. Only the control
+  // plane supplies the D1 projection; the public branch never reads D1.
+  locals.tot = await createToTClient(tenant, await input.readCatalogD1?.(), locals.content);
   locals.themeStyle = themeToCssVars(theme);
   locals.canonicalBase = canonicalBase;
   locals.customizationEnv = customization.env;
@@ -745,7 +754,7 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   // exactly the placements that rendered on THIS page, never a wildcard.
   const widgetCsp = appWidgetCspAdditions(locals.activeWidgetPlacements ?? []);
   // Third-party marketing embeds (e.g. a Pipedrive form) the tenant opted into
-  // via .tot/config.json `embeds:`. Only scan the HTML body when the tenant
+  // via its published embeds.json. Only scan the HTML body when the tenant
   // declared at least one embed — zero cost for everyone else — and add each
   // provider's origins ONLY if its marker is actually on THIS page.
   // Prefer an opt-in the render handler resolved for a tenant the URL router

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.2.89",
+  "version": "2.2.91",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/cli/src/declared-config.mjs

@@ -0,0 +1,78 @@
+/**
+ * The `.tot/config.json` keys the platform reads, and the refusal of everything
+ * else. Shared by `tot validate` (src/validate.mjs) and the monorepo/dev-loop
+ * validator (scripts/tenant/validate.mjs), so both refuse the same keys.
+ *
+ * Mirrors packages/public-runtime/src/declared-tenant-config.mjs (this package ships
+ * to npm on its own); test/declared-config-parity.test.mjs pins the two together, so
+ * a field the platform honors can never be refused here, and a key no surface reads
+ * can never pass. Dependency-free: the storefront runner copies this file as-is.
+ */
+
+export const TOT_CONFIG_KEYS = [
+  "$schema", "tenant", "scope", "mappings", "hostPlatform", "sample", "seed",
+  "siteType", "compliance", "capabilities", "features",
+];
+// Keys other tooling has written that the platform does NOT read, with the key it does.
+const RENAMED_CONFIG_KEYS = { appDomain: "scope", tenantId: "tenant" };
+export const COMPLIANCE_KEYS = [
+  "ruleProfile", "minAge", "nicotineWarning", "shippingRestriction", "pactAct",
+  "adultSignature", "prop65", "purchaseLimit", "stateEligibility", "exciseTax",
+];
+export const FEATURE_KEYS = [
+  "catalog", "productSearch", "savedItems", "quickView", "newsletter", "commerceSitemap", "productJsonLd", "ageGate",
+];
+export const SITE_TYPES = ["commerce", "marketing"];
+
+const ERROR = "error";
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/** @typedef {{level:string, rule:string, file:string, message:string, fix?:string}} Finding */
+function mk(level, rule, file, message, fix) {
+  return { level, rule, file, message, fix };
+}
+
+/**
+ * Refuse what the platform would silently ignore: an unknown top-level key, an
+ * unknown `compliance`/`features` key, or a declared field of the wrong shape. Each
+ * one passes JSON parsing and renders nothing — on a regulated store that is a
+ * mandated notice that never appears.
+ * @param {Record<string, any>} config parsed `.tot/config.json` (an object)
+ * @param {string} [file]
+ * @returns {Finding[]}
+ */
+export function validateDeclaredConfig(config, file = ".tot/config.json") {
+  const out = [];
+  for (const key of Object.keys(config)) {
+    if (!TOT_CONFIG_KEYS.includes(key)) {
+      const renamed = RENAMED_CONFIG_KEYS[/** @type {keyof typeof RENAMED_CONFIG_KEYS} */ (key)];
+      out.push(mk(ERROR, "config-unknown-key", file,
+        `\`${key}\` is not a .tot/config.json key — the platform never reads it`,
+        renamed ? `use \`${renamed}\`` : `known keys: ${TOT_CONFIG_KEYS.join(", ")}`));
+    }
+  }
+  if (config.siteType !== undefined && !SITE_TYPES.includes(config.siteType)) {
+    out.push(mk(ERROR, "config-site-type", file, `\`siteType\` is "${config.siteType}" — must be one of ${SITE_TYPES.join(", ")}`));
+  }
+  /** @type {Array<[string, string[]]>} */
+  const objectFields = [["compliance", COMPLIANCE_KEYS], ["features", FEATURE_KEYS]];
+  for (const [field, known] of objectFields) {
+    const value = config[field];
+    if (value === undefined) continue;
+    if (!isObject(value)) {
+      out.push(mk(ERROR, `config-${field}`, file, `\`${field}\` must be an object`));
+      continue;
+    }
+    for (const key of Object.keys(value)) {
+      if (!known.includes(key)) {
+        out.push(mk(ERROR, `config-${field}-unknown-key`, `${file} ${field}`,
+          `\`${field}.${key}\` is not a ${field} key — nothing renders from it`,
+          `known keys: ${known.join(", ")}`));
+      }
+    }
+  }
+  if (config.capabilities !== undefined && !isObject(config.capabilities)) {
+    out.push(mk(ERROR, "config-capabilities", file, "`capabilities` must be an object"));
+  }
+  return out;
+}

package/packages/public-runtime/package.json

@@ -17,6 +17,7 @@
     "./image-preview-rewrite-overlay": "./src/image-preview-rewrite-overlay.ts",
     "./hosted-image-media-types": "./src/hosted-image-media-types.ts",
     "./durable-assets": "./src/durable-assets.ts",
+    "./catalog-files": "./src/catalog-files.ts",
     "./retention-holds": "./src/retention-holds.ts",
     "./tenant-embed-defaults": "./src/tenant-embed-defaults.mjs",
     "./declared-tenant-config": "./src/declared-tenant-config.mjs",

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

@@ -0,0 +1,51 @@
+/**
+ * A store's own catalog files — the cold content artifact of ADR 0033 — typed for the platform.
+ *
+ * The layout, the validator and the parser live once, in the agency kit's pure catalog module
+ * (`agency-kit/tools/lib/catalog-model/files.mjs`), which the kit's own tools, the renderer, the
+ * reconcile validator and the migration engine all import. This module only narrows its records
+ * to the canonical types in `./product.ts`; the kit's model is pinned to those types field for
+ * field by `scripts/lib/agency-kit-catalog-drift.test.mjs`.
+ */
+import {
+  readCatalogFile as readKitCatalogFile,
+  readCatalogFiles as readKitCatalogFiles,
+  type CatalogStore,
+} from "../../../agency-kit/tools/lib/catalog-model/files.mjs";
+import type { CatalogCollection, CatalogProduct } from "./product.js";
+
+export {
+  CATALOG_ARTIFACT_PREFIX,
+  CATALOG_COLLECTIONS_PREFIX,
+  CATALOG_CONTENT_DIRS,
+  CATALOG_HANDLE_RE,
+  CATALOG_PRODUCTS_PREFIX,
+  CatalogFileError,
+  catalogFileIssues,
+  classifyCatalogPath,
+  declaredAvailability,
+  planCatalogFiles,
+  type CatalogFileKind,
+  type CatalogStore,
+  type InventoryProvider,
+} from "../../../agency-kit/tools/lib/catalog-model/files.mjs";
+
+export type CatalogFileRecord =
+  | { kind: "product"; record: CatalogProduct }
+  | { kind: "collection"; record: CatalogCollection };
+
+/** One validated catalog file as its canonical record. Throws `CatalogFileError`. */
+export function readCatalogFile(relative: string, raw: string, store: CatalogStore): CatalogFileRecord {
+  return readKitCatalogFile(relative, raw, store) as unknown as CatalogFileRecord;
+}
+
+/** A whole validated catalog. Throws `CatalogFileError` naming every failing file. */
+export function readCatalogFiles(
+  entries: Iterable<{ path: string; raw: string | null }>,
+  store: CatalogStore,
+): { products: CatalogProduct[]; collections: CatalogCollection[] } {
+  return readKitCatalogFiles(entries, store) as unknown as {
+    products: CatalogProduct[];
+    collections: CatalogCollection[];
+  };
+}

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

@@ -103,7 +103,7 @@ export const STOREFRONT_CSP_ALLOWLIST = {
 
 /**
  * Curated catalog of known third-party embeds a tenant may opt into. Keyed by a
- * stable provider slug the tenant lists in `.tot/config.json` `embeds:`; the
+ * stable provider slug the tenant lists in its `embeds.json`; the
  * platform (never the tenant) owns the exact origins each provider needs, so a
  * tenant can enable "pipedrive" without ever hand-writing a CSP origin — and a
  * novel provider requires a reviewed catalog entry here, not a config edit.
@@ -170,7 +170,7 @@ export interface EmbedCspAdditions {
  * CSP additions for the third-party embeds ACTUALLY rendered on this page.
  *
  * An origin is added only when BOTH hold: (1) the tenant opted the provider in
- * via `.tot/config.json` `embeds:` (audit trail + platform review of novel
+ * via its `embeds.json` (audit trail + platform review of novel
  * providers), and (2) the provider's marker appears in the rendered HTML (so a
  * page that doesn't embed the form never carries the origin). This keeps the
  * strict policy tenant- AND page-scoped — never a blanket global relaxation.

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

@@ -503,10 +503,16 @@ export interface TenantConfig {
    * the pages that actually contain it (see `embedCspAdditions`). A provider not
    * in the catalog needs a reviewed platform addition, not a config edit — so
    * this stays an auditable allow-list, never an escape hatch to arbitrary hosts.
-   * Declared in the tenant's platform config alongside `siteType`/`capabilities`.
+   * The platform default comes from tenant-embed-defaults.mjs; a tenant opts in
+   * itself by committing `embeds.json` (see `resolveEffectiveEmbeds`).
    */
   embeds?: string[];
-  /** Regulated-commerce affordances; undefined for unregulated tenants. */
+  /**
+   * Regulated-commerce affordances; undefined for unregulated tenants. A tenant
+   * declares these in its `.tot/config.json`; every render reads them through
+   * `applyDeclaredTenantConfig` (declared-tenant-config.mjs), never off the bare
+   * tenant record alone.
+   */
   compliance?: ComplianceConfig;
   /**
    * Per-tenant newsletter compliance/sender config. Sourced when a digest is
@@ -622,6 +628,25 @@ export interface TenantConfig {
      */
     htmlCachePolicy?: HtmlCachePolicy;
   };
+  /**
+   * Catalog serving (ADR 0033). The store's own `content/catalog/` files are the
+   * system of record; this declares which artifact serves reads.
+   *
+   * `"files"` (the default): the store's catalog files, then the platform's
+   * grandfathered in-repo snapshot for the same data scope, then an empty catalog.
+   * `"d1"`: the derived D1 serving projection, read on the control plane only.
+   * Never inferred from a tenant id.
+   */
+  catalog?: {
+    serving?: "files" | "d1";
+  };
+  /**
+   * Availability (hot) provider (ADR 0033). Availability is never read from catalog
+   * content files. Absent ⇒ `"mirror"`, the only implemented provider.
+   */
+  inventory?: {
+    provider: "mirror" | "live-hydrate" | "tot-authoritative";
+  };
   /**
    * Storefront product/subscription state — the paywall the platform gates GO-LIVE
    * on. This is the storefront's

package/scripts/dev/standalone-graft-plan.mjs

@@ -1,35 +1,57 @@
 // @ts-check
 /**
  * Pure planning for `tot dev --workspace` grafts: which checkout-relative paths
- * get copied into the in-tree `tenants/<id>/` layout the app globs, and whether
- * each is a file or a directory tree. Decision-only — scripts/tot-dev.mjs does
- * the actual fs copy/backup/watch effects per planned entry.
+ * get copied where in the in-tree `tenants/<id>/` layout the app globs, and
+ * whether each is a file or a directory tree. Decision-only — scripts/tot-dev.mjs
+ * does the actual fs copy/backup/watch effects per planned entry.
+ *
+ * A mapping's `workspace` is where the files live in the checkout; its `repo`
+ * names what they are, tenant-relative (`theme.json`, `content/`, …). They land
+ * under THIS tenant's directory — the same resolution the hosted reconcile uses
+ * (agency-kit/tools/lib/tot-repo-mappings.mjs), whatever tenant segment `repo`
+ * spells — so the dev server serves them at the same `/tenants/<tenant>/…` the
+ * hosted preview does.
  */
+import { tenantDirRelative } from "../lib/tenant-dirs.mjs";
+import { parseMappingTarget } from "../../agency-kit/tools/lib/tot-repo-mappings.mjs";
+
+const TOT_CONFIG = ".tot/config.json";
 
 /**
- * @param {Array<{workspace?: unknown, kind?: unknown}>} mappings the checkout's
- *   own `.tot/config.json` `mappings` array (content/, public/, theme.json, …)
- * @returns {{ workspace: string, isDir: boolean }[]}
+ * @param {string} tenant canonical tenant id (the checkout config's `tenant`)
+ * @param {unknown} mappings the checkout's own `.tot/config.json` `mappings` array
+ *   (content/, public/, theme.json, …)
+ * @returns {{ workspace: string, target: string | null, isDir: boolean }[]} checkout-relative
+ *   `workspace` and repo-relative `target` (POSIX); `target` is null for a mapping whose `repo` is
+ *   not a valid `tenants/<id>/<path>` target, which the caller skips
  */
-export function standaloneGraftPlan(mappings) {
+export function standaloneGraftPlan(tenant, mappings) {
+  const root = tenantDirRelative(tenant);
   const plan = [];
   const seen = new Set();
   for (const map of Array.isArray(mappings) ? mappings : []) {
     const workspace = String(map?.workspace ?? "").replace(/\/+$/, "");
     if (!workspace || seen.has(workspace)) continue;
     seen.add(workspace);
-    plan.push({ workspace, isDir: map?.kind !== "file" });
+    if (workspace === TOT_CONFIG) {
+      plan.push({ workspace, target: `${root}/${TOT_CONFIG}`, isDir: false });
+      continue;
+    }
+    const declared = parseMappingTarget(map?.repo);
+    const rel = declared ? declared.rel.replace(/\/+$/, "") : null;
+    const target = rel === null ? null : rel ? `${root}/${rel}` : root;
+    plan.push({ workspace, target, isDir: map?.kind !== "file" });
   }
   // `.tot/config.json` is never itself one of the declared `mappings` (those map
   // content/public/theme.json) but IS the tenant's own declared platform config
   // — siteType/compliance/capabilities/features (see
-  // apps/storefront/src/config/devTenantSeed.ts TOT_CONFIG_TENANT_FIELDS and
-  // resolver.ts declaredConfigs()) — the same file
+  // packages/public-runtime/src/declared-tenant-config.mjs, applied by
+  // apps/storefront/src/config/declaredTenantConfig.ts) — the same file
   // scripts/tenant/materialize-tenant-content.mjs copies for a Gitea-sourced
   // tenant. Graft it unconditionally so a regulated store's mandated notices
   // resolve from the SAME declared config locally as they would once published.
-  if (!seen.has(".tot/config.json")) {
-    plan.push({ workspace: ".tot/config.json", isDir: false });
+  if (!seen.has(TOT_CONFIG)) {
+    plan.push({ workspace: TOT_CONFIG, target: `${root}/${TOT_CONFIG}`, isDir: false });
   }
   return plan;
 }

package/scripts/tenant/materialize-tenant-content.mjs

@@ -71,6 +71,7 @@ import { tmpdir } from "node:os";
 import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { tenantDirRelative } from "../lib/tenant-dirs.mjs";
+import { parseMappingTarget } from "../../agency-kit/tools/lib/tot-repo-mappings.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const repoRoot = resolve(here, "..", "..");
@@ -153,7 +154,13 @@ function canonicalMappings(tenant) {
  */
 export function copyMapping({ checkoutDir, root, tenant, mapping, log = (/** @type {string} */ _m) => {} }) {
   const src = join(checkoutDir, mapping.workspace.replace(/\/+$/, ""));
-  const target = resolveTargetPath(root, tenant, mapping.repo.replace(/\/+$/, ""));
+  // The mapping names WHAT the files are (its tenant-relative target); the
+  // tenant being materialized names WHOSE — never the target's tenant segment.
+  const declared = parseMappingTarget(mapping.repo);
+  if (!declared) {
+    throw new Error(`mapping target "${mapping.repo}" escapes tenants/${tenant}/ — refusing`);
+  }
+  const target = resolveTargetPath(root, tenant, `tenants/${tenant}/${declared.rel}`.replace(/\/+$/, ""));
   if (target === resolve(root, tenantDirRelative(tenant))) {
     throw new Error("mapping target cannot replace the tenant root");
   }

package/scripts/tenant/validate.mjs

@@ -5,7 +5,7 @@
  * Catches, BEFORE a commit reaches the hosted storefront, the classes of tenant
  * defect that otherwise fail silently or as a cryptic runtime/reconcile error:
  *   · `.tot/config.json` mapping-shape drift  (the #24/#25 regression — a `kind:"dir"`
- *     / missing-`repo` mapping makes the flow-back reconcile `mapToArtifact` throw)
+ *     / missing-`repo` mapping makes the flow-back reconcile refuse it)
  *   · malformed `theme.json` / `home.json` / `chrome.json`  (an eager Vite glob turns
  *     these into a WHOLE-APP BUILD FAILURE)
  *   · raw HTML that isn't a servable document, or drops CSS under the CSP nonce
@@ -15,7 +15,7 @@
  *
  * Design principle — "valid locally ≡ will reconcile in storefront": the checks below
  * mirror the reconcile pipeline's own gate (`@tot/private-controlplane`
- * customization-reconcile.ts `mapToArtifact` / `validateRawHtml`). Keep them in step.
+ * customization-reconcile.ts `validateMappingShape` / `validateRawHtml`, and the shared mapping resolver `tot-repo-mappings.mjs`). Keep them in step.
  *
  * Dependency-free. Two modes (mirrors scripts/tot-dev.mjs):
  *   node scripts/tenant/validate.mjs <tenant>                # monorepo: tenants/<tenant>/
@@ -38,7 +38,13 @@ import {
   isSafeRehostedAssetPathForTenant,
   isSafeStorefrontHref,
 } from "../../packages/public-runtime/src/extension-contract-values.mjs";
+import {
+  foreignTenantSegments,
+  parseMappingTarget,
+  workspacePathForTenantRelative,
+} from "../../agency-kit/tools/lib/tot-repo-mappings.mjs";
 import { validateVisualParityClosure } from "../../packages/cli/src/visual-parity.mjs";
+import { validateDeclaredConfig } from "../../packages/cli/src/declared-config.mjs";
 
 /** Catalogued embed slugs a tenant may opt into (mirror of EMBED_PROVIDERS). */
 const KNOWN_EMBED_SLUGS = new Set(KNOWN_EMBEDS.map((p) => p.slug));
@@ -97,7 +103,7 @@ const REQUIRED_WORKSPACES = ["content/", "public/", "theme.json"];
 
 /**
  * Validate a parsed `.tot/config.json` against the shape the reconcile pipeline
- * (`mapToArtifact`) requires. Pure — no I/O — so the CI regression test can call it.
+ * (`validateMappingShape`) requires. Pure — no I/O — so the CI regression test can call it.
  * @param {any} config parsed JSON
  * @param {string} file path for messages
  * @returns {Finding[]}
@@ -110,6 +116,8 @@ export function validateConfigShape(config, file = ".tot/config.json") {
   if (typeof config.tenant !== "string" || !config.tenant) {
     out.push(mk(ERROR, "config-tenant", file, "`tenant` must be a non-empty string"));
   }
+  // The same refusal `tot validate` applies: a key no surface reads never passes.
+  out.push(...validateDeclaredConfig(config, file));
   if (!Array.isArray(config.mappings)) {
     out.push(mk(ERROR, "config-mappings", file, "`mappings` must be an array", "seed shape: [{workspace,repo,kind}]"));
     return out; // nothing more to check without the array
@@ -123,18 +131,29 @@ export function validateConfigShape(config, file = ".tot/config.json") {
     }
     if (typeof m.workspace !== "string" || !m.workspace) {
       out.push(mk(ERROR, "mapping-workspace", at, "`workspace` must be a non-empty string"));
-    } else {
-      seen.add(m.workspace.replace(/\/+$/, "") + (m.kind === "tree" ? "/" : ""));
-      seen.add(m.workspace);
     }
-    // THE regression guard: reconcile's mapToArtifact dereferences m.repo and only
-    // knows "file" vs tree — a missing repo or kind:"dir" makes it throw at runtime.
+    // THE regression guard: reconcile reads the tenant-relative target out of
+    // m.repo and only knows "file" vs tree — a missing/unparseable repo or
+    // kind:"dir" is refused there, so refuse it here first.
     if (typeof m.repo !== "string" || !m.repo) {
       out.push(
         mk(ERROR, "mapping-repo", at,
-          `mapping for "${m.workspace ?? "?"}" is missing a string \`repo\` (reconcile mapToArtifact throws on undefined.repo)`,
+          `mapping for "${m.workspace ?? "?"}" is missing a string \`repo\` (the reconcile refuses it)`,
           `add "repo": "tenants/${config.tenant ?? "<id>"}/${(m.workspace ?? "").replace(/\/+$/, "")}${m.kind === "file" ? "" : "/"}"`),
       );
+    } else {
+      const target = parseMappingTarget(m.repo);
+      if (!target) {
+        out.push(
+          mk(ERROR, "mapping-repo", at,
+            `mapping for "${m.workspace ?? "?"}" targets "${m.repo}" — \`repo\` must be a clean path under tenants/<id>/ (the reconcile refuses it)`,
+            `e.g. "repo": "tenants/${config.tenant ?? "<id>"}/content/"`),
+        );
+      } else {
+        // Coverage is about WHAT is mapped (the target), not where it lives.
+        seen.add(target.rel.replace(/\/+$/, "") + (m.kind === "tree" ? "/" : ""));
+        seen.add(target.rel);
+      }
     }
     if (!KNOWN_KINDS.has(m.kind)) {
       out.push(
@@ -998,16 +1017,9 @@ export function validateTenant(tenantDir, opts = {}) {
   /** @type {Finding[]} */
   const findings = [];
   const rel = (p) => relative(tenantDir, p) || p;
-  const contentDir = join(tenantDir, "content");
-  const publicDir = join(tenantDir, "public");
-  const pagesDir = join(contentDir, "pages-html");
-
-  // 0. basic layout
-  if (!existsSync(contentDir)) {
-    findings.push(mk(ERROR, "layout", "content/", "no content/ directory"));
-  }
 
-  // 1. .tot/config.json — shape (flow-back readiness)
+  // 1. .tot/config.json — shape (flow-back readiness). Read first: its mappings
+  // say where theme.json / content/ / public/ live in this tree.
   const configPath = join(tenantDir, ".tot", "config.json");
   let config = null;
   if (existsSync(configPath)) {
@@ -1018,7 +1030,18 @@ export function validateTenant(tenantDir, opts = {}) {
       config = value;
       findings.push(...validateConfigShape(value, ".tot/config.json"));
     }
-  } else {
+  }
+  const located = (tenantRel) => join(tenantDir, workspacePathForTenantRelative(config, tenantRel));
+  const contentDir = located("content");
+  const publicDir = located("public");
+  const pagesDir = join(contentDir, "pages-html");
+
+  // 0. basic layout
+  if (!existsSync(contentDir)) {
+    findings.push(mk(ERROR, "layout", rel(contentDir) + "/", `no ${rel(contentDir)}/ directory`));
+  }
+
+  if (!existsSync(configPath)) {
     findings.push(
       mk(WARN, "config-absent", ".tot/config.json",
         "no .tot/config.json — tenant can serve but is NOT flow-back-ready (reconcile has nothing to map)",
@@ -1031,7 +1054,28 @@ export function validateTenant(tenantDir, opts = {}) {
     );
   }
   const scope = opts.scope || config?.scope;
-  const activeTenantId = opts.tenantId || scope || config?.tenant;
+  // The canonical tenant id: the one the asset rule binds to and the one the
+  // mappings' targets resolve under — never a directory name.
+  const activeTenantId = opts.tenantId || config?.tenant || scope;
+  if (config && activeTenantId) {
+    for (const f of foreignTenantSegments(config, activeTenantId)) {
+      findings.push(
+        mk(WARN, "mapping-tenant-segment", ".tot/config.json",
+          `mapping for "${f.workspace}" targets "${f.repo}", naming tenant "${f.segment}" — this store is "${activeTenantId}". ` +
+            `It still resolves under tenants/${activeTenantId}/ (the segment is not read), and its assets are served at /tenants/${activeTenantId}/...`,
+          `write "repo": "tenants/${activeTenantId}/${parseMappingTarget(f.repo)?.rel ?? ""}" so the config agrees with itself ` +
+            `(the agency kit's tools/repair-tenant-config.mjs rewrites the whole config)`),
+      );
+    }
+  }
+  // Publication refuses a config whose `scope` is not the store's id.
+  if (config && typeof config.tenant === "string" && config.scope !== config.tenant) {
+    findings.push(
+      mk(WARN, "config-scope-mismatch", ".tot/config.json",
+        `"scope" is ${JSON.stringify(config.scope ?? null)} but "tenant" is "${config.tenant}" — publication refuses a config whose scope is not the store's id`,
+        `set "scope" to "${config.tenant}" (the agency kit's tools/repair-tenant-config.mjs rewrites the whole config)`),
+    );
+  }
   // platform-route awareness: which framework routes the host platform owns for this tenant
   const mode = opts.mode === "workspace" ? "workspace" : "monorepo";
   const hostIsPlatform = mode === "monorepo" || config?.hostPlatform === "tot-storefront";
@@ -1041,18 +1085,18 @@ export function validateTenant(tenantDir, opts = {}) {
   }
 
   // 2. theme.json — parse (a malformed one is a WHOLE-APP BUILD FAILURE)
-  const themePath = join(tenantDir, "theme.json");
+  const themePath = located("theme.json");
   if (existsSync(themePath)) {
     const { error } = readJsonSafe(themePath);
     if (error) {
       findings.push(
-        mk(ERROR, "theme-parse", "theme.json",
+        mk(ERROR, "theme-parse", rel(themePath),
           `invalid JSON: ${error}`, "theme.json is loaded by an eager Vite glob — a parse error fails the entire storefront build"),
       );
     }
   }
 
-  const capabilitiesPath = join(tenantDir, "capabilities.json");
+  const capabilitiesPath = located("capabilities.json");
   if (existsSync(capabilitiesPath)) {
     const { value, error } = readJsonSafe(capabilitiesPath);
     if (error) {
@@ -1062,7 +1106,7 @@ export function validateTenant(tenantDir, opts = {}) {
     }
   }
 
-  const scriptsPath = join(tenantDir, "scripts.json");
+  const scriptsPath = located("scripts.json");
   if (existsSync(scriptsPath)) {
     const { value, error } = readJsonSafe(scriptsPath);
     if (error) {
@@ -1072,7 +1116,7 @@ export function validateTenant(tenantDir, opts = {}) {
     }
   }
 
-  const embedsPath = join(tenantDir, "embeds.json");
+  const embedsPath = located("embeds.json");
   if (existsSync(embedsPath)) {
     const { value, error } = readJsonSafe(embedsPath);
     if (error) {
@@ -1177,9 +1221,7 @@ export function validateTenant(tenantDir, opts = {}) {
   // content/ plus the root config files.
   const conflictScanFiles = [
     ...walk(contentDir, hasScanExt),
-    ...["theme.json", "capabilities.json", "scripts.json", join(".tot", "config.json")]
-      .map((f) => join(tenantDir, f))
-      .filter((p) => existsSync(p)),
+    ...[themePath, capabilitiesPath, scriptsPath, configPath].filter((p) => existsSync(p)),
   ];
   for (const p of conflictScanFiles) {
     const lines = detectConflictMarkers(readFileSync(p, "utf8"));
@@ -1200,9 +1242,8 @@ export function validateTenant(tenantDir, opts = {}) {
   // compare against, since the opt-in may be the platform build-time default.
   if (existsSync(contentDir)) {
     let declaredEmbeds = null;
-    const embedsFile = join(tenantDir, "embeds.json");
-    if (existsSync(embedsFile)) {
-      const { value } = readJsonSafe(embedsFile);
+    if (existsSync(embedsPath)) {
+      const { value } = readJsonSafe(embedsPath);
       if (Array.isArray(value)) declaredEmbeds = value.filter((s) => typeof s === "string");
     }
     for (const f of lintTenantEmbeds({ dir: contentDir, declared: declaredEmbeds }).findings) {