@tokenoftrust/cli 2.2.12 → 2.2.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.2.12",
+  "version": "2.2.14",
   "description": "Token of Trust developer CLI — clone a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",

package/src/commands/dev.mjs

@@ -51,6 +51,7 @@ import { startHeartbeatFromEnv } from "../dev-heartbeat.mjs";
 import { streamDevLogs } from "../dev-logs.mjs";
 import { cockpitUrlFrom } from "../banner.mjs";
 import { recordDiagnostic } from "../diagnostics.mjs";
+import { lockRendererDir, unlockRendererDir, rendererDirInUse } from "../renderer-lock.mjs";
 
 // Kept for the internal `tot start` migration path. `tot dev` itself is native-only.
 const DEFAULT_DEV_IMAGE =
@@ -914,8 +915,19 @@ export function rendererArtifactComplete(runnerDir) {
  * runner tree per version forever. Only touches `public-*` dirs: the entitled
  * path caches by bare version and sample tarball runs by `sample-*`, both left
  * alone. Best-effort — a failure here never breaks `tot dev`.
+ *
+ * NEVER deletes a dir a running `tot dev` session is still serving files out
+ * of (per renderer-lock.mjs's cross-process lock) — resolving a newer runner
+ * in one terminal must not crash a DIFFERENT, still-running session in
+ * another with ENOENT reading its own astro templates mid-session
+ * (fb-1791304494289-ussj8l). That dir is simply left for a later prune once
+ * nothing holds it; `log` reports the deferral instead of pruning silently.
  */
-function prunePublicRunnerCache(cacheRoot, keepVersion) {
+export function prunePublicRunnerCache(
+  cacheRoot,
+  keepVersion,
+  { log = (/** @type {string} */ _message) => {}, pidAlive = processAlive, lockDir = undefined } = {},
+) {
   try {
     if (!cacheRoot || !existsSync(cacheRoot)) return;
     // keepVersion == null → keep NOTHING (drop every public-* dir); used when a
@@ -923,7 +935,12 @@ function prunePublicRunnerCache(cacheRoot, keepVersion) {
     const keep = keepVersion == null ? null : `public-${keepVersion}`;
     for (const name of readdirSync(cacheRoot)) {
       if (!name.startsWith("public-") || name === keep) continue;
-      rmSync(join(cacheRoot, name), { recursive: true, force: true });
+      const dir = join(cacheRoot, name);
+      if (rendererDirInUse(dir, { pidAlive, ...(lockDir ? { dir: lockDir } : {}) })) {
+        log(`~ keeping ${name} cached — a running \`tot dev\` session is still serving from it.`);
+        continue;
+      }
+      rmSync(dir, { recursive: true, force: true });
     }
   } catch {
     /* best-effort cache hygiene */
@@ -1044,21 +1061,21 @@ export async function ensureSampleRenderer(args, ctx, { env = process.env, cache
             `~ renderer: cached public runner ${wantVersion} (${declared ? "declared by this store" : "matches this CLI"})`,
           );
           setRunnerVersion(wantVersion);
-          prunePublicRunnerCache(cacheRoot, wantVersion);
+          prunePublicRunnerCache(cacheRoot, wantVersion, { log: console.error });
           return exact;
         }
         // Same version string, different published contents — a corrected
         // republish. Fall through to resolution + a fresh install (which also
         // verifies the new bytes against the new integrity).
         console.error(`~ renderer: ${wantVersion} was republished with different contents — refetching the corrected artifact`);
-        prunePublicRunnerCache(cacheRoot, null); // drop ALL public-* — none matches what npm now publishes
+        prunePublicRunnerCache(cacheRoot, null, { log: console.error }); // drop ALL public-* — none matches what npm now publishes
       } else {
         console.error(
           rendererCacheHealthy(exact)
             ? `~ renderer: cached runner at ${exact} can't report a version — refetching (forced upgrade)`
             : `~ renderer: cached runner at ${exact} is missing native bindings for ${process.platform}-${process.arch} — refetching`,
         );
-        prunePublicRunnerCache(cacheRoot, null); // drop ALL public-* — none is trustworthy
+        prunePublicRunnerCache(cacheRoot, null, { log: console.error }); // drop ALL public-* — none is trustworthy
       }
     }
   }
@@ -1096,7 +1113,7 @@ export async function ensureSampleRenderer(args, ctx, { env = process.env, cache
   setRunnerVersion(pub.version); // telemetry: the runner version running this session
   // The pinned version is now installed under public-<version> — drop any other
   // public-* dirs (e.g. the stale public-0.1.0) so they can never be reused.
-  prunePublicRunnerCache(cacheRoot, pub.version);
+  prunePublicRunnerCache(cacheRoot, pub.version, { log: console.error });
   return dir;
 }
 
@@ -1715,14 +1732,21 @@ export function spawnNativeDev(runnerDir, workspace, port, { stdio = "inherit",
     [script, "--workspace", workspace, "--port", port],
     { cwd: runnerDir, stdio: stdioArr, env: mergedEnv },
   );
+  // Claim this runnerDir for the lifetime of this child — prunePublicRunnerCache
+  // consults this lock before deleting an un-pinned cached version, so resolving
+  // a NEWER runner in one terminal can never delete the directory THIS session
+  // is still serving files out of (fb-1791304494289-ussj8l).
+  lockRendererDir(runnerDir, { pid: child.pid });
   const handle = { child, exited: false, done: /** @type {any} */ (null) };
   handle.done = new Promise((resolvePromise) => {
     child.on("exit", (code) => {
       handle.exited = true;
+      unlockRendererDir({ pid: child.pid });
       resolvePromise(code ?? 0);
     });
     child.on("error", (e) => {
       handle.exited = true;
+      unlockRendererDir({ pid: child.pid });
       console.error(fail(`could not start the native dev runner: ${e.message}`));
       resolvePromise(1);
     });

package/src/renderer-lock.mjs

@@ -0,0 +1,74 @@
+// @ts-check
+/**
+ * Cross-process lock recording which PIDs are actively serving a `tot dev`
+ * native session out of which cached renderer directory (`~/.tot/cache/renderer/
+ * <version>` or `public-<version>`). `prunePublicRunnerCache` (src/commands/dev.mjs)
+ * reads it before deleting an un-pinned cached version, so resolving a NEWER
+ * runner in one terminal can never delete the directory a DIFFERENT, still-running
+ * `tot dev` session in another terminal is serving files out of — which used to
+ * crash the live session with ENOENT reading its own astro templates mid-session
+ * (fb-1791304494289-ussj8l).
+ *
+ * Lives OUTSIDE the renderer cache tree itself (not `<runnerDir>/.tot-dev-lock`)
+ * so a lock entry is never mistaken for cache/package content and never ships
+ * inside a published runner tarball.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const RENDERER_LOCK_DIR = join(homedir(), ".tot", "run", "active-renderers");
+
+/** Record that `pid` (default: this process) is actively serving from `runnerDir`. */
+export function lockRendererDir(runnerDir, { pid = process.pid, dir = RENDERER_LOCK_DIR } = {}) {
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, String(pid)), runnerDir);
+  } catch {
+    /* best-effort — a failed lock must never block `tot dev` from starting */
+  }
+}
+
+/** Release a lock (best-effort; safe to call more than once, e.g. on every exit path). */
+export function unlockRendererDir({ pid = process.pid, dir = RENDERER_LOCK_DIR } = {}) {
+  try {
+    rmSync(join(dir, String(pid)), { force: true });
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Is any LIVE process's lock pointing at `runnerDir`? Fails CLOSED (true) on any
+ * read error — an unreadable lock state must never read as "safe to delete",
+ * since that's precisely the failure this exists to prevent. A stale (dead-pid)
+ * lock is ignored so cache hygiene still reclaims disk once nothing holds it.
+ * @param {string} runnerDir
+ * @param {{ pidAlive: (pid:number)=>boolean, dir?: string }} deps
+ */
+export function rendererDirInUse(runnerDir, { pidAlive, dir = RENDERER_LOCK_DIR }) {
+  try {
+    if (!existsSync(dir)) return false;
+    let inUse = false;
+    for (const name of readdirSync(dir)) {
+      const pid = Number(name);
+      if (!Number.isInteger(pid) || pid <= 0) continue;
+      let lockedDir;
+      try {
+        lockedDir = readFileSync(join(dir, name), "utf8");
+      } catch {
+        continue; // one unreadable lock entry must not block the rest of the scan
+      }
+      if (pidAlive(pid)) {
+        if (lockedDir === runnerDir) inUse = true;
+      } else {
+        // A crashed/killed session never ran its own exit handler — reap its
+        // lock opportunistically (best-effort) so entries don't accumulate.
+        try { rmSync(join(dir, name), { force: true }); } catch { /* best-effort */ }
+      }
+    }
+    return inUse;
+  } catch {
+    return true; // fail closed: an unreadable lock DIRECTORY must not read as "unused"
+  }
+}

package/src/tot-repo-mappings.mjs

@@ -0,0 +1,153 @@
+/**
+ * `.tot/config.json` mapping resolution — the ONE reading of a store repo's
+ * declared layout, shared by every consumer: the hosted reconcile (preview,
+ * candidate, aggregate, publication), `tot dev`'s checkout graft, `tot validate`,
+ * the platform's materialize / asset-repair scripts, and this kit's
+ * `repair-tenant-config.mjs`. The platform imports this file from the kit.
+ *
+ * A mapping is `{ workspace, repo, kind }`:
+ *   - `workspace` — where the files physically live in the store repo. It is the
+ *     only source of truth for location; nothing assumes a `tenants/<id>/` layout
+ *     inside the store's own repo.
+ *   - `repo` — the storefront artifact target, `tenants/<segment>/<rel>`. Only
+ *     `<rel>` (the tenant-relative path: `theme.json`, `content/`, `public/`, …)
+ *     is read from it. The tenant namespace always comes from the CANONICAL
+ *     tenant id — the store's registered id hosted, the config's `tenant` locally
+ *     — never from `<segment>`, so a config whose segment disagrees with its
+ *     tenant id resolves identically on every surface.
+ *
+ * Pure and dependency-free so kit tools, platform `.mjs` scripts and TypeScript
+ * consumers (types in the adjacent `.d.mts`) all import it. The published CLI
+ * installs without the kit, so it ships a byte-identical copy that its own test
+ * suite holds equal to this file.
+ */
+
+/** Platform test tenants nest one level deeper: `tenants/e2e/<id>.e2e.test/`. */
+const TARGET_RE = /^tenants\/(?:e2e\/([^/]+\.e2e\.test)|([^/]+))(?:\/(.*))?$/;
+
+/**
+ * Split a declared mapping target into the tenant segment it names and the
+ * tenant-relative path it addresses. Null when the target is not under
+ * `tenants/<segment>/`, or when its relative part is not a clean path (empty,
+ * `.` or `..` segments) — such a target could address outside the tenant.
+ * A trailing `/` (tree target) is preserved on `rel`; the tenant root is `""`.
+ * @param {unknown} repo
+ * @returns {{ segment: string, rel: string } | null}
+ */
+export function parseMappingTarget(repo) {
+  if (typeof repo !== "string") return null;
+  const m = TARGET_RE.exec(repo);
+  if (!m) return null;
+  const segment = m[1] ?? m[2];
+  const rel = m[3] ?? "";
+  const parts = rel.replace(/\/$/, "").split("/");
+  if (rel && parts.some((p) => !p || p === "." || p === "..")) return null;
+  return { segment, rel };
+}
+
+/** The canonical artifact root for a tenant: `tenants/<tenantId>/`. */
+export function tenantArtifactRoot(tenantId) {
+  return `tenants/${tenantId}/`;
+}
+
+function asDir(path) {
+  return path === "" || path.endsWith("/") ? path : `${path}/`;
+}
+
+function mappingsOf(config) {
+  return Array.isArray(config?.mappings) ? config.mappings : [];
+}
+
+/**
+ * Map a tenant-repo path to its tenant-relative path (e.g. `content/home.json`).
+ * First match wins; a `file` mapping matches exactly, a `tree` mapping by prefix.
+ * Null when no mapping covers the path or the covering mapping's target is not
+ * a valid tenant target.
+ * @param {{ mappings?: unknown }} config
+ * @param {string} workspacePath
+ * @returns {string | null}
+ */
+export function mapWorkspaceToTenantRelative(config, workspacePath) {
+  for (const m of mappingsOf(config)) {
+    if (!m || typeof m !== "object" || typeof m.workspace !== "string") continue;
+    if (m.kind === "file") {
+      if (workspacePath !== m.workspace) continue;
+      const target = parseMappingTarget(m.repo);
+      return target ? target.rel : null;
+    }
+    if (m.kind === "tree") {
+      const ws = asDir(m.workspace);
+      if (!workspacePath.startsWith(ws)) continue;
+      const target = parseMappingTarget(m.repo);
+      return target ? asDir(target.rel) + workspacePath.slice(ws.length) : null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Map a tenant-repo path to its storefront artifact path under the CANONICAL
+ * tenant root (`tenants/<tenantId>/<rel>`). Null when unmapped.
+ * @param {{ mappings?: unknown }} config
+ * @param {string} tenantId
+ * @param {string} workspacePath
+ * @returns {string | null}
+ */
+export function mapWorkspaceToArtifact(config, tenantId, workspacePath) {
+  const rel = mapWorkspaceToTenantRelative(config, workspacePath);
+  return rel === null ? null : tenantArtifactRoot(tenantId) + rel;
+}
+
+/**
+ * The inverse: where a tenant-relative path (`theme.json`, `content`, `public`,
+ * `content/home.json`) lives in the tenant repo, per the declared mappings.
+ * Unmapped paths resolve to themselves — the flat checkout layout — so a
+ * consumer still finds files the mappings do not cover (and the config-coverage
+ * check reports the gap).
+ * @param {{ mappings?: unknown }} config
+ * @param {string} relPath tenant-relative, no leading `/`
+ * @returns {string}
+ */
+export function workspacePathForTenantRelative(config, relPath) {
+  const bare = relPath.replace(/\/$/, "");
+  for (const m of mappingsOf(config)) {
+    if (!m || typeof m !== "object" || typeof m.workspace !== "string") continue;
+    const target = parseMappingTarget(m.repo);
+    if (!target) continue;
+    const targetRel = target.rel.replace(/\/$/, "");
+    const ws = m.workspace.replace(/\/$/, "");
+    if (m.kind === "file") {
+      if (targetRel === bare) return ws;
+      continue;
+    }
+    if (m.kind !== "tree") continue;
+    if (targetRel === bare) return ws;
+    const prefix = asDir(targetRel);
+    if (bare.startsWith(prefix)) {
+      const rest = bare.slice(prefix.length);
+      return ws ? `${ws}/${rest}` : rest;
+    }
+  }
+  return bare;
+}
+
+/**
+ * Mappings whose declared target names a tenant segment other than the
+ * canonical tenant id. They still resolve correctly (the segment is never
+ * read); this exists so validators can tell the author the config disagrees
+ * with itself.
+ * @param {{ mappings?: unknown }} config
+ * @param {string} tenantId
+ * @returns {{ workspace: string, repo: string, segment: string }[]}
+ */
+export function foreignTenantSegments(config, tenantId) {
+  const out = [];
+  for (const m of mappingsOf(config)) {
+    if (!m || typeof m !== "object") continue;
+    const target = parseMappingTarget(m.repo);
+    if (target && target.segment !== tenantId) {
+      out.push({ workspace: String(m.workspace ?? ""), repo: m.repo, segment: target.segment });
+    }
+  }
+  return out;
+}

package/src/validate.mjs

@@ -5,7 +5,7 @@
  *
  * Design principle — "valid locally ≡ will reconcile in storefront": these checks
  * mirror the reconcile pipeline's own gate (@tot/private-controlplane
- * customization-reconcile.ts `mapToArtifact` / `validateRawHtml`). Kept in step
+ * customization-reconcile.ts `validateMappingShape` / `validateRawHtml`, and the shared mapping resolver `tot-repo-mappings.mjs`). Kept in step
  * with the in-repo source of truth `scripts/tenant/validate.mjs` (which the CI
  * regression test imports) — including its platform-route awareness (commerce
  * tenants own /collections, /products/<handle>, /search, /saved, /account, /cart,
@@ -17,6 +17,11 @@
  */
 import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
+import {
+  foreignTenantSegments,
+  parseMappingTarget,
+  workspacePathForTenantRelative,
+} from "./tot-repo-mappings.mjs";
 
 const NUL = String.fromCharCode(0);
 export const ERROR = "error";
@@ -63,9 +68,74 @@ const hasScanExt = (p) => CONFLICT_SCAN_EXT.has((p.match(/\.[^./\\]+$/) || [""])
 const KNOWN_KINDS = new Set(["file", "tree"]);
 const REQUIRED_WORKSPACES = ["content/", "public/", "theme.json"];
 
+// The keys the platform reads in `.tot/config.json`. 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.
+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 isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/**
+ * 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.
+ * @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[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;
+}
+
 /**
  * Validate a parsed `.tot/config.json` against the shape the reconcile pipeline
- * (`mapToArtifact`) requires. Pure — no I/O.
+ * (`validateMappingShape`) requires. Pure — no I/O.
  * @returns {Finding[]}
  */
 export function validateConfigShape(config, file = ".tot/config.json") {
@@ -76,6 +146,7 @@ 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"));
   }
+  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;
@@ -89,18 +160,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(
@@ -1025,16 +1107,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)) {
@@ -1045,14 +1120,46 @@ 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)"),
     );
   }
   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";
@@ -1062,18 +1169,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) {
@@ -1083,7 +1190,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) {
@@ -1093,7 +1200,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) {
@@ -1193,9 +1300,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"));
@@ -1214,9 +1319,8 @@ export function validateTenant(tenantDir, opts = {}) {
   // origin, is blocking; advisory (info) when there's no embeds.json to compare.
   {
     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 = new Set(value.filter((s) => typeof s === "string"));
     }
     for (const file of walk(contentDir, (p) => p.endsWith(".html"))) {