@salesforce/afv-skills 1.22.0 → 1.24.0

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

@@ -1,1045 +0,0 @@
-"""Fetch all 24 Data Cloud artifacts for one Agentforce session.
-
-Given a session UUID and an `sf` org alias, this CLI drives the waterfall
-of DC queries defined in `assets/dc/*.sql`, lands each result under the
-nested layout:
-
-    DATA_ROOT/<org_id_15>/<agent_api_name>__<agent_version>/<sid>/dc.<name>.json
-
-…via `storage.save`, and emits a `dc._session_manifest.json` summarizing
-counts, timings, and empty-by-design reasons.
-
-Design contract:
-  - SQL loaded via `dc.load_sql(name, **params)` only — no inline concat.
-  - Responses parsed via `dc.parse(response)` — no inline dict digging.
-  - Persistence via `storage.save(data, org, agent, ver, sid, "dc", name)`
-    — no direct writes. Every on-disk path is validated by
-    ``paths.session_dir`` before it's touched.
-  - Identity is resolved BEFORE the first write. The sessions + participants
-    queries run first so (org_id_15, agent_api_name, agent_version) can be
-    derived; those three segments name the session dir.
-  - Every output file is written exactly once; empty artifacts go through
-    `_fetch_empty(name, reason)` so the manifest records why.
-  - Rerunning the same session overwrites prior artifacts.
-
-Invocation:
-    python3 scripts/fetch_dc.py --session <uuid> --org <alias> [--verbose]
-
-After the waterfall finishes, the fetcher chains two downstream steps:
-  1. assemble_dc.main_for_session → dc._session_tree.json
-     (skip with --no-assemble).
-  2. render_dc.main_for_session → dc._session_summary.md
-     (skip with --no-render). Runs against the on-disk tree from step 1
-     or a prior run.
-
-## DC-access preflight
-
-Before the waterfall starts, we run a single cheap probe:
-
-    SELECT Id FROM ssot__AIAgentSession__dlm WHERE ssot__Id__c = '<esc_sid>' LIMIT 1
-
-If the probe fails (401/403, no org alias, resolve_org failure), we raise
-``DcAccessDenied`` and the top-level ``main()`` branches on
-``sys.stdin.isatty()``:
-
-  - Interactive (tty): print a 2-option menu, read one line from stdin.
-    (1) retry with a different --org  (2) cancel.
-  - Headless (no tty): emit a single-line JSON preamble to stdout and
-    ``exit(10)`` immediately. Orchestrators (subagents, CI, ``claude -p``)
-    see ``exit(10)`` as the stable contract for "DC access denied".
-
-``exit(10)`` is the stable contract between this skill and any orchestrator
-wrapper — a non-zero exit code that is distinct from generic errors.
-"""
-from __future__ import annotations
-
-import argparse
-import html
-import json
-import re
-import subprocess
-import sys
-import time
-from datetime import datetime, timezone
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).parent))
-
-from config import DATA_ROOT, paths, sql as _sql_mod
-from dc import SQL_DIR, DCQueryError, load_sql, post, resolve_org
-from storage import save
-
-
-# ---- preflight / exit contracts -------------------------------------------
-
-# Exit code reserved for "DC access denied".
-# Orchestrators grep for this specifically. See module docstring for the full
-# contract; do not reuse for other failure modes.
-EXIT_DC_ACCESS_DENIED = 10
-
-
-class DcAccessDenied(RuntimeError):
-    """DC probe failed in a way that tells us DC is unusable for this session.
-
-    Carries both a short machine-readable ``reason`` (for the JSON preamble
-    payload — e.g. ``"401"``, ``"no_org"``, ``"resolve_org_failed"``) and a
-    longer human-readable ``detail`` (surfaced in the interactive prompt).
-    """
-
-    def __init__(self, reason: str, detail: str) -> None:
-        self.reason = reason
-        self.detail = detail
-        super().__init__(f"{reason}: {detail}")
-
-
-def preflight_dc_access(
-    session_id: str,
-    org_alias: str,
-) -> tuple[str, str]:
-    """Probe DC for this session. Returns (instance_url, token) on success.
-
-    Runs the cheapest possible DC query — a single ``LIMIT 1`` against
-    ``ssot__AIAgentSession__dlm`` — to establish that:
-      - ``sf`` CLI can resolve the org alias to an instance URL + token.
-      - DC accepts the token (no 401/403).
-      - The session id is well-formed SOQL (no literal injection).
-
-    Raises ``DcAccessDenied`` on failure. The ``session_id`` is escaped
-    via ``sql._escape_sql_literal`` before being interpolated, matching
-    the Batch-C defense for ``_session_row_live``. The probe does NOT
-    require the session to exist — a zero-row response is success
-    (proves DC is reachable and auth'd).
-    """
-    # Stage 1: resolve org alias → instance_url + token. Any failure here
-    # is classified as "no_org" / "resolve_org_failed" — we never got far
-    # enough to hit DC.
-    try:
-        instance_url, token = resolve_org(org_alias)
-    except SystemExit as e:
-        raise DcAccessDenied("no_org", str(e)) from e
-
-    # Stage 2: issue the probe. Reuse ``sessions`` template with a narrow
-    # WHERE clause + LIMIT 1. The escape hardens against injection at the
-    # literal interpolation point.
-    esc_sid = _sql_mod._escape_sql_literal(session_id)
-    probe_sql = (
-        f"SELECT ssot__Id__c FROM ssot__AIAgentSession__dlm "
-        f"WHERE ssot__Id__c = '{esc_sid}' LIMIT 1"
-    )
-    try:
-        post(probe_sql, instance_url, token, "preflight")
-    except DCQueryError as e:
-        msg = str(e)
-        # Classify based on the HTTP code in the error message. The error
-        # body carries ``http=<code>`` right at the start per dc.post().
-        if "http=401" in msg:
-            raise DcAccessDenied("401", msg) from e
-        if "http=403" in msg:
-            raise DcAccessDenied("403", msg) from e
-        raise DcAccessDenied("dc_probe_failed", msg) from e
-    return instance_url, token
-
-
-def _emit_dc_access_denied_preamble(
-    reason: str,
-    detail: str,
-) -> None:
-    """Headless fallback: emit the machine-readable preamble to stdout.
-
-    Single-line JSON per the Batch-D plan. Followed by ``exit(EXIT_DC_ACCESS_DENIED)``
-    by the caller. Kept separate so tests can drive it without spawning a
-    subprocess.
-    """
-    payload = {
-        "status":  "DC_ACCESS_DENIED",
-        "reason":  reason,
-        "detail":  detail,
-        "options": [
-            {"code": "1", "action": "retry", "arg": "--org <alias>"},
-            {"code": "2", "action": "cancel"},
-        ],
-    }
-    print(json.dumps(payload))
-
-
-def _handle_dc_access_denied(
-    exc: DcAccessDenied,
-    *,
-    session_id: str,
-    is_tty: bool,
-) -> int:
-    """Branch on tty presence and return an exit code.
-
-    Interactive: print the 2-option menu; read one line from stdin.
-      - ``1`` → signal caller to retry (returns ``EXIT_DC_ACCESS_DENIED``;
-        outer ``main()`` may re-prompt for alias in a bounded loop — for
-        now we surface the exit code and let the user re-invoke).
-      - ``2`` → return 0 (user cancelled; graceful exit).
-
-    Headless: emit JSON preamble + ``EXIT_DC_ACCESS_DENIED`` immediately.
-    """
-    if not is_tty:
-        _emit_dc_access_denied_preamble(exc.reason, exc.detail)
-        return EXIT_DC_ACCESS_DENIED
-
-    _log(
-        f"\nThis skill requires Data Cloud access, which failed: "
-        f"{exc.detail}\nYour options:\n"
-        f"  (1) Retry with a different org alias (pass --org <alias>)\n"
-        f"  (2) Cancel\nPick one: "
-    )
-    try:
-        choice = sys.stdin.readline().strip()
-    except (KeyboardInterrupt, EOFError):
-        return 0
-    if choice == "1":
-        _log("Re-invoke with: python3 fetch_dc.py --session "
-             f"{session_id} --org <new-alias>")
-        return EXIT_DC_ACCESS_DENIED
-    # Any other response is treated as cancel.
-    return 0
-
-
-# ---- constants -------------------------------------------------------------
-
-_INTERNAL_TRACE_RE = re.compile(r'"internalTraceId":"([a-f0-9]+)"')  # @rule-suppress starter-sec-002 — re.compile, not exec/eval
-_NOT_SET = {"", "NOT_SET", None}
-# Mirrors _shared/fs_guard.API_NAME_RE. Duplicated locally as a pre-flight
-# gate so the cross-role fallback's adopted api_name string satisfies the
-# path-builder's regex before we hand it to paths.session_dir(). Without
-# this, paths.session_dir would reject the path with an opaque
-# ValidationError after the fallback claimed success — operator confusion.
-# Anchored \A...\Z + `.fullmatch()` (not ^...$ + .match) so trailing
-# newlines don't slip through; matches the security pattern in fs_guard.
-_API_NAME_RE = re.compile(r"\A[A-Za-z0-9_]+\Z")  # @rule-suppress starter-sec-002 — re.compile, not exec/eval
-# Mirrors _shared/fs_guard.AGENT_VERSION_RE. Used by the cross-role
-# fallback so we never adopt a malformed version string into a session-dir
-# path.
-_VERSION_RE = re.compile(r"\Av[0-9]+\Z")  # @rule-suppress starter-sec-002 — re.compile, not exec/eval
-
-# All 24 .sql templates — checked for existence at startup.
-_TEMPLATES = (
-    "sessions", "interactions", "messages", "moments", "participants",
-    "tag_associations", "gateway_requests",
-    "steps", "moment_interactions",
-    "telemetry_spans", "generations", "app_generation",
-    "gateway_request_tags", "gateway_responses", "gateway_records",
-    "gateway_request_metadata", "gateway_request_llm",
-    "feedback",
-    "content_quality", "content_category", "feedback_details",
-    "tag_definitions", "tag_definition_associations", "tags",
-)
-
-
-# ---- small helpers ---------------------------------------------------------
-
-def _in_list(ids: list[str]) -> str:
-    """SQL `IN (…)` fragment. Dedupes, drops NOT_SET/empty, preserves order."""
-    seen: dict[str, None] = {}
-    for i in ids:
-        if i and i not in _NOT_SET and i not in seen:
-            seen[i] = None
-    return "(" + ",".join(f"'{i}'" for i in seen) + ")"
-
-
-def _extract_trace_ids(interactions: list[dict]) -> list[str]:
-    """Pull runtime trace_ids from interaction rows.
-
-    `ssot__TelemetryTraceId__c` is often empty — the real trace_id lives
-    HTML-escaped inside `ssot__AttributeText__c` as `"internalTraceId":"…"`.
-    See references/dc_dmo_fields.md for the full gotcha.
-    """
-    out: list[str] = []
-    for r in interactions:
-        tid = r.get("ssot__TelemetryTraceId__c") or ""
-        if tid and tid not in _NOT_SET:
-            out.append(tid)
-            continue
-        attr = html.unescape(r.get("ssot__AttributeText__c") or "")
-        m = _INTERNAL_TRACE_RE.search(attr)
-        if m:
-            out.append(m.group(1))
-    # dedupe, preserve order
-    return list(dict.fromkeys(out))
-
-
-def _preflight_templates() -> None:
-    """Refuse to start if any .sql template is missing."""
-    missing = [n for n in _TEMPLATES if not (SQL_DIR / f"{n}.sql").is_file()]
-    if missing:
-        raise SystemExit(
-            f"missing SQL templates in {SQL_DIR}: {', '.join(missing)}"
-        )
-
-
-# ---- fetch helpers (single entry point for disk writes + manifest) --------
-
-def _log(msg: str) -> None:
-    print(msg, file=sys.stderr, flush=True)
-
-
-def _fetch(
-    ctx: dict,
-    wave: int,
-    name: str,
-    where: str,
-    order_by: str = "",
-    *,
-    join_path: str | None = None,
-) -> list[dict]:
-    """Run a live query, save result, append manifest entry, return rows."""
-    sql = load_sql(name, WHERE_CLAUSE=where, ORDER_BY=order_by)
-    if ctx["verbose"]:
-        _log(f"    SQL[{name}]:\n{sql}\n")
-    t0 = time.monotonic()
-    try:
-        rows = post(sql, ctx["instance_url"], ctx["token"], name)
-    except DCQueryError as e:
-        elapsed_ms = int((time.monotonic() - t0) * 1000)
-        _log(f"  dc.{name:<30} ERROR ({elapsed_ms}ms)")
-        entry = {
-            "name": name, "wave": wave, "rows": 0,
-            "elapsed_ms": elapsed_ms, "status": "error",
-            "_unavailable_reason": str(e).splitlines()[0],
-        }
-        ctx["queries"].append(entry)
-        return []
-    elapsed_ms = int((time.monotonic() - t0) * 1000)
-    # Only persist when there's data. Zero-row / error / skipped outcomes
-    # are recorded in the manifest (status + _unavailable_reason); a
-    # matching dc.<name>.json would be an empty `[]` file adding noise to
-    # the per-session directory. assemble_dc._load tolerates missing
-    # files by returning [].
-    if rows:
-        save(
-            rows,
-            ctx["org_id_15"],
-            ctx["agent_api_name"],
-            ctx["agent_version"],
-            ctx["session_id"],
-            "dc",
-            name,
-        )
-    entry = {
-        "name": name, "wave": wave, "rows": len(rows),
-        "elapsed_ms": elapsed_ms,
-        "status": "ok" if rows else "empty",
-    }
-    if join_path:
-        entry["join_path"] = join_path
-    if not rows:
-        entry["_unavailable_reason"] = (
-            f"query returned zero rows for where={where[:120]}"
-        )
-    ctx["queries"].append(entry)
-    _log(f"  dc.{name:<30} rows={len(rows):<5} ({elapsed_ms}ms)")
-    return rows
-
-
-def _fetch_empty(ctx: dict, wave: int, name: str, reason: str) -> None:
-    """Record a skipped query in the manifest — no HTTP call, no artifact file."""
-    ctx["queries"].append({
-        "name": name, "wave": wave, "rows": 0,
-        "elapsed_ms": 0, "status": "skipped",
-        "_unavailable_reason": reason,
-    })
-    _log(f"  dc.{name:<30} SKIPPED ({reason})")
-
-
-# ---- main entry point -----------------------------------------------------
-
-def main() -> int:
-    ap = argparse.ArgumentParser(
-        prog="fetch_dc.py",
-        description="Fetch all 24 DC artifacts for one Agentforce session.",
-    )
-    ap.add_argument("--session", required=True,
-                    help="AI-agent session UUID, OR a Salesforce MessagingSession id "
-                         "(0Mw... prefix). Messaging ids are resolved to the UUID "
-                         "via a one-row DC lookup before the waterfall starts.")
-    ap.add_argument("--org", required=True, help="sf org alias")
-    ap.add_argument("--verbose", action="store_true", help="dump each SQL before POST")
-    ap.add_argument("--no-assemble", action="store_true",
-                    help="skip tree assembly after fetch")
-    ap.add_argument("--no-render", action="store_true",
-                    help="skip summary markdown rendering")
-    # 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())
-
-    _preflight_templates()
-
-    # Accept either a UUID or a MessagingSession id (0Mw...). The resolver
-    # passes UUIDs through unchanged; on messaging ids it tries disk first
-    # (any prior fetch left dc.sessions.json behind under DATA_ROOT), and
-    # falls back to a live one-row DC lookup only if disk misses. This keeps
-    # fetch_dc consistent with every other entry point and avoids a
-    # round-trip when re-invoking against an already-fetched session.
-    # On multi-match or zero-match the resolver exits with a diagnostic.
-    from resolve_session import is_messaging_id, resolve_disk_or_live
-    input_id = args.session
-    session_id = resolve_disk_or_live(input_id, org=args.org)
-    if is_messaging_id(input_id):
-        _log(f"resolved messaging id {input_id} → AiAgentSession {session_id}")
-
-    # Preflight — one cheap probe before the waterfall starts.
-    # Fails fast with DcAccessDenied on 401/403/no-org. The outer try
-    # block routes the exception through _handle_dc_access_denied, which
-    # emits either an interactive prompt or a JSON preamble depending on
-    # tty presence, then exits with EXIT_DC_ACCESS_DENIED (10).
-    try:
-        instance_url, token = preflight_dc_access(session_id, args.org)
-    except DcAccessDenied as exc:
-        return _handle_dc_access_denied(
-            exc,
-            session_id=session_id,
-            is_tty=sys.stdin.isatty(),
-        )
-    _log(f"org:     {instance_url}")
-    _log(f"session: {session_id}\n")
-
-    ctx = {
-        "session_id": session_id,
-        "org_alias": args.org,
-        "instance_url": instance_url,
-        "token": token,
-        "verbose": args.verbose,
-        "queries": [],
-        "started_at": datetime.now(timezone.utc),
-        # Populated by _resolve_identity() before the first storage.save call.
-        "org_id_15": None,
-        "agent_api_name": None,
-        "agent_version": None,
-    }
-
-    _run_waterfall(ctx)
-
-    _write_manifest(ctx)
-
-    if not args.no_assemble:
-        from assemble_dc import main_for_session as _assemble
-        _assemble(args.session)
-
-    if not args.no_render:
-        from render_dc import main_for_session as _render
-        _render(args.session)  # SystemExits if tree is missing
-
-    return 0
-
-
-def _fetch_no_save(
-    ctx: dict, wave: int, name: str, where: str, order_by: str = "",
-) -> list[dict]:
-    """Variant of ``_fetch`` that skips the on-disk write.
-
-    Used for the identity-resolution phase: ``sessions`` and ``participants``
-    run before we know ``(org_id_15, agent_api_name, agent_version)``, which
-    are required to build the target session dir. We stash the rows and
-    write them via ``storage.save`` once identity is resolved.
-
-    Manifest entry is still appended so the final ``dc._session_manifest.json``
-    mirrors every query run.
-    """
-    sql = load_sql(name, WHERE_CLAUSE=where, ORDER_BY=order_by)
-    if ctx["verbose"]:
-        _log(f"    SQL[{name}]:\n{sql}\n")
-    t0 = time.monotonic()
-    try:
-        rows = post(sql, ctx["instance_url"], ctx["token"], name)
-    except DCQueryError as e:
-        elapsed_ms = int((time.monotonic() - t0) * 1000)
-        _log(f"  dc.{name:<30} ERROR ({elapsed_ms}ms)")
-        ctx["queries"].append({
-            "name": name, "wave": wave, "rows": 0,
-            "elapsed_ms": elapsed_ms, "status": "error",
-            "_unavailable_reason": str(e).splitlines()[0],
-        })
-        return []
-    elapsed_ms = int((time.monotonic() - t0) * 1000)
-    entry = {
-        "name": name, "wave": wave, "rows": len(rows),
-        "elapsed_ms": elapsed_ms,
-        "status": "ok" if rows else "empty",
-    }
-    if not rows:
-        entry["_unavailable_reason"] = (
-            f"query returned zero rows for where={where[:120]}"
-        )
-    ctx["queries"].append(entry)
-    _log(f"  dc.{name:<30} rows={len(rows):<5} ({elapsed_ms}ms)  [deferred save]")
-    return rows
-
-
-def _lookup_org_id_via_sf_cli(org_alias: str) -> str:
-    """Return the 15-char org id from ``sf org display --target-org <alias>``.
-
-    Fallback path for ``_resolve_identity``: the DMO field
-    ``ssot__InternalOrganizationId__c`` is occasionally null on
-    otherwise-well-formed sessions (materialization gap in the SSOT
-    pipeline). Since the authenticated ``sf`` alias already knows the
-    org id, we ask the CLI directly rather than failing the whole run.
-
-    Matches the shell pattern used by ``dc.resolve_org`` — same argv, same
-    JSON shape (``.result.id``). Any non-zero exit, missing binary, or
-    malformed payload propagates to the caller as an exception so the
-    outer ``_resolve_identity`` can raise a unified "both sources failed"
-    diagnostic.
-    """
-    proc = subprocess.run(
-        ["sf", "org", "display", "--target-org", org_alias, "--json"],
-        capture_output=True, text=True, check=True,
-    )
-    payload = json.loads(proc.stdout)
-    org_id = (payload.get("result") or {}).get("id") or ""
-    if len(org_id) < 15:
-        raise ValueError(
-            f"sf org display returned result.id={org_id!r} (len<15)"
-        )
-    return org_id[:15]
-
-
-def _resolve_identity(
-    sessions: list[dict],
-    participants: list[dict],
-    org_alias: str,
-) -> tuple[str, str, str]:
-    """Derive (org_id_15, agent_api_name, agent_version) from wave-1 rows.
-
-    - ``org_id_15`` — ``sessions[0].ssot__InternalOrganizationId__c[:15]``,
-      falling back to ``sf org display --target-org <org_alias>`` when the
-      DMO field is null/empty/shorter-than-15 (a known SSOT materialization
-      gap; the authenticated CLI alias knows the org id regardless).
-    - ``agent_api_name`` / ``agent_version`` — first AGENT participant row
-      (sorted by participant id for determinism) with both fields populated.
-
-    **Dominant-agent policy:** if multiple AGENT participants are present
-    (handoff sessions), the one with the lexicographically first
-    ``agent_api_name`` wins. Matches the ``sorted(agents_observed)[0]``
-    rule used by ``_session_row_live`` so every writer agrees on the
-    session's home dir.
-
-    Raises ``SystemExit`` with a clear diagnostic when any segment cannot
-    be derived. We deliberately do NOT fall back to a catch-all "unknown"
-    agent dir — writing under a synthetic identity would let every
-    ambiguous session pile into the same folder and corrupt the layout
-    invariant downstream readers depend on.
-    """
-    if not sessions:
-        raise SystemExit(
-            "fetch_dc: sessions query returned 0 rows; "
-            "cannot resolve org identity — is the session id correct?"
-        )
-    org_id_18 = sessions[0].get("ssot__InternalOrganizationId__c") or ""
-    if org_id_18 and len(org_id_18) >= 15:
-        org_id_15 = org_id_18[:15]
-    else:
-        # DMO field is null/empty/short. The session is otherwise well-formed
-        # — fall back to the authenticated sf alias for the org id.
-        try:
-            org_id_15 = _lookup_org_id_via_sf_cli(org_alias)
-        except (subprocess.CalledProcessError, FileNotFoundError,
-                json.JSONDecodeError, ValueError) as e:
-            raise SystemExit(
-                f"fetch_dc: both DMO field and sf org display failed — "
-                f"sessions[0].ssot__InternalOrganizationId__c={org_id_18!r}, "
-                f"sf org display --target-org {org_alias!r} error: "
-                f"{type(e).__name__}: {e}"
-            )
-        _log(
-            f"  org_id_15 fallback to sf org display: {org_id_15} "
-            f"(DMO field was null)"
-        )
-
-    # Collect every AGENT participant with a non-empty agent_api_name +
-    # agent_version. Sort by (api_name, version) for a stable dominant-
-    # agent pick on handoffs.
-    candidates = sorted(
-        {
-            (
-                p.get("ssot__AiAgentApiName__c") or "",
-                p.get("ssot__AiAgentVersionApiName__c") or "",
-            )
-            for p in participants
-            if p.get("ssot__AiAgentSessionParticipantRole__c") == "AGENT"
-        }
-    )
-    # Drop entries missing either field.
-    candidates = [(n, v) for n, v in candidates if n and v and n not in _NOT_SET and v not in _NOT_SET]
-    if not candidates:
-        # Fallback: some agent shapes (e.g. MyAgent on Messaging)
-        # leave AGENT rows with api_name/version=NOT_SET while USER (or
-        # other-role) participant rows carry both fields. Harvest from
-        # ANY role first so we land on the real (api_name, version) pair
-        # — that's what assemble_dc later reconciles into the tree, so
-        # the dir name and tree.identity will agree out of the gate
-        # rather than dir=__v0/ + tree=__v24/.
-        cross_role = sorted({
-            (
-                p.get("ssot__AiAgentApiName__c") or "",
-                p.get("ssot__AiAgentVersionApiName__c") or "",
-            )
-            for p in participants
-        })
-        cross_role = [
-            (n, v) for n, v in cross_role
-            if n and n not in _NOT_SET
-            and v and v not in _NOT_SET
-            and _API_NAME_RE.fullmatch(n)
-            and _VERSION_RE.fullmatch(v)
-        ]
-        if cross_role:
-            api_name, version = cross_role[0]
-            _log(
-                f"  identity fallback: strict AGENT-row resolution failed; "
-                f"using api_name={api_name!r} version={version!r} from a "
-                f"non-AGENT participant row"
-            )
-            return org_id_15, api_name, version
-        # Last-ditch fallback: api_name from any role, but no version
-        # available anywhere. Stamp version='v0' (placeholder satisfying
-        # ^v[0-9]+$). Without this, the entire DC pipeline is unrunnable
-        # for those sessions even though all the downstream rows exist.
-        # The Builder Previewer shape legitimately lands here — every
-        # version_api_name in DC for that session truly is empty/v0.
-        any_names = sorted({
-            (p.get("ssot__AiAgentApiName__c") or "")
-            for p in participants
-        })
-        any_names = [n for n in any_names if n and n not in _NOT_SET]
-        # Only promote names that satisfy fs_guard's API_NAME_RE — otherwise
-        # paths.session_dir would reject the dir later with an opaque
-        # ValidationError. Cleaner UX is to fall through to the original
-        # SystemExit, which carries actionable diagnostic text.
-        any_names = [n for n in any_names if _API_NAME_RE.fullmatch(n)]
-        if any_names:
-            _log(
-                f"  identity fallback: strict AGENT-row resolution failed; "
-                f"no participant row carries (api_name, version) together; "
-                f"using api_name={any_names[0]!r} from any participant row, "
-                f"version='v0' (placeholder)"
-            )
-            return org_id_15, any_names[0], "v0"
-        raise SystemExit(
-            "fetch_dc: no AGENT participants with agent_api_name + "
-            "agent_version on this session; cannot resolve identity. "
-            "If the session was created recently, STDM materialization "
-            "may not have completed yet — retry in a few minutes. "
-            "Otherwise the session may be malformed."
-        )
-    agent_api_name, agent_version = candidates[0]
-    return org_id_15, agent_api_name, agent_version
-
-
-def _run_waterfall(ctx: dict) -> None:
-    """5-wave forward-only orchestration.
-
-    Wave 1 fetches session-scoped rows directly keyed on the session id.
-    Wave 2 fetches interaction-scoped rows (Steps, MomentInteractions).
-    Wave 3 fans out to Generation (via Step.GenerationId) and to the full
-    Gateway audit chain (via GatewayRequest.sessionId__c harvested in
-    wave 1 — GatewayResponse, Tags, ObjRecord, Metadata, LLM).
-    Wave 4 fetches Generation-scoped child rows (Quality, Category,
-    Feedback children).
-    Wave 5 fetches the agent/tag catalog (not session-keyed).
-
-    Every edge is forward from Session. See `references/dc_dmo_fields.md`
-    for the full join map.
-
-    Wave-1 ordering: ``sessions`` + ``participants`` run first with
-    deferred saves so ``_resolve_identity`` can compute the session's
-    target dir BEFORE any on-disk write. Without this ordering, the
-    first ``storage.save`` call would fail validation (``paths.session_dir``
-    requires the 3 identity segments). Once identity is stamped on
-    ``ctx``, remaining wave-1 queries save through the normal ``_fetch``
-    path.
-    """
-    sid = ctx["session_id"]
-    sid_q = f"'{sid}'"
-
-    # ---- wave 1a: identity resolution (deferred save) --------------------
-    _log("== wave 1a: identity resolution ==")
-    sessions = _fetch_no_save(ctx, 1, "sessions",
-                              f"ssot__Id__c = {sid_q}")
-    participants = _fetch_no_save(ctx, 1, "participants",
-                                  f"ssot__AiAgentSessionId__c = {sid_q}")
-    (
-        ctx["org_id_15"],
-        ctx["agent_api_name"],
-        ctx["agent_version"],
-    ) = _resolve_identity(sessions, participants, ctx["org_alias"])
-    _log(
-        f"  identity: org={ctx['org_id_15']}  "
-        f"agent={ctx['agent_api_name']}  version={ctx['agent_version']}"
-    )
-
-    # Flush deferred writes now that identity is known. Empty results
-    # stay unwritten (same contract as ``_fetch``).
-    if sessions:
-        save(
-            sessions, ctx["org_id_15"], ctx["agent_api_name"],
-            ctx["agent_version"], sid, "dc", "sessions",
-        )
-    if participants:
-        save(
-            participants, ctx["org_id_15"], ctx["agent_api_name"],
-            ctx["agent_version"], sid, "dc", "participants",
-        )
-
-    # ---- wave 1b: remaining session-scoped (5 queries) -------------------
-    _log("\n== wave 1b: session-scoped ==")
-    interactions = _fetch(ctx, 1, "interactions",
-                          f"ssot__AiAgentSessionId__c = {sid_q}",
-                          "ORDER BY ssot__StartTimestamp__c")
-    messages = _fetch(ctx, 1, "messages",
-                      f"ssot__AiAgentSessionId__c = {sid_q}",
-                      "ORDER BY ssot__MessageSentTimestamp__c")
-    moments = _fetch(ctx, 1, "moments",
-                     f"ssot__AiAgentSessionId__c = {sid_q}",
-                     "ORDER BY ssot__StartTimestamp__c")
-    _fetch(ctx, 1, "tag_associations",
-           f"ssot__AiAgentSessionId__c = {sid_q}")
-    # sessionId__c is stored as a literal quoted string ('"<uuid>"'); raw-UUID
-    # exact match returns 0 rows. LIKE handles both '"<uuid>"' and any future
-    # variant cleanly. See references/dc_dmo_fields.md.
-    gw_requests = _fetch(ctx, 1, "gateway_requests",
-                         f"sessionId__c LIKE '%{sid}%'",
-                         "ORDER BY timestamp__c")
-
-    # Harvest IDs from wave 1 for downstream waves
-    interaction_ids = [r.get("ssot__Id__c") for r in interactions]
-    # Agent name harvest: moments DMO is sparse — many short or
-    # abandoned-before-tagging sessions never write a moment row, leaving
-    # agent_api_names empty even though the agent identity was already
-    # resolved upstream. Fall through to participants (always populated
-    # for any session with ≥1 turn) and finally to ctx.agent_api_name
-    # (resolved during identity wave 1a from BotDefinition).
-    _harvested = {
-        r["ssot__AiAgentApiName__c"]
-        for r in moments
-        if r.get("ssot__AiAgentApiName__c") and r["ssot__AiAgentApiName__c"] not in _NOT_SET
-    }
-    _harvested |= {
-        r["ssot__AiAgentApiName__c"]
-        for r in participants
-        if r.get("ssot__AiAgentApiName__c") and r["ssot__AiAgentApiName__c"] not in _NOT_SET
-    }
-    if not _harvested and ctx.get("agent_api_name"):
-        _harvested = {ctx["agent_api_name"]}
-    agent_api_names = sorted(_harvested)
-    gw_req_ids = [r.get("gatewayRequestId__c") for r in gw_requests]
-    trace_ids = _extract_trace_ids(interactions)
-    _log(f"  harvested: {len(interaction_ids)} interactions, "
-         f"{len(moments)} moments, trace_ids={len(trace_ids)}, "
-         f"gw_req_ids={len(gw_req_ids)}, agents={agent_api_names}")
-
-    # ---- wave 2: interaction/moment-scoped (2 queries) --------------------
-    _log("\n== wave 2: interaction/moment-scoped ==")
-    interaction_in = _in_list(interaction_ids)
-    if interaction_in != "()":
-        steps = _fetch(ctx, 2, "steps",
-                       f"ssot__AiAgentInteractionId__c IN {interaction_in}",
-                       "ORDER BY ssot__StartTimestamp__c")
-        _fetch(ctx, 2, "moment_interactions",
-               f"ssot__AiAgentInteractionId__c IN {interaction_in}")
-    else:
-        steps = []
-        _fetch_empty(ctx, 2, "steps",
-                     "no interactions for session")
-        _fetch_empty(ctx, 2, "moment_interactions",
-                     "no interactions for session")
-
-    # Harvest generation IDs from steps for forward fetch of GenAIGeneration.
-    # (Step.ssot__GenAiGatewayResponseId__c / ssot__GenAiGatewayRequestId__c are
-    # NOT harvested — those would be backward chains. Gateway audit rows are
-    # fetched forward from the session via GatewayRequest.sessionId__c in wave 1.)
-    step_gen_ids = [s.get("ssot__GenerationId__c") for s in steps]
-    _log(f"  harvested: generation_ids={len([x for x in step_gen_ids if x and x not in _NOT_SET])}")
-
-    # ---- wave 3: trace/generation/gateway fanout (6 queries) --------------
-    _log("\n== wave 3: trace/generation/gateway fanout ==")
-
-    # telemetry_spans — on trace_ids from interactions
-    trace_in = _in_list(trace_ids)
-    if trace_in != "()":
-        _fetch(ctx, 3, "telemetry_spans",
-               f"ssot__TelemetryTrace__c IN {trace_in}",
-               "ORDER BY ssot__StartDateTime__c")
-    else:
-        _fetch_empty(ctx, 3, "telemetry_spans",
-                     "no trace_ids extractable from interactions "
-                     "(TelemetryTraceId__c empty and no internalTraceId in AttributeText__c)")
-
-    # generations — canonical path: steps.ssot__GenerationId__c
-    gen_in = _in_list(step_gen_ids)
-    if gen_in != "()":
-        generations = _fetch(ctx, 3, "generations",
-                             f"generationId__c IN {gen_in}",
-                             "ORDER BY timestamp__c",
-                             join_path="steps.ssot__GenerationId__c")
-        # app_generation — same join key as generations (sibling DMO)
-        _fetch(ctx, 3, "app_generation",
-               f"generationId__c IN {gen_in}",
-               "ORDER BY timestamp__c",
-               join_path="steps.ssot__GenerationId__c")
-    else:
-        generations = []
-        _fetch_empty(ctx, 3, "generations",
-                     "no step.ssot__GenerationId__c values on this session "
-                     "(all steps had NOT_SET or steps table was empty)")
-        _fetch_empty(ctx, 3, "app_generation",
-                     "no step.ssot__GenerationId__c values on this session "
-                     "(all steps had NOT_SET or steps table was empty)")
-
-    # --- Gateway audit chain (forward-only from session) ------------------
-    # All audit rows flow forward from Session via GatewayRequest.sessionId__c
-    # (harvested in wave 1). Every child table is keyed on the authoritative
-    # gw_req_ids from that wave-1 fetch:
-    #
-    #   GenAIGatewayResponse       generationRequestId__c IN {gw_req_ids}
-    #   GenAIGatewayRequestTag     parent__c              IN {gw_req_ids}
-    #   GenAIGtwyObjRecord         parent__c              IN {gw_req_ids}
-    #   GenAIGtwyRequestMetadata   parent__c              IN {gw_req_ids}
-    #   GenAIGtwyRequestLLM        parent__c              IN {gw_req_ids}
-    #
-    # No Step->Response->Request chain. Step's GenAiGatewayRequestId__c and
-    # GenAiGatewayResponseId__c FKs exist but we don't harvest them: they
-    # only cover LLM_STEP-owned calls and miss nested features like
-    # PromptTemplateGenerationsInvocable. The session-direct fetch in wave 1
-    # is the authoritative set.
-    gw_req_in = _in_list(gw_req_ids)
-    if gw_req_in != "()":
-        _fetch(ctx, 3, "gateway_responses",
-               f"generationRequestId__c IN {gw_req_in}",
-               "ORDER BY timestamp__c",
-               join_path="gateway_requests.gatewayRequestId__c")
-        _fetch(ctx, 3, "gateway_request_tags",
-               f"parent__c IN {gw_req_in}")
-        _fetch(ctx, 3, "gateway_records",
-               f"parent__c IN {gw_req_in}")
-        _fetch(ctx, 3, "gateway_request_metadata",
-               f"parent__c IN {gw_req_in}")
-        _fetch(ctx, 3, "gateway_request_llm",
-               f"parent__c IN {gw_req_in}")
-    else:
-        gw_empty_reason = (
-            "no gateway_requests matched GatewayRequest.sessionId__c LIKE "
-            "'%<sid>%' in wave 1 — Trust Layer gateway logging may be "
-            "disabled for this org, or the session produced no LLM calls"
-        )
-        for n in ("gateway_responses", "gateway_request_tags", "gateway_records",
-                  "gateway_request_metadata", "gateway_request_llm"):
-            _fetch_empty(ctx, 3, n, gw_empty_reason)
-
-    # feedback — keyed by generationId (no session col on GenAIFeedback)
-    gen_ids_for_feedback = [r.get("generationId__c") for r in generations]
-    feedback_in = _in_list(gen_ids_for_feedback)
-    if feedback_in != "()":
-        feedback = _fetch(ctx, 3, "feedback",
-                          f"generationId__c IN {feedback_in}")
-    else:
-        feedback = []
-        _fetch_empty(ctx, 3, "feedback",
-                     "no generation_ids available (generations wave was empty)")
-
-    # ---- wave 4: generation/feedback-dependent (3 queries) ----------------
-    _log("\n== wave 4: generation/feedback-dependent ==")
-    gen_only_in = _in_list(gen_ids_for_feedback)
-    if gen_only_in != "()":
-        quality = _fetch(ctx, 4, "content_quality",
-                         f"parent__c IN {gen_only_in}")
-    else:
-        quality = []
-        _fetch_empty(ctx, 4, "content_quality",
-                     "no generation_ids (parent__c IN cannot be empty)")
-
-    # content_category — parent is (generation_ids ∪ quality.id__c)
-    quality_ids = [r.get("id__c") or r.get("ssot__Id__c") for r in quality]
-    category_parent_ids = gen_ids_for_feedback + quality_ids
-    category_in = _in_list(category_parent_ids)
-    if category_in != "()":
-        _fetch(ctx, 4, "content_category",
-               f"parent__c IN {category_in}")
-    else:
-        _fetch_empty(ctx, 4, "content_category",
-                     "no generation_ids or quality_ids to parent to")
-
-    # feedback_details — parent is feedback row id.
-    # GenAIFeedback__dlm PK is `feedbackId__c` (no ssot__ prefix, verified via describe);
-    # the old harvest used ssot__Id__c which doesn't exist on this DMO.
-    feedback_ids = [r.get("feedbackId__c") for r in feedback]
-    feedback_ids_in = _in_list(feedback_ids)
-    if feedback_ids_in != "()":
-        _fetch(ctx, 4, "feedback_details",
-               f"parent__c IN {feedback_ids_in}")
-    else:
-        _fetch_empty(ctx, 4, "feedback_details",
-                     "no feedback rows for this session "
-                     "(no user thumbs-up/down on any generation)")
-
-    # ---- wave 5: tag catalog (agent-scoped) -------------------------------
-    _log("\n== wave 5: tag catalog ==")
-    # Live orgs use 'Available' (not Help-doc's 'Active'). If that returns
-    # zero rows, retry unfiltered — some orgs have a different enum value or
-    # the definitions predate the Status field. See references/dc_dmo_fields.md.
-    tag_defs = _fetch(ctx, 5, "tag_definitions",
-                      "ssot__Status__c = 'Available'")
-    if not tag_defs:
-        _log("  (tag_definitions Status='Available' empty — retrying unfiltered)")
-        # Pop the empty entry so _fetch can append a fresh one for the retry.
-        # The retry overwrites the same on-disk artifact (last run wins).
-        ctx["queries"].pop()
-        tag_defs = _fetch(ctx, 5, "tag_definitions",
-                          "ssot__Id__c IS NOT NULL")
-        # Tag the retry in the manifest for traceability.
-        ctx["queries"][-1]["notes"] = (
-            "retried unfiltered after Status='Available' returned 0 rows"
-        )
-        if not tag_defs:
-            ctx["queries"][-1]["_unavailable_reason"] = (
-                "tag_definitions truly empty on this org"
-            )
-
-    agent_in = _in_list(agent_api_names)
-    if agent_in != "()":
-        _fetch(ctx, 5, "tag_definition_associations",
-               f"ssot__AiAgentApiName__c IN {agent_in}")
-    else:
-        _fetch_empty(ctx, 5, "tag_definition_associations",
-                     "no agent api names observed in moments")
-
-    def_ids = [r.get("ssot__Id__c") for r in tag_defs]
-    def_in = _in_list(def_ids)
-    if def_in != "()":
-        _fetch(ctx, 5, "tags",
-               f"ssot__AiAgentTagDefinitionId__c IN {def_in}")
-    else:
-        _fetch_empty(ctx, 5, "tags",
-                     "no tag_definition ids (tag_definitions was empty)")
-
-    # Tally steps by type for the session_shape classifier.
-    steps_by_type = {
-        "LLM_STEP": 0, "ACTION_STEP": 0, "TOPIC_STEP": 0,
-        "TRUST_GUARDRAILS_STEP": 0, "SESSION_END": 0,
-    }
-    for s in steps:
-        t = s.get("ssot__AiAgentInteractionStepType__c")
-        if t in steps_by_type:
-            steps_by_type[t] += 1
-
-    # Stash harvested-id counts for the manifest
-    steps_with_gen = sum(1 for g in step_gen_ids if g and g not in _NOT_SET)
-    ctx["harvested_ids"] = {
-        "sessions": len(sessions),
-        "messages": len(messages),
-        "interactions": len(interaction_ids),
-        "moments": len(moments),
-        "steps_total": len(steps),
-        "steps_by_type": steps_by_type,
-        "steps_with_generation_id": steps_with_gen,
-        "trace_ids_from_interactions": len(trace_ids),
-        "gateway_request_ids": len(gw_req_ids),
-        "generation_ids": sum(
-            1 for g in gen_ids_for_feedback if g and g not in _NOT_SET
-        ),
-        "agents_observed": agent_api_names,
-    }
-
-    # Classify session shape. 5-value enum; rules evaluated top-to-bottom, first-match-wins.
-    # See references/dc_dmo_fields.md for rationale.
-    ctx["session_shape"] = _classify_session_shape(
-        sessions_count=len(sessions),
-        steps_total=len(steps),
-        llm_step_count=steps_by_type["LLM_STEP"],
-        steps_with_generation_id=steps_with_gen,
-        gw_req_count=len(gw_req_ids),
-    )
-
-
-def _classify_session_shape(*, sessions_count, steps_total, llm_step_count,
-                            steps_with_generation_id, gw_req_count):
-    """6-value session-shape diagnostic. First match wins.
-
-    Rules (top-to-bottom):
-    - session_not_found                       — sessions.json returned 0 rows
-    - interactions_not_materialized_yet       — gw_reqs > 0 AND steps == 0. Gateway DMOs
-                                                materialize within minutes; STDM Interaction
-                                                / Step / Message DMOs can take hours to days.
-                                                Detected BEFORE abandoned_before_llm because
-                                                gw_req_count > 0 is a stronger positive signal
-                                                than steps_total > 0 (and the two rules'
-                                                inputs are disjoint on this path — steps == 0
-                                                here, gw_reqs == 0 for abandoned).
-    - abandoned_before_llm                    — steps > 0, LLM_STEP == 0, gw_reqs == 0
-    - gateway_requests_dropped_by_stdm        — LLM_STEP > 0
-                                                AND gw_reqs == 0 AND steps_with_generation_id == 0.
-                                                STDM dropped not just gateway_requests but also
-                                                generations (the join chain Step→Generation
-                                                is broken). Frequently observed on Atlas-routed
-                                                sessions; visible in Splunk LLMGatewayUsageEventWriter
-                                                even when DC has zero rows.
-    - planner_ran_no_gateway_logs             — LLM_STEP > 0 AND steps_with_generation_id > 0
-                                                AND gw_reqs == 0 (the extra guard prevents a
-                                                broken generations-IN-clause from being
-                                                misclassified here). Generations wrote to DC,
-                                                gateway_requests did not — narrower defect than
-                                                gateway_requests_dropped_by_stdm.
-    - complete                                — everything else (the "normal" bucket,
-                                                including partial chain-orphan sessions)
-
-    See references/dc_dmo_fields.md for rationale.
-    """
-    if sessions_count == 0:
-        return "session_not_found"
-    if gw_req_count > 0 and steps_total == 0:
-        return "interactions_not_materialized_yet"
-    if steps_total > 0 and llm_step_count == 0 and gw_req_count == 0:
-        return "abandoned_before_llm"
-    # When LLM_STEPs ran but neither gateway_requests nor generations
-    # wrote, the STDM exporter dropped both. Distinct from
-    # planner_ran_no_gateway_logs (which still has generation rows).
-    if (llm_step_count > 0 and steps_with_generation_id == 0
-            and gw_req_count == 0):
-        return "gateway_requests_dropped_by_stdm"
-    if (llm_step_count > 0 and steps_with_generation_id > 0
-            and gw_req_count == 0):
-        return "planner_ran_no_gateway_logs"
-    return "complete"
-
-
-def _write_manifest(ctx: dict) -> None:
-    """Emit dc._session_manifest.json next to the 24 artifacts."""
-    finished = datetime.now(timezone.utc)
-    elapsed_ms = int((finished - ctx["started_at"]).total_seconds() * 1000)
-    manifest = {
-        "_doc": "Per-query summary of this DC fetch run.",
-        "session_id": ctx["session_id"],
-        "org_alias": ctx["org_alias"],
-        "instance_url": ctx["instance_url"],
-        # Identity resolved in wave 1a, before any on-disk write. Stamped
-        # here so downstream readers can recover (org, agent, version)
-        # without re-parsing the tree.
-        "org_id_15": ctx.get("org_id_15"),
-        "agent_api_name": ctx.get("agent_api_name"),
-        "agent_version": ctx.get("agent_version"),
-        "session_shape": ctx.get("session_shape", "unknown"),
-        "started_at_utc": ctx["started_at"].isoformat().replace("+00:00", "Z"),
-        "finished_at_utc": finished.isoformat().replace("+00:00", "Z"),
-        "elapsed_ms": elapsed_ms,
-        "queries": ctx["queries"],
-        "harvested_ids": ctx.get("harvested_ids", {}),
-    }
-    target = paths.session_dir(
-        ctx["org_id_15"],
-        ctx["agent_api_name"],
-        ctx["agent_version"],
-        ctx["session_id"],
-    ) / "dc._session_manifest.json"
-    target.parent.mkdir(parents=True, exist_ok=True)
-    target.write_text(json.dumps(manifest, indent=2, default=str) + "\n")
-    _log(f"\nmanifest: {target}  ({elapsed_ms}ms total)")
-
-
-if __name__ == "__main__":
-    sys.exit(main())