Module hierarchy 

Parent-child containment model and goal progress computation.

This module provides higher-level query functions that operate on the SQLite projection database to answer hierarchy questions:

• Which items are children of a given goal?
• What is a goal’s progress (done/total direct children)?
• What is a goal’s recursive progress (rolling up through nested goals)?
• Is a reparenting operation valid?
• What is the full subtree of a given item?
• What are the ancestors of a given item?

Terminology

• Parent: An item whose parent_id is null (root) or set to another item.
• Goal: An item with kind = 'goal'. Only goals may have children (reparenting to a non-goal is rejected).
• Progress: The ratio of done (or archived) children to total non-deleted children. Nested goals contribute their own progress recursively.

Cycle prevention

validate_reparent checks that the proposed new parent is not a descendant of the item being moved, preventing reference cycles.

Error handling

All functions return HierarchyError, which distinguishes between domain errors (wrong kind, cycle detected, item not found) and database errors.

Structs

GoalProgress

Progress of a goal: how many children are done vs total.

Enums

HierarchyError

Errors that can occur in hierarchy operations.

Functions

compute_direct_progress

Compute the direct progress of a goal: counts its immediate children.

compute_nested_progress

Compute the nested progress of a goal, rolling up through the entire subtree.

get_ancestors

Get the ancestor chain of an item, from immediate parent up to root.

get_subtree_ids

Get all item IDs in the subtree rooted at root_id, including root_id itself.

validate_reparent

Validate that reparenting item_id under new_parent_id is allowed.