03 — Test c: Parent/Child/Grandchild Tree-Axis Filter Plan (READ-ONLY)

Goal: Given a root IU (or canonical address), return its descendant subtree (children, grandchildren, …) with depth and ancestry, DOT-callable and automated. Read-only: zero mutation.

Owner law: Điều 38/39 (IU structure). Mutation: none. Gate: none. Approval: none. Event/queue impact: none. Rollback: N/A. Readiness: HIGH.

1. Live substrate (verified)

• fn_iu_subtree (live; prior T03 PASS: depth 2, 8 descendants).
• iu_tree_path (199 rows, materialized ancestry), iu_relation (60 parent/child edges), iu_tree_change_log (56).
• Envelope axis-C cols: axis_c_parent_id, axis_c_depth, axis_c_ancestors (array), axis_c_ancestor_addresses (array).
• Views: v_iu_tree, v_iu_source_outline.

2. Root/parent choices

Pick roots with known subtree depth from the live corpus:

• Primary: the DIEU-37 cut root (17 IUs in a cut; tree relations present) — a real law-document tree.
• Secondary: a DIEU-35 root (36 pieces, T01 reconstruct PASS) for a deeper/wider tree.
• Degenerate: a leaf IU (expect 0 descendants) to test the empty-subtree boundary.

The harness resolves the root by canonical address → unit_id (no hardcoded uuids).

3. Subtree contract

filter_axis_c_subtree(
  p_root_unit_id   uuid = NULL,   -- one of root id / address required
  p_root_address   text = NULL,
  p_max_depth      int  = NULL,   -- NULL = unbounded
  p_include_self   bool = true
) RETURNS TABLE(unit_id uuid, canonical_address text, axis_c_depth int,
                axis_c_parent_id uuid, axis_c_ancestors uuid[], rel_path text)

Delegates to fn_iu_subtree; cross-checks against iu_tree_path (materialized) and iu_relation (edges). Order by axis_c_depth, axis_a_sort_order for stable, outline-shaped output.

4. Descendant expectations

For each chosen root, the harness pre-computes the expected descendant set three independent ways and requires all three to agree:

1. fn_iu_subtree(root) recursion;
2. iu_tree_path rows whose ancestor array contains root;
3. transitive closure over iu_relation edges.

5. Cycle / orphan checks

• Cycle: assert no unit appears in its own axis_c_ancestors; assert max realized depth is finite and matches iu_tree_path. Any cycle → FAIL (data-integrity alarm).
• Orphan: assert every non-root descendant has a resolvable axis_c_parent_id that is itself in the subtree or is the root. Dangling parent → orphan finding (ties to the "đẻ rơi"/orphan invariant, Điều 0-G/36).
• Drift: v_iu_three_axis_envelope_drift and fn_iu_three_axis_envelope_drift_check reconcile envelope axis-C against iu_tree_path.

6. Needed DOT wrapper

dot_iu_subtree (read-only) — wraps filter_axis_c_subtree, audit row mutating=false. Gap: absent from catalog (the catalog reorders/reparents pieces but offers no read-only subtree query command).

7. No-mutation proof

fn_iu_subtree/filter_axis_c_subtree are STABLE, SELECT-only. Harness BEGIN…ROLLBACK wrapper; assert 0 deltas on information_unit, iu_relation, iu_tree_path, iu_tree_change_log, event_outbox.

8. Assertions

1. Three-way agreement (recursion == tree_path == edge-closure) for each root.
2. Depth correctness: reported axis_c_depth equals BFS depth from root.
3. No cycle / no orphan (§5).
4. Empty-subtree boundary: leaf root returns only itself (or 0 with include_self=false).
5. Determinism: repeated calls byte-identical.
6. Zero mutation.

9. Evidence rows

dot_iu_command_run (mutating=false) + JSON {root_address, max_depth, descendant_count, three_way_agree:true, cycle_free:true, orphan_free:true, deltas_zero} per root.

10. Failure modes

Mode	Detection	Handling
tree_path stale vs edges	three-way disagreement	report drift; recommend gated refresh (separate op); FAIL test
Cycle in relations	assertion 3	FAIL hard; integrity incident
Orphan descendant	assertion 3	FAIL; orphan finding logged
Unresolvable root	resolution step	refuse with explicit error

11. Exact PASS criteria

PASS iff assertions 1–6 hold for all three chosen roots (primary, secondary, degenerate), DOT wrapper records mutating=false, deltas zero. Drift or cycle/orphan → PARTIAL/FAIL with documented finding.

12. Author-ready implementation note

Implement in the same macro as test b (IU_TEST_B_C_READONLY_HARNESS_IMPLEMENTATION_XHIGH). Reuse fn_iu_subtree; do not re-implement recursion. b + c together form the zero-risk read-only harness that produces the first evidence-backed PASS and establishes the harness pattern (audit row + JSON evidence + BEGIN/ROLLBACK delta proof) reused by f/d/e.