feat(union): overlay-aware resolution (WP-0008 T5)

resolve() layers open overlays onto canonical pages (overlay_state=DRAFT always
surfaced; overlaid body projected when policy.show_drafts); draft-only edits make
a not-yet-existing page resolvable. Never hides an unapplied overlay (I-4). Policy
gains show_drafts. 4 tests green, pyflakes clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

tests/test_overlay_aware_read.py

@@ -0,0 +1,50 @@
+"""Tests for overlay-aware union read (SHARD-WP-0008 T5)."""
+
+from shard_wiki.adapters import FolderAdapter
+from shard_wiki.coordination import DecisionLog, OverlayEngine
+from shard_wiki.model import Identity
+from shard_wiki.policy import Policy
+from shard_wiki.provenance import OverlayState
+from shard_wiki.union import ResolutionKind, UnionGraph
+
+
+def _union(tmp_path, files, policy=None):
+    for rel, text in files.items():
+        (tmp_path / rel).write_text(text, encoding="utf-8")
+    log = DecisionLog()
+    u = UnionGraph("space", log=log, policy=policy) if policy else UnionGraph("space", log=log)
+    u.attach(FolderAdapter("wikiA", tmp_path))
+    return u, OverlayEngine("space", log)
+
+
+def test_no_overlay_reads_clean(tmp_path):
+    u, _ = _union(tmp_path, {"Home.md": "canon"})
+    page = u.resolve("Home").single()
+    assert page.body == "canon"
+    assert page.envelope.overlay_state is OverlayState.NONE
+
+
+def test_open_overlay_surfaces_draft_and_projects_body(tmp_path):
+    u, eng = _union(tmp_path, {"Home.md": "canon"})
+    eng.draft(Identity("wikiA", "Home"), "my draft", base_rev=None)
+    page = u.resolve("Home").single()
+    assert page.envelope.overlay_state is OverlayState.DRAFT  # never hidden
+    assert page.body == "my draft"  # projected (show_drafts default True)
+
+
+def test_show_drafts_false_keeps_canonical_body_but_still_flags(tmp_path):
+    u, eng = _union(tmp_path, {"Home.md": "canon"}, policy=Policy(show_drafts=False))
+    eng.draft(Identity("wikiA", "Home"), "my draft", base_rev=None)
+    page = u.resolve("Home").single()
+    assert page.body == "canon"  # not projected
+    assert page.envelope.overlay_state is OverlayState.DRAFT  # but still surfaced (I-4)
+
+
+def test_draft_only_new_page_becomes_resolvable(tmp_path):
+    u, eng = _union(tmp_path, {"Home.md": "x"})
+    assert u.resolve("Brand").is_red_link  # nothing yet
+    eng.draft(Identity("wikiA", "Brand"), "drafted into being", base_rev=None)
+    res = u.resolve("Brand")
+    assert res.kind is ResolutionKind.SINGLE
+    assert res.single().body == "drafted into being"
+    assert res.single().envelope.overlay_state is OverlayState.DRAFT