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

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

@@ -0,0 +1,410 @@
+/**
+ * Safe, NON-EXECUTING parser for a GTM (Google Tag Manager) container export.
+ *
+ * SECURITY CONTRACT (the whole point of this module):
+ *   - The export is treated as inert DATA. Nothing in it is ever executed,
+ *     evaluated, interpreted, compiled, or run. There is no `eval`, no
+ *     `new Function`, no dynamic `import()`, no `vm`, no template compilation.
+ *   - Fields that would be code in a live GTM runtime (Custom HTML `html`,
+ *     Custom Template `templateData` / `sandboxedJsForServer`, Custom JavaScript
+ *     variable `javascript`) are captured as opaque inert strings inside each
+ *     record's `raw` bag — see `sanitizeValue`.
+ *   - Pure data-in/data-out: no I/O, no network, no filesystem, no timers, no
+ *     globals mutated. `TextEncoder`/`TextDecoder`/`JSON.parse` are the only
+ *     platform primitives used, all read-only.
+ *   - Strict bounds are enforced BEFORE parse (byte cap) and DURING a structural
+ *     walk (depth/nodes/array-len). Over-length strings are truncated with a
+ *     flag, never rejected. Prototype-polluting keys are quarantined.
+ *   - The parser NEVER throws on bad input; it returns a structured result.
+ */
+
+import type { ParseBounds } from "./bounds.js";
+import { DEFAULT_BOUNDS, enforceBounds, resolveBounds } from "./bounds.js";
+import type {
+  GtmContainer,
+  GtmContainerVersion,
+  GtmInertRecord,
+  GtmParseAccounting,
+  GtmParseResult,
+} from "./types.js";
+import type { GtmViolation } from "./bounds.js";
+
+export { DEFAULT_BOUNDS } from "./bounds.js";
+
+/** Keys that must never become live prototype writes; skipped into a quarantine count. */
+const POLLUTING_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+/** `containerVersion` collection keys we model as arrays of inert records. */
+const COLLECTION_KEYS = [
+  "tag",
+  "trigger",
+  "variable",
+  "builtInVariable",
+  "customTemplate",
+  "folder",
+  "zone",
+  "client",
+  "gtagConfig",
+  "transformation",
+] as const;
+
+/** `containerVersion` metadata keys we lift onto the typed model. */
+const METADATA_KEYS = new Set([
+  "containerId",
+  "path",
+  "publicId",
+  "fingerprint",
+  "name",
+  "container", // nested container object holding some of the above
+]);
+
+/** Candidate keys GTM uses for a record's id, in preference order. */
+const ID_KEYS = [
+  "tagId",
+  "triggerId",
+  "variableId",
+  "clientId",
+  "zoneId",
+  "folderId",
+  "templateId",
+  "transformationId",
+  "gtagConfigId",
+  "builtInVariableId",
+  "id",
+] as const;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** UTF-8 byte length of a string. */
+function utf8ByteLength(input: string): number {
+  return new TextEncoder().encode(input).length;
+}
+
+/** Mutable accounting scratch threaded through extraction. */
+interface Accountant {
+  truncatedStrings: number;
+  quarantinedKeys: number;
+}
+
+/**
+ * Produce a deep INERT clone of `value`:
+ *   - objects become null-prototype (`Object.create(null)`), so a stray
+ *     `__proto__`/`constructor`/`prototype` key can never pollute a real
+ *     prototype; those keys are skipped and counted instead.
+ *   - strings over `maxStringLen` are truncated with a recorded flag.
+ *   - numbers/booleans/null pass through; anything exotic (function/symbol —
+ *     impossible from JSON.parse, defensive only) is dropped to null.
+ *
+ * Recursion is bounded by `maxDepth` (already guaranteed by `enforceBounds`,
+ * re-checked here defensively); depth overflow collapses to null.
+ */
+function sanitizeValue(
+  value: unknown,
+  bounds: ParseBounds,
+  acct: Accountant,
+  depth: number,
+): unknown {
+  if (depth > bounds.maxDepth) return null;
+
+  if (typeof value === "string") {
+    // inert-by-design: captured as opaque data, never executed. Code-bearing GTM
+    // fields (Custom HTML `html`, template `templateData`/`sandboxedJsForServer`,
+    // Custom JS `javascript`) arrive here as plain strings and stay plain strings.
+    if (value.length > bounds.maxStringLen) {
+      acct.truncatedStrings += 1;
+      return value.slice(0, bounds.maxStringLen);
+    }
+    return value;
+  }
+
+  if (typeof value === "number" || typeof value === "boolean" || value === null) {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    const out: unknown[] = [];
+    const limit = Math.min(value.length, bounds.maxArrayLen);
+    for (let i = 0; i < limit; i += 1) {
+      out.push(sanitizeValue(value[i], bounds, acct, depth + 1));
+    }
+    return out;
+  }
+
+  if (isPlainObject(value)) {
+    const out: Record<string, unknown> = Object.create(null);
+    for (const key of Object.keys(value)) {
+      if (POLLUTING_KEYS.has(key)) {
+        // Quarantine: never write these keys into the model.
+        acct.quarantinedKeys += 1;
+        continue;
+      }
+      out[key] = sanitizeValue(value[key], bounds, acct, depth + 1);
+    }
+    return out;
+  }
+
+  // Unreachable for JSON.parse output (no functions/symbols); defensive.
+  return null;
+}
+
+/** Read a string field off an object, returning null if absent/non-string. */
+function liftString(obj: Record<string, unknown>, key: string): string | null {
+  const v = obj[key];
+  return typeof v === "string" ? v : null;
+}
+
+/** Build one inert record: lift id/name/type, keep the COMPLETE inert bag as `raw`. */
+function toRecord(value: unknown, bounds: ParseBounds, acct: Accountant): GtmInertRecord {
+  const raw = sanitizeValue(value, bounds, acct, 0) as Record<string, unknown>;
+  let id: string | null = null;
+  let name: string | null = null;
+  let type: string | null = null;
+  if (isPlainObject(value)) {
+    for (const key of ID_KEYS) {
+      const candidate = liftString(value, key);
+      if (candidate !== null) {
+        id = candidate;
+        break;
+      }
+    }
+    name = liftString(value, "name");
+    type = liftString(value, "type");
+  }
+  return { id, name, type, raw };
+}
+
+/** Extract an array-valued collection into inert records (missing/non-array → []). */
+function toCollection(
+  containerVersion: Record<string, unknown>,
+  key: string,
+  bounds: ParseBounds,
+  acct: Accountant,
+): GtmInertRecord[] {
+  const arr = containerVersion[key];
+  if (!Array.isArray(arr)) return [];
+  const out: GtmInertRecord[] = [];
+  const limit = Math.min(arr.length, bounds.maxArrayLen);
+  for (let i = 0; i < limit; i += 1) {
+    out.push(toRecord(arr[i], bounds, acct));
+  }
+  return out;
+}
+
+/**
+ * Parse a GTM container export (format v2) into an inert typed model.
+ *
+ * NEVER throws and NEVER executes any part of the input.
+ */
+export function parseGtmExport(
+  input: string | Uint8Array,
+  bounds?: Partial<ParseBounds>,
+): GtmParseResult {
+  const b = resolveBounds(bounds);
+  const violations: GtmViolation[] = [];
+
+  // 1. Measure bytes and reject over cap BEFORE JSON.parse.
+  let byteLength: number;
+  if (input instanceof Uint8Array) {
+    byteLength = input.byteLength;
+  } else if (typeof input === "string") {
+    // Fast pre-check: UTF-8 byte length >= char count, so char count over the cap
+    // is already over the byte cap — reject without encoding a huge string.
+    if (input.length > b.maxBytes) {
+      return {
+        ok: false,
+        violations: [
+          {
+            path: "(input)",
+            code: "max_bytes",
+            message: `Input exceeds ${b.maxBytes} bytes; rejected before parse.`,
+          },
+        ],
+      };
+    }
+    byteLength = utf8ByteLength(input);
+  } else {
+    return {
+      ok: false,
+      violations: [
+        { path: "(input)", code: "invalid_input", message: "Input must be a string or Uint8Array." },
+      ],
+    };
+  }
+  if (byteLength > b.maxBytes) {
+    return {
+      ok: false,
+      violations: [
+        {
+          path: "(input)",
+          code: "max_bytes",
+          message: `Input is ${byteLength} bytes, over the ${b.maxBytes} byte cap; rejected before parse.`,
+        },
+      ],
+    };
+  }
+
+  // 2. Decode bytes → text (reject invalid UTF-8), then JSON.parse in try/catch.
+  let text: string;
+  if (input instanceof Uint8Array) {
+    try {
+      text = new TextDecoder("utf-8", { fatal: true }).decode(input);
+    } catch {
+      return {
+        ok: false,
+        violations: [
+          { path: "(input)", code: "invalid_utf8", message: "Input bytes are not valid UTF-8." },
+        ],
+      };
+    }
+  } else {
+    text = input;
+  }
+
+  let root: unknown;
+  try {
+    root = JSON.parse(text);
+  } catch (err) {
+    return {
+      ok: false,
+      violations: [
+        {
+          path: "(input)",
+          code: "invalid_json",
+          message: `Input is not valid JSON: ${err instanceof Error ? err.message : "parse error"}.`,
+        },
+      ],
+    };
+  }
+
+  // 3. Assert top-level v2 shape.
+  if (!isPlainObject(root)) {
+    return {
+      ok: false,
+      violations: [{ path: "(root)", code: "type", message: "Export root must be a JSON object." }],
+    };
+  }
+  const efv = root["exportFormatVersion"];
+  if (typeof efv !== "number" || !Number.isFinite(efv)) {
+    violations.push({
+      path: "exportFormatVersion",
+      code: "type",
+      message: "`exportFormatVersion` must be a finite number.",
+    });
+  }
+  const containerVersionRaw = root["containerVersion"];
+  if (!isPlainObject(containerVersionRaw)) {
+    violations.push({
+      path: "containerVersion",
+      code: "type",
+      message: "`containerVersion` must be a JSON object.",
+    });
+  }
+  if (violations.length > 0) {
+    return { ok: false, violations };
+  }
+  const containerVersion = containerVersionRaw as Record<string, unknown>;
+
+  // 4. Structural bounds walk (depth/nodes/array-len). Any breach → hard reject.
+  const boundsViolations = enforceBounds(root, b);
+  if (boundsViolations.length > 0) {
+    return { ok: false, violations: boundsViolations };
+  }
+
+  // 5. Extract collections into the inert model, quarantining polluting keys.
+  const acct: Accountant = { truncatedStrings: 0, quarantinedKeys: 0 };
+  const counts: Record<string, number> = Object.create(null);
+
+  const collections = {} as Record<(typeof COLLECTION_KEYS)[number], GtmInertRecord[]>;
+  for (const key of COLLECTION_KEYS) {
+    const records = toCollection(containerVersion, key, b, acct);
+    collections[key] = records;
+    counts[key] = records.length;
+  }
+
+  // Container metadata: prefer the nested `container` object where present.
+  const nested = isPlainObject(containerVersion["container"])
+    ? (containerVersion["container"] as Record<string, unknown>)
+    : undefined;
+  const meta = (key: string): string | null =>
+    liftString(containerVersion, key) ?? (nested ? liftString(nested, key) : null);
+
+  const modeledContainerVersion: GtmContainerVersion = {
+    containerId: meta("containerId"),
+    path: meta("path"),
+    publicId: meta("publicId"),
+    fingerprint: liftString(containerVersion, "fingerprint"),
+    name: meta("name"),
+    tag: collections.tag,
+    trigger: collections.trigger,
+    variable: collections.variable,
+    builtInVariable: collections.builtInVariable,
+    customTemplate: collections.customTemplate,
+    folder: collections.folder,
+    zone: collections.zone,
+    client: collections.client,
+    gtagConfig: collections.gtagConfig,
+    transformation: collections.transformation,
+  };
+
+  // 6. Complete accounting: nothing silently dropped.
+  const collectionSet = new Set<string>(COLLECTION_KEYS);
+  const unknownContainerKeys: string[] = [];
+  for (const key of Object.keys(containerVersion)) {
+    if (POLLUTING_KEYS.has(key)) {
+      acct.quarantinedKeys += 1;
+      continue;
+    }
+    if (!collectionSet.has(key) && !METADATA_KEYS.has(key)) {
+      unknownContainerKeys.push(key);
+    }
+  }
+  const unknownTopLevelKeys: string[] = [];
+  for (const key of Object.keys(root)) {
+    if (POLLUTING_KEYS.has(key)) {
+      acct.quarantinedKeys += 1;
+      continue;
+    }
+    if (key !== "exportFormatVersion" && key !== "containerVersion") {
+      unknownTopLevelKeys.push(key);
+    }
+  }
+
+  const accounting: GtmParseAccounting = {
+    counts,
+    unknownTopLevelKeys,
+    unknownContainerKeys,
+    truncatedStrings: acct.truncatedStrings,
+    quarantinedKeys: acct.quarantinedKeys,
+    totalNodes: countNodes(root, b),
+  };
+
+  const container: GtmContainer = {
+    exportFormatVersion: efv as number,
+    containerVersion: modeledContainerVersion,
+  };
+
+  return { ok: true, container, accounting };
+}
+
+/**
+ * Count nodes for accounting (the tree already passed `enforceBounds`, so this is
+ * bounded by `maxNodes`). Iterative to stay stack-safe.
+ */
+function countNodes(root: unknown, bounds: ParseBounds): number {
+  let nodes = 0;
+  const stack: unknown[] = [root];
+  while (stack.length > 0 && nodes <= bounds.maxNodes) {
+    const value = stack.pop();
+    nodes += 1;
+    if (Array.isArray(value)) {
+      const limit = Math.min(value.length, bounds.maxArrayLen);
+      for (let i = 0; i < limit; i += 1) stack.push(value[i]);
+    } else if (value !== null && typeof value === "object") {
+      const obj = value as Record<string, unknown>;
+      for (const key of Object.keys(obj)) stack.push(obj[key]);
+    }
+  }
+  return nodes;
+}

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

