@tokenoftrust/storefront-runner 2.0.4 → 2.0.5

package/apps/storefront/src/lib/tracking/publishSafetyNet.ts

@@ -0,0 +1,162 @@
+/**
+ * Publish-time `data-tot-el` safety net — the FALLBACK identity path for
+ * content that never flows through git review.
+ *
+ * `dt-id-writeback` (a sibling unit) is the PRIMARY path: a git-time rewriter
+ * that proposes `data-tot-el` for git-tracked tenant content and writes it
+ * back to source as a reviewable diff. This module exists for everything
+ * that bypasses that review — AI-edit drafts materialized into
+ * `dev-draft:` KV (see `DevDraftContentProvider`, lib/storyblok/provider.ts)
+ * and direct KV-published edits (`PublishedContentProvider`'s overlay over
+ * the customization store). Content sourced from `LocalContentProvider`
+ * (build-bundled from git-tracked `tenants/<id>/content/*`) is explicitly
+ * OUT of scope here — it is dt-id-writeback's job, and re-stamping it here
+ * would fight a human-reviewed, permanently-committed id.
+ *
+ * Shares the SAME structural derivation engine
+ * (`@tot/public-runtime`'s tracking-id-derivation.ts) the git-time rewriter
+ * uses, fed from an `HTMLRewriter` element/end-tag callback pair instead of
+ * a `parse5` tree — see the "Feeding it" section of
+ * docs/architecture/interaction-tracking-attribute-contract.md and
+ * dt-id-derivation's handoff note ("keep an ancestor stack across
+ * HTMLRewriter element/end-tag callbacks and derive at the open tag; one
+ * deriver per document").
+ *
+ * NO DOM-TEXT READS: only `element.tagName` and `element.attributes` are
+ * ever read here, matching the payload guardrail
+ * tracking-id-derivation.ts's own module doc documents and tests (a source
+ * sweep + a closed attribute allowlist) — never `element.text`, never a
+ * child's character data.
+ */
+import {
+  createTrackingIdDeriver,
+  isTrackableNode,
+  TRACKING_ATTR_EL,
+  type StructuralNode,
+} from "@tot/public-runtime";
+
+/**
+ * HTML elements with no end tag. Never pushed onto the ancestor stack, and
+ * `onEndTag` is never registered for them — HTMLRewriter would never call a
+ * callback registered on a void element's (nonexistent) end tag.
+ */
+const VOID_TAGS: ReadonlySet<string> = new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr",
+]);
+
+/**
+ * Minimal shape of the Workers `HTMLRewriter` Element handler this module
+ * needs. Deliberately NOT `@cloudflare/workers-types` (not installed in this
+ * repo — see apps/storefront/env.d.ts's own note) — a local, narrow surface
+ * so this file typechecks in both the Workers runtime and plain Node/vitest.
+ */
+interface RewriterElement {
+  tagName: string;
+  attributes: IterableIterator<[string, string]>;
+  /** True for a void element or one written self-closed (`<foo />`) — either
+   * way, no end tag will ever fire for it. */
+  selfClosing?: boolean;
+  setAttribute(name: string, value: string): void;
+  onEndTag(handler: () => void | Promise<void>): void;
+}
+
+interface MinimalHTMLRewriter {
+  on(selector: string, handlers: { element(el: RewriterElement): void }): MinimalHTMLRewriter;
+  transform(response: Response): Response;
+}
+
+type HTMLRewriterCtor = new () => MinimalHTMLRewriter;
+
+function getHtmlRewriterCtor(): HTMLRewriterCtor | null {
+  const ctor = (globalThis as Record<string, unknown>).HTMLRewriter;
+  return typeof ctor === "function" ? (ctor as HTMLRewriterCtor) : null;
+}
+
+/**
+ * True when the Workers `HTMLRewriter` global is available in this runtime.
+ * Absent in plain Node (vitest, `astro check`, a bare `node` script) — every
+ * caller must treat a false return as "pass the content through unchanged",
+ * never throw. Exported so tests can assert the no-op fallback explicitly.
+ */
+export function hasHtmlRewriter(): boolean {
+  return getHtmlRewriterCtor() !== null;
+}
+
+/** Build the closed-allowlist-fed attrs bag HTMLRewriter's Element exposes. */
+function attrsOf(element: RewriterElement): Record<string, string> {
+  const attrs: Record<string, string> = {};
+  for (const [name, value] of element.attributes) attrs[name] = value;
+  return attrs;
+}
+
+/**
+ * Stamp `data-tot-el` onto every trackable element in `html` that doesn't
+ * already declare one — a single streaming pass, ONE deriver for the whole
+ * document (so ids stay unique within it), maintaining an outermost-first
+ * open-tag stack across element/end-tag callbacks the same way a `parse5`
+ * tree walk would.
+ *
+ * An element that already carries `data-tot-el` (confidence: "declared") is
+ * left completely untouched — its value is only `reserve()`-d into this
+ * document's deriver, so a later element in the SAME pass can never propose
+ * a colliding id. There is no pre-scan pass (this repo has no prior art for
+ * one over raw tenant HTML at publish time — see the module doc): a
+ * declared id that appears LATER in the document than an already-derived
+ * proposal is a known, accepted single-pass limitation, no worse than
+ * shipping no identity for this content at all.
+ *
+ * No-op (returns `html` unchanged) when `HTMLRewriter` isn't available in
+ * this runtime.
+ */
+export async function stampTrackingIdsAtPublish(html: string): Promise<string> {
+  const HTMLRewriter = getHtmlRewriterCtor();
+  if (!HTMLRewriter) return html;
+
+  const deriver = createTrackingIdDeriver();
+  // Outermost-first open-tag stack, shared across every element/end-tag
+  // callback for the WHOLE document — one deriver, one stack, per document
+  // (dt-id-derivation's handoff note).
+  const stack: StructuralNode[] = [];
+
+  const rewriter = new HTMLRewriter().on("*", {
+    element(element: RewriterElement) {
+      const tag = element.tagName.toLowerCase();
+      const attrs = attrsOf(element);
+      const node: StructuralNode = { tag, attrs };
+      const existing = attrs[TRACKING_ATTR_EL];
+
+      if (existing && existing.trim().length > 0) {
+        // confidence: "declared" — already identified. Leave it alone; just
+        // reserve it so nothing derived later in this pass can collide.
+        deriver.reserve(existing);
+      } else if (isTrackableNode(node)) {
+        const ancestors = stack.slice();
+        const derived = deriver.derive({ node, ancestors });
+        element.setAttribute(TRACKING_ATTR_EL, derived.el);
+      }
+
+      if (!VOID_TAGS.has(tag) && !element.selfClosing) {
+        stack.push(node);
+        element.onEndTag(() => {
+          stack.pop();
+        });
+      }
+    },
+  });
+
+  const rewritten = rewriter.transform(new Response(html));
+  return await rewritten.text();
+}

