Query.Plan

Description#

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.