feat(436): arbitrary-depth rule-builder group nesting #584

Merged
timothy merged 1 commits from feat/436-deeper-nesting into main 2026-07-25 11:47:15 +02:00
Owner

fixes #436

Generalizes the rule builder from the one-level "Kodi" nesting model to arbitrary depth under a shared cap MAX_GROUP_DEPTH = 5.

What changed

The restriction turned out to live in only two places, not four — compile.ts and validation.ts were already recursive and are untouched:

  • types.ts — Group was already structurally recursive; added the exported cap MAX_GROUP_DEPTH = 5.
  • parse.ts — the allowNested: boolean cap becomes a depth counter recursing to the cap. Deeper input stays out of subset ⇒ null (raw-text fallback), so parse remains the exact inverse of compile and the accepted grammar is not widened.
  • RuleBuilder.tsx — "Add group" gate depth === 0 → depth < MAX_GROUP_DEPTH; added box-sizing: border-box on the group box (no global reset per spa-conventions §1, so each level's 12px padding would otherwise overflow the dialog at depth).
  • Tests — property-test generator nests to the cap and asserts the corpus actually reached it (a silently-shallow generator would otherwise pass vacuously); explicit depth-3 cases across compile/parse/validation/RuleBuilder.

The cap is a policy choice, not a technical limit, and is a single exported const read by all three consumers (parser, UI gate, property-test generator) — no second hardcoded depth.

Latent bug fixed along the way

parse.ts gained isParenWrapped(), replacing a naive startsWith('(') && endsWith(')'). The old check lossily accepted adjacent groups: (genre:"a")(genre:"b") parsed into a garbage single-rule tree with value a")(genre:"b, violating the exact-inverse invariant — opening such a saved query in the builder and re-saving would silently corrupt it. The new code correctly returns null (raw-text fallback). This is a narrowing, not a widening.

Verification

  • npm test 990/990 · npm run lint clean · npm run build ok · tsc --noEmit clean
  • Independent adversarial review (cold brief, different model): 20,000 generated trees × 10 seeds at nesting probability 0.5 with corpus verifiably reaching depth 5 → zero round-trip failures; differential old-vs-new fuzz over 15,000 compiled old-model queries → 0 divergences; simulated generator regressions (capped at 1 and at 4) correctly fail the depth-coverage guard.
  • Cap boundaries confirmed empirically from both directions: 5-deep wrap round-trips, 6-deep wrap → null, degrading to raw-text mode rather than crashing or truncating.

Docs (same PR)

  • docs/spa-conventions.md §12 — nesting model rewritten.
  • docs/decisions.md — new active record spa.rulebuilder-nesting, superseding spa.smartcollection-rule-builder@2026-07-18.
  • docs/decisions/archive/spa.md (new) — predecessor relocated verbatim, heading unchanged, reciprocal superseded-by. decisions_validate.py → OK.
fixes #436 Generalizes the rule builder from the one-level "Kodi" nesting model to arbitrary depth under a shared cap `MAX_GROUP_DEPTH = 5`. ## What changed The restriction turned out to live in only two places, not four — `compile.ts` and `validation.ts` were **already** recursive and are untouched: - `types.ts` — `Group` was already structurally recursive; added the exported cap `MAX_GROUP_DEPTH = 5`. - `parse.ts` — the `allowNested: boolean` cap becomes a `depth` counter recursing to the cap. Deeper input stays **out of subset ⇒ `null`** (raw-text fallback), so `parse` remains the exact inverse of `compile` and the accepted grammar is not widened. - `RuleBuilder.tsx` — "Add group" gate `depth === 0` → `depth < MAX_GROUP_DEPTH`; added `box-sizing: border-box` on the group box (no global reset per spa-conventions §1, so each level's 12px padding would otherwise overflow the dialog at depth). - Tests — property-test generator nests to the cap **and asserts the corpus actually reached it** (a silently-shallow generator would otherwise pass vacuously); explicit depth-3 cases across compile/parse/validation/RuleBuilder. The cap is a policy choice, not a technical limit, and is a single exported const read by all three consumers (parser, UI gate, property-test generator) — no second hardcoded depth. ## Latent bug fixed along the way `parse.ts` gained `isParenWrapped()`, replacing a naive `startsWith('(') && endsWith(')')`. The old check **lossily accepted** adjacent groups: `(genre:"a")(genre:"b")` parsed into a garbage single-rule tree with value `a")(genre:"b`, violating the exact-inverse invariant — opening such a saved query in the builder and re-saving would silently corrupt it. The new code correctly returns `null` (raw-text fallback). This is a narrowing, not a widening. ## Verification - `npm test` 990/990 · `npm run lint` clean · `npm run build` ok · `tsc --noEmit` clean - Independent adversarial review (cold brief, different model): 20,000 generated trees × 10 seeds at nesting probability 0.5 with corpus verifiably reaching depth 5 → zero round-trip failures; differential old-vs-new fuzz over 15,000 compiled old-model queries → **0 divergences**; simulated generator regressions (capped at 1 and at 4) correctly **fail** the depth-coverage guard. - Cap boundaries confirmed empirically from both directions: 5-deep wrap round-trips, 6-deep wrap → `null`, degrading to raw-text mode rather than crashing or truncating. ## Docs (same PR) - `docs/spa-conventions.md` §12 — nesting model rewritten. - `docs/decisions.md` — new active record `spa.rulebuilder-nesting`, superseding `spa.smartcollection-rule-builder@2026-07-18`. - `docs/decisions/archive/spa.md` (new) — predecessor relocated verbatim, heading unchanged, reciprocal `superseded-by`. `decisions_validate.py` → OK.
timothy added 1 commit 2026-07-25 11:11:28 +02:00
feat(436): arbitrary-depth rule-builder group nesting
Build ErsatzTV Image / API docs in sync (OpenAPI + endpoint index) (pull_request) Successful in 13s
Build ErsatzTV Image / Formatting (changed .cs conform to .editorconfig) (pull_request) Successful in 34s
PR Gates / Docs update reminder (pull_request) Successful in 38s
PR Gates / CI image pin matches docker/ci (pull_request) Successful in 42s
PR Gates / decisions lifecycle (pull_request) Successful in 1m1s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 17m3s
Build ErsatzTV Image / Functional E2E (curl contracts) (pull_request) Successful in 17m14s
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 22m32s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Has been skipped
6cf99718ee
The rule builder's Group nesting was capped at one level (#176's Kodi
model). Generalize it to recursive nesting bounded by a single shared
constant, MAX_GROUP_DEPTH (types.ts, = 5, root group is depth 0):

