test(search): pin boundary cases and re-pin goldens [roadmap:v0.10.3]

Add the token-boundary battery to the resolve battery: tokenization
(camelCase, non-alnum, punctuation-only), prefix matching, word-boundary
exclusion, multi-term AND, the five-tier ordering (id > title > path >
heading > body), body-only match with snippet, first-line determinism, and
the metadata-match byte-identical shape. Add the lore-vs-Explorer named
regression to the dogfood battery on the dogfood corpus.

Extend the mcp battery: a body-match snippet payload byte-equal to the CLI
find JSON, the metadata-match four-field shape, and whole-item truncation
of a snippet-bearing match.

Re-pin the find goldens to the new semantics ('markdown' now also surfaces
a roadmap by its body, with a snippet) and update the Explorer adapter's
trailing-type-token test, whose punctuation-only query no longer means
'match everything' under token matching.

Author: tcballard

tests/golden/find_human.txt

@@ -1,3 +1,5 @@
-RAC-01JY4M8X2QZ7  decision  Markdown Is the Canonical Source Format
+RAC-01JY4M8X2QZ7     decision  Markdown Is the Canonical Source Format
+v0-canonical-format  roadmap   Canonical Format Roadmap
+                               ↳ Initiatives: Adopt Markdown everywhere.
 
-1 match(es) for 'markdown'.
+2 match(es) for 'markdown'.

tests/golden/find_json.txt

@@ -2,13 +2,21 @@
   "schema_version": "1",
   "query": "markdown",
   "type": null,
-  "match_count": 1,
+  "match_count": 2,
   "matches": [
     {
       "id": "RAC-01JY4M8X2QZ7",
       "type": "decision",
       "title": "Markdown Is the Canonical Source Format",
       "path": "tests/fixtures/resolve/markdown-first.md"
+    },
+    {
+      "id": "v0-canonical-format",
+      "type": "roadmap",
+      "title": "Canonical Format Roadmap",
+      "path": "tests/fixtures/resolve/v0-canonical-format.md",
+      "section": "Initiatives",
+      "snippet": "Adopt Markdown everywhere."
     }
   ]
 }

tests/test_dogfood.py

@@ -106,6 +106,23 @@ def test_demo_keywords_surface_the_decision():
         assert DEMO_DECISION_ID in ids, f"{query!r} did not surface {DEMO_DECISION_ID}: {ids}"
 
 
+def test_lore_does_not_match_explorer_artifacts():
+    """Named regression (ADR-037): `lore` is a substring of "Explorer" but not a
+    token prefix of it. On the dogfood corpus — which carries both Lore and many
+    Explorer artifacts — `rac find lore` must return only Lore-related artifacts
+    and never an Explorer one."""
+    result = find_artifacts(CORPUS, "lore")
+    assert result.match_count > 0  # the Lore product-identity artifacts exist
+    leaked = [m.path for m in result.matches if "explorer" in m.path.casefold()]
+    assert leaked == [], f"`lore` leaked Explorer artifacts: {leaked}"
+    # Every match is genuinely Lore-related: the token appears in its content.
+    for m in result.matches:
+        text = Path(m.path).read_text(encoding="utf-8").casefold()
+        from rac.services.resolve import tokenize
+
+        assert "lore" in tokenize(text), f"{m.path} matched 'lore' without a lore token"
+
+
 def test_demo_decision_resolves_with_content():
     """get_artifact's resolver finds the decision and its content carries the
     hard-DELETE prohibition the grounded agent must cite."""

tests/test_explorer_adapter.py

@@ -236,7 +236,11 @@ def test_search_rows_rank_like_rac_find():
 def test_search_rows_trailing_type_token_filters():
     adapter = ExplorerAdapter(str(FIXTURES / "all_types"))
     adapter.load()
-    filtered = adapter.search_rows(". decision")
+    # "all" is a token of every artifact's path (the all_types fixture dir); the
+    # trailing "decision" filters to the one decision. Token-boundary matching
+    # (ADR-037) replaced substring matching, so a punctuation-only query no
+    # longer means "match everything" — the query must carry a real token.
+    filtered = adapter.search_rows("all decision")
     assert filtered.rows
     assert all(row.type == "decision" for row in filtered.rows)
 

tests/test_mcp_tools.py

@@ -129,6 +129,47 @@ def test_search_artifacts_empty_result_is_not_an_error():
     assert "error" not in payload
 
 
