Module path 

Logical-path construction and decomposition.

Binoc logical paths use two separators with distinct meaning (see the parsed-children ADR, docs/adr/2026-06-14-parsed_children_and_decompose_boundaries.md):

• MEMBER_SEP (/) — membership: structure that already existed as a navigable tree (directory entries, paths inside an extracted archive). No format had to be decoded to reveal it.
• DECOMPOSE_SEP (/>) — decompose boundary: a node binoc had to open a format to reveal (the immediate members of an archive expansion, and every parsed table / sheet / section).

Segment names beginning with > are escaped as \> so an ordinary member named >q1.csv is written dir/\>q1.csv, not dir/>q1.csv.

The separators are cosmetic: nothing in the engine decides behavior by parsing a path string. Parent/child relationships come from the IR tree, and child kind rides on ItemRef.projection_hint.item_type. These helpers exist so that the few places that do need to construct or walk a path (expansion, container parsers, projection nesting) share one implementation instead of hand-rolling format!/split calls.

Constants

DECOMPOSE_SEP

Marker introducing a decompose-boundary child (a node revealed by opening a format). Two characters: a slash followed by >.

MEMBER_SEP

Separator between members of an already-navigable container.

Functions

decompose_child

Append name as a decompose-boundary child of parent (the /> separator).

escape_segment

Escape a logical path segment for inclusion after either separator.

file_name

The final segment of a logical path, after the last separator of either kind.

member_child

Append name as an ordinary member of parent (the / separator).

segments

Walk path, yielding (cumulative_path, segment_name) for each segment in order. The cumulative path preserves the original separators, so it matches node paths constructed with member_child/decompose_child and can be used directly as a projection node key.