package/apps/storefront/src/lib/tracking/tenantD1Registry.ts

@@ -0,0 +1,214 @@
+/**
+ * Resolve (and, on first sight, provision) ONE TENANT'S OWN raw-interaction D1
+ * database.
+ *
+ * The isolation claim of `dt-storage-per-tenant-d1` rests on this module: the
+ * ONLY way the write path gets a database handle is `resolveTenantStore()`,
+ * which takes a tenant id and returns a `Queryable` bound to that tenant's
+ * database UUID and nothing else. There is no handle in this codebase that
+ * spans two tenants' raw rows, so a forgotten `WHERE tenant_id = ?` cannot leak
+ * across tenants — the wrong-tenant rows are not in the database being queried.
+ *
+ * THE THREE STEPS, all idempotent and all cached per isolate:
+ *   1. NAME   — derive the database name deterministically from the tenant id
+ *               (`<prefix>-<sanitized tenant>-<8 hex of sha256(tenant)>`). The
+ *               hash suffix is what keeps the mapping injective after
+ *               sanitizing: two distinct tenant ids that sanitize to the same
+ *               slug still get different databases.
+ *   2. DIRECTORY — read `tracking_tenant_databases` in the shared
+ *               STOREFRONT_APPS_DB for an existing `(name, uuid)`. Present ⇒
+ *               done, zero control-plane calls on the hot path.
+ *   3. PROVISION — absent ⇒ find-or-create the D1 database over REST, apply the
+ *               idempotent schema, stamp `interaction_store_meta`, and record
+ *               the mapping in the directory. Concurrent first-beacons race
+ *               benignly: `ensureDatabase` re-resolves by name and the
+ *               directory write is an upsert.
+ *
+ * BEST-EFFORT, NEVER THROWS. Every entry point returns `undefined` when the
+ * store cannot be reached (no REST credentials, no apps-DB directory, a
+ * control-plane error) — "sink unavailable, skip it", the posture
+ * `activity/store.ts` already sets for an unbound sink. A telemetry beacon must
+ * never fail because storage is unconfigured.
+ */
+import { sha256Hex } from "@tot/public-runtime";
+import { readEnv } from "../env.js";
+import type { Queryable } from "../d1/catalog.js";
+import {
+  ensureDatabase,
+  fromD1Rest,
+  type D1ControlConfig,
+} from "./d1Control.js";
+import {
+  INTERACTION_D1_SCHEMA,
+  INTERACTION_SCHEMA_VERSION,
+  interactionMetaUpsert,
+} from "./interactionSchema.js";
+
+/** Fallback name prefix when `TRACKING_D1_NAME_PREFIX` is unset. */
+const DEFAULT_NAME_PREFIX = "tot-storefront-dt";
+
+/** D1 database names are limited; keep the readable slug well inside it. */
+const MAX_SLUG_LEN = 32;
+
+/** A resolved per-tenant store: the tenant it belongs to and its query handle. */
+export interface TenantInteractionStore {
+  tenantId: string;
+  databaseName: string;
+  databaseUuid: string;
+  db: Queryable;
+}
+
+/** One directory row of `tracking_tenant_databases`. */
+export interface TenantDatabaseRecord {
+  tenant_id: string;
+  database_name: string;
+  database_uuid: string;
+  schema_version: number;
+}
+
+/**
+ * Deterministic, injective database name for a tenant. The readable slug is for
+ * humans in the Cloudflare dashboard; the hash suffix is what guarantees two
+ * different tenant ids never collide onto one database even when their slugs do.
+ */
+export async function tenantDatabaseName(tenantId: string, prefix: string): Promise<string> {
+  const slug =
+    tenantId
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, MAX_SLUG_LEN)
+      .replace(/-+$/, "") || "tenant";
+  const digest = (await sha256Hex(tenantId)).slice(0, 8);
+  return `${prefix}-${slug}-${digest}`;
+}
+
+/** The configured name prefix for this environment. */
+export async function trackingNamePrefix(): Promise<string> {
+  return (await readEnv("TRACKING_D1_NAME_PREFIX")) ?? DEFAULT_NAME_PREFIX;
+}
+
+/** Read a tenant's directory row, or null. Never throws. */
+export async function readTenantDatabase(
+  apps: Queryable,
+  tenantId: string,
+): Promise<TenantDatabaseRecord | null> {
+  try {
+    return await apps.first<TenantDatabaseRecord>(
+      `SELECT tenant_id, database_name, database_uuid, schema_version
+         FROM tracking_tenant_databases WHERE tenant_id = ?`,
+      tenantId,
+    );
+  } catch {
+    return null;
+  }
+}
+
+/** Upsert a tenant's directory row. Never throws. */
+export async function recordTenantDatabase(
+  apps: Queryable,
+  record: { tenantId: string; databaseName: string; databaseUuid: string; at: string },
+): Promise<void> {
+  try {
+    await apps.run(
+      `INSERT INTO tracking_tenant_databases
+         (tenant_id, database_name, database_uuid, schema_version, created_at, updated_at, pruned_rows)
+       VALUES (?,?,?,?,?,?,0)
+       ON CONFLICT(tenant_id) DO UPDATE SET
+         database_name = excluded.database_name,
+         database_uuid = excluded.database_uuid,
+         schema_version = excluded.schema_version,
+         updated_at = excluded.updated_at`,
+      record.tenantId,
+      record.databaseName,
+      record.databaseUuid,
+      INTERACTION_SCHEMA_VERSION,
+      record.at,
+      record.at,
+    );
+  } catch (err) {
+    console.error(
+      `[tracking:interaction] directory write failed for ${record.tenantId}: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+}
+
+/** Apply the idempotent per-tenant schema and stamp its meta row. */
+export async function applyInteractionSchema(
+  db: Queryable,
+  tenantId: string,
+  at: string,
+): Promise<void> {
+  await db.exec(INTERACTION_D1_SCHEMA);
+  const meta = interactionMetaUpsert(tenantId, at);
+  await db.run(meta.sql, ...meta.params);
+}
+
+/** Injected seams — so the whole resolution is testable without Cloudflare. */
+export interface ResolveDeps {
+  /** The shared STOREFRONT_APPS_DB handle holding the directory table. */
+  apps: Queryable;
+  /** D1 REST credentials + transport. */
+  control: D1ControlConfig;
+  /** Environment-scoped database-name prefix. */
+  namePrefix: string;
+  /** ISO-8601 "now", for the directory + meta rows. */
+  at: string;
+}
+
+/**
+ * Resolve a tenant's store, provisioning it on first sight. Returns undefined
+ * when the store cannot be reached — never throws.
+ *
+ * A resolved handle is cached per isolate (`storeCache`) so the steady state is
+ * ZERO control-plane and ZERO directory calls per beacon.
+ */
+const storeCache = new Map<string, TenantInteractionStore>();
+
+/** Test seam: drop the per-isolate resolution cache. */
+export function clearTenantStoreCache(): void {
+  storeCache.clear();
+}
+
+export async function resolveTenantStore(
+  tenantId: string,
+  deps: ResolveDeps,
+): Promise<TenantInteractionStore | undefined> {
+  if (!tenantId) return undefined;
+  const cached = storeCache.get(tenantId);
+  if (cached) return cached;
+
+  try {
+    const existing = await readTenantDatabase(deps.apps, tenantId);
+    if (existing && existing.schema_version >= INTERACTION_SCHEMA_VERSION) {
+      const store: TenantInteractionStore = {
+        tenantId,
+        databaseName: existing.database_name,
+        databaseUuid: existing.database_uuid,
+        db: fromD1Rest(deps.control, existing.database_uuid),
+      };
+      storeCache.set(tenantId, store);
+      return store;
+    }
+
+    // First sight for this tenant (or a schema bump): provision.
+    const databaseName = existing?.database_name ?? (await tenantDatabaseName(tenantId, deps.namePrefix));
+    const databaseUuid = existing?.database_uuid ?? (await ensureDatabase(deps.control, databaseName));
+    const db = fromD1Rest(deps.control, databaseUuid);
+    await applyInteractionSchema(db, tenantId, deps.at);
+    await recordTenantDatabase(deps.apps, { tenantId, databaseName, databaseUuid, at: deps.at });
+
+    const store: TenantInteractionStore = { tenantId, databaseName, databaseUuid, db };
+    storeCache.set(tenantId, store);
+    return store;
+  } catch (err) {
+    console.error(
+      `[tracking:interaction] store resolution failed for ${tenantId}: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+    return undefined;
+  }
+}

package/apps/storefront/src/lib/tracking/tenantReadAccess.ts

@@ -0,0 +1,138 @@
+/**
+ * Merchant-facing READ authorization over the per-tenant interaction D1
+ * databases `dt-storage-per-tenant-d1` built (`tenantD1Registry.ts`,
+ * `interactionStore.ts`). This is `dt-tenant-isolation`: the release-order
+ * doc's hard invariant is "no merchant-visible surface ships until this
+ * lands", and this module is that surface's data-access layer.
+ *
+ * THE ISOLATION GUARANTEE THIS MODULE RELIES ON (built by
+ * `dt-storage-per-tenant-d1`, not re-implemented here): `resolveTenantStore`
+ * is the ONLY way to get a `Queryable`, and it is bound to exactly one
+ * tenant's database UUID. There is no handle anywhere that spans two
+ * tenants' rows, so every function below is safe to call with an UNSCOPED
+ * `SELECT` — the database itself is the isolation boundary, not the `WHERE`
+ * clause. A `tenant_id = ?` predicate is still included below (matching the
+ * `TenantInteractionStore.tenantId` the caller resolved — NEVER a
+ * client-suppliable value) as defence-in-depth and to keep the row's
+ * redundant `tenant_id` column meaningful, not because it is what makes the
+ * isolation hold.
+ *
+ * `assertStoreOwnership` is the extra check this unit adds on top: before
+ * trusting a resolved store for a read, confirm `interaction_store_meta`
+ * (stamped by `dt-storage-per-tenant-d1` at provision time) actually says
+ * this database belongs to the tenant we resolved it for. A resolution bug
+ * that somehow handed back the wrong store is caught here rather than
+ * silently serving the wrong tenant's rows to a merchant.
+ */
+import type { TenantInteractionStore } from "./tenantD1Registry.js";
+
+/** One row of the merchant-visible recent-events feed. */
+export interface RecentInteractionEvent {
+  type: string;
+  el: string;
+  action: string | null;
+  placement: string | null;
+  scope: string | null;
+  ts: string;
+  ingestedAt: string;
+}
+
+/** One rolled-up (action, el) count — the merchant-visible summary shape. */
+export interface InteractionActionCount {
+  el: string;
+  action: string;
+  count: number;
+}
+
+export interface InteractionInsights {
+  totalEvents: number;
+  byAction: InteractionActionCount[];
+  recent: RecentInteractionEvent[];
+}
+
+/** Cap on the recent-events feed — a dashboard preview, not an export. */
+const DEFAULT_RECENT_LIMIT = 50;
+const MAX_RECENT_LIMIT = 200;
+
+/**
+ * Confirm a resolved store's `interaction_store_meta` row actually names the
+ * tenant we resolved it for. Returns `false` (never throws) on any mismatch,
+ * a missing meta row, or a query failure — all fail-closed: the caller must
+ * treat that as "cannot verify this store, do not read from it."
+ */
+export async function assertStoreOwnership(
+  store: Pick<TenantInteractionStore, "tenantId" | "db">,
+): Promise<boolean> {
+  try {
+    const meta = await store.db.first<{ tenant_id: string }>(
+      `SELECT tenant_id FROM interaction_store_meta WHERE id = 1`,
+    );
+    return !!meta && meta.tenant_id === store.tenantId;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Recent raw events for ONE tenant's own store, newest first. Scoped to the
+ * resolved store's database (the isolation boundary) AND to its
+ * `tenantId` (defence-in-depth) — there is no parameter here through which a
+ * caller can ask for a different tenant's rows; the only tenant this can
+ * ever return is the one `store` was resolved for.
+ */
+export async function readRecentInteractionEvents(
+  store: Pick<TenantInteractionStore, "tenantId" | "db">,
+  opts?: { limit?: number },
+): Promise<RecentInteractionEvent[]> {
+  const limit = Math.max(1, Math.min(opts?.limit ?? DEFAULT_RECENT_LIMIT, MAX_RECENT_LIMIT));
+  return store.db.all<RecentInteractionEvent>(
+    `SELECT type, el, action, placement, scope, ts, ingested_at AS ingestedAt
+       FROM interaction_events
+      WHERE tenant_id = ?
+      ORDER BY ingested_at DESC
+      LIMIT ?`,
+    store.tenantId,
+    limit,
+  );
+}
+
+/**
+ * Simple aggregate over ONE tenant's own store: total row count + a rollup by
+ * (el, action). Mirrors the AE dimension tuple's spirit but computed directly
+ * off the tenant's own raw rows, scoped the same way as
+ * {@link readRecentInteractionEvents}.
+ */
+export async function readInteractionSummary(
+  store: Pick<TenantInteractionStore, "tenantId" | "db">,
+): Promise<{ totalEvents: number; byAction: InteractionActionCount[] }> {
+  const totalRow = await store.db.first<{ n: number }>(
+    `SELECT COUNT(*) AS n FROM interaction_events WHERE tenant_id = ?`,
+    store.tenantId,
+  );
+  const byAction = await store.db.all<InteractionActionCount>(
+    `SELECT el, COALESCE(action, '') AS action, COUNT(*) AS count
+       FROM interaction_events
+      WHERE tenant_id = ?
+      GROUP BY el, action
+      ORDER BY count DESC`,
+    store.tenantId,
+  );
+  return { totalEvents: totalRow?.n ?? 0, byAction };
+}
+
+/**
+ * The full merchant-visible read: ownership-asserted, then summary + recent
+ * feed off the SAME scoped store. Returns `undefined` when the store fails
+ * the ownership assertion — fail-closed, never a partial/best-guess result.
+ */
+export async function readTenantInteractionInsights(
+  store: Pick<TenantInteractionStore, "tenantId" | "db">,
+  opts?: { limit?: number },
+): Promise<InteractionInsights | undefined> {
+  if (!(await assertStoreOwnership(store))) return undefined;
+  const [summary, recent] = await Promise.all([
+    readInteractionSummary(store),
+    readRecentInteractionEvents(store, opts),
+  ]);
+  return { totalEvents: summary.totalEvents, byAction: summary.byAction, recent };
+}

package/apps/storefront/src/lib/tracking-writeback/rewriteTrackingIds.ts

@@ -0,0 +1,175 @@
+/**
+ * `data-tot-el` writeback (dt-id-writeback) — the git-time rewriter that turns
+ * `tracking-id-derivation.ts`'s PROPOSALS into an actual attribute in a tenant's
+ * source HTML, so a human reviews and accepts a real diff (never a silent
+ * runtime mutation). Mirrors the pattern `the-build/toc.ts` already uses for
+ * heading anchors: parse5 fragment/document tree, mutate in place, re-`serialize()`
+ * ONLY when something actually changed (byte-preserving otherwise).
+ *
+ * Scope: tenant-authored BODY documents only (`content/home.html`,
+ * `content/<tenant>/pages-html/<slug>.html`) — never governed chrome, which
+ * `trackingAttributes()` / `trackingAttributesHtml()` already stamp via a
+ * separate, non-derived path (`dt-stamp-chrome-nav`). This module does not know
+ * about chrome and must never be pointed at `chrome.html` / `chrome.json`.
+ *
+ * Contract: docs/architecture/interaction-tracking-attribute-contract.md
+ * ("Deriving `data-tot-el`").
+ */
+import { parse, parseFragment, serialize } from "parse5";
+import {
+  createTrackingIdDeriver,
+  isTrackableNode,
+  TRACKING_ATTR_EL,
+  type DerivationOptions,
+  type DerivationConfidence,
+  type StructuralNode,
+} from "@tot/public-runtime";
+
+/** Minimal structural view of a parse5 node (duck-typed, as toc.ts does). */
+interface P5Attr {
+  name: string;
+  value: string;
+}
+interface P5Node {
+  nodeName: string;
+  tagName?: string;
+  attrs?: P5Attr[];
+  childNodes?: P5Node[];
+}
+
+/** One proposed (or already-declared) `data-tot-el` this pass encountered. */
+export interface TrackingWritebackProposal {
+  /** The proposed (or, for a `"declared"` row, the pre-existing) value. */
+  el: string;
+  confidence: DerivationConfidence;
+  /** Most-significant-first, per `DerivedTrackingId.signals` — the diff annotation. */
+  signals: readonly string[];
+  /** True iff a human should name this element before accepting the diff. */
+  needsReview: boolean;
+  /** True iff `data-tot-el` was ALREADY present (nothing written; verbatim). */
+  alreadyDeclared: boolean;
+  /** The element's tag, for the review listing. */
+  tag: string;
+  /** A short open-tag snippet (no children) so a reviewer can locate the element. */
+  snippet: string;
+}
+
+export interface TrackingWritebackResult {
+  /** The (possibly) rewritten source. Byte-identical to the input when `changed` is false. */
+  html: string;
+  /** True iff at least one element gained a new `data-tot-el`. */
+  changed: boolean;
+  /** Every candidate element seen, in document order — declared rows included. */
+  proposals: TrackingWritebackProposal[];
+}
+
+function attrsToRecord(attrs?: P5Attr[]): Record<string, string> | undefined {
+  if (!attrs || attrs.length === 0) return undefined;
+  const rec: Record<string, string> = {};
+  for (const a of attrs) rec[a.name] = a.value;
+  return rec;
+}
+
+function toStructuralNode(node: P5Node): StructuralNode {
+  return { tag: (node.tagName ?? "").toLowerCase(), attrs: attrsToRecord(node.attrs) };
+}
+
+function openTagSnippet(node: StructuralNode): string {
+  const attrs = node.attrs ?? {};
+  const parts = Object.entries(attrs)
+    .filter((entry): entry is [string, string] => typeof entry[1] === "string")
+    .map(([k, v]) => `${k}="${v}"`);
+  return `<${node.tag}${parts.length ? " " + parts.join(" ") : ""}>`;
+}
+
+function isElement(node: P5Node): node is P5Node & { tagName: string } {
+  return typeof node.tagName === "string" && node.tagName.length > 0;
+}
+
+/** Every `data-tot-el` value anywhere in the tree, in document order — the
+ * pre-existing identities a fresh proposal must never collide with, per the
+ * derivation engine's own handoff ("reserve() every id already in the source,
+ * BEFORE deriving"). Deliberately unfiltered by {@link isTrackableNode}: a
+ * hand-authored id on an element this pass wouldn't otherwise touch still
+ * occupies the namespace. */
+function* declaredIds(root: P5Node): Generator<string> {
+  for (const child of root.childNodes ?? []) {
+    if (isElement(child)) {
+      const value = child.attrs?.find((a) => a.name === TRACKING_ATTR_EL)?.value?.trim();
+      if (value) yield value;
+    }
+    yield* declaredIds(child);
+  }
+}
+
+/**
+ * Walk the tree in document order, yielding every trackable element with its
+ * ancestor stack (OUTERMOST first — the derivation engine's own contract).
+ */
+function* candidates(
+  root: P5Node,
+  ancestors: readonly P5Node[] = [],
+): Generator<{ node: P5Node; ancestors: readonly P5Node[] }> {
+  for (const child of root.childNodes ?? []) {
+    if (isElement(child)) {
+      if (isTrackableNode(toStructuralNode(child))) {
+        yield { node: child, ancestors };
+      }
+      yield* candidates(child, [...ancestors, child]);
+    } else {
+      yield* candidates(child, ancestors);
+    }
+  }
+}
+
+/** Whether `html` looks like a full document (vs. a body-only fragment). */
+function isFullDocument(html: string): boolean {
+  return /^\s*(<!doctype\s|<html[\s>])/i.test(html);
+}
+
+/**
+ * Propose (and write) `data-tot-el` for every undeclared trackable element in
+ * `html`. Pure: no I/O, no network. `confidence: "declared"` elements are
+ * returned in `proposals` for a complete review listing but are NEVER mutated —
+ * a declared identity is permanent (per the derivation engine's own contract).
+ *
+ * `html` may be a full tenant document (`content/home.html`, doctype + `<html>`)
+ * or a body-only fragment (`content/<tenant>/pages-html/<slug>.html`) — detected
+ * automatically so one function serves both writeback call sites.
+ */
+export function deriveTrackingWriteback(
+  html: string,
+  options?: DerivationOptions,
+): TrackingWritebackResult {
+  const fullDocument = isFullDocument(html);
+  const root = (fullDocument ? parse(html) : parseFragment(html)) as unknown as P5Node;
+
+  const deriver = createTrackingIdDeriver(options);
+  for (const id of declaredIds(root)) deriver.reserve(id);
+
+  const proposals: TrackingWritebackProposal[] = [];
+  let changed = false;
+
+  for (const { node, ancestors } of candidates(root)) {
+    const structural = toStructuralNode(node);
+    const alreadyDeclared = Boolean(structural.attrs?.[TRACKING_ATTR_EL]?.trim());
+    const derived = deriver.derive({
+      node: structural,
+      ancestors: ancestors.map(toStructuralNode),
+    });
+    proposals.push({
+      el: derived.el,
+      confidence: derived.confidence,
+      signals: derived.signals,
+      needsReview: derived.needsReview,
+      alreadyDeclared,
+      tag: structural.tag,
+      snippet: openTagSnippet(structural),
+    });
+    if (alreadyDeclared) continue; // declared verbatim — never overwritten
+    node.attrs = [...(node.attrs ?? []), { name: TRACKING_ATTR_EL, value: derived.el }];
+    changed = true;
+  }
+
+  return { html: changed ? serialize(root as never) : html, changed, proposals };
+}