@salesforce/afv-skills 1.22.0 → 1.23.0

package/skills/investigating-agentforce-d360/scripts/assemble_dc.py

@@ -1,1624 +0,0 @@
-"""Assemble dc._session_tree.json from fetched DC artifacts.
-
-Given `DATA_ROOT/<sid>/dc.*.json` + `dc._session_manifest.json` (produced by
-`scripts/fetch_dc.py`), this module joins the rows in memory and emits:
-
-  - dc._session_tree.json    — session-rooted hierarchical view
-                                (Interaction → Step → Generation →
-                                GatewayRequest, with audit rows nested)
-
-The human-readable markdown summary is produced by a separate stage,
-`scripts/render_dc.py`, which reads only the tree.
-
-Design contract (see references/dc_pipeline_contract.md):
-
-  - No DMO fetches. Pure in-memory compute over already-fetched artifacts.
-  - Driven off `manifest["queries"][*]["name"]` — adding a 25th DMO to
-    fetch_dc.py doesn't require changes here (it just won't be placed in
-    the tree until the logic is extended).
-  - Declared binding chain nests GatewayRequest under LLM_STEP via
-    `Step.ssot__GenerationId__c → Generation → GatewayResponse → Request`.
-  - Chain-orphan GW calls fall through to a timestamp-window rule
-    (tier dominates: ACTION → TOPIC → TRUST_GUARDRAILS → any other;
-    innermost Step wins within a tier).
-  - PK collisions and parse warnings surface in `counts.*`, not stderr-only.
-
-Invocation:
-    python3 scripts/assemble_dc.py --session <sid>
-"""
-from __future__ import annotations
-
-import argparse
-import functools
-import html
-import json
-import re
-import sys
-from collections import defaultdict
-from dataclasses import dataclass, field
-from datetime import datetime
-from pathlib import Path
-from typing import Any, Dict, Iterable, List, Literal, Optional, Set, Tuple
-
-sys.path.insert(0, str(Path(__file__).parent))
-
-from config import DATA_ROOT, paths
-
-
-# ---- sentinels + constants -------------------------------------------------
-
-_NOT_SET = {"", "NOT_SET", None}
-_INTERNAL_TRACE_RE = re.compile(r'"internalTraceId":"([a-f0-9]+)"')  # @rule-suppress starter-sec-002 — re.compile, not eval/exec
-
-# Real, non-placeholder agent version. Matches the canonical `^v[0-9]+$`
-# shape that paths.session_dir requires AND excludes the `v0` placeholder
-# stamped by fetch_dc's MyAgent fallback (fetch_dc.py:570-597).
-# Used by `_promote_identity` to decide whether session_identity carries
-# a richer agent_version that should win over a manifest placeholder.
-_REAL_VERSION_RE = re.compile(r'^v[0-9]+$')  # @rule-suppress starter-sec-002 — re.compile, not eval/exec
-
-# Tier order for timestamp-window fallback. "any other" is an implicit last-resort
-# catch-all covering LLM_STEP (without declared binding), SESSION_END, and any
-# future step types not explicitly listed.
-_TIER_ORDER = ("ACTION_STEP", "TOPIC_STEP", "TRUST_GUARDRAILS_STEP")
-
-# Canonical identity-field name → ordered list of `gateway_request_tags.tag__c`
-# values that carry it, tried in order. Agent versions emit different tag
-# names: newer Atlas ReAct agents use `agent_developer_name` /
-# `agent_version_api_name`; legacy MyAgent builds omit the developer
-# name entirely and use the unprefixed `version_api_name`. First non-null
-# value wins. A single-element list means "no fallback known."
-_TAG_KEY_ALIASES: Dict[str, Tuple[str, ...]] = {
-    "agent_api_name": ("agent_developer_name",),
-    "agent_version": ("agent_version_api_name", "version_api_name"),
-}
-
-
-# ---- typed namespaces ------------------------------------------------------
-#
-# Four frozen dataclasses replace the former dict-bags. frozen=True guards
-# attribute re-assignment, not mutation of the dict values themselves — the
-# producers are responsible for handing in plain dicts (not defaultdicts) so
-# downstream helpers don't rely on auto-creation the type doesn't promise.
-
-@dataclass(frozen=True)
-class Indexes:
-    interactions_by_id: Dict[str, dict]
-    participants_by_id: Dict[str, dict]
-    generations_by_id: Dict[str, dict]
-    gw_req_by_id: Dict[str, dict]
-    gw_resp_by_resp_id: Dict[str, dict]
-    feedback_by_id: Dict[str, dict]
-    gw_resp_by_req_id: Dict[str, List[dict]]
-    steps_by_interaction: Dict[str, List[dict]]
-    messages_by_interaction: Dict[str, List[dict]]
-    gw_tags_by_parent: Dict[str, List[dict]]
-    gw_md_by_parent: Dict[str, List[dict]]
-    gw_llm_by_parent: Dict[str, List[dict]]
-    quality_by_parent: Dict[str, List[dict]]
-    quality_by_id: Dict[str, dict]
-    feedback_by_gen: Dict[str, List[dict]]
-    feedback_details_by_parent: Dict[str, List[dict]]
-    participant_role_by_id: Dict[str, Optional[str]]
-
-
-@dataclass(frozen=True)
-class PolymorphicSplits:
-    categories_by_generation: Dict[str, List[dict]]
-    categories_by_quality: Dict[str, List[dict]]
-    gw_records_by_gw_req: Dict[str, List[dict]]
-    gw_records_by_feedback: Dict[str, List[dict]]
-    tag_assoc_session: List[dict]
-    tag_assoc_by_interaction: Dict[str, List[dict]]
-    tag_assoc_by_moment: Dict[str, List[dict]]
-
-
-@dataclass(frozen=True)
-class BindingResults:
-    declared_gw_ids: Set[str]
-    declared_steps_with_gw: frozenset
-    step_id_to_gw_id: Dict[str, Optional[str]]
-    declared_collisions: int
-
-
-@dataclass(frozen=True)
-class Catalog:
-    agents_observed: List[str]
-    tag_definitions: List[dict]
-    tag_definition_associations: List[dict]
-    tags: List[dict]
-
-
-@dataclass
-class BinderCtx:
-    """Per-interaction scratch state used only by the timestamp-window pass.
-
-    Kept in a parallel `Dict[iid, BinderCtx]` instead of stashed on the
-    interaction view, so binder state can never leak into the emitted tree.
-    """
-    start_ts: Optional[datetime]
-    end_ts: Optional[datetime]
-    steps_with_ts: List[Tuple[dict, Optional[datetime], Optional[datetime]]]
-    reserved_step_ids: frozenset
-
-
-# ---- session-dir resolution ----------------------------------------------
-
-def _find_session_dir(sid: str) -> Path:
-    """Locate the session dir under the nested layout.
-
-    Given only a session id, we don't know ``(org, agent, version)`` upfront.
-    Strategy:
-
-    1. Validate ``sid`` against ``paths.SESSION_ID_RE`` at entry. ``sid`` comes
-       in via argv / resolve_session and flows directly into path composition
-       (``<org>/_sessions/<sid>.link``) and glob patterns; an unvalidated
-       value here would undo the traversal guard added in PR #657 BLOCKER-2.
-    2. Breadcrumb lookup: ``DATA_ROOT/<org>/_sessions/<sid>.link`` is a plain-
-       text relative-path pointer written by ``storage.save``. Iterate all
-       orgs, read each ``.link``, resolve against the breadcrumb's parent,
-       and **enforce containment** — a tampered or stale breadcrumb whose
-       target escapes ``DATA_ROOT`` is skipped (not raised) so a single
-       malicious breadcrumb can't DoS the whole resolver. Falls through to
-       the glob fallback on any breadcrumb miss.
-    3. Glob fallback: ``DATA_ROOT/*/*/<sid>/`` — ``sid`` is now validated at
-       entry so the pattern is fixed-depth and cannot glob outside its
-       intended 2-level subtree.
-    4. Raise ``SystemExit`` with a clear hint to run fetch_dc.py first.
-
-    Returns the absolute directory path.
-    """
-    # Validate first — rejects "../etc", "a/b", "", None, and control chars.
-    # ``sid`` from here on is safe to use as a path segment and as the tail
-    # of a fixed-depth glob.
-    paths.validate_session_id(sid)
-    root = paths.DATA_ROOT
-    if root.is_dir():
-        # Resolve DATA_ROOT once so containment checks don't repeat the walk.
-        root_resolved = root.resolve()
-        for org_dir in root.iterdir():
-            if not org_dir.is_dir():
-                continue
-            link = org_dir / "_sessions" / f"{sid}.link"
-            if link.is_file():
-                try:
-                    rel = link.read_text().strip()
-                except OSError:
-                    continue
-                # Resolve relative to the breadcrumb's parent (_sessions/),
-                # then enforce that the resolved path stays inside
-                # DATA_ROOT. ``.link`` contents are user-writable — a planted
-                # breadcrumb with ``../../../../etc/passwd`` must NOT pivot
-                # the assembler outside the plugin's data tree.
-                target = (link.parent / rel).resolve()
-                if not target.is_relative_to(root_resolved):
-                    # Stale or malicious breadcrumb. Skip — fall through to
-                    # the glob fallback rather than raising, so one bad
-                    # breadcrumb in one org doesn't block discovery in
-                    # another.
-                    continue
-                if target.is_dir():
-                    return target
-        # Glob fallback. ``sid`` is validated; the pattern is fixed-depth.
-        matches = list(root.glob(f"*/*/{sid}"))
-        if len(matches) == 1:
-            return matches[0]
-        if len(matches) > 1:
-            # Placeholder agent dirs (leading-underscore name like
-            # ``<org>/_agent_<botid>__v0/``) mark provisional sessions
-            # whose identity wasn't fully resolved at first write. When a
-            # real (agent, version) dir also exists for the same session,
-            # it's the authoritative home; the placeholder is stale.
-            # Prefer the real dir.
-            real = [p for p in matches if not p.parent.name.startswith("_")]
-            if len(real) == 1:
-                return real[0]
-            raise SystemExit(
-                f"assemble_dc: session {sid} resolves to {len(matches)} dirs "
-                f"under {root} — ambiguous. Check for duplicate sessions "
-                f"across agents."
-            )
-    raise SystemExit(
-        f"assemble_dc: session dir for {sid} not found under {root}; "
-        f"run fetch_dc.py first"
-    )
-
-
-# ---- loaders ---------------------------------------------------------------
-
-def _load(session_dir: Path, name: str, parse_warnings: List[str]) -> List[dict]:
-    """Load dc.<name>.json from session_dir. Missing → []. Malformed → [] + warning."""
-    p = session_dir / f"dc.{name}.json"
-    if not p.is_file():
-        return []
-    try:
-        return json.loads(p.read_text())
-    except (json.JSONDecodeError, OSError) as e:
-        print(f"assemble_dc: WARN dc.{name}.json unreadable: {str(e).splitlines()[0]}",
-              file=sys.stderr)
-        parse_warnings.append(name)
-        return []
-
-
-def _load_manifest(session_dir: Path) -> dict:
-    p = session_dir / "dc._session_manifest.json"
-    if not p.is_file():
-        raise SystemExit(
-            f"assemble_dc: manifest not found at {p}; run fetch_dc.py first"
-        )
-    manifest = json.loads(p.read_text())
-    if "queries" not in manifest:
-        raise SystemExit("assemble_dc: manifest schema changed — no 'queries' key")
-    return manifest
-
-
-def _load_all(sid: str) -> Tuple[dict, Dict[str, List[dict]], List[str], Path]:
-    """Return (manifest, rows_by_name, parse_warnings, session_dir).
-
-    Iterates manifest["queries"][*]["name"] rather than a hard-coded list —
-    a new DMO added to fetch_dc.py is picked up automatically.
-    """
-    session_dir = _find_session_dir(sid)
-    manifest = _load_manifest(session_dir)
-    parse_warnings: List[str] = []
-    rows = {
-        q["name"]: _load(session_dir, q["name"], parse_warnings)
-        for q in manifest["queries"]
-    }
-    return manifest, rows, parse_warnings, session_dir
-
-
-# ---- small helpers ---------------------------------------------------------
-
-def _clean(value: Any) -> Any:
-    """NOT_SET sentinel → None. Other values pass through."""
-    return None if value in _NOT_SET else value
-
-
-def _harvest_str(value: Any) -> Optional[str]:
-    """Harvest-layer string normalizer for the session-identity block.
-
-    Handles three quirks that `_clean` deliberately does not:
-    1. **html.unescape** — tag values arrive double-escaped
-       (`"&quot;0Xx…&quot;"`).
-    2. **Quote-strip** — after unescape most tag values are wrapped in
-       literal `"` characters; strip them.
-    3. **`UNSET_VALUE` sentinel** — Data Cloud emits this on a small set
-       of optional columns (e.g. `gateway_requests.promptTemplateVersionNo__c`,
-       certain `tag_first` values on cold-start sessions). Not observed
-       on the columns `_build_session_identity` currently reads, but
-       included defensively since the sentinel is part of the DC schema
-       contract and a harvest-layer reader should collapse it to None.
-
-    The binding / index layer uses `_clean()` / `_NOT_SET` which
-    intentionally omits these rules — they would be noise there.
-    """
-    if value is None:
-        return None
-    s = html.unescape(str(value)).strip()
-    if len(s) >= 2 and s.startswith('"') and s.endswith('"'):
-        s = s[1:-1]
-    return None if s in ("", "NOT_SET", "UNSET_VALUE") else s
-
-
-def _promote_identity(
-    manifest_value: Any,
-    session_identity_value: Any,
-    *,
-    kind: Literal["api_name", "version"],
-) -> Any:
-    """Pick the richer of (manifest, session_identity) for a top-level identity slot.
-
-    Background. ``fetch_dc._resolve_identity`` walks AGENT-role participant
-    rows for ``(api_name, version)``. On agent shapes like MyAgent the
-    AGENT rows can leave both fields NOT_SET, so the resolver falls back
-    (fetch_dc.py:570-597) to picking ``api_name`` from any participant row
-    and stamping ``version="v0"`` as a placeholder satisfying
-    ``paths.session_dir``'s ``^v[0-9]+$`` shape. The placeholder is enough
-    to land the session in a directory, but it's wrong: by wave 5 the
-    fetch has materialized ``gateway_request_tags`` rows carrying the real
-    ``agent_version_api_name`` (e.g. ``v24``), and ``_build_session_identity``
-    correctly harvests it onto ``session.identity``. The top-level
-    ``identity`` block was previously copied verbatim from the manifest,
-    so the placeholder leaked downstream while the right value sat
-    visible in the same JSON.
-
-    Policy:
-
-    - ``kind="version"``: if manifest is the ``"v0"`` placeholder AND
-      session_identity carries a non-``v0`` value matching ``^v[0-9]+$``,
-      promote. Otherwise keep manifest.
-    - ``kind="api_name"``: if manifest is NOT_SET-ish (None / "" / "NOT_SET"
-      / "NOT SET") AND session_identity has a real value, promote.
-      Otherwise keep manifest. (Crucially, when session_identity is None
-      and manifest has a value, we keep manifest — the strict AGENT-row
-      pick is intentional on healthy sessions.)
-    - When manifest and session_identity both carry real-but-disagreeing
-      values, the manifest wins. The strict AGENT-row pick is the
-      authoritative source on a normal session; we only promote in the
-      narrow case where the manifest carries a known placeholder /
-      NOT_SET sentinel and the harvest layer has something better.
-    """
-    if kind == "version":
-        if manifest_value != "v0":
-            return manifest_value
-        if not isinstance(session_identity_value, str):
-            return manifest_value
-        if session_identity_value == "v0":
-            return manifest_value
-        if not _REAL_VERSION_RE.match(session_identity_value):
-            return manifest_value
-        return session_identity_value
-    # kind == "api_name"
-    if manifest_value not in (None, "", "NOT_SET", "NOT SET"):
-        return manifest_value
-    if isinstance(session_identity_value, str) and session_identity_value:
-        return session_identity_value
-    return manifest_value
-
-
-def _reconcile_top_identity(
-    manifest: dict, session_identity: dict, org_id_15: Any,
-) -> dict:
-    """Build the top-level ``identity`` block, promoting placeholders.
-
-    Centralizes the policy in one place so the happy path
-    (`_assemble_session`) and the gateway-direct fallback don't drift
-    apart. Emits a stderr note when promotion fires so an investigator
-    sees the divergence at run time.
-    """
-    manifest_api = manifest.get("agent_api_name")
-    manifest_ver = manifest.get("agent_version")
-    session_api = session_identity.get("agent_api_name")
-    session_ver = session_identity.get("agent_version")
-
-    promoted_api = _promote_identity(manifest_api, session_api, kind="api_name")
-    promoted_ver = _promote_identity(manifest_ver, session_ver, kind="version")
-
-    if promoted_api != manifest_api:
-        print(
-            f"assemble_dc: identity promoted: agent_api_name "
-            f"{manifest_api!r} -> {promoted_api!r} (from session.identity)",
-            file=sys.stderr,
-        )
-    if promoted_ver != manifest_ver:
-        print(
-            f"assemble_dc: identity promoted: agent_version "
-            f"{manifest_ver} -> {promoted_ver} (from session.identity)",
-            file=sys.stderr,
-        )
-
-    return {
-        "org_id_15": org_id_15,
-        "agent_api_name": promoted_api,
-        "agent_version": promoted_ver,
-    }
-
-
-def _resolve_end_type(session_row: dict, rows: dict) -> Optional[str]:
-    """Resolve the session's terminal outcome with a Session→Step fallback.
-
-    Session DMO's ``ssot__AiAgentSessionEndType__c`` is authoritative when
-    populated, but on Messaging-channel and short E&O sessions it stays
-    ``NOT_SET`` even after the SESSION_END interaction has materialized.
-    The runtime writes the actual outcome (``CLOSED_USER_REQUEST``,
-    ``USER_ENDED``, ``ESCALATED``, ``TRANSFERRED``, ``TIMEOUT``) onto the
-    SESSION_END step's ``ssot__Name__c`` instead. Fall through to that
-    step when Session.EndType is missing, so the rendered summary stops
-    saying "session end not yet materialized in STDM" for sessions that
-    actually completed cleanly.
-    """
-    primary = _clean(session_row.get("ssot__AiAgentSessionEndType__c"))
-    if primary:
-        return primary
-    for step in rows.get("steps", []) or ():
-        if step.get("ssot__AiAgentInteractionStepType__c") == "SESSION_END":
-            name = _clean(step.get("ssot__Name__c"))
-            if name:
-                return name
-    return None
-
-
-def _ts(value: Any) -> Optional[datetime]:
-    """Parse an ISO-8601 timestamp. NOT_SET / non-string → None (unbounded)."""
-    if not isinstance(value, str) or value in _NOT_SET:
-        return None
-    try:
-        return datetime.fromisoformat(value.replace("Z", "+00:00"))
-    except ValueError:
-        return None
-
-
-def _index_unique(rows: Iterable[dict], key: str,
-                  collisions: List[dict], dmo_label: str) -> Dict[str, dict]:
-    """Build a {key_value: row} dict. On collision: first-write-wins + record."""
-    out: Dict[str, dict] = {}
-    for r in rows:
-        k = r.get(key)
-        if k in _NOT_SET:
-            continue
-        if k in out:
-            collisions.append({"dmo": dmo_label, "key": k})
-        else:
-            out[k] = r
-    return out
-
-
-def _groupby(rows: Iterable[dict], key: str) -> Dict[str, List[dict]]:
-    out: Dict[str, List[dict]] = defaultdict(list)
-    for r in rows:
-        k = r.get(key)
-        if k not in _NOT_SET:
-            out[k].append(r)
-    return dict(out)
-
-
-def _extract_trace_id(interaction: dict) -> Optional[str]:
-    """Prefer the primary column; fall back to AttributeText regex."""
-    tid = interaction.get("ssot__TelemetryTraceId__c")
-    if tid and tid not in _NOT_SET:
-        return tid
-    attr = interaction.get("ssot__AttributeText__c") or ""
-    if not attr:
-        return None
-    m = _INTERNAL_TRACE_RE.search(html.unescape(attr))
-    return m.group(1) if m else None
-
-
-# ---- declared binding chain ------------------------------------------------
-
-def _declared_gw_for_step(step: dict,
-                          generations_by_id: Dict[str, dict],
-                          gw_resp_by_resp_id: Dict[str, dict],
-                          gw_req_by_id: Dict[str, dict]) -> Optional[dict]:
-    """Step → Generation → Response → Request. Returns the GatewayRequest row or None."""
-    gen_id = step.get("ssot__GenerationId__c")
-    if gen_id in _NOT_SET:
-        return None
-    gen = generations_by_id.get(gen_id)
-    if not gen:
-        return None
-    resp_id = gen.get("generationResponseId__c")
-    if resp_id in _NOT_SET:
-        return None
-    resp = gw_resp_by_resp_id.get(resp_id)
-    if not resp:
-        return None
-    req_id = resp.get("generationRequestId__c")
-    if req_id in _NOT_SET:
-        return None
-    return gw_req_by_id.get(req_id)
-
-
-# ---- timestamp-window fallback --------------------------------------------
-
-def _tier(step_type: str) -> int:
-    """Lower is better. 0 = ACTION, 1 = TOPIC, 2 = GUARDRAIL, 3 = any other."""
-    try:
-        return _TIER_ORDER.index(step_type)
-    except ValueError:
-        return len(_TIER_ORDER)  # "any other"
-
-
-def _window_contains(gw_ts: datetime, start: Optional[datetime],
-                     end: Optional[datetime]) -> bool:
-    """Closed-closed containment. None end_ts → +∞. Missing start → no match."""
-    if start is None:
-        return False
-    if gw_ts < start:
-        return False
-    if end is None:
-        return True  # open-ended upward
-    return gw_ts <= end
-
-
-def _bind_ts_window(gw_req: dict,
-                    steps_with_ts: List[Tuple[dict, datetime, Optional[datetime]]],
-                    interaction_window: Tuple[Optional[datetime], Optional[datetime]],
-                    reserved_step_ids: "frozenset[str]") -> Tuple[str, Optional[str]]:
-    """Return (placement, bound_step_id).
-
-    placement ∈ {"step", "interaction", "unbound"}.
-    bound_step_id is set only when placement == "step".
-    """
-    gw_ts_raw = gw_req.get("timestamp__c")
-    gw_ts = _ts(gw_ts_raw)
-    if gw_ts is None:
-        return ("unbound", None)
-
-    # Step candidates: contains gw_ts AND not already declared-bound.
-    candidates = [
-        (step, start, end)
-        for step, start, end in steps_with_ts
-        if step["ssot__Id__c"] not in reserved_step_ids
-           and _window_contains(gw_ts, start, end)
-    ]
-    if candidates:
-        # Best tier → innermost (shortest window) → latest start_ts.
-        def sort_key(c):
-            step, start, end = c
-            tier = _tier(step.get("ssot__AiAgentInteractionStepType__c", ""))
-            # Window size; treat None end_ts as "longest" (so nested closed wins).
-            if end is None:
-                width = float("inf")
-            else:
-                width = (end - start).total_seconds()
-            # Invert latest-start-wins by negating seconds since epoch.
-            return (tier, width, -start.timestamp())
-        candidates.sort(key=sort_key)
-        winner = candidates[0][0]
-        return ("step", winner["ssot__Id__c"])
-
-    # Interaction window.
-    i_start, i_end = interaction_window
-    if _window_contains(gw_ts, i_start, i_end):
-        return ("interaction", None)
-    return ("unbound", None)
-
-
-# ---- gateway-request view builder -----------------------------------------
-
-def _build_gw_view(gw_req: dict, binding_method: str, *,
-                   idx: Indexes, dispatch: PolymorphicSplits,
-                   bound_step_id: Optional[str] = None) -> dict:
-    """Build one GatewayRequest view row.
-
-    `idx` and `dispatch` are kw-only so `functools.partial(_build_gw_view,
-    idx=..., dispatch=...)` bindings don't collide with positional args at
-    the 3 call sites (declared / timestamp_window / unbound).
-    """
-    gw_id = gw_req["gatewayRequestId__c"]
-    responses = idx.gw_resp_by_req_id.get(gw_id, [])
-    view: Dict[str, Any] = {
-        "binding_method": binding_method,
-        "gateway_request_id": gw_id,
-        "feature": _clean(gw_req.get("feature__c")),
-        "model": _clean(gw_req.get("model__c")),
-        "provider": _clean(gw_req.get("provider__c")),
-        "prompt_template_dev_name": _clean(gw_req.get("promptTemplateDevName__c")),
-        "prompt_tokens": gw_req.get("promptTokens__c"),
-        "completion_tokens": gw_req.get("completionTokens__c"),
-        "total_tokens": gw_req.get("totalTokens__c"),
-        # Carry the raw input prompt through the hierarchical view so the
-        # renderer can surface it in the opt-in "Planner LLM calls" section.
-        # The 64 KB display cap lives in render_dc, not here — the tree
-        # stores the authoritative payload.
-        "prompt_text": gw_req.get("prompt__c"),
-        "response": responses[0] if responses else None,
-        "tags": idx.gw_tags_by_parent.get(gw_id, []),
-        "records": dispatch.gw_records_by_gw_req.get(gw_id, []),
-        "metadata": idx.gw_md_by_parent.get(gw_id, []),
-        "llm": idx.gw_llm_by_parent.get(gw_id, []),
-    }
-    if bound_step_id is not None:
-        view["bound_to_step_id"] = bound_step_id
-    return view
-
-
-# ---- main assembly ---------------------------------------------------------
-
-def _build_indexes(rows: Dict[str, List[dict]], collisions: List[dict]) -> Indexes:
-    """Build all primary-key dicts and groupby tables. Returns a frozen Indexes."""
-    return Indexes(
-        interactions_by_id=_index_unique(
-            rows.get("interactions", []), "ssot__Id__c", collisions, "interactions_by_id"),
-        participants_by_id=_index_unique(
-            rows.get("participants", []), "ssot__Id__c", collisions, "participants_by_id"),
-        generations_by_id=_index_unique(
-            rows.get("generations", []), "generationId__c", collisions, "generations_by_id"),
-        gw_req_by_id=_index_unique(
-            rows.get("gateway_requests", []), "gatewayRequestId__c", collisions, "gw_req_by_id"),
-        gw_resp_by_resp_id=_index_unique(
-            rows.get("gateway_responses", []), "generationResponseId__c",
-            collisions, "gw_resp_by_resp_id"),
-        feedback_by_id=_index_unique(
-            rows.get("feedback", []), "feedbackId__c", collisions, "feedback_by_id"),
-        gw_resp_by_req_id=_groupby(rows.get("gateway_responses", []), "generationRequestId__c"),
-        steps_by_interaction=_groupby(rows.get("steps", []), "ssot__AiAgentInteractionId__c"),
-        messages_by_interaction=_groupby(rows.get("messages", []), "ssot__AiAgentInteractionId__c"),
-        gw_tags_by_parent=_groupby(rows.get("gateway_request_tags", []), "parent__c"),
-        gw_md_by_parent=_groupby(rows.get("gateway_request_metadata", []), "parent__c"),
-        gw_llm_by_parent=_groupby(rows.get("gateway_request_llm", []), "parent__c"),
-        quality_by_parent=_groupby(rows.get("content_quality", []), "parent__c"),
-        quality_by_id={q["id__c"]: q for q in rows.get("content_quality", []) if q.get("id__c")},
-        feedback_by_gen=_groupby(rows.get("feedback", []), "generationId__c"),
-        feedback_details_by_parent=_groupby(rows.get("feedback_details", []), "parent__c"),
-        participant_role_by_id={
-            p["ssot__Id__c"]: p.get("ssot__AiAgentSessionParticipantRole__c")
-            for p in rows.get("participants", []) if p.get("ssot__Id__c")
-        },
-    )
-
-
-def _dispatch_polymorphic(rows: Dict[str, List[dict]], idx: Indexes) -> PolymorphicSplits:
-    """Split ContentCategory, GtwyObjRecord, and TagAssociation by polymorphic parent.
-
-    Producers accumulate into defaultdicts for ergonomics, but the returned
-    dataclass stores plain dicts — frozen `Dict[...]` typing can't promise
-    auto-creation, so don't let it leak.
-    """
-    # ContentCategory: parent is either a generation or a quality row.
-    cat_by_gen: Dict[str, List[dict]] = defaultdict(list)
-    cat_by_qual: Dict[str, List[dict]] = defaultdict(list)
-    for cat in rows.get("content_category", []):
-        parent = cat.get("parent__c")
-        if parent in _NOT_SET:
-            continue
-        if parent in idx.generations_by_id:
-            cat_by_gen[parent].append(cat)
-        elif parent in idx.quality_by_id:
-            cat_by_qual[parent].append(cat)
-
-    # GtwyObjRecord: parent is either a gateway_request or a feedback row.
-    rec_by_gw: Dict[str, List[dict]] = defaultdict(list)
-    rec_by_fb: Dict[str, List[dict]] = defaultdict(list)
-    for rec in rows.get("gateway_records", []):
-        parent = rec.get("parent__c")
-        if parent in _NOT_SET:
-            continue
-        if parent in idx.gw_req_by_id:
-            rec_by_gw[parent].append(rec)
-        elif parent in idx.feedback_by_id:
-            rec_by_fb[parent].append(rec)
-
-    # TagAssociation: exactly one of session/interaction/moment FK is populated.
-    ta_session: List[dict] = []
-    ta_by_int: Dict[str, List[dict]] = defaultdict(list)
-    ta_by_mom: Dict[str, List[dict]] = defaultdict(list)
-    for ta in rows.get("tag_associations", []):
-        if ta.get("ssot__AiAgentSessionId__c") not in _NOT_SET:
-            ta_session.append(ta)
-        elif ta.get("ssot__AiAgentInteractionId__c") not in _NOT_SET:
-            ta_by_int[ta["ssot__AiAgentInteractionId__c"]].append(ta)
-        elif ta.get("ssot__AiAgentMomentId__c") not in _NOT_SET:
-            ta_by_mom[ta["ssot__AiAgentMomentId__c"]].append(ta)
-
-    return PolymorphicSplits(
-        categories_by_generation=dict(cat_by_gen),
-        categories_by_quality=dict(cat_by_qual),
-        gw_records_by_gw_req=dict(rec_by_gw),
-        gw_records_by_feedback=dict(rec_by_fb),
-        tag_assoc_session=ta_session,
-        tag_assoc_by_interaction=dict(ta_by_int),
-        tag_assoc_by_moment=dict(ta_by_mom),
-    )
-
-
-def _filter_catalog(rows: Dict[str, List[dict]]) -> Catalog:
-    """Filter org-wide tag vocabulary to only what's reachable from session agents."""
-    agents = {
-        p.get("ssot__AiAgentApiName__c") for p in rows.get("participants", [])
-        if p.get("ssot__AiAgentSessionParticipantRole__c") == "AGENT"
-           and p.get("ssot__AiAgentApiName__c") not in _NOT_SET
-    } | {
-        m.get("ssot__AiAgentApiName__c") for m in rows.get("moments", [])
-        if m.get("ssot__AiAgentApiName__c") not in _NOT_SET
-    }
-    # Mirror fetch_dc._resolve_identity's USER-row fallback. On agent shapes
-    # like MyAgent, AGENT-role rows leave api_name=NOT_SET while USER
-    # rows correctly carry the agent's api_name. Without this fallback, the
-    # session lands in a `<api_name>__v0/` directory but `agents_observed`
-    # is empty — directory and rendered catalog disagree. Only fires when the
-    # primary (AGENT + moments) sources turned up nothing usable; in normal
-    # sessions the USER and AGENT rows agree and the union is idempotent.
-    if not agents:
-        agents = {
-            p.get("ssot__AiAgentApiName__c") for p in rows.get("participants", [])
-            if p.get("ssot__AiAgentApiName__c") not in _NOT_SET
-        }
-    agents_observed = sorted(a for a in agents if a)
-    relevant_assocs = [
-        a for a in rows.get("tag_definition_associations", [])
-        if a.get("ssot__AiAgentApiName__c") in agents_observed
-    ]
-    relevant_def_ids = {
-        a["ssot__AiAgentTagDefinitionId__c"] for a in relevant_assocs
-        if a.get("ssot__AiAgentTagDefinitionId__c") not in _NOT_SET
-    }
-    return Catalog(
-        agents_observed=agents_observed,
-        tag_definitions=[d for d in rows.get("tag_definitions", [])
-                         if d.get("ssot__Id__c") in relevant_def_ids],
-        tag_definition_associations=relevant_assocs,
-        tags=[t for t in rows.get("tags", [])
-              if t.get("ssot__AiAgentTagDefinitionId__c") in relevant_def_ids],
-    )
-
-
-def _build_session_identity(rows: Dict[str, List[dict]], manifest: dict) -> dict:
-    """Harvest 18 identity fields from 4 DMOs for the `session.identity` block.
-
-    All row iteration is preceded by a deterministic sort so repeated runs
-    produce byte-identical output regardless of fetch order. `_harvest_str()` is
-    the shared normalizer — html.unescape + quote-strip + NOT_SET /
-    UNSET_VALUE / empty coercion. See references/dc_pipeline_contract.md
-    §2.9a for the field-to-column mapping.
-    """
-    # --- gateway_requests: sort by (timestamp__c, gatewayRequestId__c) ---
-    gwr_sorted = sorted(
-        rows.get("gateway_requests", []),
-        key=lambda r: (r.get("timestamp__c") or "",
-                       r.get("gatewayRequestId__c") or ""),
-    )
-
-    def _first_gwr(key: str) -> Optional[str]:
-        for r in gwr_sorted:
-            v = _harvest_str(r.get(key))
-            if v is not None:
-                return v
-        return None
-
-    org_id = _first_gwr("orgId__c")
-    platform_user_id = _first_gwr("userId__c")
-    planner_id = _first_gwr("plannerId__c")
-    bot_version_id = _first_gwr("botVersionId__c")
-    app_type = _first_gwr("appType__c")
-
-    # --- gateway_request_tags: sort by (parent__c, tag__c, tagValue__c) ---
-    tags_sorted = sorted(
-        rows.get("gateway_request_tags", []),
-        key=lambda r: (r.get("parent__c") or "",
-                       r.get("tag__c") or "",
-                       r.get("tagValue__c") or ""),
-    )
-    tag_first: Dict[str, Optional[str]] = {}
-    for t in tags_sorted:
-        k = t.get("tag__c")
-        if not k or k in tag_first:
-            continue
-        tag_first[k] = _harvest_str(t.get("tagValue__c"))
-
-    # --- sessions[0] — always exactly one row per session on this path ---
-    sessions = rows.get("sessions", [])
-    session_row = sessions[0] if sessions else {}
-
-    # --- participants: first USER-role row by ssot__Id__c ---
-    participants_sorted = sorted(
-        rows.get("participants", []),
-        key=lambda r: r.get("ssot__Id__c") or "",
-    )
-    messaging_end_user_id = None
-    for p in participants_sorted:
-        if p.get("ssot__AiAgentSessionParticipantRole__c") == "USER":
-            v = _harvest_str(p.get("ssot__ParticipantId__c"))
-            if v is not None:
-                messaging_end_user_id = v
-                break
-
-    def _aliased(identity_key: str) -> Optional[str]:
-        """Resolve an identity field via its tag-name fallback chain.
-
-        Parameter name intentionally avoids shadowing `dataclasses.field`.
-        """
-        for tag_key in _TAG_KEY_ALIASES[identity_key]:
-            v = tag_first.get(tag_key)
-            if v is not None:
-                return v
-        return None
-
-    # Expose VariableText__c bootstrap variables. Production messaging
-    # sessions leave this NOT_SET; Builder Previewer populates it with
-    # test-harness keys (__resolved_locale__, __supports_result_display__,
-    # etc.). Surfacing this is what makes channel-mode visible in the
-    # renderer.
-    messaging_session_id = _harvest_str(session_row.get("ssot__RelatedMessagingSessionId__c"))
-    voice_call_id = _harvest_str(session_row.get("ssot__RelatedVoiceCallId__c"))
-    bootstrap_variables = _parse_bootstrap_variables(
-        session_row.get("ssot__VariableText__c")
-    )
-
-    # Derive a `mode` field. ssot__AiAgentChannelType__c is identical for
-    # MIAW production and Builder Previewer (`SCRT2 - EmbeddedMessaging`);
-    # we have to look at related-id population and bootstrap_variables to
-    # tell them apart.
-    mode = _derive_mode(messaging_session_id, voice_call_id, bootstrap_variables)
-
-    # `voice_call_id` + `individual_id` are null on EmbeddedMessaging sessions.
-    # They populate on authenticated channels (voice, Experience Cloud with
-    # linked Individual). Kept for schema parallelism with messaging_session_id.
-    return {
-        "org_id": org_id,
-        "platform_user_id": platform_user_id,
-        "planner_id": planner_id,
-        "bot_version_id": bot_version_id,
-        "app_type": app_type,
-        "bot_id": tag_first.get("bot_id"),
-        "bot_name": tag_first.get("bot_name"),
-        "agent_api_name": _aliased("agent_api_name"),
-        "agent_label": tag_first.get("agent_label"),
-        "agent_version": _aliased("agent_version"),
-        "agent_type": tag_first.get("agent_type"),
-        "planner_name": tag_first.get("planner_name"),
-        "planner_type": tag_first.get("planner_type"),
-        "configured_model": tag_first.get("configured_model_name"),
-        "messaging_session_id": messaging_session_id,
-        "messaging_end_user_id": messaging_end_user_id,
-        "voice_call_id": voice_call_id,
-        "individual_id": _harvest_str(session_row.get("ssot__IndividualId__c")),
-        "bootstrap_variables": bootstrap_variables,
-        "mode": mode,
-    }
-
-
-# Test-harness bootstrap keys that are observed in Builder Previewer sessions
-# but NOT in MIAW production. The presence of any of these in
-# `ssot__VariableText__c` is the strongest at-rest signal that a session was
-# run through the Previewer rather than against a real customer messaging
-# session. Listed here as a frozenset so it's read-only at module level.
-# Builder Previewer adds these keys to ssot__VariableText__c at session
-# bootstrap; MIAW production sessions don't seed them. Used by _derive_mode
-# to distinguish previewer runs from real customer messaging sessions.
-_BUILDER_PREVIEWER_INDICATOR_KEYS: frozenset[str] = frozenset({
-    "__resolved_locale__",
-    "__locale_instruction__",
-    "__supports_result_display__",
-    "__show_tool_results_invoked__",
-})
-
-
-def _parse_bootstrap_variables(raw: Any) -> Optional[dict]:
-    """Parse `ssot__VariableText__c` defensively.
-
-    On real sessions this field can be:
-      - missing / None / NOT_SET / UNSET_VALUE         → returns None
-      - well-formed JSON (Builder Previewer)            → returns the dict
-      - HTML-entity-encoded JSON (some surfaces emit
-        the `&quot;`-escaped form)                      → unescaped, returns the dict
-      - truncated or malformed JSON                     → returns
-        `{"_parse_error": True, "_raw": <first 200 chars>}` so the renderer
-        can still flag that a bootstrap exists, just not parseable.
-
-    Returns None for the empty cases so the caller can treat None as
-    "no bootstrap" without distinguishing missing from sentinel.
-    """
-    if raw is None:
-        return None
-    s = html.unescape(str(raw)).strip()
-    if not s or s in _NOT_SET or s in ("NOT_SET", "UNSET_VALUE"):
-        return None
-    try:
-        parsed = json.loads(s)
-    except (json.JSONDecodeError, ValueError):
-        return {"_parse_error": True, "_raw": s[:200]}
-    # Defensive: VariableText__c is documented as a JSON object; if a future
-    # version emits a JSON array or scalar, surface it under `_raw` rather
-    # than letting downstream code crash on `.get()`.
-    if not isinstance(parsed, dict):
-        return {"_parse_error": True, "_raw": s[:200]}
-    return parsed
-
-
-def _derive_mode(
-    messaging_session_id: Optional[str],
-    voice_call_id: Optional[str],
-    bootstrap_variables: Optional[dict],
-) -> str:
-    """Distinguish MIAW production from Builder Previewer from voice.
-
-    `ssot__AiAgentChannelType__c` is identical (`SCRT2 - EmbeddedMessaging`)
-    for MIAW and Builder Previewer — useless for distinguishing them. The
-    real signals, in priority order:
-
-    1. `ssot__RelatedVoiceCallId__c` set ↔ voice channel.
-    2. `ssot__RelatedMessagingSessionId__c` set ↔ MIAW production
-       (a real MessagingSession record exists).
-    3. `RelatedMessagingSessionId__c` NOT_SET AND bootstrap_variables
-       contains test-harness keys ↔ Builder Previewer.
-    4. None of the above ↔ unknown (e.g. headless API runs, agent script
-       previewer cases that don't seed VariableText__c).
-
-    Return a stable enum string the renderer can match on.
-    """
-    if voice_call_id:
-        return "voice"
-    if messaging_session_id:
-        return "production_messaging"
-    if isinstance(bootstrap_variables, dict):
-        if set(bootstrap_variables) & _BUILDER_PREVIEWER_INDICATOR_KEYS:
-            return "builder_previewer"
-    return "unknown"
-
-
-def _declared_binding_pass(rows: Dict[str, List[dict]], idx: Indexes) -> BindingResults:
-    """Walk every step; claim GWs reachable via the declared chain.
-
-    Returns BindingResults(declared_gw_ids, declared_steps_with_gw,
-    step_id_to_gw_id, declared_collisions). `declared_steps_with_gw` is a
-    frozenset so downstream consumers can't accidentally mutate it.
-    `step_id_to_gw_id[step_id]` is the GW id when declared, or None when this
-    step's declared GW was already claimed by an earlier step (collision sentinel).
-    `declared_collisions` is the aggregate count of collision-sentinel entries.
-    """
-    declared_gw_ids: set = set()
-    declared_steps_with_gw: set = set()
-    step_id_to_gw_id: Dict[str, Optional[str]] = {}
-    for step in rows.get("steps", []):
-        gw_req = _declared_gw_for_step(
-            step, idx.generations_by_id, idx.gw_resp_by_resp_id, idx.gw_req_by_id)
-        if gw_req is None:
-            continue
-        gw_id = gw_req["gatewayRequestId__c"]
-        if gw_id in declared_gw_ids:
-            # Collision: second+ step reaches a GW already claimed.
-            step_id_to_gw_id[step["ssot__Id__c"]] = None
-            continue
-        declared_gw_ids.add(gw_id)
-        declared_steps_with_gw.add(step["ssot__Id__c"])
-        step_id_to_gw_id[step["ssot__Id__c"]] = gw_id
-    return BindingResults(
-        declared_gw_ids=declared_gw_ids,
-        declared_steps_with_gw=frozenset(declared_steps_with_gw),
-        step_id_to_gw_id=step_id_to_gw_id,
-        declared_collisions=sum(1 for v in step_id_to_gw_id.values() if v is None),
-    )
-
-
-def _build_step_view(step: dict, idx: Indexes, dispatch: PolymorphicSplits,
-                     step_id_to_gw_id: Dict[str, Optional[str]],
-                     build_gw) -> dict:
-    """Emit one Step view, including its Generation and (if declared) GatewayRequest.
-
-    `build_gw` is a `functools.partial` pre-bound with `idx`/`dispatch`
-    (see `assemble()`); call sites only supply `gw_req`, `binding_method`,
-    and optionally `bound_step_id`.
-    """
-    sid_step = step["ssot__Id__c"]
-    gen_id = step.get("ssot__GenerationId__c")
-    gen = idx.generations_by_id.get(gen_id) if gen_id not in _NOT_SET else None
-    generation_view = _build_generation_view(
-        gen, idx.quality_by_parent, dispatch.categories_by_generation,
-        dispatch.categories_by_quality, idx.feedback_by_gen,
-        idx.feedback_details_by_parent, dispatch.gw_records_by_feedback,
-    ) if gen is not None else None
-
-    gw_id = step_id_to_gw_id.get(sid_step)
-    gw_view = None
-    collision_flag = gw_id is None and sid_step in step_id_to_gw_id
-    if gw_id is not None:
-        gw_view = build_gw(idx.gw_req_by_id[gw_id], "declared")
-
-    # Mirror the bound gateway_request's model identifier onto the step
-    # itself so renderers can show "LLM_STEP <name> · <model>" without
-    # dereferencing the nested gateway view. The mirror is None when no
-    # gateway_request is bound (declared chain didn't reach, or the STDM
-    # exporter dropped writes — see the `gateway_requests_dropped_by_stdm`
-    # session_shape).
-    step_model_name = gw_view.get("model") if gw_view else None
-
-    step_view: Dict[str, Any] = {
-        "id": sid_step,
-        "type": step.get("ssot__AiAgentInteractionStepType__c"),
-        "name": step.get("ssot__Name__c"),
-        "start_ts": step.get("ssot__StartTimestamp__c"),
-        "end_ts": step.get("ssot__EndTimestamp__c"),
-        "error_text": _clean(step.get("ssot__ErrorMessageText__c")),
-        "model_name": step_model_name,
-        "generation": generation_view,
-        "gateway_request": gw_view,
-    }
-    if collision_flag:
-        step_view["gateway_request_collision"] = True
-    return step_view
-
-
-def _build_message_view(m: dict, participant_role_by_id: Dict[str, str]) -> dict:
-    mtype = m.get("ssot__AiAgentInteractionMessageType__c")
-    pid = m.get("ssot__AiAgentSessionParticipantId__c")
-    role = participant_role_by_id.get(pid)
-    if role is None:
-        role = "USER" if mtype == "Input" else "AGENT" if mtype == "Output" else None
-    return {
-        "message_id": m.get("ssot__Id__c"),
-        "type": mtype,
-        "role": role,
-        "participant_id": pid,
-        "text": m.get("ssot__ContentText__c"),
-        "content_type": m.get("ssot__AiAgentInteractionMsgContentType__c"),
-        "modality": m.get("Modality__c"),
-        "ts": m.get("ssot__MessageSentTimestamp__c"),
-    }
-
-
-def _build_interaction_view(interaction: dict, rows: Dict[str, List[dict]],
-                            idx: Indexes, dispatch: PolymorphicSplits,
-                            binding: BindingResults,
-                            build_gw) -> Tuple[dict, BinderCtx]:
-    """Emit one Interaction view plus its BinderCtx.
-
-    Returns (view, binder_ctx). Binder scratch state lives in the `BinderCtx`
-    and is keyed externally by `iid`; it never touches the emitted view, so
-    it can't leak into `dc._session_tree.json`. `build_gw` is the
-    `functools.partial` from `assemble()`.
-    """
-    iid = interaction["ssot__Id__c"]
-    trace_id = _extract_trace_id(interaction)
-
-    steps_sorted = sorted(
-        idx.steps_by_interaction.get(iid, []),
-        key=lambda s: (s.get("ssot__StartTimestamp__c") or "", s.get("ssot__Id__c") or ""))
-    step_views = [_build_step_view(s, idx, dispatch, binding.step_id_to_gw_id, build_gw)
-                  for s in steps_sorted]
-
-    # Step windows consumed only by _ts_window_pass via the parallel BinderCtx.
-    steps_with_ts: List[Tuple[dict, Optional[datetime], Optional[datetime]]] = [
-        (s, _ts(s.get("ssot__StartTimestamp__c")), _ts(s.get("ssot__EndTimestamp__c")))
-        for s in steps_sorted if _ts(s.get("ssot__StartTimestamp__c")) is not None
-    ]
-
-    messages_sorted = sorted(
-        idx.messages_by_interaction.get(iid, []),
-        key=lambda r: (r.get("ssot__MessageSentTimestamp__c") or "",
-                       r.get("ssot__Id__c") or ""))
-    msg_views = [_build_message_view(m, idx.participant_role_by_id)
-                 for m in messages_sorted]
-
-    view = {
-        "id": iid,
-        "type": interaction.get("ssot__AiAgentInteractionType__c"),
-        "topic": _clean(interaction.get("ssot__TopicApiName__c")),
-        "trace_id": trace_id,
-        "start_ts": interaction.get("ssot__StartTimestamp__c"),
-        "end_ts": interaction.get("ssot__EndTimestamp__c"),
-        "messages": msg_views,
-        "telemetry_spans": [s for s in rows.get("telemetry_spans", [])
-                            if s.get("ssot__TelemetryTrace__c") == trace_id],
-        "steps": step_views,
-        "timestamp_bound_gateway_calls": [],  # appended by _ts_window_pass
-        "tag_associations": dispatch.tag_assoc_by_interaction.get(iid, []),
-    }
-    binder_ctx = BinderCtx(
-        start_ts=_ts(interaction.get("ssot__StartTimestamp__c")),
-        end_ts=_ts(interaction.get("ssot__EndTimestamp__c")),
-        steps_with_ts=steps_with_ts,
-        reserved_step_ids=binding.declared_steps_with_gw,
-    )
-    return view, binder_ctx
-
-
-def _ts_window_pass(interactions_view: List[dict],
-                    binders: Dict[str, BinderCtx],
-                    idx: Indexes,
-                    binding: BindingResults,
-                    build_gw) -> Tuple[List[dict], dict]:
-    """Place every chain-orphan GW via timestamp-window, or into unbound[].
-
-    Reads per-interaction binder state from the parallel `binders` dict keyed
-    by `iv["id"]` — never from the view itself. Mutates `interactions_view`
-    in place only to append to `timestamp_bound_gateway_calls[]` (an emission
-    field, pre-initialized to `[]` in `_build_interaction_view`).
-
-    Returns (unbound_gw_calls, gw_binding_counts).
-    """
-    unbound: List[dict] = []
-    counts = {
-        "declared": len(binding.declared_gw_ids),
-        "timestamp_window": 0,
-        "unbound": 0,
-        "declared_collisions": binding.declared_collisions,
-    }
-    for gw_id, gw_req in idx.gw_req_by_id.items():
-        if gw_id in binding.declared_gw_ids:
-            continue
-        placed = False
-        for iv in interactions_view:
-            bctx = binders[iv["id"]]
-            placement, bound_step_id = _bind_ts_window(
-                gw_req,
-                bctx.steps_with_ts,
-                (bctx.start_ts, bctx.end_ts),
-                bctx.reserved_step_ids,
-            )
-            if placement in ("step", "interaction"):
-                iv["timestamp_bound_gateway_calls"].append(
-                    build_gw(gw_req, "timestamp_window", bound_step_id=bound_step_id))
-                counts["timestamp_window"] += 1
-                placed = True
-                break
-        if not placed:
-            unbound.append(build_gw(gw_req, "unbound"))
-            counts["unbound"] += 1
-
-    # Defense in depth: if anyone reintroduces the binder-cache-on-view
-    # pattern in a future edit, this catches it before the tree ever writes.
-    assert not any(k.startswith("_") for iv in interactions_view for k in iv), \
-        "binder scratch state leaked into interaction view — do not stash on the view dict"
-
-    return unbound, counts
-
-
-def _build_moments_view(rows: Dict[str, List[dict]], dispatch: PolymorphicSplits) -> List[dict]:
-    """session.moments[] with interaction_ids[] back-refs derived from MomentInteraction."""
-    by_moment: Dict[str, List[str]] = defaultdict(list)
-    for mi in rows.get("moment_interactions", []):
-        mid = mi.get("ssot__AiAgentMomentId__c")
-        iid = mi.get("ssot__AiAgentInteractionId__c")
-        if mid not in _NOT_SET and iid not in _NOT_SET:
-            by_moment[mid].append(iid)
-
-    moments_sorted = sorted(
-        rows.get("moments", []),
-        key=lambda r: (r.get("ssot__StartTimestamp__c") or "", r.get("ssot__Id__c") or ""))
-    return [
-        {
-            "moment_id": m.get("ssot__Id__c"),
-            "agent_api_name": _clean(m.get("ssot__AiAgentApiName__c")),
-            "agent_version": _clean(m.get("ssot__AiAgentVersionApiName__c")),
-            "request_summary_text": _clean(m.get("ssot__RequestSummaryText__c")),
-            "response_summary_text": _clean(m.get("ssot__ResponseSummaryText__c")),
-            "interaction_ids": sorted(by_moment.get(m.get("ssot__Id__c"), [])),
-            "start_ts": m.get("ssot__StartTimestamp__c"),
-            "end_ts": m.get("ssot__EndTimestamp__c"),
-            "tag_associations": dispatch.tag_assoc_by_moment.get(m.get("ssot__Id__c"), []),
-        }
-        for m in moments_sorted
-    ]
-
-
-def _build_participants_view(rows: Dict[str, List[dict]]) -> List[dict]:
-    return [
-        {
-            "participant_id": p.get("ssot__Id__c"),
-            "role": p.get("ssot__AiAgentSessionParticipantRole__c"),
-            "agent_api_name": _clean(p.get("ssot__AiAgentApiName__c")),
-            "agent_version": _clean(p.get("ssot__AiAgentVersionApiName__c")),
-            "agent_type": _clean(p.get("ssot__AiAgentType__c")),
-        }
-        for p in sorted(
-            rows.get("participants", []),
-            key=lambda r: (r.get("ssot__StartTimestamp__c") or "", r.get("ssot__Id__c") or ""))
-    ]
-
-
-def _build_counts(rows: Dict[str, List[dict]], dispatch: PolymorphicSplits,
-                  binding_counts: dict,
-                  manifest: dict, collisions: List[dict],
-                  parse_warnings: List[str]) -> dict:
-    int_by_type: Dict[str, int] = defaultdict(int)
-    step_by_type: Dict[str, int] = defaultdict(int)
-    for i in rows.get("interactions", []):
-        int_by_type[i.get("ssot__AiAgentInteractionType__c")] += 1
-    for s in rows.get("steps", []):
-        step_by_type[s.get("ssot__AiAgentInteractionStepType__c")] += 1
-
-    return {
-        "interactions_total": len(rows.get("interactions", [])),
-        "interactions_turn": int_by_type.get("TURN", 0),
-        "interactions_session_end": int_by_type.get("SESSION_END", 0),
-        "steps_total": len(rows.get("steps", [])),
-        "steps_by_type": {
-            k: step_by_type.get(k, 0) for k in
-            ("LLM_STEP", "ACTION_STEP", "TOPIC_STEP", "TRUST_GUARDRAILS_STEP", "SESSION_END")
-        },
-        "generations": len(rows.get("generations", [])),
-        "gateway_requests": len(rows.get("gateway_requests", [])),
-        "gateway_responses": len(rows.get("gateway_responses", [])),
-        "gateway_metadata": len(rows.get("gateway_request_metadata", [])),
-        "gateway_llm": len(rows.get("gateway_request_llm", [])),
-        "gateway_records_grounded": sum(len(v) for v in dispatch.gw_records_by_gw_req.values()),
-        "gateway_records_feedback": sum(len(v) for v in dispatch.gw_records_by_feedback.values()),
-        "feedback": len(rows.get("feedback", [])),
-        "audit_chain_1to1_ok": (
-            len(rows.get("gateway_requests", [])) == len(rows.get("gateway_responses", []))
-        ),
-        "gw_binding": binding_counts,
-        "session_shape": manifest.get("session_shape", "unknown"),
-        "pk_collisions": collisions,
-        "parse_warnings": parse_warnings,
-    }
-
-
-def assemble(sid: str) -> Tuple[dict, Path]:
-    """Orchestrate: load → index → dispatch → bind → build views → counts → tree.
-
-    Returns (tree, session_dir). The session_dir is resolved by
-    ``_find_session_dir`` (via breadcrumb or glob) and passed back so
-    the caller can write ``dc._session_tree.json`` next to the inputs
-    without re-scanning the disk.
-    """
-    manifest, rows, parse_warnings, session_dir = _load_all(sid)
-
-    # Short-circuit: session row not found.
-    sessions = rows.get("sessions", [])
-    if not sessions:
-        return _minimal_tree_session_not_found(sid, manifest, parse_warnings), session_dir
-
-    # Short-circuit: STDM Interaction/Step/Message DMOs haven't materialized yet
-    # (gateway_requests present, interactions/steps empty). Render the gateway
-    # chain directly instead of silently emitting an empty tree.
-    if manifest.get("session_shape") == "interactions_not_materialized_yet":
-        return _assemble_gateway_direct(sid, rows, manifest, parse_warnings), session_dir
-
-    collisions: List[dict] = []
-    # Phase 1: independent bags.
-    idx = _build_indexes(rows, collisions)
-    dispatch = _dispatch_polymorphic(rows, idx)
-    catalog = _filter_catalog(rows)
-    # Phase 2: derived bag that depends on idx.
-    binding = _declared_binding_pass(rows, idx)
-
-    # Bind the invariant gw-view args once; call sites supply only the varying ones.
-    build_gw = functools.partial(_build_gw_view, idx=idx, dispatch=dispatch)
-
-    # Build per-Interaction views + parallel binder state (sorted by start_ts).
-    interactions_view: List[dict] = []
-    binders: Dict[str, BinderCtx] = {}
-    for interaction in sorted(
-            rows.get("interactions", []),
-            key=lambda r: (r.get("ssot__StartTimestamp__c") or "",
-                           r.get("ssot__Id__c") or "")):
-        view, bctx = _build_interaction_view(interaction, rows, idx, dispatch, binding, build_gw)
-        interactions_view.append(view)
-        binders[view["id"]] = bctx
-
-    # Timestamp-window fallback; mutates interactions_view only via
-    # timestamp_bound_gateway_calls[].append.
-    unbound_gw_calls, gw_binding_counts = _ts_window_pass(
-        interactions_view, binders, idx, binding, build_gw)
-
-    session_row = sessions[0]
-    session_identity = _build_session_identity(rows, manifest)
-    # `org_id_15` is the canonical 15-char slice used by path helpers.
-    # Prefer the manifest-stamped value (resolved in wave 1a of fetch_dc
-    # from sessions[0].ssot__InternalOrganizationId__c); fall back to
-    # slicing session_identity.org_id (the 18-char form from
-    # gateway_requests) when the manifest is missing the field (older
-    # artifacts predate the manifest stamp).
-    org_id_15 = manifest.get("org_id_15")
-    if not org_id_15 and session_identity.get("org_id"):
-        org_id_15 = session_identity["org_id"][:15]
-    session_identity["org_id_15"] = org_id_15
-
-    # Top-level identity block — canonical location for the 3 segments
-    # needed to name the session dir. Richer identity fields live under
-    # `session.identity` as before.
-    # Promote richer values from `session_identity` when the manifest carries
-    # placeholders (notably ``agent_version="v0"`` from the MyAgent
-    # fallback in fetch_dc.py:570-597) — without this, the top-level block
-    # diverges from `session.identity` in the same JSON file.
-    top_identity = _reconcile_top_identity(manifest, session_identity, org_id_15)
-
-    return {
-        "identity": top_identity,
-        "session": {
-            "id": sid,
-            "_schema_version": 1,
-            "org": {
-                "alias": manifest.get("org_alias"),
-                "instance_url": manifest.get("instance_url"),
-            },
-            "identity": session_identity,
-            "start_ts": session_row.get("ssot__StartTimestamp__c"),
-            "end_ts": session_row.get("ssot__EndTimestamp__c"),
-            "end_type": _resolve_end_type(session_row, rows),
-            "channel": _harvest_str(session_row.get("ssot__AiAgentChannelType__c")),
-            "participants": _build_participants_view(rows),
-            "moments": _build_moments_view(rows, dispatch),
-            "interactions": interactions_view,
-            "session_tag_associations": dispatch.tag_assoc_session,
-            "unbound_gateway_calls": unbound_gw_calls,
-            "counts": _build_counts(rows, dispatch, gw_binding_counts,
-                                    manifest, collisions, parse_warnings),
-        },
-        "catalog": {
-            "agents_observed": catalog.agents_observed,
-            "tag_definitions": catalog.tag_definitions,
-            "tag_definition_associations": catalog.tag_definition_associations,
-            "tags": catalog.tags,
-        },
-        "_doc": (
-            "Assembled from "
-            "DATA_ROOT/<org>/<agent>__<ver>/<sid>/dc.*.json. "
-            "See dc._session_manifest.json for per-query counts and empty reasons. "
-            "Contract: references/dc_pipeline_contract.md."
-        ),
-    }, session_dir
-
-
-def _build_generation_view(gen: dict,
-                           quality_by_parent: Dict[str, List[dict]],
-                           categories_by_generation: Dict[str, List[dict]],
-                           categories_by_quality: Dict[str, List[dict]],
-                           feedback_by_gen: Dict[str, List[dict]],
-                           feedback_details_by_parent: Dict[str, List[dict]],
-                           gw_records_by_feedback: Dict[str, List[dict]]) -> dict:
-    gen_id = gen["generationId__c"]
-    # Quality rows with their TOXICITY sub-categories nested.
-    quality_rows = []
-    for q in quality_by_parent.get(gen_id, []):
-        q_view = dict(q)
-        q_view["_toxicity_subcategories"] = categories_by_quality.get(q.get("id__c"), [])
-        quality_rows.append(q_view)
-
-    # Feedback rows with details + feedback-attachment records nested.
-    feedback_rows = []
-    for fb in feedback_by_gen.get(gen_id, []):
-        fid = fb.get("feedbackId__c")
-        feedback_rows.append({
-            "feedback_id": fid,
-            "feedback": fb.get("feedback__c"),
-            "action": fb.get("action__c"),
-            "details": feedback_details_by_parent.get(fid, []),
-            "records": gw_records_by_feedback.get(fid, []),
-        })
-
-    return {
-        "generation_id": gen_id,
-        "response_id": _clean(gen.get("generationResponseId__c")),
-        "response_text": gen.get("responseText__c"),
-        "masked_response_text": gen.get("maskedResponseText__c"),
-        "response_parameters": gen.get("responseParameters__c"),
-        "feature": _clean(gen.get("feature__c")),
-        "quality": quality_rows,
-        "categories": categories_by_generation.get(gen_id, []),
-        "feedback": feedback_rows,
-    }
-
-
-_STDM_LAG_NOTE = (
-    "Interaction/Step/Message DMOs materialize on a separate cadence from "
-    "Gateway DMOs. For fresh sessions this view reflects the gateway chain "
-    "directly. Re-run in 24–72 hours for the full hierarchical trace."
-)
-
-
-def _assemble_gateway_direct(sid: str, rows: Dict[str, List[dict]],
-                              manifest: dict,
-                              parse_warnings: List[str]) -> dict:
-    """Build a gateway-chain-only tree for sessions whose STDM hierarchy hasn't materialized.
-
-    Mirrors ``_minimal_tree_session_not_found`` in shape, but populates a
-    ``session.gateway_chain[]`` harvested directly from ``gateway_requests``
-    joined to ``gateway_request_tags`` / ``gateway_request_metadata`` /
-    ``gateway_responses``. ``session.interactions`` is an explicit empty list
-    so consumers that walk it simply no-op.
-
-    The sentinel ``_source = "gateway_direct"`` is consumed by
-    ``render_dc._render_gateway_direct``.
-    """
-    sessions = rows.get("sessions", [])
-    session_row = sessions[0] if sessions else {}
-
-    # Reuse the canonical identity harvester — same tag-alias fallbacks,
-    # same normalization — and apply the same org_id_15 fallback as the
-    # happy path so the top-level identity block is consistent across shapes.
-    session_identity = _build_session_identity(rows, manifest)
-    org_id_15 = manifest.get("org_id_15")
-    if not org_id_15 and session_identity.get("org_id"):
-        org_id_15 = session_identity["org_id"][:15]
-    session_identity["org_id_15"] = org_id_15
-
-    # Same placeholder-promotion policy as the happy path — see
-    # `_reconcile_top_identity` for why we don't trust the manifest blindly.
-    top_identity = _reconcile_top_identity(manifest, session_identity, org_id_15)
-
-    # Group the child DMOs by parent once so the per-request loop stays O(n).
-    tags_by_req: Dict[str, List[dict]] = _groupby(
-        rows.get("gateway_request_tags", []), "parent__c")
-    md_by_req: Dict[str, List[dict]] = _groupby(
-        rows.get("gateway_request_metadata", []), "parent__c")
-    resp_by_req: Dict[str, List[dict]] = _groupby(
-        rows.get("gateway_responses", []), "generationRequestId__c")
-
-    # Deterministic order: sort by (timestamp__c, gatewayRequestId__c) so
-    # repeat runs on the same inputs produce byte-identical output.
-    gw_sorted = sorted(
-        rows.get("gateway_requests", []),
-        key=lambda r: (r.get("timestamp__c") or "",
-                       r.get("gatewayRequestId__c") or ""),
-    )
-
-    gateway_chain: List[dict] = []
-    for gw in gw_sorted:
-        gw_id = gw.get("gatewayRequestId__c")
-        # sf__Id (platform row id) isn't harvested by fetch_dc; the logical
-        # PK is gatewayRequestId__c. Keep both keys on the view so readers
-        # can lift either without re-joining.
-        sf_id = gw.get("sf__Id")
-
-        # timestamp: prefer the columns named in the change-request
-        # (requestTimeStamp__c, createdAt__c), then fall back to the
-        # documented column (timestamp__c in references/dc_dmo_fields.md).
-        timestamp = (
-            _clean(gw.get("requestTimeStamp__c"))
-            or _clean(gw.get("createdAt__c"))
-            or _clean(gw.get("timestamp__c"))
-        )
-
-        # Tag-driven fields. Use _harvest_str for html-unescape + quote-strip —
-        # same normalizer _build_session_identity uses on tag values.
-        tag_first: Dict[str, Optional[str]] = {}
-        for t in sorted(
-                tags_by_req.get(gw_id, []),
-                key=lambda r: (r.get("tag__c") or "",
-                               r.get("tagValue__c") or "")):
-            k = t.get("tag__c")
-            if not k or k in tag_first:
-                continue
-            tag_first[k] = _harvest_str(t.get("tagValue__c"))
-
-        # Prompt-template name: prefer the direct column on the request;
-        # fall back to the tag alias used by older agent builds.
-        prompt_template_dev_name = (
-            _clean(gw.get("promptTemplateDevName__c"))
-            or tag_first.get("prompt_template_dev_name")
-        )
-        # `feature` likewise prefers the typed column, falls back to tag.
-        feature = _clean(gw.get("feature__c")) or tag_first.get("feature")
-
-        # Response side — take the first by response timestamp. 1:1 invariant
-        # holds on every live session we've observed, but defend against the
-        # in-flight-call edge case by sorting deterministically.
-        responses_sorted = sorted(
-            resp_by_req.get(gw_id, []),
-            key=lambda r: (r.get("timestamp__c") or "",
-                           r.get("generationResponseId__c") or ""),
-        )
-        response_view: Optional[dict] = None
-        if responses_sorted:
-            resp = responses_sorted[0]
-            response_view = {
-                "timestamp": _clean(resp.get("timestamp__c")),
-                "finish_reason": _parse_finish_reason_params(resp.get("parameters__c")),
-            }
-
-        gateway_chain.append({
-            "gateway_request_id": gw_id,
-            "sf_id": sf_id,
-            "timestamp": timestamp,
-            "model": _clean(gw.get("model__c")),
-            "provider": _clean(gw.get("provider__c")),
-            "prompt_template_dev_name": prompt_template_dev_name,
-            "feature": feature,
-            "prompt_tokens": gw.get("promptTokens__c"),
-            "completion_tokens": gw.get("completionTokens__c"),
-            "total_tokens": gw.get("totalTokens__c"),
-            # Raw prompt is authoritative on disk (dc.gateway_requests.json);
-            # the 64 KB display cap lives in the render layer, not here.
-            "prompt_text": gw.get("prompt__c"),
-            "metadata": md_by_req.get(gw_id, []),
-            "tags": tags_by_req.get(gw_id, []),
-            "response": response_view,
-        })
-
-    return {
-        "identity": top_identity,
-        "_source": "gateway_direct",
-        "session": {
-            "id": sid,
-            "_schema_version": 1,
-            "org": {
-                "alias": manifest.get("org_alias"),
-                "instance_url": manifest.get("instance_url"),
-            },
-            "identity": session_identity,
-            "start_ts": session_row.get("ssot__StartTimestamp__c"),
-            "end_ts": session_row.get("ssot__EndTimestamp__c"),
-            "end_type": _resolve_end_type(session_row, rows),
-            "channel": _harvest_str(session_row.get("ssot__AiAgentChannelType__c")),
-            "participants": _build_participants_view(rows),
-            # Explicit empty list — downstream consumers walk this and must
-            # no-op safely when STDM hasn't materialized yet.
-            "interactions": [],
-            "gateway_chain": gateway_chain,
-            "_stdm_lag_note": _STDM_LAG_NOTE,
-            "counts": {
-                "session_shape": manifest.get("session_shape",
-                                              "interactions_not_materialized_yet"),
-                "gateway_requests": len(rows.get("gateway_requests", [])),
-                "gateway_responses": len(rows.get("gateway_responses", [])),
-                "gateway_metadata": len(rows.get("gateway_request_metadata", [])),
-                "gateway_tags": len(rows.get("gateway_request_tags", [])),
-                "interactions_total": 0,
-                "steps_total": 0,
-                "parse_warnings": parse_warnings,
-            },
-        },
-        "_doc": (
-            f"Session {sid}: STDM Interaction/Step/Message DMOs have not "
-            "materialized yet (they lag Gateway DMOs by hours to days). "
-            "Tree carries the gateway chain harvested directly from "
-            "GenAIGatewayRequest + related audit DMOs. Re-run fetch_dc.py "
-            "in 24–72h once the STDM hierarchy has caught up for the full "
-            "hierarchical trace."
-        ),
-    }
-
-
-def _parse_finish_reason_params(parameters: Optional[str]) -> Optional[str]:
-    """Lift finish_reason out of GatewayResponse.parameters__c.
-
-    The field arrives HTML-escaped and the finish_reason value itself is
-    often wrapped in escaped quotes (e.g. `\\"stop\\"`). Mirrors
-    ``render_dc._parse_finish_reason`` but against the gateway-response
-    parameters column rather than Generation.responseParameters__c.
-    """
-    if not parameters:
-        return None
-    try:
-        decoded = html.unescape(parameters)
-        parsed = json.loads(decoded)
-    except (ValueError, TypeError):
-        return None
-    raw = parsed.get("finish_reason") if isinstance(parsed, dict) else None
-    if not isinstance(raw, str):
-        return None
-    return raw.replace("\\", "").strip('"').strip() or None
-
-
-def _minimal_tree_session_not_found(sid: str, manifest: dict,
-                                     parse_warnings: List[str]) -> dict:
-    # Note: deliberately does NOT include `session.identity` — harvest
-    # sources (gateway_requests, gateway_request_tags, sessions[0],
-    # participants) are all empty on this path. Renderer's minimal-tree
-    # branch must handle absent identity. DOES include _schema_version so
-    # the renderer's version check doesn't warn on every not-found session.
-    #
-    # Top-level `identity` still carries the manifest-stamped (org, agent,
-    # version) when available — the session dir already exists under that
-    # identity or the manifest couldn't have been read. Breadcrumb readers
-    # depend on this block being present on EVERY tree, not just
-    # full-populated ones.
-    return {
-        "identity": {
-            "org_id_15": manifest.get("org_id_15"),
-            "agent_api_name": manifest.get("agent_api_name"),
-            "agent_version": manifest.get("agent_version"),
-        },
-        "session": {
-            "id": sid,
-            "_schema_version": 1,
-            "org": {
-                "alias": manifest.get("org_alias"),
-                "instance_url": manifest.get("instance_url"),
-            },
-            "counts": {
-                "session_shape": manifest.get("session_shape", "session_not_found"),
-                "parse_warnings": parse_warnings,
-            },
-        },
-        "_doc": (
-            f"Session {sid} did not resolve in Data Cloud "
-            "(sessions.json returned 0 rows). Check the session id, or wait for "
-            "STDM materialization. No interactions, catalog, or audit rows available."
-        ),
-    }
-
-
-# ---- public entry points --------------------------------------------------
-
-def main_for_session(sid: str) -> int:
-    """Called by fetch_dc.py's auto-run hook and by `--session` CLI.
-
-    Writes ``dc._session_tree.json`` into the session dir located by
-    ``_find_session_dir`` (via breadcrumb / glob) — the caller does not
-    need to know ``(org, agent, version)`` to invoke the assembler.
-    """
-    tree, session_dir = assemble(sid)
-    tree_path = session_dir / "dc._session_tree.json"
-    tree_path.write_text(json.dumps(tree, indent=2, sort_keys=True, default=str) + "\n")
-    print(f"assemble_dc: wrote {tree_path}", file=sys.stderr)
-    return 0
-
-
-def main() -> int:
-    ap = argparse.ArgumentParser(
-        prog="assemble_dc.py",
-        description="Assemble dc._session_tree.json for one session.",
-    )
-    ap.add_argument("--session", required=True,
-                    help="AI-agent session UUID or MessagingSession id (0Mw...). "
-                         "Messaging ids are resolved from disk "
-                         "(DATA_ROOT/*/dc.sessions.json); run fetch_dc.py first "
-                         "if the session hasn't been fetched yet.")
-    # Runtime-agnostic path overrides; default to ~/.vibe/...
-    from _shared.cli_override import add_cli_flags, apply_overrides
-    add_cli_flags(ap)
-    args = ap.parse_args()
-    apply_overrides(args, caller_globals=globals())
-    from resolve_session import resolve_disk_or_live
-    sid = resolve_disk_or_live(args.session)
-    return main_for_session(sid)
-
-
-if __name__ == "__main__":
-    sys.exit(main())