Rule builder: support nesting deeper than one level (#176 follow-up) #436

Closed
opened 2026-07-18 01:50:37 +02:00 by timothy · 3 comments
Owner

Follow-up to #176 (PR #433). The Kodi model ships one level of group nesting (covers type:movie AND (genre:Horror OR genre:Thriller)). If a real query needs deeper nesting, extend the model, compiler, parser (the allowNested cap in parse.ts), and the round-trip property test. YAGNI until then.

Done-when

  • adversarial review passed
  • deeper nesting round-trips; property test extended
Follow-up to #176 (PR #433). The Kodi model ships one level of group nesting (covers `type:movie AND (genre:Horror OR genre:Thriller)`). If a real query needs deeper nesting, extend the model, compiler, parser (the `allowNested` cap in `parse.ts`), and the round-trip property test. YAGNI until then. ## Done-when - [x] adversarial review passed - [x] deeper nesting round-trips; property test extended
timothy added the enhancementpriority: lowfrontend labels 2026-07-18 01:50:37 +02:00
Author
Owner

🔗 Session bundle — rule builder (#176 follow-ups): #434, #435, #436, #437, #438

All frontend RuleBuilder follow-ups deferred from #176: facet-value typeahead (#434), relative-date operators (#435), deeper nesting (#436), inline adoption in ChannelBuilder & Auto-Tune (#437), input validation & polish (#438). One SPA component, one session.

When you claim any member, check this cluster for co-workable siblings and sweep the disjoint set in one session (per docs/handoffs/chicorytv-issue-queue.md → bundles).

🔗 **Session bundle — rule builder (#176 follow-ups):** #434, #435, #436, #437, #438 All frontend RuleBuilder follow-ups deferred from #176: facet-value typeahead (#434), relative-date operators (#435), deeper nesting (#436), inline adoption in ChannelBuilder & Auto-Tune (#437), input validation & polish (#438). One SPA component, one session. When you claim any member, check this cluster for co-workable siblings and sweep the disjoint set in one session (per docs/handoffs/chicorytv-issue-queue.md → bundles).
timothy added the in-progress label 2026-07-25 10:50:57 +02:00
Author
Owner

Claiming — Claude Code session 2026-07-25, bundled with #440 (shared frontend label, disjoint slices).

Note on this issue's own YAGNI gate: the rule-builder cluster (#434/#435/#437/#438) has fully landed, and #437 put the RuleBuilder inline in Channel Builder, which broadens authoring exposure. Picking this up as the last open member of that cluster; confirmed with the operator before claiming.

Claiming — Claude Code session 2026-07-25, bundled with #440 (shared `frontend` label, disjoint slices). Note on this issue's own YAGNI gate: the rule-builder cluster (#434/#435/#437/#438) has fully landed, and #437 put the RuleBuilder inline in Channel Builder, which broadens authoring exposure. Picking this up as the last open member of that cluster; confirmed with the operator before claiming.
Author
Owner

Closing record

Outcome: Shipped via PR #584 (merged, 6cf99718). The rule builder now supports arbitrary-depth group nesting under a shared cap MAX_GROUP_DEPTH = 5, replacing the one-level "Kodi" model. Scope turned out smaller than the issue anticipated: compile.ts and validation.ts were already recursive and are untouched — the one-level restriction lived only in parse.ts's allowNested flag and the RuleBuilder.tsx "Add group" gate.

Root cause: n/a (feature, not a bug) — but see Reusable knowledge for a latent bug found en route.

Decisions/conventions changed: Added spa.rulebuilder-nesting (2026-07-25), superseding spa.smartcollection-rule-builder@2026-07-18. The predecessor was relocated verbatim, heading unchanged to the new docs/decisions/archive/spa.md with a reciprocal superseded-by.

Reusable knowledge:

  1. The old parser had a silent data-corruption path that this change fixes. parse.ts previously treated any part matching startsWith('(') && endsWith(')') as one wrapped group, so (genre:"a")(genre:"b") parsed into a garbage single-rule tree with value a")(genre:"b — a lossy accept that violates the exact-inverse invariant. Opening such a hand-typed saved query in the builder and re-saving would have silently corrupted it. isParenWrapped() (quote/escape-aware: the leading ( must be the one closed by the trailing )) returns null instead, falling back to raw-text editing. Differential fuzzing over 15,000 compiled old-model queries found 0 divergences otherwise, so this is a pure narrowing.
  2. A property-test generator can pass vacuously. A seeded generator that silently produces only shallow trees would satisfy a nesting round-trip test while testing nothing. The fix is an assertion that the generated corpus actually reached MAX_GROUP_DEPTH; review verified it by simulating regressions (generator capped at 1 → FAILS; capped at 4 → FAILS).
  3. The cap must be one const with three consumers. MAX_GROUP_DEPTH is read by the parser, the UI gate, and the property-test generator. A second hardcoded depth anywhere would let the builder author a tree its own parser rejects, stranding the user's query into raw-text mode on reload.

Verification: npm test 990/990, lint clean, npm run build ok, tsc --noEmit clean. Independent adversarial review (cold brief, different model family): 20,000 generated trees × 10 seeds at nesting probability 0.5 with the corpus verifiably reaching depth 5 → zero round-trip failures; differential old-vs-new fuzz over 15,000 queries → 0 divergences; cap boundaries confirmed empirically from both directions (5-deep round-trips, 6-deep → null → raw-text fallback, no crash or truncation). CI green on 6cf99718 (Build & push image correctly skipped — docs/SPA-only change, #416's docs-only detect).

Deferred: none.

Docs updated: docs/spa-conventions.md §12 (nesting model rewritten), docs/decisions.md (new record), docs/decisions/archive/spa.md (new file, predecessor relocated), docs/decisions/README.md (regenerated).

## Closing record **Outcome:** Shipped via PR #584 (merged, `6cf99718`). The rule builder now supports arbitrary-depth group nesting under a shared cap `MAX_GROUP_DEPTH = 5`, replacing the one-level "Kodi" model. Scope turned out smaller than the issue anticipated: `compile.ts` and `validation.ts` were **already** recursive and are untouched — the one-level restriction lived only in `parse.ts`'s `allowNested` flag and the `RuleBuilder.tsx` "Add group" gate. **Root cause:** n/a (feature, not a bug) — but see Reusable knowledge for a latent bug found en route. **Decisions/conventions changed:** Added `spa.rulebuilder-nesting` (2026-07-25), superseding `spa.smartcollection-rule-builder@2026-07-18`. The predecessor was relocated **verbatim, heading unchanged** to the new `docs/decisions/archive/spa.md` with a reciprocal `superseded-by`. **Reusable knowledge:** 1. **The old parser had a silent data-corruption path that this change fixes.** `parse.ts` previously treated any part matching `startsWith('(') && endsWith(')')` as one wrapped group, so `(genre:"a")(genre:"b")` parsed into a *garbage single-rule tree* with value `a")(genre:"b` — a lossy accept that violates the exact-inverse invariant. Opening such a hand-typed saved query in the builder and re-saving would have silently corrupted it. `isParenWrapped()` (quote/escape-aware: the leading `(` must be the one closed by the trailing `)`) returns `null` instead, falling back to raw-text editing. Differential fuzzing over 15,000 compiled old-model queries found **0 divergences** otherwise, so this is a pure narrowing. 2. **A property-test generator can pass vacuously.** A seeded generator that silently produces only shallow trees would satisfy a nesting round-trip test while testing nothing. The fix is an assertion that the generated corpus *actually reached* `MAX_GROUP_DEPTH`; review verified it by simulating regressions (generator capped at 1 → FAILS; capped at 4 → FAILS). 3. **The cap must be one const with three consumers.** `MAX_GROUP_DEPTH` is read by the parser, the UI gate, and the property-test generator. A second hardcoded depth anywhere would let the builder author a tree its own parser rejects, stranding the user's query into raw-text mode on reload. **Verification:** `npm test` 990/990, lint clean, `npm run build` ok, `tsc --noEmit` clean. Independent adversarial review (cold brief, different model family): 20,000 generated trees × 10 seeds at nesting probability 0.5 with the corpus verifiably reaching depth 5 → zero round-trip failures; differential old-vs-new fuzz over 15,000 queries → 0 divergences; cap boundaries confirmed empirically from both directions (5-deep round-trips, 6-deep → `null` → raw-text fallback, no crash or truncation). CI green on `6cf99718` (`Build & push image` correctly `skipped` — docs/SPA-only change, #416's docs-only detect). **Deferred:** none. **Docs updated:** `docs/spa-conventions.md` §12 (nesting model rewritten), `docs/decisions.md` (new record), `docs/decisions/archive/spa.md` (new file, predecessor relocated), `docs/decisions/README.md` (regenerated).
timothy removed the in-progress label 2026-07-25 11:49:22 +02:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: timothy/ersatztv#436