+def test_search_artifacts_body_match_carries_snippet():
+    # `tightly` appears only in the requirement's body ("Services are tightly
+    # coupled"). The body tier (ADR-038) surfaces it with section + snippet, and
+    # the tool payload is byte-identical to the CLI's find JSON.
+    payload = call(CORPUS, "search_artifacts", {"query": "tightly"})
+    assert payload["match_count"] == 1
+    match = payload["matches"][0]
+    assert match["id"] == REQ
+    assert match["section"] == "Problem"
+    assert match["snippet"] == "Services are tightly coupled."
+    cli = json.loads(json_output.render_find_json(find_artifacts(CORPUS, "tightly")))
+    assert payload == cli
+
+
+def test_search_artifacts_metadata_match_omits_snippet_fields():
+    # A title match (no body hit) keeps the four-field metadata shape exactly
+    # (ADR-007): no section/snippet keys appear.
+    payload = call(CORPUS, "search_artifacts", {"query": "decoupled", "type": "requirement"})
+    assert [m["id"] for m in payload["matches"]] == [REQ]
+    assert list(payload["matches"][0]) == ["id", "type", "title", "path"]
+
+
+def test_search_snippet_match_truncates_as_whole_item():
+    # A snippet-bearing match truncates as one whole item under a small budget:
+    # the snippet rides inside its entry, so it is never split mid-element.
+    full = call(CORPUS, "search_artifacts", {"query": "services"})
+    assert full["match_count"] >= 2 and "truncated" not in full
+    budget = 220
+    payload = call(CORPUS, "search_artifacts", {"query": "services"}, budget=budget)
+    assert payload["truncated"] is True
+    assert payload["match_count"] == full["match_count"]
+    assert len(payload["matches"]) < full["match_count"]
+    # Every kept entry is structurally complete: either a metadata shape or a
+    # metadata-plus-snippet shape, never a fragment.
+    for m in payload["matches"]:
+        assert {"id", "type", "title", "path"} <= set(m)
+        assert set(m) <= {"id", "type", "title", "path", "section", "snippet"}
+        if "snippet" in m or "section" in m:
+            assert "section" in m and "snippet" in m
+
+
 # --- get_related -------------------------------------------------------------
 
 

tests/test_resolve.py

@@ -168,6 +168,153 @@ def test_search_empty_repository_valid_no_match(tmp_path):
     assert result.matches == []
 
 
