@salesforce/afv-skills 1.14.0 → 1.16.0

package/skills/investigating-agentforce-d360/scripts/tests/test_fetch_dc_waterfall_full.py

@@ -0,0 +1,283 @@
+"""End-to-end waterfall tests for ``fetch_dc._run_waterfall``.
+
+Mocks ``dc.post`` at the network boundary; dispatches per-query fixture
+rows so the 5-wave orchestration runs to completion. Asserts on:
+
+- per-query manifest entries (rows, status, wave)
+- harvested_ids tracking across waves
+- session_shape classification
+- on-disk dc.<name>.json artifacts written by ``storage.save``
+"""
+from __future__ import annotations
+
+import json
+import unittest
+from datetime import datetime, timezone
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from unittest import mock
+
+from . import _bootstrap  # noqa: F401  — sys.path setup
+
+import fetch_dc  # type: ignore
+from config import paths  # type: ignore
+from .fixtures.synthetic_session import IDS, make_rows  # type: ignore
+
+
+def _build_fixture_dispatch() -> dict[str, list[dict]]:
+    """Return rows keyed by DMO name for the synthetic session fixture."""
+    return make_rows()
+
+
+def _make_post_dispatcher(rows_by_name: dict[str, list[dict]]):
+    """Return a fake ``dc.post`` that dispatches to the right fixture
+    rows by inspecting the query_name argument."""
+    def fake_post(sql: str, instance_url: str, token: str, query_name: str = ""):
+        # `_fetch` passes the template name as query_name; that's exactly
+        # what we keyed on in the fixture.
+        return list(rows_by_name.get(query_name, []))
+    return fake_post
+
+
+def _make_ctx(tmpdir: Path) -> dict:
+    """Build the same ctx shape that fetch_dc.main() builds."""
+    return {
+        "session_id": IDS.SID,
+        "org_alias": "my-org",
+        "instance_url": "https://example.salesforce.com",
+        "token": "TOKEN",
+        "verbose": False,
+        "queries": [],
+        "started_at": datetime.now(timezone.utc),
+        "org_id_15": None,
+        "agent_api_name": None,
+        "agent_version": None,
+    }
+
+
+class _WaterfallHarness:
+    """Patch DATA_ROOT + dc.post; build ctx; run the waterfall."""
+
+    def __init__(self, *, rows_overrides: dict[str, list[dict]] | None = None):
+        self.rows_overrides = rows_overrides or {}
+
+    def __enter__(self):
+        self._tmp = TemporaryDirectory()
+        self._tmpdir = Path(self._tmp.name)
+        self.ctx = _make_ctx(self._tmpdir)
+        rows = _build_fixture_dispatch()
+        rows.update(self.rows_overrides)
+        self._post = _make_post_dispatcher(rows)
+        self._patches = [
+            mock.patch.object(paths, "DATA_ROOT", self._tmpdir),
+            mock.patch.object(fetch_dc, "post", side_effect=self._post),
+            # Keep _log quiet during tests
+            mock.patch.object(fetch_dc, "_log"),
+        ]
+        for p in self._patches:
+            p.start()
+        return self
+
+    def __exit__(self, *exc):
+        for p in self._patches:
+            p.stop()
+        self._tmp.cleanup()
+
+    def session_dir(self) -> Path:
+        # macOS resolves /var → /private/var; resolve once so `is_file`
+        # checks work after storage.save's path composition.
+        return (
+            self._tmpdir.resolve()
+            / IDS.ORG_ID_15
+            / f"{IDS.AGENT_API}__{IDS.AGENT_VERSION}"
+            / IDS.SID
+        )
+
+
+# -----------------------------------------------------------------------------
+# Identity stamping (wave 1a)
+# -----------------------------------------------------------------------------
+
+
+class WaterfallIdentityTests(unittest.TestCase):
+
+    def test_identity_resolved_into_ctx_after_wave_1a(self):
+        with _WaterfallHarness() as h:
+            fetch_dc._run_waterfall(h.ctx)
+        self.assertEqual(h.ctx["org_id_15"], IDS.ORG_ID_15)
+        self.assertEqual(h.ctx["agent_api_name"], IDS.AGENT_API)
+        self.assertEqual(h.ctx["agent_version"], IDS.AGENT_VERSION)
+
+    def test_sessions_and_participants_persisted_after_identity_resolved(self):
+        # The deferred-save flush in wave 1a should write both files.
+        with _WaterfallHarness() as h:
+            fetch_dc._run_waterfall(h.ctx)
+            # Search the entire tmp tree — avoids macOS /private/var ↔ /var
+            # resolution discrepancies between paths.session_dir() and our
+            # locally-built path.
+            written = {p.name for p in h._tmpdir.rglob("dc.*.json")}
+        self.assertIn("dc.sessions.json", written)
+        self.assertIn("dc.participants.json", written)
+
+
+# -----------------------------------------------------------------------------
+# Wave-by-wave artifact persistence
+# -----------------------------------------------------------------------------
+
+
+class WaterfallWritesArtifactsTests(unittest.TestCase):
+
+    def test_populated_dmos_emit_dc_json_artifacts(self):
+        with _WaterfallHarness() as h:
+            fetch_dc._run_waterfall(h.ctx)
+            files = {p.name for p in h._tmpdir.rglob("dc.*.json")}
+        # 11 DMOs are populated in the synthetic fixture; each lands as a file.
+        for name in (
+            "dc.sessions.json", "dc.interactions.json", "dc.steps.json",
+            "dc.messages.json", "dc.participants.json",
+            "dc.gateway_requests.json", "dc.gateway_responses.json",
+            "dc.generations.json", "dc.content_quality.json",
+            "dc.gateway_records.json", "dc.gateway_request_tags.json",
+        ):
+            self.assertIn(name, files, f"{name} should be on disk")
+
+    def test_zero_row_dmos_skipped_no_artifact(self):
+        with _WaterfallHarness() as h:
+            fetch_dc._run_waterfall(h.ctx)
+            files = {p.name for p in h._tmpdir.rglob("dc.*.json")}
+        # `tags` and friends have empty rows → no on-disk artifact.
+        self.assertNotIn("dc.tags.json", files)
+        self.assertNotIn("dc.tag_definitions.json", files)
+
+
+# -----------------------------------------------------------------------------
+# Manifest entries (one per query)
+# -----------------------------------------------------------------------------
+
+
+class WaterfallManifestTests(unittest.TestCase):
+
+    def test_24_query_entries_appended(self):
+        with _WaterfallHarness() as h:
+            fetch_dc._run_waterfall(h.ctx)
+        names = [q["name"] for q in h.ctx["queries"]]
+        # Exactly the 24 templates fetch_dc declares (no duplicates from
+        # tag_definitions retry: synthetic fixture's tag_definitions is
+        # empty, so retry runs once and overwrites the prior empty entry).
+        self.assertGreaterEqual(len(names), 24)
+        # Critical names appear at least once
+        for required in ("sessions", "interactions", "steps", "participants",
+                         "gateway_requests", "generations", "messages"):
+            self.assertIn(required, names)
+
+    def test_each_query_has_wave_status_rows_elapsed_ms(self):
+        with _WaterfallHarness() as h:
+            fetch_dc._run_waterfall(h.ctx)
+        for q in h.ctx["queries"]:
+            self.assertIn("name", q)
+            self.assertIn("wave", q)
+            self.assertIn("rows", q)
+            self.assertIn("status", q)
+            self.assertIn("elapsed_ms", q)
+            self.assertIn(q["status"], ("ok", "empty", "skipped", "error"))
+
+
+# -----------------------------------------------------------------------------
+# harvested_ids
+# -----------------------------------------------------------------------------
+
+
+class WaterfallHarvestedIdsTests(unittest.TestCase):
+
+    def test_harvested_ids_match_fixture_counts(self):
+        with _WaterfallHarness() as h:
+            fetch_dc._run_waterfall(h.ctx)
+            harvested = h.ctx["harvested_ids"]
+        self.assertEqual(harvested["sessions"], 1)
+        self.assertEqual(harvested["interactions"], 3)
+        self.assertEqual(harvested["steps_total"], 3)
+        self.assertEqual(harvested["gateway_request_ids"], 2)
+        # moments DMO is empty; fetch_dc falls through to the participants
+        # harvest (AGENT participant row carries IDS.AGENT_API = "DemoAgent").
+        from .fixtures.synthetic_session import IDS  # type: ignore
+        self.assertEqual(harvested["agents_observed"], [IDS.AGENT_API])
+
+    def test_steps_by_type_categorizes_correctly(self):
+        with _WaterfallHarness() as h:
+            fetch_dc._run_waterfall(h.ctx)
+            sbt = h.ctx["harvested_ids"]["steps_by_type"]
+        # Synthetic fixture has 1 each of TOPIC_STEP, ACTION_STEP, TRUST_GUARDRAILS_STEP
+        self.assertEqual(sbt["ACTION_STEP"], 1)
+        self.assertEqual(sbt["TOPIC_STEP"], 1)
+        self.assertEqual(sbt["TRUST_GUARDRAILS_STEP"], 1)
+        self.assertEqual(sbt["LLM_STEP"], 0)
+
+
+# -----------------------------------------------------------------------------
+# Session-shape classification
+# -----------------------------------------------------------------------------
+
+
+class WaterfallSessionShapeTests(unittest.TestCase):
+
+    def test_normal_session_classified_as_complete(self):
+        with _WaterfallHarness() as h:
+            fetch_dc._run_waterfall(h.ctx)
+        self.assertEqual(h.ctx["session_shape"], "complete")
+
+    def test_no_steps_with_gateway_requests_classified_as_lag(self):
+        # Override: empty interactions/steps/messages but keep gateway_requests.
+        rows = make_rows()
+        rows["interactions"] = []
+        rows["steps"] = []
+        rows["messages"] = []
+        with _WaterfallHarness(rows_overrides=rows) as h:
+            fetch_dc._run_waterfall(h.ctx)
+        self.assertEqual(h.ctx["session_shape"], "interactions_not_materialized_yet")
+
+    def test_steps_no_llm_no_gateway_classified_as_abandoned(self):
+        # ACTION_STEP + TOPIC_STEP exist but no LLM_STEP and no gateway_requests.
+        rows = make_rows()
+        rows["gateway_requests"] = []
+        rows["gateway_responses"] = []
+        rows["gateway_records"] = []
+        rows["gateway_request_tags"] = []
+        with _WaterfallHarness(rows_overrides=rows) as h:
+            fetch_dc._run_waterfall(h.ctx)
+        self.assertEqual(h.ctx["session_shape"], "abandoned_before_llm")
+
+
+# -----------------------------------------------------------------------------
+# Empty harvest branches (zero IDs → _fetch_empty path)
+# -----------------------------------------------------------------------------
+
+
+class WaterfallEmptyHarvestTests(unittest.TestCase):
+
+    def test_no_interactions_skips_steps_via_fetch_empty(self):
+        rows = make_rows()
+        rows["interactions"] = []
+        with _WaterfallHarness(rows_overrides=rows) as h:
+            fetch_dc._run_waterfall(h.ctx)
+        # The steps query should be in the manifest as 'skipped'.
+        steps_entries = [q for q in h.ctx["queries"] if q["name"] == "steps"]
+        self.assertEqual(len(steps_entries), 1)
+        self.assertEqual(steps_entries[0]["status"], "skipped")
+        self.assertIn("no interactions", steps_entries[0]["_unavailable_reason"])
+
+    def test_no_gateway_requests_skips_audit_chain(self):
+        rows = make_rows()
+        rows["gateway_requests"] = []
+        with _WaterfallHarness(rows_overrides=rows) as h:
+            fetch_dc._run_waterfall(h.ctx)
+        # gateway_responses + tags + records + metadata + llm all skipped
+        for name in ("gateway_responses", "gateway_request_tags",
+                     "gateway_records", "gateway_request_metadata",
+                     "gateway_request_llm"):
+            entries = [q for q in h.ctx["queries"] if q["name"] == name]
+            self.assertEqual(entries[0]["status"], "skipped",
+                             f"{name} should be skipped")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/investigating-agentforce-d360/scripts/tests/test_identity_coherence.py

