@tokenoftrust/storefront-runner 1.4.2-rc.0 → 2.0.0

package/packages/public-runtime/src/gtm-migration/bounds.ts

@@ -0,0 +1,138 @@
+/**
+ * Bounds for the GTM container-export parser.
+ *
+ * A GTM export is untrusted, possibly-adversarial DATA. The parser treats it as
+ * inert bytes and NEVER executes any of it. Bounds are enforced BEFORE parse (a
+ * raw-byte cap, checked ahead of `JSON.parse`) and DURING a post-parse structural
+ * tree-walk, so a malicious/huge export is rejected safely instead of exhausting
+ * the worker.
+ *
+ * Depth, node-count, and array-length breaches are HARD violations (the export is
+ * rejected). Over-length strings are NOT a hard reject — they are truncated with a
+ * recorded flag at extraction time (see parse.ts); enforcing that here would fight
+ * the contract, so this walk does not fail on string length.
+ */
+
+/** A structural violation with a JSON path to the offending value. */
+export interface GtmViolation {
+  /** JSON path to the offending value, e.g. `containerVersion.tag[3]`. */
+  path: string;
+  /** Stable machine code, e.g. `max_depth`, `max_nodes`, `max_array_len`. */
+  code: string;
+  message: string;
+}
+
+/** Strict, tunable caps applied before and during a parse. */
+export interface ParseBounds {
+  /** Raw-input byte cap, checked BEFORE `JSON.parse`. */
+  maxBytes: number;
+  /** Maximum nesting depth of the parsed tree (root = depth 0). */
+  maxDepth: number;
+  /** Maximum total number of nodes (objects, arrays, primitives) visited. */
+  maxNodes: number;
+  /** Maximum length of any single array. */
+  maxArrayLen: number;
+  /** Maximum length of any single string; over-length strings are TRUNCATED, not rejected. */
+  maxStringLen: number;
+}
+
+export const DEFAULT_BOUNDS: ParseBounds = {
+  maxBytes: 8 * 1024 * 1024, // 8 MiB
+  maxDepth: 64,
+  maxNodes: 200_000,
+  maxArrayLen: 50_000,
+  maxStringLen: 256 * 1024, // 256 KiB
+};
+
+/** Merge a partial override over the defaults, ignoring non-finite/negative caps. */
+export function resolveBounds(partial?: Partial<ParseBounds>): ParseBounds {
+  const out: ParseBounds = { ...DEFAULT_BOUNDS };
+  if (partial) {
+    for (const key of Object.keys(DEFAULT_BOUNDS) as (keyof ParseBounds)[]) {
+      const v = partial[key];
+      if (typeof v === "number" && Number.isFinite(v) && v > 0) out[key] = v;
+    }
+  }
+  return out;
+}
+
+function joinPath(path: string, key: string): string {
+  return path ? `${path}.${key}` : key;
+}
+
+/** Internal cap so the violations list itself cannot grow unboundedly on adversarial input. */
+const MAX_VIOLATIONS = 1000;
+
+/**
+ * Walk the parsed tree iteratively (explicit stack — never recursion, so an
+ * adversarially deep tree cannot overflow the JS call stack) and report each
+ * structural breach. Returns HARD violations only; an empty array means the tree
+ * is within structural bounds. String length is handled by truncation at
+ * extraction, not here.
+ */
+export function enforceBounds(root: unknown, bounds: ParseBounds): GtmViolation[] {
+  const violations: GtmViolation[] = [];
+  const add = (path: string, code: string, message: string): void => {
+    if (violations.length < MAX_VIOLATIONS) violations.push({ path, code, message });
+  };
+
+  let nodes = 0;
+  let depthReported = false;
+  let nodesReported = false;
+
+  // Stack of { value, path, depth }. Root is depth 0.
+  const stack: { value: unknown; path: string; depth: number }[] = [
+    { value: root, path: "", depth: 0 },
+  ];
+
+  while (stack.length > 0) {
+    const frame = stack.pop()!;
+    const { value, path, depth } = frame;
+
+    nodes += 1;
+    if (nodes > bounds.maxNodes) {
+      if (!nodesReported) {
+        add(
+          path || "(root)",
+          "max_nodes",
+          `Node count exceeded ${bounds.maxNodes}; input rejected.`,
+        );
+        nodesReported = true;
+      }
+      // Stop the entire walk: continuing is pointless and costly.
+      break;
+    }
+
+    if (depth > bounds.maxDepth) {
+      if (!depthReported) {
+        add(path || "(root)", "max_depth", `Depth exceeded ${bounds.maxDepth}; input rejected.`);
+        depthReported = true;
+      }
+      // Do not descend past the depth cap on this branch.
+      continue;
+    }
+
+    if (Array.isArray(value)) {
+      if (value.length > bounds.maxArrayLen) {
+        add(
+          path || "(root)",
+          "max_array_len",
+          `Array length ${value.length} exceeded ${bounds.maxArrayLen}; input rejected.`,
+        );
+      }
+      const limit = Math.min(value.length, bounds.maxArrayLen);
+      for (let i = 0; i < limit; i += 1) {
+        stack.push({ value: value[i], path: `${path}[${i}]`, depth: depth + 1 });
+      }
+    } else if (value !== null && typeof value === "object") {
+      // Plain object (null-prototype or otherwise). Enumerate own keys.
+      const obj = value as Record<string, unknown>;
+      for (const key of Object.keys(obj)) {
+        stack.push({ value: obj[key], path: joinPath(path, key), depth: depth + 1 });
+      }
+    }
+    // Primitives (string/number/boolean/null) are leaf nodes — counted, not descended.
+  }
+
+  return violations;
+}