@@ -0,0 +1,266 @@
+/**
+ * Pure, NON-EXECUTING reference-extraction helpers for the GTM migration graph.
+ *
+ * SECURITY CONTRACT (inherited from the parser — a reviewer WILL reject violations):
+ *   - This is pure DATA transformation. Nothing here executes, evaluates,
+ *     interprets, or compiles any part of the (untrusted) GTM export. `{{...}}`
+ *     variable-reference extraction is STRING SCANNING ONLY (a bounded regex walk),
+ *     never evaluation of the referenced variable or of any code-bearing field.
+ *   - Pure and deterministic: no I/O, no network, no filesystem, no timers, no
+ *     globals mutated. Same input → same output, stable ordering.
+ *   - Every scan is BOUNDED (token caps) so an adversarial string/bag cannot blow
+ *     up the walk. Missing/wrong-typed fields degrade to empty, never throw.
+ *   - `raw` bags are null-prototype (see parse.ts); reads here use own-key access
+ *     and never trust a prototype chain.
+ */
+
+import type { GtmInertRecord } from "./types.js";
+
+/**
+ * Matches a single GTM variable reference token `{{Variable Name}}`.
+ *
+ * The inner class excludes `{` and `}` so nested/broken braces cannot span tokens,
+ * and `+?` keeps the match minimal. This is a lexical scan of inert text — the
+ * captured name is DATA (a lookup key), never something we evaluate.
+ */
+const TOKEN_RE = /\{\{\s*([^{}]+?)\s*\}\}/g;
+
+/**
+ * GTM custom-template type discriminator. A tag/variable backed by a custom
+ * template carries a `type` like `cvt_<containerId>_<n>` (which equals the
+ * template's `templateId`). This is a shape test only — no interpretation.
+ */
+const CUSTOM_TEMPLATE_TYPE_RE = /^cvt_/;
+
+/**
+ * Result of a bounded `{{...}}` token scan — the recovered names plus whether
+ * the PER-STRING match cap engaged (see `extractVariableTokensReport`).
+ */
+export interface ExtractVariableTokensResult {
+  /** Referenced variable names, trimmed/de-duplicated, insertion-ordered. */
+  readonly tokens: string[];
+  /**
+   * True when some individual string in `value` carried MORE `{{...}}`
+   * regex matches than `cap` allows to be consumed — i.e. the per-string
+   * match cap engaged and later matches in that string were never scanned.
+   * Distinct from the overall distinct-token cap (`tokens.length >= cap`),
+   * which the caller can already observe directly.
+   */
+  readonly perStringCapped: boolean;
+}
+
+/**
+ * Recursively scan an arbitrary inert JSON value for GTM `{{Variable Name}}`
+ * references and return the referenced variable NAMES (trimmed, de-duplicated,
+ * insertion-ordered for determinism) plus per-string cap observability, capped
+ * at `cap` total names.
+ *
+ * Bounded on every axis so an adversarial value cannot blow up the walk:
+ *   - at most `cap` distinct names are returned (scan stops once reached);
+ *   - at most `cap` regex matches are consumed per individual string;
+ *   - object/array traversal is depth-first over own keys/indices only.
+ *
+ * NEVER executes anything: `{{...}}` is matched as text, the name is kept as a
+ * string key. Non-string leaves contribute nothing.
+ */
+export function extractVariableTokensReport(value: unknown, cap: number): ExtractVariableTokensResult {
+  const out: string[] = [];
+  let perStringCapped = false;
+  if (!(Number.isFinite(cap) && cap > 0)) return { tokens: out, perStringCapped };
+  const seen = new Set<string>();
+
+  // Explicit stack — iterative traversal, so a deeply nested bag cannot overflow
+  // the JS call stack. (The parser already depth-bounds `raw`, defensive here.)
+  const stack: unknown[] = [value];
+  while (stack.length > 0) {
+    if (seen.size >= cap) break;
+    const node = stack.pop();
+
+    if (typeof node === "string") {
+      TOKEN_RE.lastIndex = 0;
+      let match: RegExpExecArray | null;
+      let perString = 0;
+      while ((match = TOKEN_RE.exec(node)) !== null) {
+        if (perString >= cap) {
+          // Bound work on a single adversarial string — more matches remained
+          // in this string than the per-string cap allows to be consumed.
+          perStringCapped = true;
+          break;
+        }
+        perString += 1;
+        const name = match[1] ?? "";
+        const trimmed = name.trim();
+        if (trimmed.length === 0) continue;
+        if (!seen.has(trimmed)) {
+          seen.add(trimmed);
+          out.push(trimmed);
+          if (seen.size >= cap) break;
+        }
+        // Guard against a zero-width match looping forever (regex uses +?, but
+        // be defensive if the engine ever returns an empty match).
+        if (match.index === TOKEN_RE.lastIndex) TOKEN_RE.lastIndex += 1;
+      }
+      continue;
+    }
+
+    if (Array.isArray(node)) {
+      // Push in reverse so pop() yields left-to-right (stable) order.
+      for (let i = node.length - 1; i >= 0; i -= 1) stack.push(node[i]);
+      continue;
+    }
+
+    if (node !== null && typeof node === "object") {
+      const obj = node as Record<string, unknown>;
+      const keys = Object.keys(obj);
+      for (let i = keys.length - 1; i >= 0; i -= 1) {
+        const k = keys[i];
+        if (k !== undefined) stack.push(obj[k]);
+      }
+    }
+  }
+
+  return { tokens: out, perStringCapped };
+}
+
+/**
+ * Convenience wrapper over `extractVariableTokensReport` for callers that only
+ * need the recovered names (not per-string cap observability).
+ */
+export function extractVariableTokens(value: unknown, cap: number): string[] {
+  return extractVariableTokensReport(value, cap).tokens;
+}
+
+/** 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;
+}
+
+/**
+ * Read a GTM trigger-id list off a record's `raw` under `key`
+ * (`firingTriggerId` / `blockingTriggerId`). GTM stores these as arrays of id
+ * STRINGS. Defensive: missing/non-array → `[]`; non-string / empty entries are
+ * dropped; result is de-duplicated with stable order.
+ */
+export function readTriggerIds(raw: Record<string, unknown>, key: string): string[] {
+  const v = own(raw, key);
+  if (!Array.isArray(v)) return [];
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const entry of v) {
+    if (typeof entry !== "string") continue;
+    if (entry.length === 0) continue;
+    if (seen.has(entry)) continue;
+    seen.add(entry);
+    out.push(entry);
+  }
+  return out;
+}
+
+/**
+ * Read `parentFolderId` off a record's `raw`. Defensive: missing / non-string /
+ * empty → `null`.
+ */
+export function readParentFolderId(raw: Record<string, unknown>): string | null {
+  const v = own(raw, "parentFolderId");
+  return typeof v === "string" && v.length > 0 ? v : null;
+}
+
+/** True when a `type` string denotes a GTM custom template (`cvt_<containerId>_<n>`). */
+export function isCustomTemplateType(type: string | null): boolean {
+  return typeof type === "string" && CUSTOM_TEMPLATE_TYPE_RE.test(type);
+}
+
+/**
+ * The custom-template type reference a tag/variable uses, or `null` when its
+ * `type` is not a custom-template type. The returned string is the FULL
+ * `cvt_<containerId>_<n>` token; resolve it against the `customTemplate`
+ * collection either directly (see `readTemplateTrailingId` for the common
+ * case where the collection is keyed by the bare `<n>`).
+ */
+export function readTemplateTypeRef(record: GtmInertRecord): string | null {
+  return isCustomTemplateType(record.type) ? record.type : null;
+}
+
+/**
+ * Extract the trailing `<n>` segment from a `cvt_<containerId>_<n>`
+ * custom-template type token — the substring after the LAST underscore. A
+ * real GTM tag/variable carries the full `cvt_<containerId>_<n>` as its
+ * `type`, while the `customTemplate` record it points at advertises just the
+ * bare `<n>` as its `templateId` (see `readTemplateId`). This is a pure
+ * string split, never interpretation of the token's meaning.
+ *
+ * Defensive: not a custom-template type, or a malformed/truncated token with
+ * nothing after the last underscore (e.g. `"cvt_5_"`) → `null`.
+ */
+export function readTemplateTrailingId(type: string): string | null {
+  if (!isCustomTemplateType(type)) return null;
+  const idx = type.lastIndexOf("_");
+  if (idx < 0 || idx === type.length - 1) return null;
+  return type.slice(idx + 1);
+}
+
+/**
+ * The `templateId` a `customTemplate` record advertises (what a tag/variable's
+ * `cvt_*` type resolves against). Falls back to the record's lifted `id`.
+ * Defensive: missing/non-string → `null`.
+ */
+export function readTemplateId(record: GtmInertRecord): string | null {
+  const v = own(record.raw, "templateId");
+  if (typeof v === "string" && v.length > 0) return v;
+  return record.id;
+}
+
+/**
+ * GTM reserves a high numeric id block for BUILT-IN triggers it never
+ * materializes as `trigger` collection objects (a container export lists the
+ * built-ins a tag fires on only by their reserved id, e.g. `2147479553` for
+ * "All Pages"). The block sits just under the signed-32-bit ceiling; container-
+ * relative trigger ids are small integers, so the boundary cleanly separates the
+ * two. A `firingTriggerId`/`blockingTriggerId` in this range is a valid built-in
+ * reference — NOT a broken/dangling one.
+ */
+export const GTM_RESERVED_TRIGGER_MIN = 2_147_479_553;
+export const GTM_RESERVED_TRIGGER_MAX = 2_147_483_647; // signed-32-bit max
+
+/**
+ * Known reserved built-in trigger ids → their GTM label. Ids in the reserved
+ * range but absent here resolve to a generic built-in label rather than
+ * dangling. This is a pure lookup table — no interpretation of the id's meaning.
+ */
+const KNOWN_BUILTIN_TRIGGERS = new Map<string, string>([
+  ["2147479553", "All Pages"],
+  ["2147479572", "Consent Initialization"],
+  ["2147479573", "Initialization"],
+]);
+
+/** A resolved built-in trigger: its display label + whether the exact id is known. */
+export interface BuiltInTriggerInfo {
+  readonly label: string;
+  readonly known: boolean;
+}
+
+/**
+ * Resolve a trigger-id string to built-in-trigger info when it falls in GTM's
+ * reserved range, else `null` (a real container-relative id, or a non-numeric /
+ * out-of-range token that must be treated as a genuine reference). Pure string →
+ * bounded numeric parse; never interprets the id's runtime meaning.
+ */
+export function resolveBuiltInTrigger(id: string): BuiltInTriggerInfo | null {
+  // Bounded, digits-only parse — an adversarial huge/garbage token never resolves.
+  if (!/^[0-9]{1,10}$/.test(id)) return null;
+  const n = Number(id);
+  if (!Number.isSafeInteger(n)) return null;
+  if (n < GTM_RESERVED_TRIGGER_MIN || n > GTM_RESERVED_TRIGGER_MAX) return null;
+  const label = KNOWN_BUILTIN_TRIGGERS.get(id);
+  return label ? { label, known: true } : { label: "GTM built-in trigger", known: false };
+}
+
+/**
+ * True when a `{{...}}` reference token names a GTM BUILT-IN variable — the
+ * underscore-prefixed internal dataLayer names (e.g. `{{_event}}`) that a
+ * container references but never materializes in the `variable` /
+ * `builtInVariable` collections. Such a reference is valid, not dangling.
+ */
+export function isBuiltInVariableRef(name: string): boolean {
+  return name.length > 1 && name.charCodeAt(0) === 0x5f /* '_' */;
+}