@@ -0,0 +1,327 @@
+"""Top-level vs nested identity coherence under manifest-placeholder shapes.
+
+Regression coverage for the bug where ``fetch_dc._resolve_identity`` falls
+through its strict AGENT-participant pick (fetch_dc.py:570-597) on agent
+shapes like MyAgent — leaving the manifest with
+``agent_version="v0"`` (placeholder) — while wave 5 then materializes
+``gateway_request_tags`` rows that carry the real ``v24``. The harvester
+``_build_session_identity`` correctly reads ``v24`` into
+``session.identity.agent_version``, but the top-level ``identity`` block
+was previously copied straight off the manifest and silently disagreed
+with the same JSON file's nested copy.
+
+These tests pin the promotion policy implemented by
+``_promote_identity`` / ``_reconcile_top_identity``:
+
+  - manifest "v0" + session "v24"     -> top promotes to v24
+  - manifest "v3" + session None      -> top stays v3 (manifest wins)
+  - manifest api None + session real  -> top promotes
+  - manifest "v3" + session "v5"      -> top stays v3 (manifest wins;
+                                          strict AGENT pick is intentional)
+  - manifest "v0" + session "v0"      -> top stays v0 (no real value
+                                          available; placeholder leak
+                                          remains visible to investigator)
+
+Plus a full round-trip through ``assemble_dc.assemble`` to confirm the
+top-level and nested identity records agree on a real MyAgent-shape
+session.
+"""
+from __future__ import annotations
+
+import json
+import unittest
+from copy import deepcopy
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from unittest import mock
+
+from . import _bootstrap  # noqa: F401  — sys.path setup
+
+import assemble_dc  # type: ignore
+from config import paths  # type: ignore
+from .fixtures.synthetic_session import (  # type: ignore
+    IDS, make_manifest, make_rows, write_to_disk,
+)
+
+
+# -----------------------------------------------------------------------------
+# Unit tests for _promote_identity (single-field policy)
+# -----------------------------------------------------------------------------
+
+
+class PromoteVersionTests(unittest.TestCase):
+    """`_promote_identity(..., kind="version")` — placeholder-only promotion."""
+
+    def test_v0_placeholder_promoted_when_session_has_real_version(self):
+        out = assemble_dc._promote_identity("v0", "v24", kind="version")
+        self.assertEqual(out, "v24")
+
+    def test_keeps_manifest_value_when_session_identity_is_none(self):
+        # Manifest already real; no reason to look elsewhere.
+        out = assemble_dc._promote_identity("v3", None, kind="version")
+        self.assertEqual(out, "v3")
+
+    def test_keeps_v0_when_session_also_returns_v0(self):
+        # No real value harvestable. Placeholder remains visible so
+        # the investigator can still see the resolution failed.
+        out = assemble_dc._promote_identity("v0", "v0", kind="version")
+        self.assertEqual(out, "v0")
+
+    def test_keeps_v0_when_session_value_is_garbage(self):
+        # Session shouldn't be able to "promote" a non-version-shaped string.
+        out = assemble_dc._promote_identity("v0", "garbage", kind="version")
+        self.assertEqual(out, "v0")
+
+    def test_keeps_v0_when_session_value_is_none(self):
+        out = assemble_dc._promote_identity("v0", None, kind="version")
+        self.assertEqual(out, "v0")
+
+    def test_no_promotion_when_both_real_but_disagree(self):
+        # Strict AGENT-row pick is intentional — manifest wins.
+        out = assemble_dc._promote_identity("v3", "v5", kind="version")
+        self.assertEqual(out, "v3")
+
+
+class PromoteApiNameTests(unittest.TestCase):
+    """`_promote_identity(..., kind="api_name")` — NOT_SET-ish promotion."""
+
+    def test_none_manifest_promoted_when_session_has_value(self):
+        out = assemble_dc._promote_identity(
+            None, "MyAgent", kind="api_name",
+        )
+        self.assertEqual(out, "MyAgent")
+
+    def test_not_set_string_promoted_when_session_has_value(self):
+        out = assemble_dc._promote_identity(
+            "NOT_SET", "MyAgent", kind="api_name",
+        )
+        self.assertEqual(out, "MyAgent")
+
+    def test_empty_manifest_promoted_when_session_has_value(self):
+        out = assemble_dc._promote_identity("", "MyAgent", kind="api_name")
+        self.assertEqual(out, "MyAgent")
+
+    def test_keeps_manifest_value_when_session_is_none(self):
+        # Symmetric of the version case — manifest wins when session
+        # has nothing to offer.
+        out = assemble_dc._promote_identity(
+            "MyAgent", None, kind="api_name",
+        )
+        self.assertEqual(out, "MyAgent")
+
+    def test_keeps_manifest_when_both_real(self):
+        out = assemble_dc._promote_identity(
+            "ManifestAgent", "SessionAgent", kind="api_name",
+        )
+        self.assertEqual(out, "ManifestAgent")
+
+
+# -----------------------------------------------------------------------------
+# Reconcile helper — composed policy across both fields + stderr note
+# -----------------------------------------------------------------------------
+
+
+class ReconcileTopIdentityTests(unittest.TestCase):
+
+    def test_reconcile_emits_stderr_note_when_version_promoted(self):
+        manifest = {"agent_api_name": "MyAgent", "agent_version": "v0"}
+        session_identity = {
+            "agent_api_name": None,
+            "agent_version": "v24",
+        }
+        with mock.patch("sys.stderr") as fake_stderr:
+            top = assemble_dc._reconcile_top_identity(
+                manifest, session_identity, "00DXX0000000ABC",
+            )
+        self.assertEqual(top["agent_version"], "v24")
+        self.assertEqual(top["agent_api_name"], "MyAgent")
+        self.assertEqual(top["org_id_15"], "00DXX0000000ABC")
+        # The stderr note format is part of the contract — at least
+        # one print call mentioning "promoted" must fire.
+        emitted = [
+            call.args[0] for call in fake_stderr.write.call_args_list
+            if call.args
+        ]
+        self.assertTrue(
+            any("promoted" in str(s) for s in emitted),
+            f"expected promotion note on stderr; got writes: {emitted}",
+        )
+
+    def test_reconcile_silent_when_no_promotion_needed(self):
+        manifest = {"agent_api_name": "DemoAgent", "agent_version": "v5"}
+        session_identity = {
+            "agent_api_name": "DemoAgent",
+            "agent_version": "v5",
+        }
+        with mock.patch("sys.stderr") as fake_stderr:
+            top = assemble_dc._reconcile_top_identity(
+                manifest, session_identity, "00DXX0000000ABC",
+            )
+        self.assertEqual(top["agent_version"], "v5")
+        emitted = [
+            call.args[0] for call in fake_stderr.write.call_args_list
+            if call.args
+        ]
+        self.assertFalse(
+            any("promoted" in str(s) for s in emitted),
+            f"unexpected promotion note: {emitted}",
+        )
+
+
+# -----------------------------------------------------------------------------
+# Full-fixture round-trip — MyAgent-shape session through assemble()
+# -----------------------------------------------------------------------------
+
+
+def _serviceagent2_shape_disk_writer(tmp_root: Path) -> Path:
+    """Materialize a MyAgent-shape session under tmp_root.
+
+    Mutates the synthetic fixture so that:
+
+      - manifest carries the placeholder ``agent_version="v0"`` (mirrors
+        what ``fetch_dc._resolve_identity``'s fallback stamps).
+      - the AGENT participant row has its ``ssot__AiAgentVersionApiName__c``
+        cleared to NOT_SET (so ``_build_session_identity`` doesn't pick up
+        a version from there).
+      - ``gateway_request_tags`` carries an ``agent_version_api_name=v24``
+        tag against the declared GW request, so the harvester finds the
+        real value.
+
+    The session dir lives under ``<org>/<api_name>__v0/<sid>/`` to match the
+    placeholder-stamped layout fetch_dc actually writes on this path.
+    """
+    rows = make_rows()
+
+    # AGENT row: clear version so _build_session_identity has no hint
+    # via that path; the harvest must come from gateway_request_tags.
+    for p in rows["participants"]:
+        if p.get("ssot__AiAgentSessionParticipantRole__c") == "AGENT":
+            p["ssot__AiAgentVersionApiName__c"] = "NOT_SET"
+
+    # Add the agent_version_api_name tag against the declared GW request.
+    rows["gateway_request_tags"].append({
+        "id__c": "tag-agent-version",
+        "parent__c": IDS.GW_REQ_DECLARED,
+        "tag__c": "agent_version_api_name",
+        "tagValue__c": '"v24"',  # quoted form mirrors live shape
+    })
+    # Plus agent_developer_name so session.identity.agent_api_name
+    # also gets a real value to test the api_name path.
+    rows["gateway_request_tags"].append({
+        "id__c": "tag-agent-dev",
+        "parent__c": IDS.GW_REQ_DECLARED,
+        "tag__c": "agent_developer_name",
+        "tagValue__c": '"MyAgent"',
+    })
+
+    # Manifest: placeholder version, real api_name (matches the
+    # MyAgent fallback's actual output — it stamps api_name from
+    # any participant row but version is forced to "v0").
+    manifest = make_manifest()
+    manifest["agent_api_name"] = "MyAgent"
+    manifest["agent_version"] = "v0"
+    manifest["org_id_15"] = IDS.ORG_ID_15
+
+    # Layout: <org>/<api_name>__v0/<sid>/ — the placeholder-shaped dir.
+    sdir = tmp_root / IDS.ORG_ID_15 / "MyAgent__v0" / IDS.SID
+    sdir.mkdir(parents=True, exist_ok=True)
+
+    (sdir / "dc._session_manifest.json").write_text(
+        json.dumps(manifest, indent=2) + "\n"
+    )
+    for name, rs in rows.items():
+        if rs:
+            (sdir / f"dc.{name}.json").write_text(
+                json.dumps(rs, indent=2) + "\n"
+            )
+
+    # Breadcrumb for _find_session_dir's primary path.
+    link_dir = tmp_root / IDS.ORG_ID_15 / "_sessions"
+    link_dir.mkdir(parents=True, exist_ok=True)
+    (link_dir / f"{IDS.SID}.link").write_text(
+        f"../MyAgent__v0/{IDS.SID}\n"
+    )
+    return sdir
+
+
+class AssembleEndToEndIdentityCoherenceTests(unittest.TestCase):
+    """The bug repro — top-level vs nested identity must agree after fix."""
+
+    def test_top_identity_promoted_when_manifest_has_v0_and_tags_have_v24(self):
+        with TemporaryDirectory() as tmp:
+            tmp_root = Path(tmp)
+            _serviceagent2_shape_disk_writer(tmp_root)
+            with mock.patch.object(paths, "DATA_ROOT", tmp_root):
+                tree, _ = assemble_dc.assemble(IDS.SID)
+        # The harvester (_build_session_identity) reads v24 from tags.
+        self.assertEqual(tree["session"]["identity"]["agent_version"], "v24")
+        # The top-level — previously v0 — must now agree.
+        self.assertEqual(tree["identity"]["agent_version"], "v24")
+
+    def test_top_and_session_identity_agree_on_agent_version(self):
+        with TemporaryDirectory() as tmp:
+            tmp_root = Path(tmp)
+            _serviceagent2_shape_disk_writer(tmp_root)
+            with mock.patch.object(paths, "DATA_ROOT", tmp_root):
+                tree, _ = assemble_dc.assemble(IDS.SID)
+        # The whole point of the fix.
+        self.assertEqual(
+            tree["identity"]["agent_version"],
+            tree["session"]["identity"]["agent_version"],
+        )
+
+    def test_api_name_top_level_keeps_manifest_when_session_returns_null(self):
+        # Mirror the live live-verification observation: top-level
+        # api_name is "MyAgent" (from manifest), session.identity
+        # api_name is None because no agent_developer_name tag fired.
+        # Strip the agent_developer_name tag we added in the helper.
+        with TemporaryDirectory() as tmp:
+            tmp_root = Path(tmp)
+            _serviceagent2_shape_disk_writer(tmp_root)
+            sdir = tmp_root / IDS.ORG_ID_15 / "MyAgent__v0" / IDS.SID
+            tags_path = sdir / "dc.gateway_request_tags.json"
+            tags = json.loads(tags_path.read_text())
+            tags = [t for t in tags if t.get("tag__c") != "agent_developer_name"]
+            tags_path.write_text(json.dumps(tags, indent=2) + "\n")
+
+            with mock.patch.object(paths, "DATA_ROOT", tmp_root):
+                tree, _ = assemble_dc.assemble(IDS.SID)
+        # session.identity.agent_api_name None — no harvestable value.
+        self.assertIsNone(tree["session"]["identity"]["agent_api_name"])
+        # Top-level keeps manifest's "MyAgent" — promotion does NOT
+        # erase a real manifest value when session has nothing to offer.
+        self.assertEqual(tree["identity"]["agent_api_name"], "MyAgent")
+
+
+# -----------------------------------------------------------------------------
+# Sanity: the existing happy-path fixture still produces matching identity
+# (regression guard against the fix mutating the simple case).
+# -----------------------------------------------------------------------------
+
+
+class HappyPathStillCoherentTests(unittest.TestCase):
+
+    def test_happy_path_unchanged(self):
+        # The synthetic fixture's gateway_request_tags don't include
+        # `agent_version_api_name`, so session.identity.agent_version is
+        # None on this path. The fix's policy preserves the manifest
+        # value ("v5") in that case — verifying the no-promote branch
+        # doesn't accidentally null out the top-level when the harvest
+        # layer has nothing to offer.
+        with TemporaryDirectory() as tmp:
+            tmp_root = Path(tmp)
+            write_to_disk(tmp_root)
+            with mock.patch.object(paths, "DATA_ROOT", tmp_root):
+                tree, _ = assemble_dc.assemble(IDS.SID)
+        self.assertEqual(tree["identity"]["agent_version"], IDS.AGENT_VERSION)
+        self.assertEqual(tree["identity"]["agent_api_name"], IDS.AGENT_API)
+        # session.identity may be None here (no agent_version_api_name tag);
+        # the top-level keeps the manifest's real value, which is the point.
+        self.assertIn(
+            tree["session"]["identity"]["agent_version"],
+            (None, IDS.AGENT_VERSION),
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()