package/packages/public-runtime/src/gtm-migration/disposition-rules.ts

@@ -0,0 +1,361 @@
+/**
+ * The GTM-type → migration-disposition ruleset: the data-driven knowledge that
+ * turns an inert GTM object into one of five disposition classes. Kept as tables
+ * + small predicates (not a wall of `if`s) so the classification contract is
+ * auditable and extensible in one place.
+ *
+ * PRODUCT BOUNDARY (drives the taxonomy): the storefront supports migration FROM
+ * GTM, never EXECUTION of GTM. There is no GTM runtime, no Custom HTML/JS, no
+ * custom-template/sandboxed-JS execution, no dataLayer runtime. Any GTM object
+ * that is fundamentally code to be executed is unsupported BY DESIGN — a
+ * deliberate boundary, not a defect.
+ *
+ * SECURITY CONTRACT (inherited — a reviewer WILL reject violations):
+ *   - Pure DATA transformation. Nothing here executes, evaluates, interprets, or
+ *     compiles any part of the export. Code-bearing fields are read as inert text
+ *     for their PRESENCE/type only, never run.
+ *   - Pure and deterministic: no I/O, no globals, stable output for stable input.
+ *   - Null-prototype safety: every lookup keyed by an attacker-controlled
+ *     id/name/type goes through a `Map`/`Set`, never an object literal.
+ *
+ * PRECEDENCE (highest wins; tested):
+ *   1. code-bearing            → unsupported-by-design   (code-execution-unsupported)
+ *   2. UA deprecated (tag `ua`)→ retire                  (ua-deprecated-retire)
+ *   3. orphaned/unused var     → retire                  (orphaned-unused)
+ *   4. explicit kind/type rule → per the tables below
+ *   5. safe default            → portable-with-review    (unmapped-type-review)
+ * Dangling references are always `retire` (dangling-reference) — see dispositions.ts.
+ */
+
+import type { GraphNode } from "./graph.js";
+import { isCustomTemplateType } from "./references.js";
+import type { DispositionClass } from "./dispositions.js";
+
+/** Every stable machine reason code the engine can emit, each mapped to one class. */
+export type ReasonCode =
+  | "code-execution-unsupported"
+  | "no-native-trigger-semantics"
+  | "ga4-native"
+  | "native-equivalent"
+  | "ua-deprecated-retire"
+  | "dangling-reference"
+  | "orphaned-unused"
+  | "google-ads-review"
+  | "await-managed-support"
+  | "native-mapping-review"
+  | "unmapped-type-review"
+  | "heatmap-excluded-protected-surfaces"
+  | "no-direct-mapping";
+
+/** One classification outcome: the class, the stable code, and a human explanation. */
+export interface DispositionVerdict {
+  readonly disposition: DispositionClass;
+  readonly reasonCode: ReasonCode;
+  readonly explanation: string;
+}
+
+/**
+ * Single source of truth: reason code → its disposition class + base explanation.
+ * A finite-key record, so lookups are total (never `undefined`).
+ */
+export const REASON_CATALOG: Record<ReasonCode, { disposition: DispositionClass; explanation: string }> = {
+  "code-execution-unsupported": {
+    disposition: "unsupported-by-design",
+    explanation:
+      "Token of Trust never executes GTM code; rebuild the intent as a native integration.",
+  },
+  "no-native-trigger-semantics": {
+    disposition: "unsupported-by-design",
+    explanation:
+      "This trigger depends on client-side script with no native named equivalent Token of Trust can honor; rebuild the intent natively.",
+  },
+  "ga4-native": {
+    disposition: "automatically-portable",
+    explanation: "Maps 1:1 to native GA4; moves automatically with no code.",
+  },
+  "native-equivalent": {
+    disposition: "automatically-portable",
+    explanation: "Maps 1:1 to a native concept with no code or ambiguity; moves automatically.",
+  },
+  "ua-deprecated-retire": {
+    disposition: "retire",
+    explanation: "Universal Analytics is deprecated by Google with no migration target; retire it.",
+  },
+  "dangling-reference": {
+    disposition: "retire",
+    explanation: "References an object that does not exist in the container; retire the broken reference.",
+  },
+  "orphaned-unused": {
+    disposition: "retire",
+    explanation:
+      "Referenced by nothing and referencing nothing, so it carries no standalone value; retire it.",
+  },
+  "google-ads-review": {
+    disposition: "portable-with-review",
+    explanation:
+      "Recognized Google Ads tag with a native adapter; confirm the conversion configuration before migrating.",
+  },
+  "await-managed-support": {
+    disposition: "portable-with-review",
+    explanation:
+      "Recognized third-party vendor whose native adapter is demand-gated; confirm managed support before migrating.",
+  },
+  "native-mapping-review": {
+    disposition: "portable-with-review",
+    explanation: "Recognized concept that maps to native but needs human confirmation of the mapping.",
+  },
+  "unmapped-type-review": {
+    disposition: "portable-with-review",
+    explanation:
+      "Unrecognized type with no known native mapping; review manually — never assumed automatically portable.",
+  },
+  "heatmap-excluded-protected-surfaces": {
+    disposition: "requires-redesign",
+    explanation:
+      "Heatmap/session-recording vendor excluded from protected and checkout surfaces by policy; redesign around that boundary.",
+  },
+  "no-direct-mapping": {
+    disposition: "requires-redesign",
+    explanation: "Recognized concept with no direct native mapping; achievable through a different native design.",
+  },
+};
+
+/** The class a reason code implies (derived from the catalog). */
+export function dispositionForReason(code: ReasonCode): DispositionClass {
+  return REASON_CATALOG[code].disposition;
+}
+
+/** Build a verdict from a reason code, optionally appending a per-object detail. */
+export function verdict(code: ReasonCode, detail?: string): DispositionVerdict {
+  const entry = REASON_CATALOG[code];
+  const explanation = detail ? `${entry.explanation} (${detail})` : entry.explanation;
+  return { disposition: entry.disposition, reasonCode: code, explanation };
+}
+
+// --- Type tables (data-driven; the extension seam for new GTM types) ----------
+
+/**
+ * Recognized tag `type` → reason code. Absent types fall to the safe default
+ * (`unmapped-type-review`). `html` is intentionally NOT here — it is code-bearing
+ * and caught by the higher-priority code-execution rule. `ua` is handled ahead of
+ * this table (it retires, and must beat any vendor rule).
+ */
+export const TAG_TYPE_RULES = new Map<string, ReasonCode>([
+  // Google Analytics 4 / Google tag — native.
+  ["googtag", "ga4-native"],
+  ["gaawc", "ga4-native"], // GA4 configuration
+  ["gaawe", "ga4-native"], // GA4 event
+  // Google Ads — recognized, needs conversion-config review.
+  ["awct", "google-ads-review"], // Conversion Tracking
+  ["gclidw", "google-ads-review"], // Conversion Linker
+  // Managed-pending third-party vendors — native adapter is demand/roadmap-gated.
+  ["bzi", "await-managed-support"], // LinkedIn Insight
+  ["hubspot", "await-managed-support"],
+  ["capterra", "await-managed-support"],
+  ["g2", "await-managed-support"],
+  // Heatmap / session-recording vendors — excluded from protected/checkout surfaces.
+  ["hjtc", "heatmap-excluded-protected-surfaces"], // Hotjar
+  ["clarity", "heatmap-excluded-protected-surfaces"], // Microsoft Clarity
+  ["fullstory", "heatmap-excluded-protected-surfaces"],
+  ["mouseflow", "heatmap-excluded-protected-surfaces"],
+  ["mf", "heatmap-excluded-protected-surfaces"], // Mouseflow (GTM gallery-template type code)
+  ["smartlook", "heatmap-excluded-protected-surfaces"],
+]);
+
+/**
+ * Recognized variable `type` → reason code. Absent types fall to the safe default.
+ * `jsm` (Custom JavaScript) is code-bearing and caught earlier, not listed here.
+ */
+export const VARIABLE_TYPE_RULES = new Map<string, ReasonCode>([
+  ["c", "native-equivalent"], // constant
+  ["u", "native-equivalent"], // URL
+  ["v", "native-mapping-review"], // data layer variable
+  ["j", "native-mapping-review"], // JavaScript global variable
+  ["k", "native-mapping-review"], // first-party cookie
+  ["smm", "native-mapping-review"], // lookup table
+  ["remm", "native-mapping-review"], // regex table lookup
+  ["d", "native-mapping-review"], // DOM element
+  ["aev", "native-mapping-review"], // auto-event variable
+]);
+
+/**
+ * Recognized trigger `type` (normalized: lowercased, non-alphanumerics stripped,
+ * so `DOM_READY` and `domReady` collapse to one key) → reason code. Absent types
+ * fall to the safe default.
+ */
+export const TRIGGER_TYPE_RULES = new Map<string, ReasonCode>([
+  // Native named page-lifecycle / interaction semantics — portable.
+  ["pageview", "native-equivalent"],
+  ["domready", "native-equivalent"],
+  ["windowloaded", "native-equivalent"],
+  ["click", "native-equivalent"],
+  ["linkclick", "native-equivalent"],
+  // Native exists but needs mapping confirmation.
+  ["formsubmission", "native-mapping-review"],
+  ["historychange", "native-mapping-review"],
+  ["elementvisibility", "native-mapping-review"],
+  ["customevent", "native-mapping-review"],
+  ["init", "native-mapping-review"],
+  ["consentinit", "native-mapping-review"],
+  // No native named equivalent — depends on client-side script we do not run.
+  ["scrolldepth", "no-native-trigger-semantics"],
+  ["youtubevideo", "no-native-trigger-semantics"],
+  ["timer", "no-native-trigger-semantics"],
+  ["jserror", "no-native-trigger-semantics"],
+  // Recognized concept, no direct mapping — redesign.
+  ["triggergroup", "no-direct-mapping"],
+  ["serverpixel", "no-direct-mapping"],
+]);
+
+/** GTM object kinds with a fixed kind-level disposition (independent of `type`). */
+export const KIND_RULES = new Map<GraphNode["kind"], ReasonCode>([
+  ["folder", "native-equivalent"], // pure organization
+  ["zone", "no-direct-mapping"],
+  ["client", "no-direct-mapping"],
+  ["transformation", "no-direct-mapping"],
+  ["gtagConfig", "no-direct-mapping"],
+]);
+
+/**
+ * Built-in variable `type` prefixes that depend on client-side interaction capture
+ * (clicks, forms, scroll, video, element visibility, JS errors, history). These map
+ * to native but need review; all other built-ins are straight native equivalents.
+ */
+const INTERACTION_BUILTIN_PREFIXES: readonly string[] = [
+  "CLICK",
+  "FORM",
+  "SCROLL",
+  "VIDEO",
+  "ELEMENT",
+  "ERROR",
+  "HISTORY",
+  "NEW_HISTORY",
+];
+
+/** Normalize a tag/variable `type` for exact matching: lowercase, trimmed. */
+function normalizeExact(type: string | null): string {
+  return typeof type === "string" ? type.trim().toLowerCase() : "";
+}
+
+/** Normalize a trigger `type`: lowercase + strip non-alphanumerics (camelCase ≈ UPPER_SNAKE). */
+function normalizeTrigger(type: string | null): string {
+  return typeof type === "string" ? type.toLowerCase().replace(/[^a-z0-9]/g, "") : "";
+}
+
+/** Read a null-prototype-safe own value off a `raw` bag (missing → undefined). */
+function own(raw: Record<string, unknown>, key: string): unknown {
+  return Object.prototype.hasOwnProperty.call(raw, key) ? raw[key] : undefined;
+}
+
+/** True when a `raw` field holds a non-empty array (used for tag sequencing detection). */
+function hasNonEmptyArray(raw: Record<string, unknown>, key: string): boolean {
+  const v = own(raw, key);
+  return Array.isArray(v) && v.length > 0;
+}
+
+/** Context the classifier needs beyond the node itself — derived from the graph edges. */
+export interface NodeRuleContext {
+  /** The node has an outgoing `usesTemplate` edge (→ code-bearing). */
+  readonly usesTemplate: boolean;
+  /** The node is touched by at least one real edge (in or out) or makes a reference. */
+  readonly connected: boolean;
+}
+
+/**
+ * True when a node is fundamentally GTM code to be executed — the highest-priority
+ * disposition. Reads types/fields for presence only; never executes anything.
+ */
+export function isCodeBearing(node: GraphNode, ctx: NodeRuleContext): boolean {
+  if (node.kind === "customTemplate") return true; // a template IS code
+  if (isCustomTemplateType(node.type)) return true; // `cvt_*` type resolves to a template
+  if (ctx.usesTemplate) return true; // wired to a custom template
+  if (node.kind === "tag" && normalizeExact(node.type) === "html") return true; // Custom HTML
+  if (node.kind === "variable" && normalizeExact(node.type) === "jsm") return true; // Custom JS
+  return false;
+}
+
+/** A short human detail for an object's explanation. */
+function detailFor(node: GraphNode): string {
+  const label = node.name ?? node.id ?? node.key;
+  const typePart = node.type ? ` type "${node.type}"` : "";
+  return `${node.kind} "${label}"${typePart}`;
+}
+
+function classifyTag(node: GraphNode, detail: string): DispositionVerdict {
+  const type = normalizeExact(node.type);
+  // UA is the one tag type that retires rather than reviews — beats every vendor rule.
+  if (type === "ua") return verdict("ua-deprecated-retire", detail);
+  // Tag sequencing / priority has no direct native mapping — redesign.
+  if (hasNonEmptyArray(node.record.raw, "setupTag") || hasNonEmptyArray(node.record.raw, "teardownTag")) {
+    return verdict("no-direct-mapping", `${detail}: uses tag sequencing`);
+  }
+  const rule = TAG_TYPE_RULES.get(type);
+  if (rule) return verdict(rule, detail);
+  // Unrecognized tag type — safe default, NEVER auto, NEVER silently unsupported.
+  return verdict("unmapped-type-review", detail);
+}
+
+function classifyVariable(node: GraphNode, detail: string): DispositionVerdict {
+  const rule = VARIABLE_TYPE_RULES.get(normalizeExact(node.type));
+  if (rule) return verdict(rule, detail);
+  return verdict("unmapped-type-review", detail);
+}
+
+function classifyBuiltInVariable(node: GraphNode, detail: string): DispositionVerdict {
+  const upper = typeof node.type === "string" ? node.type.trim().toUpperCase() : "";
+  for (const prefix of INTERACTION_BUILTIN_PREFIXES) {
+    if (upper.startsWith(prefix)) return verdict("native-mapping-review", detail);
+  }
+  return verdict("native-equivalent", detail);
+}
+
+function classifyTrigger(node: GraphNode, detail: string): DispositionVerdict {
+  const rule = TRIGGER_TYPE_RULES.get(normalizeTrigger(node.type));
+  if (rule) return verdict(rule, detail);
+  return verdict("unmapped-type-review", detail);
+}
+
+/**
+ * Classify a single graph node into exactly one disposition, applying the full
+ * precedence chain. Every node returns a verdict — nothing is left unclassified.
+ */
+export function classifyNode(node: GraphNode, ctx: NodeRuleContext): DispositionVerdict {
+  const detail = detailFor(node);
+
+  // 0. Synthetic GTM built-ins (reserved triggers, `_`-prefixed variables) map to
+  // native page/event semantics. A recognized built-in is straight native-portable;
+  // an unknown reserved-range id maps to native but needs mapping confirmation.
+  if (node.builtIn) {
+    if (node.builtIn.of === "variable") return verdict("native-equivalent", detail);
+    return node.builtIn.known
+      ? verdict("native-equivalent", detail)
+      : verdict("native-mapping-review", detail);
+  }
+
+  // 1. Code-bearing wins over everything.
+  if (isCodeBearing(node, ctx)) return verdict("code-execution-unsupported", detail);
+
+  switch (node.kind) {
+    case "tag":
+      return classifyTag(node, detail);
+    case "variable":
+      // 3. Orphaned/unused variable — retire (beats the type rule).
+      if (!ctx.connected) return verdict("orphaned-unused", detail);
+      return classifyVariable(node, detail);
+    case "builtInVariable":
+      if (!ctx.connected) return verdict("orphaned-unused", detail);
+      return classifyBuiltInVariable(node, detail);
+    case "trigger":
+      return classifyTrigger(node, detail);
+    case "customTemplate":
+      // Defensive: already caught by code-bearing above.
+      return verdict("code-execution-unsupported", detail);
+    default: {
+      // folder / zone / client / transformation / gtagConfig.
+      const rule = KIND_RULES.get(node.kind);
+      if (rule) return verdict(rule, detail);
+      // No kind or type rule matched — safe default.
+      return verdict("unmapped-type-review", detail);
+    }
+  }
+}

