@salesforce/afv-skills 1.13.0 → 1.15.0

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

@@ -0,0 +1,220 @@
+"""Tests for ``assemble_dc._assemble_gateway_direct``.
+
+Exercises the ``interactions_not_materialized_yet`` path: session row
+resolved, gateway_requests populated, interactions/steps empty. Builds a
+minimal rows-dict fixture and calls the private assembler directly — the
+function is pure over (sid, rows, manifest, parse_warnings), so no disk
+fixtures are needed.
+
+Scope:
+  - ``_source == "gateway_direct"`` sentinel
+  - ``session.interactions == []`` (downstream consumers no-op)
+  - ``session.gateway_chain`` length == fixture's gateway_requests
+  - each gateway_chain entry has a populated ``response.timestamp``
+  - finish_reason is lifted out of the HTML-escaped parameters JSON
+  - model / provider / prompt_template_dev_name / token counts populated
+"""
+from __future__ import annotations
+
+import unittest
+
+from . import _bootstrap  # noqa: F401  — sys.path setup
+
+from assemble_dc import _assemble_gateway_direct  # type: ignore
+
+
+_SID = "01912345-0000-7000-8000-000000000001"
+
+
+def _gw_request(req_id: str, ts: str, model: str, tokens: tuple) -> dict:
+    """Shape mirrors GenAIGatewayRequest__dlm rows as fetched."""
+    prompt_tok, completion_tok, total_tok = tokens
+    return {
+        "gatewayRequestId__c": req_id,
+        "sf__Id": f"sf-{req_id}",
+        "sessionId__c": f'"{_SID}"',
+        "timestamp__c": ts,
+        "model__c": model,
+        "provider__c": "openai",
+        "promptTemplateDevName__c": "AiCopilot__ReactTopicPrompt",
+        "feature__c": "plannerservice",
+        "promptTokens__c": prompt_tok,
+        "completionTokens__c": completion_tok,
+        "totalTokens__c": total_tok,
+        "prompt__c": f"This is the prompt body for {req_id}.",
+    }
+
+
+def _gw_response(req_id: str, resp_id: str, ts: str, finish: str) -> dict:
+    """Shape mirrors GenAIGatewayResponse__dlm rows as fetched.
+
+    parameters__c is HTML-escaped JSON with the finish_reason value
+    wrapped in escaped quotes — the exact on-wire shape the live fetcher
+    produces. Mirrors the fixture used elsewhere in the test suite.
+    """
+    # Build the raw JSON first, then HTML-escape the quotes the same way
+    # the gateway serializer does.
+    raw = '{"finish_reason":"\\"' + finish + '\\""}'
+    escaped = raw.replace('"', """)
+    return {
+        "generationResponseId__c": resp_id,
+        "generationRequestId__c": req_id,
+        "parameters__c": escaped,
+        "timestamp__c": ts,
+    }
+
+
+def _tag(req_id: str, key: str, value: str) -> dict:
+    return {
+        "id__c": f"tag-{req_id}-{key}",
+        "parent__c": req_id,
+        "tag__c": key,
+        "tagValue__c": value,
+    }
+
+
+def _md(req_id: str, mtype: str, payload: str) -> dict:
+    return {
+        "id__c": f"md-{req_id}",
+        "parent__c": req_id,
+        "metadataType__c": mtype,
+        "metadata__c": payload,
+    }
+
+
+def _make_rows() -> dict:
+    session_row = {
+        "ssot__Id__c": _SID,
+        "ssot__StartTimestamp__c": "2026-05-03T10:00:00.000Z",
+        "ssot__EndTimestamp__c": None,
+        "ssot__AiAgentChannelType__c": "EmbeddedMessaging",
+        "ssot__AiAgentSessionEndType__c": None,
+    }
+    return {
+        "sessions": [session_row],
+        "participants": [],
+        "messages": [],
+        "moments": [],
+        "interactions": [],
+        "steps": [],
+        "generations": [],
+        "gateway_requests": [
+            _gw_request("gw-1", "2026-05-03T10:00:01.000Z", "gpt-4o", (100, 50, 150)),
+            _gw_request("gw-2", "2026-05-03T10:00:05.000Z", "gpt-4o", (200, 80, 280)),
+            _gw_request("gw-3", "2026-05-03T10:00:10.000Z", "gpt-4o-mini", (50, 30, 80)),
+        ],
+        "gateway_responses": [
+            _gw_response("gw-1", "resp-1", "2026-05-03T10:00:02.500Z", "stop"),
+            _gw_response("gw-2", "resp-2", "2026-05-03T10:00:06.000Z", "tool_calls"),
+            _gw_response("gw-3", "resp-3", "2026-05-03T10:00:11.000Z", "stop"),
+        ],
+        "gateway_request_tags": [
+            _tag("gw-1", "bot_id", "0Xx000000000001"),
+            _tag("gw-2", "feature", "plannerservice"),
+        ],
+        "gateway_request_metadata": [
+            _md("gw-2", "ToolCall", '{"tool":"apex"}'),
+        ],
+        "gateway_request_llm": [],
+        "content_quality": [],
+        "content_category": [],
+        "feedback": [],
+        "feedback_details": [],
+        "gateway_records": [],
+        "tag_associations": [],
+        "tag_definitions": [],
+        "tag_definition_associations": [],
+        "tags": [],
+        "app_generation": [],
+        "telemetry_spans": [],
+        "moment_interactions": [],
+    }
+
+
+def _make_manifest() -> dict:
+    return {
+        "session_id": _SID,
+        "org_alias": "test-org",
+        "instance_url": "https://example.my.salesforce.com",
+        "org_id_15": "00DXX0000000001",
+        "agent_api_name": "My_Agent",
+        "agent_version": "v1",
+        "session_shape": "interactions_not_materialized_yet",
+        "queries": [],
+    }
+
+
+class AssembleGatewayDirectTests(unittest.TestCase):
+
+    def setUp(self):
+        self.rows = _make_rows()
+        self.manifest = _make_manifest()
+        self.tree = _assemble_gateway_direct(
+            _SID, self.rows, self.manifest, parse_warnings=[])
+
+    def test_source_sentinel(self):
+        """The render layer keys off this exact string."""
+        self.assertEqual(self.tree["_source"], "gateway_direct")
+
+    def test_interactions_is_explicit_empty_list(self):
+        """Downstream consumers walk session.interactions — must exist + be empty."""
+        self.assertEqual(self.tree["session"]["interactions"], [])
+
+    def test_gateway_chain_length_matches_input(self):
+        self.assertEqual(len(self.tree["session"]["gateway_chain"]), 3)
+
+    def test_each_chain_entry_has_response_timestamp(self):
+        """Join via generationRequestId__c must populate response.timestamp on each."""
+        for call in self.tree["session"]["gateway_chain"]:
+            with self.subTest(req_id=call.get("gateway_request_id")):
+                self.assertIsNotNone(call.get("response"))
+                self.assertIsNotNone(call["response"].get("timestamp"))
+
+    def test_finish_reason_parsed(self):
+        """HTML-escaped, quote-wrapped finish_reason must decode to bare string."""
+        reasons = [c["response"]["finish_reason"]
+                   for c in self.tree["session"]["gateway_chain"]]
+        self.assertEqual(reasons, ["stop", "tool_calls", "stop"])
+
+    def test_chain_sorted_by_timestamp(self):
+        """Deterministic ordering — required for byte-identical output across runs."""
+        timestamps = [c["timestamp"] for c in self.tree["session"]["gateway_chain"]]
+        self.assertEqual(timestamps, sorted(timestamps))
+
+    def test_model_and_tokens_harvested(self):
+        first = self.tree["session"]["gateway_chain"][0]
+        self.assertEqual(first["model"], "gpt-4o")
+        self.assertEqual(first["provider"], "openai")
+        self.assertEqual(first["prompt_template_dev_name"],
+                         "AiCopilot__ReactTopicPrompt")
+        self.assertEqual(first["prompt_tokens"], 100)
+        self.assertEqual(first["total_tokens"], 150)
+
+    def test_prompt_text_untruncated_on_disk(self):
+        """Assembler stores the full prompt — the 64 KB cap is render-only."""
+        for call in self.tree["session"]["gateway_chain"]:
+            self.assertIn("This is the prompt body for",
+                          call.get("prompt_text") or "")
+
+    def test_identity_block_present(self):
+        """Top-level identity must carry (org_id_15, agent_api_name, agent_version)."""
+        self.assertEqual(self.tree["identity"]["org_id_15"], "00DXX0000000001")
+        self.assertEqual(self.tree["identity"]["agent_api_name"], "My_Agent")
+        self.assertEqual(self.tree["identity"]["agent_version"], "v1")
+
+    def test_stdm_lag_note_on_session(self):
+        note = self.tree["session"].get("_stdm_lag_note") or ""
+        self.assertIn("materialize on a separate cadence", note)
+
+    def test_counts_reflect_input_rows(self):
+        counts = self.tree["session"]["counts"]
+        self.assertEqual(counts["gateway_requests"], 3)
+        self.assertEqual(counts["gateway_responses"], 3)
+        self.assertEqual(counts["interactions_total"], 0)
+        self.assertEqual(counts["steps_total"], 0)
+        self.assertEqual(counts["session_shape"],
+                         "interactions_not_materialized_yet")
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,158 @@
+"""Integration tests for ``assemble_dc._assemble_gateway_direct``.
+
+Drives the materialization-lag path: session row + gateway_requests
+populated, but interactions / steps absent. Triggered by setting
+``manifest.session_shape = "interactions_not_materialized_yet"``.
+
+Complements ``test_assemble_dc_gateway_direct.py`` which calls the
+private function with a hand-built rows dict; this file drives the
+public ``assemble`` entry point through the disk-load path so manifest
++ rows + path resolution are all exercised.
+"""
+from __future__ import annotations
+
+import json
+import unittest
+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, write_to_disk, make_manifest,
+)
+
+
+def _materialization_lag_mutator(sdir: Path) -> None:
+    """Make the fixture look like a session whose STDM hierarchy hasn't
+    materialized yet: keep gateway_requests + gateway_responses + tags,
+    but wipe interactions / steps / messages and flip the manifest.
+
+    This is the live-DC failure mode that the gateway-direct path was
+    written to handle.
+    """
+    # Wipe interaction/step/message rows (file with empty list)
+    for name in ("interactions", "steps", "messages"):
+        (sdir / f"dc.{name}.json").write_text("[]")
+    # Update manifest session_shape so assemble's branch fires.
+    manifest = make_manifest()
+    manifest["session_shape"] = "interactions_not_materialized_yet"
+    (sdir / "dc._session_manifest.json").write_text(
+        json.dumps(manifest, indent=2)
+    )
+
+
+class _GatewayDirectHarness:
+    def __enter__(self):
+        self._tmp = TemporaryDirectory()
+        self._tmpdir = Path(self._tmp.name)
+        sdir = write_to_disk(self._tmpdir)
+        _materialization_lag_mutator(sdir)
+        self._patch = mock.patch.object(paths, "DATA_ROOT", self._tmpdir)
+        self._patch.start()
+        self.tree, self.sdir = assemble_dc.assemble(IDS.SID)
+        return self
+
+    def __exit__(self, *exc):
+        self._patch.stop()
+        self._tmp.cleanup()
+
+
+# -----------------------------------------------------------------------------
+# Top-level shape on the gateway-direct branch
+# -----------------------------------------------------------------------------
+
+
+class GatewayDirectShapeTests(unittest.TestCase):
+
+    def test_source_marker_set_to_gateway_direct(self):
+        with _GatewayDirectHarness() as h:
+            self.assertEqual(h.tree["_source"], "gateway_direct")
+
+    def test_interactions_is_empty_list(self):
+        with _GatewayDirectHarness() as h:
+            self.assertEqual(h.tree["session"]["interactions"], [])
+
+    def test_gateway_chain_populated_from_gateway_requests(self):
+        with _GatewayDirectHarness() as h:
+            chain = h.tree["session"]["gateway_chain"]
+        # Fixture has 2 gateway_requests; both make it into the chain.
+        self.assertEqual(len(chain), 2)
+        chain_ids = {gw["gateway_request_id"] for gw in chain}
+        self.assertEqual(chain_ids, {IDS.GW_REQ_DECLARED, IDS.GW_REQ_WINDOW})
+
+    def test_chain_sorted_by_timestamp(self):
+        # Earlier gateway request timestamp comes first.
+        with _GatewayDirectHarness() as h:
+            chain = h.tree["session"]["gateway_chain"]
+        timestamps = [gw.get("timestamp") for gw in chain]
+        self.assertEqual(timestamps, sorted(t or "" for t in timestamps))
+
+    def test_each_gateway_chain_entry_has_response(self):
+        # Only the declared request has a response in the fixture; the
+        # window-bound one has response=None. Both shapes are accepted.
+        with _GatewayDirectHarness() as h:
+            chain = h.tree["session"]["gateway_chain"]
+        declared = next(gw for gw in chain
+                        if gw["gateway_request_id"] == IDS.GW_REQ_DECLARED)
+        self.assertIsNotNone(declared["response"])
+
+    def test_top_identity_block_resolved_from_manifest(self):
+        with _GatewayDirectHarness() as h:
+            ident = h.tree["identity"]
+        self.assertEqual(ident["org_id_15"], IDS.ORG_ID_15)
+        self.assertEqual(ident["agent_api_name"], IDS.AGENT_API)
+        self.assertEqual(ident["agent_version"], IDS.AGENT_VERSION)
+
+    def test_counts_block_records_session_shape_and_zero_interactions(self):
+        with _GatewayDirectHarness() as h:
+            counts = h.tree["session"]["counts"]
+        self.assertEqual(counts["session_shape"],
+                         "interactions_not_materialized_yet")
+        self.assertEqual(counts["interactions_total"], 0)
+        self.assertEqual(counts["steps_total"], 0)
+        self.assertEqual(counts["gateway_requests"], 2)
+
+
+# -----------------------------------------------------------------------------
+# render_dc on the gateway-direct tree
+# -----------------------------------------------------------------------------
+
+
+class GatewayDirectRenderTests(unittest.TestCase):
+    """The gateway-direct render branch is short — covers identity,
+    lag banner, and gateway-chain table. Drives it end-to-end."""
+
+    def test_render_emits_lag_banner(self):
+        import render_dc  # noqa: WPS433
+        with _GatewayDirectHarness() as h:
+            md = render_dc.render(h.tree, manifest=None, session_dir=h.sdir)
+        # _STDM_LAG_NOTE is referenced in the gateway-direct render path
+        # — must surface as visible text. We assert on the substring
+        # "STDM" since the exact phrasing may evolve.
+        self.assertIn("STDM", md)
+
+    def test_render_lists_both_gateway_requests(self):
+        import render_dc  # noqa: WPS433
+        with _GatewayDirectHarness() as h:
+            md = render_dc.render(h.tree, manifest=None, session_dir=h.sdir)
+        # Gateway-direct render truncates IDs to 8-char prefixes — assert
+        # on the prefix substring + on the prompt-template name (verbatim
+        # in the per-call detail block).
+        self.assertIn(IDS.GW_REQ_DECLARED[:8], md)
+        self.assertIn(IDS.GW_REQ_WINDOW[:8], md)
+        self.assertIn("AiCopilot__ReactInitialPrompt", md)
+        self.assertIn("AiCopilot__PromptTemplateGenerationsInvocable", md)
+
+    def test_render_includes_session_id(self):
+        import render_dc  # noqa: WPS433
+        with _GatewayDirectHarness() as h:
+            md = render_dc.render(h.tree, manifest=None, session_dir=h.sdir)
+        self.assertIn(IDS.SID, md)
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,287 @@
+"""Tests for ``assemble_dc`` pure helpers — independent of disk fixtures.
+
+Complements ``test_assemble_dc_gateway_direct.py`` (binding chain) by
+hitting the small, mechanical helpers that bridge raw DC rows and the
+assembled tree:
+
+- ``_clean``           NOT_SET sentinel collapse
+- ``_harvest_str``     unescape + quote-strip + UNSET_VALUE
+- ``_ts``              ISO-8601 → datetime; NOT_SET / non-string → None
+- ``_index_unique``    PK dedup with first-write-wins + collision record
+- ``_groupby``         group rows by FK, dropping NOT_SET keys
+- ``_extract_trace_id`` primary col with HTML-escaped fallback
+- ``_tier``            ACTION < TOPIC < GUARDRAIL < other
+- ``_window_contains`` half-open / closed timestamp interval semantics
+- ``_load``            disk read with malformed-json tolerance
+"""
+from __future__ import annotations
+
+import json
+import unittest
+from datetime import datetime, timezone
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from . import _bootstrap  # noqa: F401  — sys.path setup
+
+import assemble_dc  # type: ignore
+
+
+# -----------------------------------------------------------------------------
+# _clean — NOT_SET → None
+# -----------------------------------------------------------------------------
+
+
+class CleanTests(unittest.TestCase):
+
+    def test_not_set_token_returns_none(self):
+        self.assertIsNone(assemble_dc._clean("NOT_SET"))
+
+    def test_empty_string_returns_none(self):
+        self.assertIsNone(assemble_dc._clean(""))
+
+    def test_actual_value_passes_through(self):
+        self.assertEqual(assemble_dc._clean("real value"), "real value")
+        self.assertEqual(assemble_dc._clean(42), 42)
+
+
+# -----------------------------------------------------------------------------
+# _harvest_str — unescape + quote-strip + UNSET_VALUE collapse
+# -----------------------------------------------------------------------------
+
+
+class HarvestStrTests(unittest.TestCase):
+
+    def test_none_returns_none(self):
+        self.assertIsNone(assemble_dc._harvest_str(None))
+
+    def test_unescapes_html_entities(self):
+        self.assertEqual(
+            assemble_dc._harvest_str("&quot;0Xx000&quot;"),
+            "0Xx000",
+        )
+
+    def test_strips_outer_double_quotes(self):
+        self.assertEqual(assemble_dc._harvest_str('"value"'), "value")
+
+    def test_unset_value_collapses_to_none(self):
+        self.assertIsNone(assemble_dc._harvest_str("UNSET_VALUE"))
+
+    def test_not_set_collapses_to_none(self):
+        self.assertIsNone(assemble_dc._harvest_str("NOT_SET"))
+
+    def test_empty_string_collapses_to_none(self):
+        self.assertIsNone(assemble_dc._harvest_str(""))
+
+
+# -----------------------------------------------------------------------------
+# _ts — ISO-8601 timestamp parsing
+# -----------------------------------------------------------------------------
+
+
+class TsTests(unittest.TestCase):
+
+    def test_parses_iso_z_timestamp(self):
+        out = assemble_dc._ts("2026-04-22T10:00:00Z")
+        self.assertEqual(out, datetime(2026, 4, 22, 10, 0, 0, tzinfo=timezone.utc))
+
+    def test_parses_iso_offset_timestamp(self):
+        out = assemble_dc._ts("2026-04-22T10:00:00+00:00")
+        self.assertEqual(out, datetime(2026, 4, 22, 10, 0, 0, tzinfo=timezone.utc))
+
+    def test_returns_none_for_non_string(self):
+        self.assertIsNone(assemble_dc._ts(None))
+        self.assertIsNone(assemble_dc._ts(12345))
+
+    def test_returns_none_for_not_set(self):
+        self.assertIsNone(assemble_dc._ts("NOT_SET"))
+        self.assertIsNone(assemble_dc._ts(""))
+
+    def test_returns_none_for_unparseable(self):
+        self.assertIsNone(assemble_dc._ts("not-a-timestamp"))
+
+
+# -----------------------------------------------------------------------------
+# _index_unique
+# -----------------------------------------------------------------------------
+
+
+class IndexUniqueTests(unittest.TestCase):
+
+    def test_builds_dict_keyed_by_field(self):
+        rows = [{"id": "a", "v": 1}, {"id": "b", "v": 2}]
+        out = assemble_dc._index_unique(rows, "id", [], dmo_label="t")
+        self.assertEqual(set(out.keys()), {"a", "b"})
+
+    def test_first_write_wins_on_collision(self):
+        rows = [{"id": "a", "v": 1}, {"id": "a", "v": 2}]
+        collisions: list[dict] = []
+        out = assemble_dc._index_unique(rows, "id", collisions, dmo_label="dmo1")
+        self.assertEqual(out["a"]["v"], 1)
+        self.assertEqual(len(collisions), 1)
+        self.assertEqual(collisions[0]["dmo"], "dmo1")
+        self.assertEqual(collisions[0]["key"], "a")
+
+    def test_skips_NOT_SET_keys(self):
+        rows = [{"id": "NOT_SET", "v": 1}, {"id": "", "v": 2}, {"id": "a", "v": 3}]
+        out = assemble_dc._index_unique(rows, "id", [], dmo_label="t")
+        self.assertEqual(set(out.keys()), {"a"})
+
+
+# -----------------------------------------------------------------------------
+# _groupby
+# -----------------------------------------------------------------------------
+
+
+class GroupbyTests(unittest.TestCase):
+
+    def test_groups_rows_by_key(self):
+        rows = [{"k": "a", "v": 1}, {"k": "b", "v": 2}, {"k": "a", "v": 3}]
+        out = assemble_dc._groupby(rows, "k")
+        self.assertEqual([r["v"] for r in out["a"]], [1, 3])
+        self.assertEqual([r["v"] for r in out["b"]], [2])
+
+    def test_skips_NOT_SET_keys(self):
+        rows = [{"k": "a", "v": 1}, {"k": "NOT_SET", "v": 2}]
+        out = assemble_dc._groupby(rows, "k")
+        self.assertNotIn("NOT_SET", out)
+        self.assertIn("a", out)
+
+
+# -----------------------------------------------------------------------------
+# _extract_trace_id
+# -----------------------------------------------------------------------------
+
+
+class ExtractTraceIdTests(unittest.TestCase):
+
+    def test_uses_primary_column_when_populated(self):
+        out = assemble_dc._extract_trace_id({"ssot__TelemetryTraceId__c": "abc"})
+        self.assertEqual(out, "abc")
+
+    def test_falls_back_to_html_escaped_attribute_text(self):
+        out = assemble_dc._extract_trace_id({
+            "ssot__TelemetryTraceId__c": "",
+            "ssot__AttributeText__c": '&quot;internalTraceId&quot;:&quot;deadbeef&quot;',
+        })
+        self.assertEqual(out, "deadbeef")
+
+    def test_returns_none_when_no_trace_id_anywhere(self):
+        out = assemble_dc._extract_trace_id({
+            "ssot__TelemetryTraceId__c": "",
+            "ssot__AttributeText__c": "no trace here",
+        })
+        self.assertIsNone(out)
+
+    def test_returns_none_for_NOT_SET(self):
+        out = assemble_dc._extract_trace_id({
+            "ssot__TelemetryTraceId__c": "NOT_SET",
+            "ssot__AttributeText__c": "",
+        })
+        self.assertIsNone(out)
+
+
+# -----------------------------------------------------------------------------
+# _tier — ACTION < TOPIC < GUARDRAIL < other
+# -----------------------------------------------------------------------------
+
+
+class TierTests(unittest.TestCase):
+
+    def test_action_step_is_lowest_tier(self):
+        self.assertLess(
+            assemble_dc._tier("ACTION_STEP"),
+            assemble_dc._tier("TOPIC_STEP"),
+        )
+
+    def test_topic_step_outranks_guardrails(self):
+        self.assertLess(
+            assemble_dc._tier("TOPIC_STEP"),
+            assemble_dc._tier("TRUST_GUARDRAILS_STEP"),
+        )
+
+    def test_unknown_step_type_falls_to_end(self):
+        self.assertEqual(
+            assemble_dc._tier("MYSTERY"),
+            len(assemble_dc._TIER_ORDER),
+        )
+
+
+# -----------------------------------------------------------------------------
+# _window_contains
+# -----------------------------------------------------------------------------
+
+
+class WindowContainsTests(unittest.TestCase):
+
+    def _ts(self, h, m, s):
+        return datetime(2026, 4, 22, h, m, s, tzinfo=timezone.utc)
+
+    def test_in_range_inclusive_of_start_and_end(self):
+        gw = self._ts(10, 0, 5)
+        self.assertTrue(
+            assemble_dc._window_contains(gw, self._ts(10, 0, 0), self._ts(10, 0, 10))
+        )
+
+    def test_open_ended_when_end_is_none(self):
+        gw = self._ts(11, 0, 0)
+        self.assertTrue(
+            assemble_dc._window_contains(gw, self._ts(10, 0, 0), None)
+        )
+
+    def test_returns_false_when_start_is_none(self):
+        gw = self._ts(10, 0, 0)
+        self.assertFalse(
+            assemble_dc._window_contains(gw, None, self._ts(11, 0, 0))
+        )
+
+    def test_returns_false_when_before_start(self):
+        gw = self._ts(9, 0, 0)
+        self.assertFalse(
+            assemble_dc._window_contains(gw, self._ts(10, 0, 0), self._ts(11, 0, 0))
+        )
+
+    def test_returns_false_when_after_end(self):
+        gw = self._ts(12, 0, 0)
+        self.assertFalse(
+            assemble_dc._window_contains(gw, self._ts(10, 0, 0), self._ts(11, 0, 0))
+        )
+
+
+# -----------------------------------------------------------------------------
+# _load — disk read with tolerance
+# -----------------------------------------------------------------------------
+
+
+class LoadTests(unittest.TestCase):
+
+    def test_returns_empty_list_when_file_missing(self):
+        with TemporaryDirectory() as t:
+            warnings: list[str] = []
+            self.assertEqual(
+                assemble_dc._load(Path(t), "missing", warnings), []
+            )
+            # Missing file is normal — no warning recorded.
+            self.assertEqual(warnings, [])
+
+    def test_returns_loaded_rows_when_file_valid(self):
+        with TemporaryDirectory() as t:
+            tmp = Path(t)
+            (tmp / "dc.sessions.json").write_text(json.dumps([{"a": 1}, {"a": 2}]))
+            warnings: list[str] = []
+            out = assemble_dc._load(tmp, "sessions", warnings)
+            self.assertEqual(out, [{"a": 1}, {"a": 2}])
+            self.assertEqual(warnings, [])
+
+    def test_returns_empty_list_and_records_warning_on_malformed_json(self):
+        with TemporaryDirectory() as t:
+            tmp = Path(t)
+            (tmp / "dc.broken.json").write_text("<<<not json>>>")
+            warnings: list[str] = []
+            out = assemble_dc._load(tmp, "broken", warnings)
+            self.assertEqual(out, [])
+            self.assertEqual(warnings, ["broken"])
+
+
+if __name__ == "__main__":
+    unittest.main()