- parse.ts: replace the allowNested boolean with a depth counter that
  recurses to the cap; deeper input stays out of subset (null -> raw-text
  fallback), so parse remains the exact inverse of compile. Sub-group
  detection now requires the leading '(' to be the one closed by the
  trailing ')' (quote/escape aware), so '(a)x(b)' can't be mistaken for
  one wrapped group.
- RuleBuilder.tsx: 'Add group' is offered while depth < MAX_GROUP_DEPTH
  instead of only at the root; nested group boxes get box-sizing:
  border-box so per-level padding can't overflow (no global reset).
- roundtrip.test.ts: the 500-tree generator nests to the cap and asserts
  the corpus actually reached it; explicit depth-3 cases added to
  compile/parse/validation tests and a depth-gate test to RuleBuilder.

compile.ts and validation.ts already recursed correctly and are unchanged.
No backend/OpenAPI change.

Docs: spa-conventions.md §12; decisions lifecycle — new active record
spa.rulebuilder-nesting, predecessor spa.smartcollection-rule-builder
relocated to docs/decisions/archive/spa.md as superseded.

fixes #436
Author
Owner

Independent adversarial review — cold review-only brief, different model family from the implementer, read-only (no fix authority).

Probes run, all reproduced rather than reasoned:

  • Round-trip exactness depth 0..5: 20,000 generated builder-valid trees × 10 seeds at nesting probability 0.5 (vs the test's 0.35), corpus verifiably reaching depth 5 → zero failures, including values containing " \ ( ) * ? : and spaces.
  • Depth-coverage guard is real: replicated the generator/seed and simulated regressions — cap-5 passes, silently-capped-at-1 FAILS, capped-at-4 FAILS. A shallow generator cannot pass vacuously.
  • isParenWrapped attack corpus: escaped quotes, value ending in backslash, unbalanced parens inside quotes, dangling trailing backslash (the i++ escape-skip past end-of-string terminates with depth≠0 → false; no crash, no false accept), (), (()), "(", adjacent-group variants — every accept round-trips, every reject correct.
  • Not a widening: splitTopLevel and parseAtom byte-identical to main. Differential fuzz over 15,000 compiled old-model queries → 0 divergences, plus a hand-written saved-query corpus (negations, ranges, wildcards, escapes, relative dates) → identical.
  • Cap boundaries agree exactly; 5-deep round-trips, 6-deep → null → raw-text fallback at SmartCollectionDialog.tsx:43. No second hardcoded depth.
  • Decisions lifecycle: validator OK; archive heading byte-identical to origin/main; reciprocal pointers match; no residual one-level description in §12.
  • 104/104 builder tests, tsc --noEmit clean.

Finding in the change's favor: the OLD parser lossily accepted adjacent groups — (genre:"a")(genre:"b") parsed to a garbage single-rule tree with value a")(genre:"b, violating the exact-inverse invariant. Re-saving such a query in the builder would have silently corrupted it. The new code returns null. Narrowing, not widening.

No blocking or nit-level defects found.

Review-verdict: MERGEABLE @ 6cf99718ee

Independent adversarial review — cold review-only brief, different model family from the implementer, read-only (no fix authority). Probes run, all reproduced rather than reasoned: - Round-trip exactness depth 0..5: 20,000 generated builder-valid trees × 10 seeds at nesting probability 0.5 (vs the test's 0.35), corpus verifiably reaching depth 5 → zero failures, including values containing `" \ ( ) * ? :` and spaces. - Depth-coverage guard is real: replicated the generator/seed and simulated regressions — cap-5 passes, silently-capped-at-1 FAILS, capped-at-4 FAILS. A shallow generator cannot pass vacuously. - `isParenWrapped` attack corpus: escaped quotes, value ending in backslash, unbalanced parens inside quotes, dangling trailing backslash (the `i++` escape-skip past end-of-string terminates with depth≠0 → false; no crash, no false accept), `()`, `(())`, `"("`, adjacent-group variants — every accept round-trips, every reject correct. - Not a widening: `splitTopLevel` and `parseAtom` byte-identical to main. Differential fuzz over 15,000 compiled old-model queries → 0 divergences, plus a hand-written saved-query corpus (negations, ranges, wildcards, escapes, relative dates) → identical. - Cap boundaries agree exactly; 5-deep round-trips, 6-deep → null → raw-text fallback at SmartCollectionDialog.tsx:43. No second hardcoded depth. - Decisions lifecycle: validator OK; archive heading byte-identical to origin/main; reciprocal pointers match; no residual one-level description in §12. - 104/104 builder tests, `tsc --noEmit` clean. Finding in the change's favor: the OLD parser lossily accepted adjacent groups — `(genre:"a")(genre:"b")` parsed to a garbage single-rule tree with value `a")(genre:"b`, violating the exact-inverse invariant. Re-saving such a query in the builder would have silently corrupted it. The new code returns null. Narrowing, not widening. No blocking or nit-level defects found. Review-verdict: MERGEABLE @ 6cf99718eec1e9781c6b916c438456e2fdf31f78
timothy merged commit fa789bc06f into main 2026-07-25 11:47:15 +02:00
timothy deleted branch feat/436-deeper-nesting 2026-07-25 11:47:16 +02:00
Sign in to join this conversation.