+# --- token-boundary battery (v0.10.3, ADR-037/ADR-038) --------------------------
+
+
+def test_tokenize_splits_on_boundaries_and_camelcase():
+    from rac.services.resolve import tokenize
+
+    assert tokenize("soft-delete") == ["soft", "delete"]
+    assert tokenize("relationships") == ["relationships"]
+    assert tokenize("Explorer") == ["explorer"]
+    assert tokenize("camelCaseWord") == ["camel", "case", "word"]
+    assert tokenize("adr-002-legacy.md") == ["adr", "002", "legacy", "md"]
+    assert tokenize("...") == []
+
+
+def test_prefix_matching_finds_whole_token(repo):
+    # `relation` must match a `relationships` token by prefix (ADR-037).
+    (repo / "decisions" / "relationships.md").write_text(
+        LEGACY_DECISION.replace("A Legacy Decision", "Relationship Validation"),
+        encoding="utf-8",
+    )
+    matches = find_artifacts(str(repo), "relation").matches
+    assert any(m.path.endswith("relationships.md") for m in matches)
+
+
+def test_word_boundary_excludes_substring_false_positive(repo):
+    # `lore` is a substring of "Explorer" but not a token prefix of it; the
+    # named regression (lore vs Explorer) lives in test_dogfood against the
+    # dogfood corpus. Here the unit form: a mid-word substring no longer hits.
+    (repo / "decisions" / "explorer.md").write_text(
+        LEGACY_DECISION.replace("A Legacy Decision", "The Explorer Surface"),
+        encoding="utf-8",
+    )
+    matches = find_artifacts(str(repo), "lore").matches
+    assert not any("explorer" in m.path.casefold() for m in matches)
+    assert not any((m.title or "").casefold().find("explorer") >= 0 for m in matches)
+
+
+def test_camelcase_split_is_searchable(repo):
+    (repo / "decisions" / "camel.md").write_text(
+        LEGACY_DECISION.replace("A Legacy Decision", "Use camelCase Identifiers"),
+        encoding="utf-8",
+    )
+    # `camel` and `case` are separate tokens after the camelCase split.
+    assert find_artifacts(str(repo), "camel").match_count >= 1
+    assert any(m.path.endswith("camel.md") for m in find_artifacts(str(repo), "case").matches)
+
+
+def test_multi_term_requires_every_term(repo):
+    (repo / "decisions" / "ab.md").write_text(
+        LEGACY_DECISION.replace("A Legacy Decision", "Alpha Bravo Decision"),
+        encoding="utf-8",
+    )
+    # Both terms present -> match; one term absent -> no match (AND semantics).
+    assert any(m.path.endswith("ab.md") for m in find_artifacts(str(repo), "alpha bravo").matches)
+    assert not any(
+        m.path.endswith("ab.md") for m in find_artifacts(str(repo), "alpha charlie").matches
+    )
+
+
+def test_tier_ordering_id_title_path_heading_body(tmp_path):
+    # Five artifacts, each making "needle" match at exactly one tier; the result
+    # order must be id, title, path, heading, body (ADR-038 ladder). Sorted-path
+    # tiebreak is irrelevant here — every artifact wins at a distinct tier.
+    base = (
+        "---\nschema_version: 1\nid: {id}\ntype: decision\n---\n"
+        "# {title}\n\n## Status\n\nAccepted\n\n## Category\n\nArchitecture\n\n"
+        "## {heading}\n\n{body}\n\n## Decision\n\nd\n\n## Consequences\n\nq\n"
+    )
+    # id tier: a legacy artifact whose filename stem (its identifier) carries the
+    # token. Path also carries it, but the id tier (rank 0) is the win.
+    (tmp_path / "needle-by-id.md").write_text(
+        "# Aaa\n\n## Context\n\nx\n\n## Decision\n\nd\n\n## Consequences\n\nq\n",
+        encoding="utf-8",
+    )
+    # title tier: token only in the title.
+    (tmp_path / "btitle.md").write_text(
+        base.format(id="RAC-TIT000000001", title="Needle Title", heading="Context", body="x"),
+        encoding="utf-8",
+    )
+    # path tier: token only in a directory component (not the stem, not id/title).
+    (tmp_path / "needledir").mkdir()
+    (tmp_path / "needledir" / "plain.md").write_text(
+        base.format(id="RAC-PTH000000001", title="Ccc", heading="Context", body="x"),
+        encoding="utf-8",
+    )
+    # heading tier: token only in a section heading.
+    (tmp_path / "dhead.md").write_text(
+        base.format(id="RAC-HED000000001", title="Ddd", heading="Needle Heading", body="x"),
+        encoding="utf-8",
+    )
+    # body tier: token only in body text.
+    (tmp_path / "ebody.md").write_text(
+        base.format(id="RAC-BOD000000001", title="Eee", heading="Context", body="needle in body"),
+        encoding="utf-8",
+    )
+    matches = find_artifacts(str(tmp_path), "needle").matches
+    order = [m.path.split("/")[-1] for m in matches]
+    assert order == ["needle-by-id.md", "btitle.md", "plain.md", "dhead.md", "ebody.md"]
+    # Only the heading and body matches carry snippets.
+    by_name = {m.path.split("/")[-1]: m for m in matches}
+    assert by_name["needle-by-id.md"].snippet is None
+    assert by_name["btitle.md"].snippet is None
+    assert by_name["plain.md"].snippet is None
+    assert by_name["dhead.md"].section == "Needle Heading"
+    assert by_name["ebody.md"].snippet == "needle in body"
+
+
+def test_body_only_match_carries_snippet(tmp_path):
+    # A decision whose body, not its title/path/id, holds the query term is
+    # found, with the section heading and matching line as its snippet (ADR-038).
+    (tmp_path / "dec.md").write_text(
+        "---\nschema_version: 1\nid: RAC-BODYONLY0001\ntype: decision\n---\n"
+        "# Unrelated Title\n\n## Status\n\nAccepted\n\n## Category\n\nArchitecture\n\n"
+        "## Context\n\nThe payments gateway must stay idempotent.\n\n"
+        "## Decision\n\nd\n\n## Consequences\n\nq\n",
+        encoding="utf-8",
+    )
+    matches = find_artifacts(str(tmp_path), "idempotent").matches
+    assert len(matches) == 1
+    m = matches[0]
+    assert m.section == "Context"
+    assert m.snippet == "The payments gateway must stay idempotent."
+    # The snippet fields ride inside the match dict (additive, ADR-007).
+    assert m.to_dict()["section"] == "Context"
+    assert m.to_dict()["snippet"] == "The payments gateway must stay idempotent."
+
+
+def test_metadata_match_has_no_snippet_fields(repo):
+    # An id/title/path match's dict is byte-identical to the pre-v0.10.3 shape.
+    match = find_artifacts(str(repo), CANONICAL_ID).matches[0]
+    assert match.section is None and match.snippet is None
+    assert set(match.to_dict()) == {"id", "type", "title", "path"}
+
+
+def test_body_snippet_is_first_matching_line_in_document_order(tmp_path):
+    (tmp_path / "dec.md").write_text(
+        "---\nschema_version: 1\nid: RAC-FIRSTLINE01\ntype: decision\n---\n"
+        "# T\n\n## Status\n\nAccepted\n\n## Category\n\nArchitecture\n\n"
+        "## Context\n\nFirst widget line.\nSecond widget line.\n\n"
+        "## Decision\n\nThird widget line.\n\n## Consequences\n\nq\n",
+        encoding="utf-8",
+    )
+    match = find_artifacts(str(tmp_path), "widget").matches[0]
+    assert match.section == "Context"
+    assert match.snippet == "First widget line."
+
+
 # --- index seams (v0.8.1): same semantics without a directory walk --------------