@tokenoftrust/cli 2.0.2 → 2.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "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/submit.mjs

@@ -52,7 +52,7 @@ import { checkoutTenant } from "./clone.mjs";
 // born-rebased submit rebuilds a candidate onto the current base with the SAME
 // engine `tot accept --refresh` uses, so the two read its result identically).
 import { normalizeRefreshResult } from "./accept.mjs";
-import { validateTenant, ERROR } from "../validate.mjs";
+import { validateTenant, ERROR, printLoudAdvisories } from "../validate.mjs";
 import { openBrowser } from "../open.mjs";
 import { startProgress } from "../progress.mjs";
 import { fail } from "../errors.mjs";
@@ -1356,33 +1356,15 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
 
   // 1. validate locally — refuse on errors.
   if (!args.skipValidate) {
-    /** Warnings that would otherwise be swallowed, but describe a defect that ships
-     *  looking healthy: [rule, headline, what it costs if ignored]. */
-    const LOUD_ADVISORY_RULES = [
-      [
-        "git-conflict-markers",
-        "git conflict markers in submitted content — an unfinished merge/rebase?",
-        "The preview will still build, but it will serve the broken markers. Resolve before shipping.",
-      ],
-      [
-        "duplicate-skip-link",
-        "duplicate skip link — your chrome already supplies one",
-        "The page renders fine and every automated check passes; a screen-reader user hears it twice.",
-      ],
-    ];
     const { ok, findings } = validateTenant(workspace, { tenantId: tenant, scope: ctx.config?.scope });
-    // Advisory but LOUD. Warnings are otherwise swallowed on the ok path, which is
-    // wrong for defects that SHIP SILENTLY: the preview builds, the console is clean,
-    // reconcile and compliance pass, and the flaw only surfaces to whoever reads the
-    // rendered page. Those get surfaced here — never blocking, since none of them
-    // makes the candidate unservable.
-    for (const [rule, headline, consequence] of LOUD_ADVISORY_RULES) {
-      const hits = findings.filter((f) => f.rule === rule);
-      if (!hits.length) continue;
-      console.error(`\n⚠ ${headline} (${hits.length} file(s))`);
-      for (const f of hits) console.error(`  ⚠ ${f.file} — ${f.message}`);
-      console.error(`  ${consequence}\n`);
-    }
+    // Advisory but LOUD (LOUD_ADVISORY_RULES, ../validate.mjs — shared with `tot
+    // validate` so the callout reads identically from either command). Warnings
+    // are otherwise swallowed on the ok path, which is wrong for defects that SHIP
+    // SILENTLY: the preview builds, the console is clean, reconcile and compliance
+    // pass, and the flaw only surfaces to whoever reads the rendered page. Those
+    // get surfaced here — never blocking, since none of them makes the candidate
+    // unservable.
+    printLoudAdvisories(findings);
     if (!ok) {
       const errs = findings.filter((f) => f.level === ERROR);
       console.error(

package/src/commands/validate.mjs

@@ -15,7 +15,7 @@
  */
 import { existsSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { validateTenant, ERROR, WARN } from "../validate.mjs";
+import { validateTenant, ERROR, WARN, printLoudAdvisories } from "../validate.mjs";
 import { fail } from "../errors.mjs";
 import { tenantDirSegments } from "../tenant-dirs.mjs";
 
@@ -94,6 +94,12 @@ export function run(argv, ctx) {
 
   const errors = findings.filter((f) => f.level === ERROR);
   const warns = findings.filter((f) => f.level === WARN);
+  // Named, grouped callouts for the advisories that ship a page looking healthy
+  // while quietly losing something — printed FIRST so the one step worth acting
+  // on (assign stable tracking ids) reads as a named step, not a warning buried
+  // among the full findings dump below. Same table `tot submit`/`tot preview`
+  // print, so the nudge reads identically wherever it's seen.
+  printLoudAdvisories(findings);
   // Never present the checkout PATH as if it were the tenant name — when the
   // tenant couldn't be resolved (e.g. an invalid/missing .tot/config.json),
   // the findings below say why; the header should say so too, not disguise

package/src/machine-id.mjs

@@ -0,0 +1,72 @@
+/**
+ * A stable per-machine identifier, persisted in `~/.tot/config.json` alongside
+ * whatever else already lives there. Read/write is additive — we merge just the
+ * `machineId` key in, so other tools' fields (e.g. `runtimes`) ride along
+ * untouched, same philosophy as token-store's schema-free credential file.
+ *
+ * Not a secret, but kept 0600 in a 0700 dir like the rest of `~/.tot` for
+ * consistency. `TOT_HOME` overrides the home dir (tests point it at a temp dir),
+ * like activity-log and token-store.
+ *
+ * Best-effort by contract: never throws. A persist failure still returns a
+ * usable (if unpersisted) id for the current call.
+ */
+import {
+  readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync,
+} from "node:fs";
+import { homedir, hostname } from "node:os";
+import { randomUUID } from "node:crypto";
+import { join, dirname } from "node:path";
+
+/** Absolute path to the machine-level config for this environment. */
+export function configPath(env = process.env) {
+  const home = env.TOT_HOME || homedir();
+  return join(home, ".tot", "config.json");
+}
+
+/** Read the parsed config, or {} if absent/unreadable/malformed. Never throws. */
+export function readConfig(env = process.env) {
+  try {
+    const parsed = JSON.parse(readFileSync(configPath(env), "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Merge `patch` into the existing config and write it back atomically (temp-file
+ * rename, 0600), preserving keys `patch` doesn't mention. Returns the merged
+ * config, or null on failure. Never throws.
+ */
+export function writeConfig(patch, env = process.env) {
+  try {
+    const filePath = configPath(env);
+    const merged = { ...readConfig(env), ...patch };
+    mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+    const tmp = `${filePath}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tmp, filePath);
+    chmodSync(filePath, 0o600);
+    return merged;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * This machine's stable id: read from config if present, else generate a UUID
+ * and persist it for next time. Never throws.
+ */
+export function ensureMachineId(env = process.env) {
+  const existing = readConfig(env).machineId;
+  if (typeof existing === "string" && existing) return existing;
+  const id = randomUUID();
+  const written = writeConfig({ machineId: id }, env);
+  return (written && written.machineId) || id;
+}
+
+/** This machine's hostname (not persisted — just os.hostname()). */
+export function host() {
+  return hostname();
+}

package/src/telemetry.mjs

@@ -0,0 +1,126 @@
+/**
+ * Git-ops telemetry — a durable, queryable record of fold/reap/sync/deploy stage
+ * transitions, so "what's slow / what's failing / what keeps needing a human" is
+ * answerable without a manual digging session after the fact.
+ *
+ * A SIBLING to activity-log.mjs, not an extension of it: activity-log is a
+ * 300-line RING (correct for its feedback-breadcrumb use case — bounded, most
+ * recent wins). Telemetry needs the opposite shape — unbounded, longitudinal
+ * history — so it uses a separate, date-partitioned, append-only stream:
+ * `~/.tot/telemetry/YYYY-MM.jsonl` (one file per UTC calendar month, partitioned
+ * by the entry's own `ts`), never truncated. Retention is "delete whole expired
+ * partitions" (see pruneOldPartitions), not the ring's overwrite-oldest-entry.
+ *
+ * Kept deliberately generic and self-describing: no coupling to
+ * workstream_analytics' event-journal shape. Callers own their own event schema
+ * (op/stage/reason codes are a separate concern — see the git-ops-telemetry
+ * handoff's U2 — not this module's).
+ *
+ * Append strategy differs from activity-log's temp+rename-the-whole-file (right
+ * for a small bounded ring, wrong here — it would mean rewriting a growing
+ * multi-KB month file on every single stage transition). Instead this appends
+ * with a single O_APPEND write() per entry: POSIX guarantees a single write()
+ * below PIPE_BUF is atomic, so concurrent writers (several git-ops scripts
+ * running at once, on one machine) can't interleave partial lines.
+ *
+ * NEVER throws / never blocks the caller — same best-effort contract as
+ * activity-log. `TOT_HOME` overrides the home dir (tests).
+ *
+ * A parallel POSIX-shell implementation lives at `scripts/lib/telemetry.sh` for
+ * the bash git-ops scripts this feeds — shelling out to `node` per stage
+ * transition would add measurement noise to the durations being measured. The
+ * two are separate, from-scratch implementations (no way to share code across
+ * languages); `scripts/lib/telemetry-cross-impl.test.mjs` exercises both against
+ * the same inputs and asserts schema-identical output as a drift guard. Any
+ * change to the on-disk shape here must be mirrored there.
+ */
+import {
+  appendFileSync, mkdirSync, chmodSync, readdirSync, rmSync, existsSync, readFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { redactArgs } from "./activity-log.mjs";
+import { ensureMachineId, host } from "./machine-id.mjs";
+
+/** Keep telemetry partitions for this many days; whole months older than this are pruned. */
+export const RETENTION_DAYS = 90;
+
+/** Directory holding all telemetry partitions for this environment. */
+export function telemetryDir(env = process.env) {
+  const home = env.TOT_HOME || homedir();
+  return join(home, ".tot", "telemetry");
+}
+
+/** The `YYYY-MM` partition key for a Date, in UTC. */
+export function monthKey(date) {
+  return date.toISOString().slice(0, 7);
+}
+
+/** Absolute path to the partition file a given Date's entries land in. */
+export function telemetryPath(date, env = process.env) {
+  return join(telemetryDir(env), `${monthKey(date)}.jsonl`);
+}
+
+function stamped(entry, env) {
+  const out = { ...entry };
+  if (!out.ts) out.ts = new Date().toISOString();
+  if (!out.host) out.host = host();
+  if (!out.machineId) out.machineId = ensureMachineId(env);
+  if (Array.isArray(out.args)) out.args = redactArgs(out.args);
+  return out;
+}
+
+/**
+ * Delete partitions wholly older than `retentionDays`. Cheap to run on every
+ * write: partition files number in the dozens at most (one per month), so a
+ * full directory listing per call is fine — no separate prune entrypoint or
+ * schedule to forget to run.
+ */
+export function pruneOldPartitions(env = process.env, { retentionDays = RETENTION_DAYS, now = new Date() } = {}) {
+  try {
+    const dir = telemetryDir(env);
+    if (!existsSync(dir)) return;
+    const cutoff = monthKey(new Date(now.getTime() - retentionDays * 24 * 60 * 60 * 1000));
+    for (const name of readdirSync(dir)) {
+      const match = name.match(/^(\d{4}-\d{2})\.jsonl$/);
+      if (match && match[1] < cutoff) {
+        rmSync(join(dir, name), { force: true });
+      }
+    }
+  } catch {
+    /* best-effort: never throw */
+  }
+}
+
+/**
+ * Append one telemetry entry to its month partition. Stamps `ts`/`host`/
+ * `machineId` when the caller omits them (never overrides an explicit value),
+ * redacts `args` if present (same secret flags as activity-log), and prunes
+ * expired partitions after a successful write. Returns the entry actually
+ * written, or null on failure. Never throws.
+ */
+export function recordTelemetry(entry, env = process.env) {
+  try {
+    const full = stamped(entry, env);
+    const dir = telemetryDir(env);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const filePath = telemetryPath(new Date(full.ts), env);
+    appendFileSync(filePath, `${JSON.stringify(full)}\n`, { mode: 0o600, flag: "a" });
+    chmodSync(filePath, 0o600);
+    pruneOldPartitions(env);
+    return full;
+  } catch {
+    return null;
+  }
+}
+
+/** Read parsed entries from one month's partition (default: current UTC month). Never throws. */
+export function readTelemetry(env = process.env, { month = "" } = {}) {
+  const key = month || monthKey(new Date());
+  const filePath = join(telemetryDir(env), `${key}.jsonl`);
+  try {
+    return readFileSync(filePath, "utf8").split("\n").filter(Boolean).map((line) => JSON.parse(line));
+  } catch {
+    return [];
+  }
+}

package/src/validate.mjs

@@ -144,6 +144,25 @@ function validateRawHtmlBody(html) {
 // test: packages/public-runtime/tests/chrome-config-shape-parity.test.ts.
 const CHROME_HEADER_VARIANTS = new Set(["primary", "minimal"]);
 const CHROME_FOOTER_VARIANTS = new Set(["default"]);
+/**
+ * The declarative-interaction-tracking rule, mirrored: every actionable item —
+ * an object carrying both `id` and `href` — declares EXACTLY ONE of a non-empty
+ * `action` (its stable intent) or `tracking: "none"` (an explicit opt-out).
+ * Declaring neither or both is a violation, and nothing is derived from `id`.
+ * Contract: docs/architecture/interaction-tracking-attribute-contract.md
+ */
+function chromeTrackingDeclared(value) {
+  if (Array.isArray(value)) return value.every(chromeTrackingDeclared);
+  if (value == null || typeof value !== "object") return true;
+  if (typeof value.id === "string" && typeof value.href === "string") {
+    const hasAction = typeof value.action === "string" && value.action.trim() !== "";
+    const optedOut = value.tracking === "none";
+    if (hasAction === optedOut) return false;
+    if (value.tracking !== undefined && !optedOut) return false;
+  }
+  return Object.values(value).every(chromeTrackingDeclared);
+}
+
 export function looksLikeChromeConfig(value) {
   if (value == null || typeof value !== "object" || Array.isArray(value)) return false;
   const header = value.header;
@@ -156,6 +175,7 @@ export function looksLikeChromeConfig(value) {
   if (footer == null || typeof footer !== "object" || Array.isArray(footer)) return false;
   if (!CHROME_FOOTER_VARIANTS.has(footer.variant)) return false;
   if (!Array.isArray(footer.columns)) return false;
+  if (!chromeTrackingDeclared(value)) return false;
   return true;
 }
 
@@ -428,6 +448,278 @@ function validateHomeDoc(doc, file) {
   return out;
 }
 
+// --- CTA / actionable-identity advisory rules (unit dt-validator-cta-rules) -
+// Three ADVISORY warnings (never block) that a schema pass alone doesn't
+// reach. `validateChromeConfig` (@tot/public-runtime chrome.ts) already
+// HARD-FAILS the governed chrome.json path on the either/or action/
+// tracking:"none" rule (interaction-tracking.ts validateTracking) — this
+// validator does not re-run that schema (deep per-item errors are the
+// write-path's job, per the looksLikeChromeConfig comment above). These three
+// catch what the schema pass doesn't:
+//   - `duplicate-cta`   — a copy-paste mistake that still PASSES schema (two
+//     actionable items sharing one governed identity).
+//   - `cta-missing-id`  — tenant-authored raw HTML fragments carry NO
+//     `data-tot-*` at all pre-derivation (see docs/architecture/interaction-
+//     tracking-attribute-contract.md "Deriving data-tot-el") — there is no
+//     schema here for validateChromeConfig to fail.
+//   - `cta-id-drift`    — `data-tot-el` is a PERMANENT identity per
+//     dt-contract-v1's decision ledger ("a change here is DRIFT and is a
+//     defect"); this one needs a PRIOR version to compare against, which a
+//     single-snapshot validateTenant() run doesn't have on its own — see
+//     `opts.previousChromeJson`, below.
+// Kept in step with scripts/tenant/validate.mjs's identical copy of this block.
+
+// --- "assign stable tracking ids" — the one named, actionable step (unit
+// dt-assign-ids-step). The three rules above are DETECTION; this is the single
+// place every touchpoint (`tot validate`, `tot submit`/`tot preview`, and the
+// `tot dev` save-loop nudge — scripts/dev/checkout-watch.mjs) points an author
+// at the SAME fix in the SAME words, so it reads as one coherent nudge no
+// matter which command surfaced it, never a fresh, differently-worded warning
+// each time. The mechanism already exists (derivation: dt-id-derivation;
+// writeback: dt-id-writeback, apps/storefront/src/pages/api/admin/tracking-
+// writeback.ts) — this names the step and points at it, it invents nothing.
+export const TRACKING_ID_STEP_NAME = "assign stable tracking ids";
+export const CTA_MISSING_ID_FIX =
+  "assign stable tracking ids: GET/POST /api/admin/tracking-writeback proposes a data-tot-el for every element that's missing one, as a reviewable candidate PR (GET first for a dry-run preview) — or run `tot validate` to see the full list before you submit.";
+
+/**
+ * The advisory rules LOUD enough to call out by NAME at `tot validate` / `tot
+ * submit` / `tot preview` — none of them block, but each ships a page that
+ * looks perfectly healthy (clean build, every other check green) while
+ * quietly losing something. `[rule, headline, what it costs if ignored]`.
+ * ONE place so every surface prints identical wording (see the block comment
+ * above); `printLoudAdvisories` is the shared renderer.
+ */
+export const LOUD_ADVISORY_RULES = [
+  [
+    "git-conflict-markers",
+    "git conflict markers in submitted content — an unfinished merge/rebase?",
+    "The preview will still build, but it will serve the broken markers. Resolve before shipping.",
+  ],
+  [
+    "duplicate-skip-link",
+    "duplicate skip link — your chrome already supplies one",
+    "The page renders fine and every automated check passes; a screen-reader user hears it twice.",
+  ],
+  [
+    "duplicate-cta",
+    "duplicate CTA identity — two actionable items share one data-tot-el",
+    "Both elements still work, but the click listener and every downstream analytics query treat them as ONE interaction — you lose the ability to tell them apart.",
+  ],
+  [
+    "cta-missing-id",
+    `actionable element with no governed identity (data-tot-el) — needs to ${TRACKING_ID_STEP_NAME}`,
+    `It renders and works fine, but it's invisible to interaction tracking — nothing about it is ever recorded. ${CTA_MISSING_ID_FIX}`,
+  ],
+  [
+    "cta-id-drift",
+    "a previously-declared data-tot-el changed value",
+    "The page still works, but everything already recorded under the old id is now orphaned — this identity is supposed to be permanent.",
+  ],
+];
+
+/**
+ * Print the LOUD-but-advisory findings as named, grouped callouts — one block
+ * per rule with a headline, every hit, and the consequence of ignoring it —
+ * so the step worth acting on (assign stable tracking ids) reads as a NAMED
+ * step, not a warning buried among dozens. Shared by `tot validate` and `tot
+ * submit`/`tot preview` so a developer sees the identical callout regardless
+ * of which command surfaced it. `log` defaults to `console.error` (this CLI's
+ * existing convention for advisory noise); injectable for tests.
+ * @param {Finding[]} findings
+ * @param {{ log?: (s: string) => void }} [opts]
+ */
+export function printLoudAdvisories(findings, { log = (s) => console.error(s) } = {}) {
+  for (const [rule, headline, consequence] of LOUD_ADVISORY_RULES) {
+    const hits = findings.filter((f) => f.rule === rule);
+    if (!hits.length) continue;
+    log(`\n⚠ ${headline} (${hits.length} finding(s))`);
+    for (const f of hits) log(`  ⚠ ${f.file} — ${f.message}`);
+    log(`  ${consequence}\n`);
+  }
+}
+
+/** Every declared actionable `id` in a ChromeConfig, with a path for
+ *  messages — the SAME field rawChrome.ts / SiteHeader.astro stamp verbatim as
+ *  `data-tot-el` (ctaIdentityAttr for header.ctas; the direct `id` field on
+ *  every other actionable shape — see @tot/public-runtime chrome.ts's
+ *  ChromeLink/ChromeNavItem/ChromeCta/ChromeActionLink), so a collision here
+ *  is a collision of GOVERNED IDENTITY, not just of an authoring label. Walks
+ *  the same shapes validateChromeConfig itself walks. Pure.
+ */
+function collectChromeActionableIds(config) {
+  const out = [];
+  const push = (id, path) => {
+    if (typeof id === "string" && id.trim()) out.push({ id: id.trim(), path });
+  };
+  const header = config?.header;
+  if (header && typeof header === "object" && !Array.isArray(header)) {
+    for (const [i, n] of (Array.isArray(header.nav) ? header.nav : []).entries()) {
+      if (n == null || typeof n !== "object") continue;
+      push(n.id, `header.nav[${i}]`);
+      for (const [j, c] of (Array.isArray(n.children) ? n.children : []).entries()) {
+        if (c && typeof c === "object") push(c.id, `header.nav[${i}].children[${j}]`);
+      }
+      for (const [j, col] of (Array.isArray(n.columns) ? n.columns : []).entries()) {
+        if (col == null || typeof col !== "object") continue;
+        for (const [k, l] of (Array.isArray(col.links) ? col.links : []).entries()) {
+          if (l && typeof l === "object") push(l.id, `header.nav[${i}].columns[${j}].links[${k}]`);
+        }
+      }
+    }
+    for (const [i, c] of (Array.isArray(header.ctas) ? header.ctas : []).entries()) {
+      if (c && typeof c === "object") push(c.id, `header.ctas[${i}]`);
+    }
+    if (header.memberCue && typeof header.memberCue === "object") push(header.memberCue.id, "header.memberCue");
+    const u = header.utilityNav;
+    if (u && typeof u === "object" && !Array.isArray(u)) {
+      for (const [i, l] of (Array.isArray(u.links) ? u.links : []).entries()) {
+        if (l && typeof l === "object") push(l.id, `header.utilityNav.links[${i}]`);
+      }
+      if (u.memberCue && typeof u.memberCue === "object") push(u.memberCue.id, "header.utilityNav.memberCue");
+    }
+  }
+  const footer = config?.footer;
+  if (footer && typeof footer === "object" && !Array.isArray(footer)) {
+    for (const [i, col] of (Array.isArray(footer.columns) ? footer.columns : []).entries()) {
+      if (col == null || typeof col !== "object") continue;
+      for (const [j, l] of (Array.isArray(col.links) ? col.links : []).entries()) {
+        if (l && typeof l === "object") push(l.id, `footer.columns[${i}].links[${j}]`);
+      }
+    }
+  }
+  return out;
+}
+
+/** `duplicate-cta`: two or more actionable items in one ChromeConfig resolve
+ *  to the SAME governed identity. Almost always a copy-paste authoring
+ *  mistake — the click listener's `closest("[data-tot-el]")` match and every
+ *  downstream analytics query assume one element per id, so a duplicate
+ *  silently merges two distinct interactions' data. WARN, never blocks: the
+ *  page still renders and both elements still work.
+ */
+function findDuplicateCtaIds(config, file) {
+  const byId = new Map();
+  for (const { id, path } of collectChromeActionableIds(config)) {
+    if (!byId.has(id)) byId.set(id, []);
+    byId.get(id).push(path);
+  }
+  const out = [];
+  for (const [id, paths] of byId) {
+    if (paths.length > 1) {
+      out.push(
+        mk(WARN, "duplicate-cta", file,
+          `id "${id}" is declared on ${paths.length} actionable items (${paths.join(", ")}) — data-tot-el must be unique per element; the click listener's closest() match and downstream analytics both assume one`,
+          "give every occurrence but one a distinct id"),
+      );
+    }
+  }
+  return out;
+}
+
+/**
+ * `cta-id-drift`: a governed actionable item's `data-tot-el` changed value
+ * between two versions of the SAME chrome.json, matched by structural
+ * position (e.g. "header.ctas[0]") — the same slot in both versions. Per
+ * dt-contract-v1's ledger `data-tot-el` is a PERMANENT identity ("a change
+ * here is DRIFT and is a defect"), unlike `data-tot-placement` which is
+ * expected to move on redesign.
+ *
+ * `previous` is an OPTIONAL caller-supplied prior chrome.json (already
+ * parsed) — this static, single-snapshot validator has no version history of
+ * its own, and no existing publish/preview utility in this repo diffs the
+ * CTA IDENTITY LIST across versions (apps/storefront/src/lib/publish and
+ * .../preview diff release ARTIFACT BYTES for the release panel, never this)
+ * to hook into instead. A version-aware caller (a future publish-time check,
+ * `tot validate --against <ref>`) supplies `previous`; this run alone never
+ * invents one, so omitting it is a silent no-op, not a missing check.
+ *
+ * A reorder/insert that shifts array positions can produce a false
+ * positive/negative here (position, not the item's own identity, is the
+ * match key) — a known limitation of matching without a stronger anchor.
+ */
+function findCtaIdDrift(previous, current, file) {
+  if (previous == null || typeof previous !== "object") return [];
+  const before = new Map(collectChromeActionableIds(previous).map((e) => [e.path, e.id]));
+  const out = [];
+  for (const { id, path } of collectChromeActionableIds(current)) {
+    const priorId = before.get(path);
+    if (priorId !== undefined && priorId !== id) {
+      out.push(
+        mk(WARN, "cta-id-drift", file,
+          `${path}.id changed from "${priorId}" to "${id}" — data-tot-el is a permanent identity; a change here is drift, not a redesign, and breaks continuity with everything already recorded under the old id`,
+          "keep the original id (a deliberate identity migration is a separate, tracked decision, not an incidental edit)"),
+      );
+    }
+  }
+  return out;
+}
+
+// Compact mirror of @tot/public-runtime tracking-id-derivation.ts's trackable-
+// tag set and `isWellFormedTrackingId` shape check — this script can't import
+// that TS package at runtime (same published-CLI/no-build-step constraint as
+// the chrome-shape mirrors above). Deliberately simplified: full structural
+// derivation (region path, confidence) needs a real parser and an ancestor
+// stack; this is a flat regex tag scan (the same style as HREF_RE/SRC_RE
+// above), so it only answers "does this element carry a well-formed
+// data-tot-el at all", not "what would a good one look like".
+const ACTIONABLE_TAG_RE = /<([a-z][a-z0-9-]*)\b([^>]*)>/gi;
+const TRACKABLE_HTML_TAGS = new Set(["a", "area", "button", "details", "summary", "form", "input", "select", "textarea", "label"]);
+const TRACKABLE_HTML_ROLES = new Set(["button", "link", "tab", "menuitem", "switch", "checkbox"]);
+
+function htmlAttr(attrs, name) {
+  const m = new RegExp(`\\b${name}\\s*=\\s*"([^"]*)"`, "i").exec(attrs);
+  return m ? m[1] : undefined;
+}
+
+/** Mirror of tracking-id-derivation.ts's `isTrackableNode`: an `<a>`/`<area>`
+ *  needs a real `href`; the fixed tag set is always a candidate; anything
+ *  else needs an interactive ARIA role. */
+function isTrackableHtmlTag(tag, attrs) {
+  if (tag === "a" || tag === "area") {
+    const href = htmlAttr(attrs, "href");
+    return typeof href === "string" && href.trim().length > 0;
+  }
+  if (TRACKABLE_HTML_TAGS.has(tag)) return true;
+  const role = htmlAttr(attrs, "role");
+  return typeof role === "string" && TRACKABLE_HTML_ROLES.has(role.trim().toLowerCase());
+}
+
+/** Mirror of tracking-id-derivation.ts's `isWellFormedTrackingId`: lowercase
+ *  kebab tokens, non-empty, within the same 64-char budget. */
+function isWellFormedCtaId(el) {
+  return typeof el === "string" && el.length > 0 && el.length <= 64 && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(el);
+}
+
+/**
+ * `cta-missing-id`: a tenant-authored HTML fragment's actionable element
+ * carries no well-formed `data-tot-el`. Tenant fragments ship NO `data-tot-*`
+ * at all pre-derivation (docs/architecture/interaction-tracking-attribute-
+ * contract.md "Deriving data-tot-el") — `validateChromeConfig`'s hard
+ * either/or failure only reaches the SCHEMA-GOVERNED chrome.json path, never
+ * a raw fragment, so an un-identified CTA here would otherwise ship silently
+ * unmeasurable: the page renders fine, every other check passes, and the
+ * element is simply invisible to interaction tracking. WARN, never blocks.
+ */
+function findMissingCtaIds(html, file) {
+  const out = [];
+  ACTIONABLE_TAG_RE.lastIndex = 0;
+  let m;
+  while ((m = ACTIONABLE_TAG_RE.exec(html))) {
+    const tag = m[1].toLowerCase();
+    const attrs = m[2] || "";
+    if (!isTrackableHtmlTag(tag, attrs)) continue;
+    const totEl = htmlAttr(attrs, "data-tot-el");
+    if (isWellFormedCtaId(totEl)) continue;
+    out.push(
+      mk(WARN, "cta-missing-id", file,
+        `a <${tag}> actionable element has ${totEl ? `a malformed data-tot-el (${JSON.stringify(totEl)})` : "no data-tot-el"} — it renders and functions but is invisible to interaction tracking`,
+        CTA_MISSING_ID_FIX),
+    );
+  }
+  return out;
+}
+
 // --- filesystem helpers ------------------------------------------------------
 function readJsonSafe(path) {
   try {
@@ -517,10 +809,13 @@ function resolvePlatformRouteOwnership(config, hostIsPlatform) {
 /**
  * Full static validation of a tenant directory (content/ public/ theme.json [.tot/]).
  * @param {string} tenantDir absolute path to the tenant dir
- * @param {{tenantId?:string, scope?:string, mode?:"monorepo"|"workspace"}} [opts]
+ * @param {{tenantId?:string, scope?:string, mode?:"monorepo"|"workspace", previousChromeJson?:any}} [opts]
  *   `mode` — "monorepo" (default): served by this platform, so commerce tenants own
  *   the framework routes. "workspace": a standalone checkout, conservative about
  *   platform-route ownership unless the config resolves the host (`hostPlatform`).
+ *   `previousChromeJson` — an already-parsed PRIOR version of content/chrome.json,
+ *   supplied by a version-aware caller, so the `cta-id-drift` check has something
+ *   to compare against (see findCtaIdDrift above). Omitted ⇒ that check is a no-op.
  * @returns {{ok:boolean, findings:Finding[]}}
  */
 export function validateTenant(tenantDir, opts = {}) {
@@ -613,6 +908,11 @@ export function validateTenant(tenantDir, opts = {}) {
         findings.push(mk(ERROR, "content-json-parse", `content/${name}`, `invalid JSON: ${error} (fails the build)`));
       } else if (name === "home.json") {
         findings.push(...validateHomeDoc(value, "content/home.json"));
+      } else if (name === "chrome.json") {
+        findings.push(...findDuplicateCtaIds(value, "content/chrome.json"));
+        if (opts.previousChromeJson != null) {
+          findings.push(...findCtaIdDrift(opts.previousChromeJson, value, "content/chrome.json"));
+        }
       }
     }
   }
@@ -663,6 +963,9 @@ export function validateTenant(tenantDir, opts = {}) {
           "use a bare <style> tag"),
       );
     }
+    // actionable elements with no (or malformed) governed identity — advisory,
+    // never blocking (see findMissingCtaIds above).
+    findings.push(...findMissingCtaIds(html, r));
 
     for (const m of html.matchAll(HREF_RE)) {
       findings.push(...checkLink(m[1].trim(), r, scope, pageTargets, platformRoutes.owns));