# LibTmux::Query::Plan

- **Module:** LibTmux
- **Package:** LibTmux
- **Language:** Raku
- **Kind:** module
- **Source:** https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/lib/LibTmux/Query/Plan.rakumod#L3
- **Page:** https://libtmux.org/en/raku/latest/reference/libtmux-query-plan/

# Planning an explicit read

` Plan.compile($filter, :$capabilities) ` performs no I/O. ` auto ` uses proven
scalar restrictions; ` never ` leaves filtering local; ` require ` throws unless
the complete predicate has an exact source implementation. The capability
value must come from the daemon incarnation that will execute the read.

For ` acquisition-mode ` ` listing `, pass ` projection ` and ` candidate-command `
together to the guarded reader. The command does not include ` -F `: the reader
adds the projection's template. Normalize physical entity IDs or session/index
link keys according to ` identity-normalization `, then apply ` matches ` to every
candidate. It always evaluates the original validated filter, including when
` fully-pushed ` is true.

For ` full-graph `, acquire one complete snapshot and apply ` matches ` to its
root entities. Do not execute the candidate command. ` source-filter ` is empty;
` acquisition-reason ` explains why an otherwise eligible scalar restriction is
deferred. ` required-relations ` retains each relationship path. Filtering child
rows first would change ` every ` and ` none `, and intersecting a separately
acquired candidate set with a later graph can lose matches during mutation.



# Inspecting source work

` steps ` exposes the translation tree, paths, exactness, expressions and refusal
reasons. Eligible conjuncts can restrict candidates while text remains local.
An AND restriction follows the captured evaluator order and stops at the first
residual subtree, retaining that subtree's own safe prefix if present. It never
moves a later restriction ahead of local work that may throw. Use an explicit
AND array when the ordering of residual evaluation matters; hash iteration is
not an ordering contract.
An OR or NOT subtree is emitted only when the complete subtree is exact.
Text and relationship predicates remain local. Empty Boolean and membership
nodes retain the same identities as the local query evaluator.

ID matching uses tmux string equality. Flags use exact zero/one equality.
Numeric comparisons use arithmetic FORMAT expressions, never lexical ordering.
The catalogue records source-proven UInt32 dimension and nonnegative Int32
window-index domains. Only integer operands within the exact IEEE-754 integer
range are eligible. Bounded operands alone cannot establish source equivalence:
the observed field's complete domain must also fit the arithmetic conversion.
Fractional operands, nullable fields and unqualified numeric fields stay local.

Boolean expressions are balanced and bounded by bytes and nesting depth. An
oversized expression remains local under ` auto ` and is refused by ` require `.
The guarded reader still enforces its own complete command/output/time limits.

## Members

### Other members

- [`Plan`](/en/raku/latest/reference/libtmux-query-plan-plan/) (class): Pure, inspectable source restrictions plus the original local filter.