package/packages/public-runtime/src/gtm-migration/dispositions.ts

@@ -0,0 +1,181 @@
+/**
+ * The migration DISPOSITION (classification) engine: assign every object in a
+ * normalized GTM migration graph — and every dangling reference — exactly one
+ * disposition class, with a stable machine reason code and a human explanation.
+ *
+ * COMPLETE ACCOUNTING is a core requirement: `classifiedObjects` equals the graph
+ * node count and `classifiedDangling` equals the dangling count, so nothing is ever
+ * left unclassified. The GTM-type → disposition knowledge lives in the extensible
+ * ruleset (`disposition-rules.ts`); this module is the pure orchestration that walks
+ * the graph and tallies the report.
+ *
+ * SECURITY CONTRACT (inherited — a reviewer WILL reject violations):
+ *   - Pure DATA transformation: nothing executes, evaluates, or interprets any part
+ *     of the export. Pure and deterministic; no I/O, no globals, stable ordering.
+ *   - Every lookup keyed by an attacker-controlled id/name/type goes through a
+ *     `Map`/`Set`, never an object literal.
+ */
+
+import type { GtmObjectKind, GraphNode, MigrationGraph } from "./graph.js";
+import { classifyNode, verdict, type NodeRuleContext } from "./disposition-rules.js";
+
+/** The five migration disposition classes — every object gets exactly one. */
+export type DispositionClass =
+  | "automatically-portable"
+  | "portable-with-review"
+  | "requires-redesign"
+  | "unsupported-by-design"
+  | "retire";
+
+/** One classified GTM object. */
+export interface ObjectDisposition {
+  readonly nodeKey: string;
+  readonly kind: GtmObjectKind;
+  readonly id: string | null;
+  readonly name: string | null;
+  readonly type: string | null;
+  readonly disposition: DispositionClass;
+  readonly reasonCode: string;
+  readonly explanation: string;
+}
+
+/** One classified dangling reference (its target object does not exist). */
+export interface DanglingDisposition {
+  readonly from: string;
+  readonly refKind: string;
+  readonly ref: string;
+  readonly disposition: DispositionClass;
+  readonly reasonCode: string;
+  readonly explanation: string;
+}
+
+/** The complete disposition report for a container. */
+export interface DispositionReport {
+  readonly objects: ObjectDisposition[];
+  readonly dangling: DanglingDisposition[];
+  readonly summary: {
+    /** Count per class across BOTH objects and dangling references. Sums to `total`. */
+    readonly byClass: Record<DispositionClass, number>;
+    /** Per object kind → per class counts (objects only; dangling has no kind). */
+    readonly byKind: Record<GtmObjectKind, Record<DispositionClass, number>>;
+    /** Total classified items = objects + dangling references. */
+    readonly total: number;
+  };
+  readonly accounting: {
+    readonly classifiedObjects: number;
+    readonly classifiedDangling: number;
+    readonly graphNodeCount: number;
+    readonly graphDanglingCount: number;
+    /** classifiedObjects===graphNodeCount && classifiedDangling===graphDanglingCount. */
+    readonly complete: boolean;
+  };
+}
+
+/** Fixed class order — drives deterministic zeroed count maps. */
+const ALL_CLASSES: readonly DispositionClass[] = [
+  "automatically-portable",
+  "portable-with-review",
+  "requires-redesign",
+  "unsupported-by-design",
+  "retire",
+];
+
+/** Fixed kind order — drives the deterministic `byKind` map. */
+const ALL_KINDS: readonly GtmObjectKind[] = [
+  "tag",
+  "trigger",
+  "variable",
+  "builtInVariable",
+  "customTemplate",
+  "folder",
+  "zone",
+  "client",
+  "gtagConfig",
+  "transformation",
+];
+
+function zeroedClassCounts(): Record<DispositionClass, number> {
+  const out = {} as Record<DispositionClass, number>;
+  for (const cls of ALL_CLASSES) out[cls] = 0;
+  return out;
+}
+
+/**
+ * Classify every node and dangling reference in a migration graph.
+ *
+ * Pure and deterministic. Output order mirrors the graph's node and dangling order.
+ */
+export function classifyMigration(graph: MigrationGraph): DispositionReport {
+  // --- Context derived from edges: usesTemplate wiring + connectivity. --------
+  const usesTemplateFrom = new Set<string>();
+  const connected = new Set<string>();
+  for (const edge of graph.edges) {
+    connected.add(edge.from);
+    connected.add(edge.to);
+    if (edge.kind === "usesTemplate") usesTemplateFrom.add(edge.from);
+  }
+  // A node that MAKES a reference (even a dangling one) is "referencing something",
+  // so it is not an orphan — conservative: prefer review over retire.
+  for (const d of graph.danglingReferences) connected.add(d.from);
+
+  const contextFor = (node: GraphNode): NodeRuleContext => ({
+    usesTemplate: usesTemplateFrom.has(node.key),
+    connected: connected.has(node.key),
+  });
+
+  // --- Objects: one disposition per node, in graph node order. ---------------
+  const objects: ObjectDisposition[] = graph.nodes.map((node) => {
+    const v = classifyNode(node, contextFor(node));
+    return {
+      nodeKey: node.key,
+      kind: node.kind,
+      id: node.id,
+      name: node.name,
+      type: node.type,
+      disposition: v.disposition,
+      reasonCode: v.reasonCode,
+      explanation: v.explanation,
+    };
+  });
+
+  // --- Dangling references: always retire, in graph dangling order. ----------
+  const dangling: DanglingDisposition[] = graph.danglingReferences.map((d) => {
+    const v = verdict("dangling-reference", `${d.kind} reference "${d.ref}" from ${d.from}`);
+    return {
+      from: d.from,
+      refKind: d.kind,
+      ref: d.ref,
+      disposition: v.disposition,
+      reasonCode: v.reasonCode,
+      explanation: v.explanation,
+    };
+  });
+
+  // --- Summary tallies. -------------------------------------------------------
+  const byClass = zeroedClassCounts();
+  const byKind = {} as Record<GtmObjectKind, Record<DispositionClass, number>>;
+  for (const kind of ALL_KINDS) byKind[kind] = zeroedClassCounts();
+
+  for (const obj of objects) {
+    byClass[obj.disposition] += 1;
+    byKind[obj.kind][obj.disposition] += 1;
+  }
+  for (const d of dangling) {
+    byClass[d.disposition] += 1;
+  }
+
+  const total = objects.length + dangling.length;
+
+  // --- Accounting invariant. --------------------------------------------------
+  const graphNodeCount = graph.nodes.length;
+  const graphDanglingCount = graph.danglingReferences.length;
+  const accounting = {
+    classifiedObjects: objects.length,
+    classifiedDangling: dangling.length,
+    graphNodeCount,
+    graphDanglingCount,
+    complete: objects.length === graphNodeCount && dangling.length === graphDanglingCount,
+  };
+
+  return { objects, dangling, summary: { byClass, byKind, total }, accounting };
+}