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.
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.
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
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.
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 main2026-07-25 11:47:15 +02:00
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
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.tsandvalidation.tswere already recursive and are untouched:types.ts—Groupwas already structurally recursive; added the exported capMAX_GROUP_DEPTH = 5.parse.ts— theallowNested: booleancap becomes adepthcounter recursing to the cap. Deeper input stays out of subset ⇒null(raw-text fallback), soparseremains the exact inverse ofcompileand the accepted grammar is not widened.RuleBuilder.tsx— "Add group" gatedepth === 0→depth < MAX_GROUP_DEPTH; addedbox-sizing: border-boxon the group box (no global reset per spa-conventions §1, so each level's 12px padding would otherwise overflow the dialog at depth).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.tsgainedisParenWrapped(), replacing a naivestartsWith('(') && endsWith(')'). The old check lossily accepted adjacent groups:(genre:"a")(genre:"b")parsed into a garbage single-rule tree with valuea")(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 returnsnull(raw-text fallback). This is a narrowing, not a widening.Verification
npm test990/990 ·npm run lintclean ·npm run buildok ·tsc --noEmitcleannull, 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 recordspa.rulebuilder-nesting, supersedingspa.smartcollection-rule-builder@2026-07-18.docs/decisions/archive/spa.md(new) — predecessor relocated verbatim, heading unchanged, reciprocalsuperseded-by.decisions_validate.py→ OK.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:
" \ ( ) * ? :and spaces.isParenWrappedattack corpus: escaped quotes, value ending in backslash, unbalanced parens inside quotes, dangling trailing backslash (thei++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.splitTopLevelandparseAtombyte-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.tsc --noEmitclean.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 valuea")(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