@salesforce/afv-skills 1.22.0 → 1.24.0

package/skills/investigating-agentforce-architecture/scripts/parse_wave.py

@@ -1,845 +0,0 @@
-#!/usr/bin/env python3
-"""Idempotent wave parser — builds `$WORK_DIR/declared_action_tree.json`.
-
-Replaces old agent Phase 4 (wave-2 init) + Phase 5/6 re-parse + MAX_WAVE cap.
-One script, one code path. The "init vs re-parse" distinction is keyed on the
-presence of `declared_action_tree.json` at call time.
-
-Flow:
-  1. Load bundle JSON, bot_definition JSON, existing tree (if any).
-  2. Walk every $WORK_DIR/sf_meta/*/unpackaged/ dir:
-     - flows/*.flow: parse actionCalls → APEX/PROMPT_TEMPLATE/STANDARD_ACTION/
-       UNKNOWN children; subflows → FLOW children. Record flow_children[flow_name].
-       Mark ("FLOW", flow_name) visited.
-     - classes/*.cls-meta.xml: mark ("APEX", name) visited.
-     - genAiPromptTemplates/*.genAiPromptTemplate: mark ("PROMPT_TEMPLATE", name).
-  3. Build tree if missing (Phase-4 init):
-     - agent metadata from bot_definition + bundle
-     - root BOT_DEFINITION node with children = topics[] only
-       (plannerActions[] retained in the bundle shape for back-compat but
-       always empty — a planner never has direct functions, 2026-05-05)
-     - each topic → TOPIC node with GEN_AI_FUNCTION children (from inline actions)
-     - each GEN_AI_FUNCTION → unwraps_to + leaf child (Flow/Apex/Prompt/Std/Unk)
-  4. Inflate every FLOW leaf recursively (depth ≤ 6) with flow_children data.
-  5. Recompute `_pending_fetches` (names not yet in visited set).
-  6. Walk tree for `node_count`, `depth`, `_kind_counts`.
-  7. Atomic write.
-
-With --finalize-cap: after loading tree, move all remaining _pending_fetches
-items to _unresolved[] with reason "max-wave-depth exceeded".
-
-Usage:
-    python3 parse_wave.py                  # init or re-parse
-    python3 parse_wave.py --finalize-cap   # drain _pending_fetches → _unresolved
-
-Inputs (env):
-    WORK_DIR, AGENT_API_NAME, AGENT_VERSION, BOT_ID, BOT_MASTER_LABEL,
-    VERSION_AUTO_PICKED
-
-Outputs:
-    $WORK_DIR/declared_action_tree.json (atomic write)
-    stderr: log lines (node counts, pending counts, etc.)
-    exit 0 on success, 1 on write failure
-"""
-import json
-import os
-import pathlib
-import sys
-import xml.etree.ElementTree as ET
-from collections import Counter
-
-
-NS = {"sf": "http://soap.sforce.com/2006/04/metadata"}
-
-
-def _t(el, p):
-    if el is None:
-        return None
-    x = el.find(p, NS)
-    return x.text if x is not None else None
-
-
-def classify_bundle_action(action: dict) -> dict:
-    """Bundle-action classifier — duplicated in plan_wave.py per 'no
-    intra-skill imports' convention. Matches old agent's Phase 3/4 logic.
-
-    Returns (unwraps_dict, leaf_dict) as in the old agent Phase 4's
-    action_node(). leaf_dict is the child appended under the GEN_AI_FUNCTION
-    node; unwraps_dict is the compact form stored on the function itself.
-    """
-    tgt = action.get("invocationTarget")
-    ttype = (action.get("invocationTargetType") or "").lower()
-    if not tgt:
-        return None, None
-    if ttype == "flow":
-        return ({"kind": "FLOW", "api_name": tgt},
-                {"kind": "FLOW", "api_name": tgt, "children": []})
-    if ttype == "apex":
-        return ({"kind": "APEX", "api_name": tgt},
-                {"kind": "APEX", "api_name": tgt})
-    if ttype == "generatepromptresponse" or ttype.startswith("prompt") or ttype.startswith("genai"):
-        return ({"kind": "PROMPT_TEMPLATE", "api_name": tgt},
-                {"kind": "PROMPT_TEMPLATE", "api_name": tgt})
-    # Canonical field name is `invocation_type` (schema 3.1). Prior
-    # versions wrote `raw_invocation_type` on bundle-sourced nodes and
-    # `raw_action_type` on flow-actionCall-sourced nodes — downstream
-    # readers (render_architecture._display_name, summarize_tree) fall
-    # back to both legacy keys for one release.
-    if ttype == "standardinvocableaction":
-        return ({"kind": "STANDARD_ACTION", "api_name": tgt, "invocation_type": ttype},
-                {"kind": "STANDARD_ACTION", "api_name": tgt, "invocation_type": ttype})
-    return ({"kind": "UNKNOWN", "api_name": tgt, "invocation_type": ttype},
-            {"kind": "UNKNOWN", "api_name": tgt, "invocation_type": ttype})
-
-
-def classify_action_call(at: str, an: str, element_name: str) -> dict:
-    """Flow actionCall classifier (old Phase 4 logic).
-
-    Canonical field name is `invocation_type` (schema 3.1). Legacy readers
-    still fall back to `raw_action_type` for one release.
-    """
-    at = at or ""
-    if at == "apex" and an:
-        return {"kind": "APEX", "element_name": element_name, "api_name": an}
-    if at == "generatePromptResponse" and an:
-        return {"kind": "PROMPT_TEMPLATE", "element_name": element_name, "api_name": an}
-    if at:
-        # Any other non-empty actionType → STANDARD_ACTION; preserve raw.
-        return {"kind": "STANDARD_ACTION", "element_name": element_name,
-                "api_name": an or at, "invocation_type": at}
-    return {"kind": "UNKNOWN", "element_name": element_name,
-            "api_name": an or "?", "invocation_type": at or ""}
-
-
-# ---------------------------------------------------------------------------
-# pure BFS step helper. Visited sets are tuple-keyed on
-# (kind, canonical_name). Pending is a dict-by-kind so cross-kind collisions
-# (Flow Foo vs Apex Foo) stay distinct.
-#
-# this is the single source of truth for wave-level BFS. Both
-# `harvest_waves` and `main()` route through here so the tuple-keyed
-# semantics are active on the production path — not just under unit tests.
-#
-# kind tokens match the runtime tree's `kind` field
-# (FLOW/APEX/PROMPT_TEMPLATE/STANDARD_ACTION). The persisted
-# `_pending_fetches` dict uses the SAME tokens so internal + on-disk
-# conventions don't diverge.
-#
-# promoted from `_BFS_KINDS` → `BFS_KINDS` so
-# cross-module callers (main.py's in-process orchestrator) import a stable
-# public symbol instead of reaching across a leading-underscore boundary.
-# Same pattern as rest_client.redact_text's promotion. The underscore
-# alias below is retained for backwards compatibility and will be removed
-# in the next minor version; new code MUST use `BFS_KINDS`.
-# unified node-truncation annotation. When a node is not fully
-# expanded (either because of a cycle back to an ancestor, or because the
-# MAX_BFS_DEPTH cap tripped), we annotate it with a `_truncated` sub-
-# object of shape `{"reason": <str>, "target": <str>}`. `reason` is one
-# of the values below; `target` is a `"KIND:name"` path pointing at the
-# first encounter (cycle) or the unreached leaf (depth-cap). Downstream
-# consumers check `_truncated["reason"]` once; no per-reason pattern
-# matching.
-#
-# Backcompat: `_cycle_back_to` is emitted alongside `_truncated` for any
-# consumer that hasn't migrated (render_architecture, summarize_tree,
-# third-party tooling). Will be removed in the next minor version.
-TRUNCATION_CYCLE = "cycle"
-TRUNCATION_MAX_DEPTH = "max-depth"
-TRUNCATION_REASONS = frozenset({TRUNCATION_CYCLE, TRUNCATION_MAX_DEPTH})
-
-
-BFS_KINDS = ("FLOW", "APEX", "PROMPT_TEMPLATE", "STANDARD_ACTION")
-
-# STANDARD_ACTION is a Salesforce-owned builtin (e.g.
-# `streamKnowledgeSearch`, `createRecord`, `sendEmail`). These are never
-# fetched — they're declared-only leaves, with the action name carrying
-# all the identity. Keeping STANDARD_ACTION in BFS_KINDS lets the tree's
-# _kind_counts tally include them and visited-bookkeeping dedup against
-# them, but they must never accumulate into `_pending_fetches`. A name
-# like `streamKnowledgeSearch` landing in _pending_fetches.STANDARD_ACTION
-# is pollution — the pipeline isn't "missing" anything; the action is
-# simply declared and never materialized.
-#
-# Callers: when collecting refs into `new_refs`, gate on FETCHABLE_KINDS
-# rather than BFS_KINDS to avoid polluting pending buckets with leaves.
-FETCHABLE_KINDS = ("FLOW", "APEX", "PROMPT_TEMPLATE")
-
-# deprecated alias. Retained so existing tests and any lingering
-# `from parse_wave import _BFS_KINDS` imports keep working. New code MUST
-# use `BFS_KINDS` (public). Planned removal in the next minor version.
-_BFS_KINDS = BFS_KINDS
-
-
-def bfs_step(
-    pending_by_kind: dict[str, set[str]],
-    visited_by_kind: dict[str, set[str]],
-    new_refs_by_kind: dict[str, set[str]],
-) -> tuple[dict[str, set[str]], list[tuple[str, str]]]:
-    """Advance one BFS wave. Returns (new_pending_by_kind, cycles).
-
-    `cycles` is a list of (kind, name) tuples for refs that were already
-    visited on this wave — callers use these to annotate `_cycle_back_to`.
-
-    Self-cycles (a ref pointing at something already visited) are filtered
-    out of pending. Cross-type tuples (Flow Foo + Apex Foo) are distinct —
-    both land in their respective pending buckets.
-
-    unknown kinds RAISE — this is an internal API; a typo in a caller
-    is a programming error, not a recoverable runtime condition. Silent drop
-    produced false confidence (the dropped ref never got fetched and no log
-    ever mentioned it). Callers must filter to `BFS_KINDS` upstream.
-    """
-    new_pending: dict[str, set[str]] = {k: set() for k in BFS_KINDS}
-    cycles: list[tuple[str, str]] = []
-    for kind, refs in new_refs_by_kind.items():
-        if kind not in BFS_KINDS:
-            raise ValueError(
-                f"unknown BFS kind {kind!r}; must be one of {sorted(BFS_KINDS)}"
-            )
-        visited = visited_by_kind.get(kind, set())
-        for name in refs:
-            if name in visited:
-                cycles.append((kind, name))
-                continue
-            # Not yet visited AND not already pending on a prior wave:
-            # OR-in unconditionally — `pending |= (new - visited)` semantics.
-            new_pending[kind].add(name)
-    # Merge with the caller's existing pending. Caller passes the authoritative
-    # pending buckets; we return the delta merged in so they can just replace.
-    merged: dict[str, set[str]] = {k: set(pending_by_kind.get(k, set())) for k in BFS_KINDS}
-    for kind, names in new_pending.items():
-        merged[kind] |= names
-    return merged, cycles
-
-
-def empty_kind_sets() -> dict[str, set[str]]:
-    """Build a fresh {kind: set()} dict covering every BFS_KINDS entry.
-
-    callers use this to seed per-kind visited / pending
-    buckets. Keeping it centralized means new kinds added to BFS_KINDS
-    automatically flow through harvest_waves, bfs_step, and main().
-
-    promoted from `_empty_kind_sets` → public so
-    cross-module callers (main.py) can import a stable name instead of
-    reaching into a private symbol. The underscore alias below is kept
-    for backwards compatibility; it will be removed in the next minor
-    version.
-    """
-    return {k: set() for k in BFS_KINDS}
-
-
-# deprecated alias. Retained for backwards compatibility with any
-# lingering `from parse_wave import _empty_kind_sets` imports; new code
-# MUST use `empty_kind_sets` (public). Planned removal in the next minor
-# version.
-_empty_kind_sets = empty_kind_sets
-
-
-def harvest_waves(
-    work_dir: pathlib.Path,
-) -> tuple[dict[str, list[dict]], dict[str, set[str]], dict[str, set[str]], list[tuple[str, str]]]:
-    """Walk sf_meta/*/unpackaged/ dirs.
-
-    Returns (flow_children, visited_by_kind, pending_by_kind, cycles).
-
-    every ref collected from Flow XML (actionCalls + subflows)
-    is routed through `bfs_step` per-flow. The tuple-keyed visited set is
-    the authoritative record; flat per-name sets have been removed.
-
-    the two dicts are keyed by `BFS_KINDS` tokens
-    (FLOW/APEX/PROMPT_TEMPLATE/STANDARD_ACTION) — matching the runtime
-    tree's `kind` field and the on-disk `_pending_fetches` layout.
-    """
-    flow_children: dict[str, list[dict]] = {}
-    visited_by_kind: dict[str, set[str]] = empty_kind_sets()
-    pending_by_kind: dict[str, set[str]] = empty_kind_sets()
-    cycles: list[tuple[str, str]] = []
-
-    sf_meta = work_dir / "sf_meta"
-    if not sf_meta.exists():
-        return flow_children, visited_by_kind, pending_by_kind, cycles
-
-    all_wave_dirs = sorted(
-        p / "unpackaged" for p in sf_meta.iterdir()
-        if p.is_dir() and (p / "unpackaged").exists()
-    )
-
-    # Pass 1: flows (+ route per-flow refs through bfs_step).
-    for wave_dir in all_wave_dirs:
-        flows_dir = wave_dir / "flows"
-        if not flows_dir.exists():
-            continue
-        for f in sorted(flows_dir.glob("*.flow")):
-            flow_name = f.stem
-            if flow_name in flow_children:
-                continue  # already harvested this wave dir (earlier iter)
-            visited_by_kind["FLOW"].add(flow_name)
-            try:
-                root = ET.parse(f).getroot()
-            except ET.ParseError:
-                flow_children[flow_name] = []
-                continue
-            children: list[dict] = []
-            # Collect per-flow refs into kind-bucketed sets for one bfs_step.
-            new_refs: dict[str, set[str]] = empty_kind_sets()
-            for ac in root.findall("sf:actionCalls", NS):
-                n = _t(ac, "sf:name")
-                at = _t(ac, "sf:actionType") or ""
-                an = _t(ac, "sf:actionName")
-                item = classify_action_call(at, an, n)
-                children.append(item)
-                k = item["kind"]
-                api = item["api_name"]
-                # Only route FETCHABLE kinds into `new_refs` — STANDARD_ACTION
-                # items stay as leaf children with no further fetching implied
-                # . UNKNOWN items are similarly skipped.
-                if k in FETCHABLE_KINDS and api:
-                    new_refs[k].add(api)
-            for sub in root.findall("sf:subflows", NS):
-                n = _t(sub, "sf:name")
-                fn = _t(sub, "sf:flowName")
-                if fn:
-                    children.append({"kind": "FLOW", "element_name": n, "api_name": fn})
-                    new_refs["FLOW"].add(fn)
-            flow_children[flow_name] = children
-            # bfs_step is the canonical merge point.
-            pending_by_kind, step_cycles = bfs_step(
-                pending_by_kind, visited_by_kind, new_refs
-            )
-            cycles.extend(step_cycles)
-
-    # Pass 2: APEX classes (mark visited).
-    for wave_dir in all_wave_dirs:
-        apex_dir = wave_dir / "classes"
-        if apex_dir.exists():
-            for f in sorted(apex_dir.glob("*.cls-meta.xml")):
-                visited_by_kind["APEX"].add(f.name.replace(".cls-meta.xml", ""))
-
-    # Pass 3: Prompt templates (mark visited).
-    for wave_dir in all_wave_dirs:
-        prompt_dir = wave_dir / "genAiPromptTemplates"
-        if prompt_dir.exists():
-            for f in sorted(prompt_dir.glob("*.genAiPromptTemplate")):
-                visited_by_kind["PROMPT_TEMPLATE"].add(f.stem)
-
-    # Passes 2/3 may have added visited entries AFTER pass-1 pending routing;
-    # prune anything that's now visited. This preserves the invariant that
-    # `pending ∩ visited = ∅` without needing a second bfs_step.
-    for kind in BFS_KINDS:
-        pending_by_kind[kind] -= visited_by_kind[kind]
-
-    return flow_children, visited_by_kind, pending_by_kind, cycles
-
-
-def init_tree(work_dir: pathlib.Path, bundle: dict) -> dict:
-    bd_rec = {}
-    bd_file = work_dir / "_bot_definition.json"
-    if bd_file.exists():
-        try:
-            recs = (json.loads(bd_file.read_text()).get("result") or {}).get("records") or []
-            if recs:
-                bd_rec = recs[0]
-        except (OSError, json.JSONDecodeError):
-            pass
-
-    tree = {
-        # 3.0 bumps the _pending_fetches key convention from
-        # Metadata-API tokens (Flow/ApexClass/GenAiPromptTemplate) to the
-        # runtime-tree `kind` tokens (FLOW/APEX/PROMPT_TEMPLATE/
-        # STANDARD_ACTION). `cache_check.py`'s schema-version gate busts any
-        # pre-3.0 cache on first run.
-        #
-        # 3.1 (2026-05-05) canonicalizes `invocation_type` on STANDARD_ACTION
-        # nodes (formerly split across `raw_invocation_type` on bundle-
-        # sourced nodes and `raw_action_type` on flow-actionCall-sourced
-        # nodes). Readers fall back to the two legacy keys for one release.
-        "_schema_version": "3.1",
-        "agent": {
-            "api_name": os.environ["AGENT_API_NAME"],
-            "version": os.environ["AGENT_VERSION"],
-            "bot_id": os.environ.get("BOT_ID", ""),
-            "master_label": bd_rec.get("MasterLabel") or os.environ.get("BOT_MASTER_LABEL", ""),
-            "description": bd_rec.get("Description"),
-            "agent_type": bd_rec.get("AgentType"),
-            "type": bd_rec.get("Type"),
-            "agent_template": bd_rec.get("AgentTemplate"),
-            "bot_source": bd_rec.get("BotSource"),
-            "generation": bundle.get("generation", "unknown"),
-            "planner_name": bundle.get("plannerName"),
-            "planner_type": bundle.get("plannerType"),
-            "_version_auto_picked": (os.environ.get("VERSION_AUTO_PICKED", "") == "true"),
-        },
-        "root": {
-            "kind": "BOT_DEFINITION",
-            "api_name": os.environ["AGENT_API_NAME"],
-            "children": [],
-        },
-        "node_count": 0,
-        "depth": 0,
-        # `_partial` + `_partial_reason` propagate from parse_wave's
-        # depth-cap detection through to emit_result's PARTIAL_OK status.
-        # `_partial_reason` values: "max-depth-cap" | "pending-refs" | null.
-        "_partial": True,
-        "_partial_reason": None,
-        "_pending_fetches": {k: [] for k in BFS_KINDS},
-        "_unresolved": [],
-        "_visited": [],
-    }
-    return tree
-
-
-def build_root_children(
-    bundle: dict,
-    visited_by_kind: dict[str, set[str]],
-    aux_visited: set[tuple[str, str]],
-) -> tuple[list[dict], dict[str, set[str]]]:
-    """Build the root's topic / plannerAction children.
-
-    bundle-scoped FLOW/APEX/PROMPT_TEMPLATE refs are collected
-    into a kind-keyed `new_refs` dict and returned to the caller, which runs
-    them through `bfs_step` for uniform pending-merge + cycle tracking.
-    This used to directly mutate three flat sets — split out so the tuple-
-    keyed semantics apply to bundle-derived refs too, not just wave-derived
-    ones.
-
-    `aux_visited` tracks non-BFS node identity (GEN_AI_FUNCTION / TOPIC) so
-    the persisted `_visited` list still represents every node the walker
-    has laid hands on. It is NOT consulted by bfs_step.
-    """
-    children: list[dict] = []
-    new_refs: dict[str, set[str]] = empty_kind_sets()
-
-    def action_node(action: dict) -> dict:
-        unwraps, leaf = classify_bundle_action(action)
-        aux_visited.add(("GEN_AI_FUNCTION", action["name"]))
-        node = {
-            "kind": "GEN_AI_FUNCTION",
-            "api_name": action["name"],
-            "unwraps_to": unwraps,
-            "children": [leaf] if leaf else [],
-        }
-        if unwraps:
-            tgt = unwraps.get("api_name")
-            kind = unwraps.get("kind")
-            # STANDARD_ACTION is declared-only, never
-            # fetched; routing it into `new_refs` would pollute
-            # `_pending_fetches.STANDARD_ACTION`. Gate on FETCHABLE_KINDS.
-            if kind in FETCHABLE_KINDS and tgt and tgt not in visited_by_kind[kind]:
-                new_refs[kind].add(tgt)
-        return node
-
-    for topic in bundle.get("topics", []) or []:
-        aux_visited.add(("TOPIC", topic["name"]))
-        children.append({
-            "kind": "TOPIC",
-            "api_name": topic["name"],
-            "children": [action_node(a) for a in topic.get("actions", []) or []],
-        })
-
-    # bundle["plannerActions"] is always [] now (a planner never has
-    # direct functions — 2026-05-05). The key stays in the bundle dict
-    # for back-compat with consumers that still call `.get("plannerActions")`.
-
-    return children, new_refs
-
-
-# ---------------------------------------------------------------------------
-# cycle-safe inflate with (kind, canonical_name) tuple-keyed tracking.
-#
-# Visited tracking uses tuple keys so a Flow `Foo` and an Apex `Foo` are
-# distinct nodes — a flat name-only set would silently drop the second one.
-# Flow→subflow cycles (direct or cross-type A→B→A) are annotated with
-# `_cycle_back_to` on the repeat node and recursion terminates immediately.
-#
-# , revised 2026-05-03: `MAX_BFS_DEPTH` is a DEFENSIVE termination
-# guard, not a functional constraint on chain depth. Must stay in sync
-# with `scripts/config.py::MAX_BFS_DEPTH` — duplicated (rather than
-# imported) because this module runs as a standalone subprocess under
-# `python3 parse_wave.py` (see `main()`) and the module has a long-standing
-# "no intra-skill imports" convention (search `no intra-skill imports'
-# convention`).
-#
-# Real cycle detection is per-branch via `visited_in_path`: a flow that
-# appears on sibling branches is NOT a cycle (e.g. `handleFlowFault`,
-# invoked from many parents), but the same flow recurring along its own
-# ancestor chain IS. Textbook DFS cycle detection.
-#
-# Before the revision this was `5` and the cap itself tripped on shared
-# utility flows (`handleFlowFault`, logging subflows) — those landed in
-# `_pending_fetches["FLOW"]` and the user saw `PARTIAL_REASON=max-depth-cap`
-# on trees that were in fact fully knowable. Bumping to 20 keeps a safety
-# net for pathological graphs while letting per-branch cycle detection do
-# the real work. On every real bot tree observed to date, the per-branch
-# check terminates well below depth 20.
-#
-# When this cap *does* trip (truly exceptional), the unreached FLOW lands
-# in `pending_out["FLOW"]` and the leaf is annotated `_truncated =
-# {reason: "max-depth", target: "FLOW:<name>"}`, exactly as before.
-MAX_BFS_DEPTH = 20
-
-# Retained alias so the `MAX_INFLATE_DEPTH` symbol (referenced in older
-# agent notes / docs) still resolves. Tracks `MAX_BFS_DEPTH` exactly; the
-# 2026-05-03 revision reinterpreted this as a defensive guard rather than
-# a functional cap, but the alias semantics are unchanged.
-MAX_INFLATE_DEPTH = MAX_BFS_DEPTH
-_FLOW_CYCLE_KINDS = frozenset({"FLOW"})  # the only kind that recurses here
-
-
-def _cycle_key(node: dict) -> tuple[str, str]:
-    """Tuple key for visited / cycle detection. Flows use canonical api_name.
-
-    keying on `(kind, api_name)` — NOT just name — so cross-kind
-    collisions (Flow Foo + Apex Foo) stay distinct.
-    """
-    return (node.get("kind") or "", node.get("api_name") or "")
-
-
-def inflate_flow_leaf(
-    leaf: dict,
-    flow_children: dict,
-    depth: int = 0,
-    visited_in_path: frozenset[tuple[str, str]] | None = None,
-    pending_out: dict[str, set[str]] | None = None,
-) -> None:
-    """Recursively expand a FLOW leaf's subflow tree.
-
-    `visited_in_path` is threaded through the recursion as an
-    IMMUTABLE frozenset — siblings at the same depth must NOT observe
-    each other's descent. Mutating a shared set would cause the second
-    sibling to be pruned as a false cycle.
-
-    `pending_out` is an OPTIONAL mutable accumulator keyed by
-    `BFS_KINDS` tokens. When the depth cap trips (`depth >= MAX_BFS_DEPTH`)
-    and the current leaf still has subflow children we'd normally expand,
-    those unreached targets are added to `pending_out[kind]` so a caller
-    can surface them as `_pending_fetches` on the tree with
-    `_partial=True` + `_partial_reason="max-depth-cap"`. When `pending_out`
-    is None (legacy callers), the cap behaves as before — silently skip.
-    """
-    # depth-cap check. We use `>=` (not `>`) so the cap matches
-    # `MAX_BFS_DEPTH` exactly — at depth 5 we do NOT expand the current
-    # leaf, and the leaf's own (kind, api_name) is recorded in
-    # `pending_out` as "unreached". Rationale: this node was supposed
-    # to be fully explored but we hit the cap on the way in. Naming
-    # the leaf itself (not its kids) is what downstream callers need
-    # to surface as `_pending_fetches["FLOW"] = [<unreached>]`.
-    if depth >= MAX_BFS_DEPTH:
-        if leaf.get("kind") == "FLOW":
-            flow_name = leaf.get("api_name")
-            if flow_name:
-                if pending_out is not None:
-                    pending_out.setdefault("FLOW", set()).add(flow_name)
-                # annotate the truncated leaf with the unified
-                # `_truncated` sub-object so rendered tree views can
-                # mark depth-capped nodes alongside cycle nodes using
-                # one predicate. The target points at the leaf itself
-                # (it was supposed to be fully explored but the cap
-                # tripped on the way in).
-                leaf["_truncated"] = {
-                    "reason": TRUNCATION_MAX_DEPTH,
-                    "target": f"FLOW:{flow_name}",
-                }
-        return
-    if leaf.get("kind") != "FLOW":
-        return
-    flow_name = leaf.get("api_name")
-    if not flow_name:
-        return
-    kids = flow_children.get(flow_name)
-    if not kids:
-        return  # no data this wave; preserve any existing children
-
-    # Extend the path-visited set with this node. Frozenset keeps sibling
-    # branches independent — mutation would cross-contaminate.
-    leaf_key = _cycle_key(leaf)
-    path_set = (visited_in_path or frozenset()) | {leaf_key}
-
-    new_children: list[dict] = []
-    for k in kids:
-        item = {"kind": k["kind"], "element_name": k.get("element_name"), "api_name": k["api_name"]}
-        # Carry the STANDARD_ACTION / UNKNOWN invocation-type qualifier
-        # through to the expanded child. Canonical key is `invocation_type`
-        # (schema 3.1); legacy `raw_action_type` kept for one release so
-        # caches built by an older parse_wave still render cleanly.
-        if "invocation_type" in k:
-            item["invocation_type"] = k["invocation_type"]
-        if "raw_action_type" in k:
-            item["raw_action_type"] = k["raw_action_type"]
-        if k["kind"] == "FLOW":
-            item["children"] = []
-            child_key = _cycle_key(item)
-            if child_key in path_set:
-                # cycle detected — annotate and do NOT recurse.
-                # Path format: "<KIND>:<name>" of the first encounter.
-                # unified `_truncated` sub-object + legacy
-                # `_cycle_back_to` for backcompat.
-                target_path = f"{child_key[0]}:{child_key[1]}"
-                item["_truncated"] = {
-                    "reason": TRUNCATION_CYCLE,
-                    "target": target_path,
-                }
-                item["_cycle_back_to"] = target_path  # deprecated alias
-                new_children.append(item)
-                continue
-            new_children.append(item)
-            inflate_flow_leaf(item, flow_children, depth + 1, path_set, pending_out)
-        else:
-            new_children.append(item)
-    leaf["children"] = new_children
-
-
-def walk_and_inflate(
-    node: dict,
-    flow_children: dict,
-    depth: int = 0,
-    pending_out: dict[str, set[str]] | None = None,
-) -> None:
-    """Walk the tree and inflate every FLOW leaf we encounter.
-
-    Each inflate call starts with an empty path-visited set — tree-walk
-    descent is not itself a Flow recursion, so ancestor GEN_AI_FUNCTION
-    or TOPIC nodes don't count toward cycle detection.
-
-    `pending_out` (optional) is threaded into every `inflate_flow_leaf`
-    call so depth-cap truncations accumulate into a single shared dict,
-    which `main()` merges into `tree["_pending_fetches"]` + flips
-    `tree["_partial"]` with reason `max-depth-cap`.
-    """
-    if node.get("kind") == "GEN_AI_FUNCTION":
-        for child in node.get("children", []) or []:
-            if child.get("kind") == "FLOW":
-                inflate_flow_leaf(child, flow_children, depth, pending_out=pending_out)
-    elif node.get("kind") == "FLOW":
-        inflate_flow_leaf(node, flow_children, depth, pending_out=pending_out)
-    for c in node.get("children", []) or []:
-        walk_and_inflate(c, flow_children, depth + 1, pending_out)
-
-
-def compute_stats(root: dict) -> tuple[int, int, dict]:
-    counts: Counter = Counter()
-
-    def walk(node: dict, d: int = 0) -> int:
-        k = node.get("kind")
-        if k:
-            counts[k] += 1
-        max_d = d
-        for c in node.get("children", []) or []:
-            max_d = max(max_d, walk(c, d + 1))
-        return max_d
-
-    depth = walk(root)
-    return sum(counts.values()), depth, dict(counts)
-
-
-def atomic_write_json(path: pathlib.Path, obj: dict) -> None:
-    tmp = path.with_suffix(path.suffix + ".tmp")
-    tmp.write_text(json.dumps(obj, indent=2))
-    os.replace(tmp, path)
-
-
-def finalize_cap(tree: dict) -> dict:
-    """Move remaining _pending_fetches items to _unresolved[].
-
-    pending and unresolved both use the same kind tokens now
-    (FLOW/APEX/PROMPT_TEMPLATE/STANDARD_ACTION) — matching the runtime
-    tree's `kind` field.
-
-    depth-cap truncation writes `_partial=True` +
-    `_partial_reason="max-depth-cap"` earlier in the pipeline. Finalize
-    preserves those signals when it drains pending → unresolved so the
-    downstream emit_result.py can still surface PARTIAL_OK with the
-    correct reason. If BOTH the depth cap AND finalize-cap fire on the
-    same run, depth-cap wins priority (set first, not overwritten).
-    """
-    pending = tree.get("_pending_fetches") or {}
-    unresolved = tree.setdefault("_unresolved", [])
-    drained_any = False
-    for kind, items in pending.items():
-        for n in items:
-            drained_any = True
-            unresolved.append({
-                "kind": kind,
-                "api_name": n,
-                "reason": "max-wave-depth exceeded",
-            })
-    tree["_pending_fetches"] = {k: [] for k in BFS_KINDS}
-
-    # if pending was drained but no `_partial_reason` is set yet,
-    # mark it as wave-depth exhaustion. DO NOT overwrite an existing
-    # `max-depth-cap` reason — the depth-cap trigger is strictly earlier
-    # and more specific.
-    if drained_any:
-        tree["_partial"] = True
-        if not tree.get("_partial_reason"):
-            tree["_partial_reason"] = "max-wave-depth"
-    return tree
-
-
-def main() -> int:
-    finalize_cap_mode = "--finalize-cap" in sys.argv
-
-    try:
-        work_dir = pathlib.Path(os.environ["WORK_DIR"])
-    except KeyError as e:
-        sys.stderr.write(f"parse_wave.py: missing env {e}\n")
-        return 1
-
-    tree_path = work_dir / "declared_action_tree.json"
-
-    # --finalize-cap: trivial; just drain pending → unresolved on existing tree
-    if finalize_cap_mode:
-        if not tree_path.is_file():
-            sys.stderr.write("parse_wave.py: --finalize-cap with no tree file; noop\n")
-            return 0
-        try:
-            tree = json.loads(tree_path.read_text())
-        except (OSError, json.JSONDecodeError) as e:
-            sys.stderr.write(f"parse_wave.py: cannot read tree: {e}\n")
-            return 1
-        tree = finalize_cap(tree)
-        try:
-            atomic_write_json(tree_path, tree)
-        except OSError as e:
-            sys.stderr.write(f"parse_wave.py: write failed: {e}\n")
-            return 1
-        sys.stderr.write(
-            f"[parse_wave] finalize-cap: {len(tree.get('_unresolved', []))} nodes unresolved\n"
-        )
-        return 0
-
-    # Standard init-or-reparse path
-    bundle_path = work_dir / "_bundle_parsed.json"
-    if not bundle_path.is_file():
-        sys.stderr.write(f"parse_wave.py: missing {bundle_path}\n")
-        return 1
-    try:
-        bundle = json.loads(bundle_path.read_text())
-    except (OSError, json.JSONDecodeError) as e:
-        sys.stderr.write(f"parse_wave.py: bundle parse error: {e}\n")
-        return 1
-
-    # Harvest wave dirs. Returns kind-keyed visited + pending dicts plus
-    # the list of (kind, name) cycles detected during per-flow BFS merges.
-    flow_children, wave_visited_by_kind, pending_by_kind, _wave_cycles = harvest_waves(work_dir)
-
-    # Load-or-init tree
-    if tree_path.is_file():
-        try:
-            tree = json.loads(tree_path.read_text())
-        except (OSError, json.JSONDecodeError) as e:
-            sys.stderr.write(f"parse_wave.py: cannot re-parse; reinitializing ({e})\n")
-            tree = init_tree(work_dir, bundle)
-    else:
-        tree = init_tree(work_dir, bundle)
-
-    # Rehydrate tuple-keyed visited from the persisted _visited list and
-    # union with wave-derived visited. Non-BFS kinds (TOPIC/GEN_AI_FUNCTION)
-    # live in `aux_visited` — they're persisted in _visited but do NOT
-    # participate in BFS routing.
-    visited_by_kind: dict[str, set[str]] = empty_kind_sets()
-    for kind, names in wave_visited_by_kind.items():
-        visited_by_kind[kind] |= names
-    aux_visited: set[tuple[str, str]] = set()
-    for pair in (tree.get("_visited") or []):
-        if not pair or len(pair) != 2:
-            continue
-        k, n = pair[0], pair[1]
-        if k in BFS_KINDS:
-            visited_by_kind[k].add(n)
-        else:
-            aux_visited.add((k, n))
-
-    # If the tree was just initialized, populate root children (only once).
-    # bundle-derived refs now flow through bfs_step via
-    # build_root_children's new_refs return value — same code path as
-    # wave-derived refs.
-    is_fresh = not (tree.get("root", {}).get("children"))
-    if is_fresh:
-        children, bundle_new_refs = build_root_children(
-            bundle, visited_by_kind, aux_visited
-        )
-        tree["root"]["children"] = children
-        pending_by_kind, _bundle_cycles = bfs_step(
-            pending_by_kind, visited_by_kind, bundle_new_refs
-        )
-
-    # Inflate Flow leaves wherever possible.
-    # `depth_cap_pending` captures subflow refs we skipped because
-    # the depth cap tripped — these get merged into `_pending_fetches`
-    # below so downstream emit_result.py can surface `PARTIAL_OK`.
-    depth_cap_pending: dict[str, set[str]] = empty_kind_sets()
-    walk_and_inflate(tree["root"], flow_children, pending_out=depth_cap_pending)
-
-    # Merge depth-cap-suppressed refs back into pending_by_kind so they
-    # land in `_pending_fetches`. Preserve any existing (already-visited)
-    # exclusion semantics — refs already fetched this run MUST NOT be
-    # re-reported as pending.
-    for kind in BFS_KINDS:
-        pending_by_kind[kind] |= depth_cap_pending.get(kind, set())
-
-    depth_cap_tripped = any(depth_cap_pending[k] for k in BFS_KINDS)
-
-    # Recompute pending (exclude anything now visited). the
-    # persisted dict uses the same `BFS_KINDS` tokens as the runtime tree
-    # and the in-memory buckets — no more Metadata-API-style aliasing.
-    tree["_pending_fetches"] = {
-        k: sorted(pending_by_kind.get(k, set()) - visited_by_kind.get(k, set()))
-        for k in BFS_KINDS
-    }
-
-    # surface a `_partial` signal when:
-    # (a) depth-cap-pending refs exist (we suppressed deep subflows), OR
-    # (b) any `_pending_fetches` bucket is non-empty at write time.
-    # `_partial_reason` identifies which of the two tripped — `max-depth-cap`
-    # takes priority when depth_cap_pending is non-empty, since the cap is
-    # the reason pending refs weren't drained to `_unresolved` yet.
-    any_pending = any(tree["_pending_fetches"][k] for k in BFS_KINDS)
-    if depth_cap_tripped:
-        tree["_partial"] = True
-        tree["_partial_reason"] = "max-depth-cap"
-    elif any_pending:
-        # Still incomplete but NOT because of the depth cap. Leave any
-        # existing reason intact if prior run set it; default to a neutral
-        # marker so emit_result.py can still flip to PARTIAL_OK.
-        tree["_partial"] = True
-        if not tree.get("_partial_reason"):
-            tree["_partial_reason"] = "pending-refs"
-    else:
-        tree["_partial"] = False
-        tree["_partial_reason"] = None
-
-    # Recompute node_count + depth + kind_counts
-    node_count, depth, kind_counts = compute_stats(tree["root"])
-    tree["node_count"] = node_count
-    tree["depth"] = depth
-    tree["_kind_counts"] = kind_counts
-
-    # Persist visited as sorted list of [kind, name] pairs. Includes aux
-    # kinds (TOPIC/GEN_AI_FUNCTION) so the replay surface is complete.
-    all_visited: set[tuple[str, str]] = set(aux_visited)
-    for kind, names in visited_by_kind.items():
-        for n in names:
-            all_visited.add((kind, n))
-    tree["_visited"] = [list(v) for v in sorted(all_visited)]
-
-    try:
-        atomic_write_json(tree_path, tree)
-    except OSError as e:
-        sys.stderr.write(f"parse_wave.py: write failed: {e}\n")
-        return 1
-
-    # log line mirrors the persisted dict's kind tokens.
-    pending_total = sum(len(v) for v in tree["_pending_fetches"].values())
-    sys.stderr.write(
-        f"[parse_wave] parsed: {node_count} nodes, depth {depth}, counts={kind_counts}, "
-        f"pending={pending_total} "
-        f"(flow={len(tree['_pending_fetches']['FLOW'])} "
-        f"apex={len(tree['_pending_fetches']['APEX'])} "
-        f"prompt_template={len(tree['_pending_fetches']['PROMPT_TEMPLATE'])} "
-        f"standard_action={len(tree['_pending_fetches']['STANDARD_ACTION'])})\n"
-    )
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())