[00123] Implement the Rusty Filter Query Grammar Parser and AST Crate

[rorychatt]

rusty-filter, a new workspace member: a hand-written lexer and
recursive-descent parser for the Filters.g4 filter-query grammar, its AST, a
type-aware validator, an evaluator, and a canonical printer. Wired into
DataTable, the query cache and the prelude, and documented.

5972 insertions across 20 files, 6 commits, 208 new tests. Every CI gate exit 0.

Commits

SHA	What
786324d	the crate: lexer, parser, AST, validator, evaluator, printer
7149f0e	differential and round-trip tests
fda2fdb	wiring into DataTable, the query cache and the prelude; docs
93a4611	merge main — #[derive(Widget)] migration, rusty-desktop
a332547	merge main — rusty-ivyml, plus main's repairs to two inherited gates
64f4189	merge main — the last two inherited failures fixed upstream

What was built

rusty-filter (~5200 lines including tests)

Module	Lines	Role
parser.rs	1617	recursive descent with ANTLR-compatible error recovery
eval.rs	846	row evaluation for all five column types
lexer.rs	792	tokenizer: bracketed column refs, string/number/date/bool literals, symbolic and word operators, the multi-word spellings
validate.rs	603	operator/type compatibility, unknown columns, literal parsing
print.rs	526	canonical query strings and cache keys
ast.rs	304	FilterGroup/Filter/Condition with wire-compatible serde
column.rs	166	ColumnDef, ColumnType, name normalization
lib.rs	92	the public surface

The AST serializes to the same JSON the browser's editor produces, down to key
presence: skip_serializing_if = "Option::is_none" keeps negate absent on
comparisons and false on text ops, because that is what the reference does.
JavaScript's single number type is reproduced too (007 → 7, 1.000 → 1).

Wiring

• DataTable::apply_filter(query) → Result<Self, Vec<ParseError>>, and
  filter_columns(), which excludes non-filterable and hidden columns.
• From<ColType> for ColumnType — eight cell types onto the validator's five,
  matching the normalization the browser applies to backend type names.
• QueryCache::filtered_key(base, filter) — appends the canonical filter so
  equivalent spellings share one cache entry and different filters do not.
• The prelude re-exports 19 items plus the crate itself.

Docs

02_concepts/07_filters.md (new, 179 lines): the grammar, an operator-spellings
table, per-type compatibility, literals, precedence, evaluation, cache keys,
frontend compatibility, and a "Not implemented" list. Plus a "Server-side
filtering" section on the DataTable page and a "Filters" section in the prelude
reference. Both code samples were compiled and run before committing, via
throwaway examples that were then deleted.

Verification — all Pass

Name	Result
RustBuild	Pass — exit 0, seven members
RustTest	Pass — 734 passed, 0 failed
RustClippy	Pass — exit 0
RustFmt	Pass — exit 0
CheckResult	Pass — eleven CI steps, all exit 0
RustyFrontendLint / Build / Test	Skipped — no file under src/frontend/ changed

Including the steps outside the four named gates: test inventory ("intact: 533 at
1d58a57, 741 in the working tree"), both shell harnesses ("ALL 13 CASES PASS",
"ALL 6 CASES PASS"), the e2e job's harness-parse and widget_harness build, and
the desktop-shell job's two steps. Details in Verification/.

What the plan got wrong

Two of the plan's stated expectations were falsified by probing the reference
bundle (filter-query-editor 2.2.0, imported from src/frontend/node_modules by
absolute file:/// URL). The tests assert measured behaviour instead,
documented at each assertion:

1. §4: an empty Or group evaluates false. It returns true. The crate
   matches the bundle.
2. §7: a print/parse round trip preserves the AST for every valid query. It
   holds for 39 of 47. The other 8 are negated leaves — printing lifts the
   negation onto a NOT (...) group, so re-parsing attaches it to a wrapper. The
   bundle was probed at each of the 8 and reshapes identically.
   round_trip.rs pins them in NOT_AST_STABLE and fails if a ninth joins them
   or a listed one starts passing. Evaluation equivalence over a 7-row corpus
   is asserted separately for all 47, so a reshaped round trip is proved to still
   mean the same thing.

Three grammar quirks the plan did not mention were measured rather than guessed:
bare equal is rejected although not equal is accepted; the or equal tail is
singular, so greater than or equals fails; and an unknown string escape keeps
its backslash. The last took two attempts — a bash heredoc silently collapsed the
backslashes in the first probe, which lied, and the wrong answer had already been
drafted into a doc page before the corrected probe caught it.

Merging against a moving target

origin/main moved three times during execution — df4e685 → e6c4398 →
9b7c764 → 1d58a57, bringing a #[derive(Widget)] migration and two entirely
new crates (rusty-desktop, rusty-ivyml). Each move was merged and every gate
re-run.

It also repaired every failure this plan had documented as inherited: two
widget_names test failures (9fb4213), two rusty-macros clippy errors
(5d81694), a rusty-macros rustfmt failure (67e4cd8), the types.rs:77
clippy error, and the pre-commit harness's three failures. Each had been proved
inherited at the time against a pristine origin/main probe extracted with git archive under its own CARGO_TARGET_DIR. Deferring them rather than repairing
them was the right call — one of the fixes was 253 lines of parser work this plan
would have duplicated.

Left for others

Artifacts/recommendations.md has three items, all follow-on work rather than
defects: wiring the rendered filter box to the parser (High), apply_filter's
consuming signature (Small), and an explicit decision on the negated-leaf
round-trip reshape (Small).

---

Commits

786324d [00123] Add rusty-filter: lexer, parser, AST, validator, evaluator, printer
7149f0e [00123] Add differential and round-trip tests for rusty-filter
fda2fdb [00123] Wire rusty-filter into DataTable and query cache; add docs
93a4611 [00123] Merge main (df4e685)
a332547 [00123] Merge main (9b7c764)
64f4189 [00123] Merge main (1d58a57)

---

Created using Ivy Tendril.