feat!: json-rules 3.4 — gate against the narrowed lens, read each scope's visit (0.30.0)

[agreenspan]

Adapts rules-builder to json-rules 3.4.0 (inixiative/json-rules#26): relations are fields, off until the first narrowing turns them on; context removed.

Do not merge until json-rules 3.4.0 is on npm. Developed and checked against the PR build (bun run check green: typecheck, examples typecheck, lint, 413 tests, against json-rules PR head fe33dee). package.json declares ^3.4.0 but bun.lock still resolves 3.3.1 — after the train publishes 3.4.0, run bun install and commit the lockfile, then CI can go green.

Why 0.29 breaks on 3.4

• It gated, coerced and described every rule against projectLens(…, { by: 'model' }). That surface is a bare lens, which turns no relation on, so every relation rule was invalid, coercion skipped relation paths, and describe() errored.
• Element scopes re-anchored a bare createLens at the related model, which dropped nested relations. Presets that went through a relation failed validation.

What changed

• resolve(source) returns a LensView: lens is the narrowed lens, used as the gate. Fetched sourceValues ride the visit at their own path: the picker offers them there, and a leaf's valid holds its value to them. The gate takes no per-path fetched set, so another path to the same model keeps its declared values. visit(at) gives the fields the lens shows at each dotted path, resolved on demand by json-rules lensVisit (nothing enumerated).
• Every scope (root, element scopes, branch groups, decoration facets) reads the visit at its own path. Leaf and array valid, coerceRule, describeRule and preset validation all run against the narrowed lens, in situ.
  • A relation is offered only where the lens turns it on.
  • A model outside json-rules' model-default tree (a second reach of a model) is not offered unless spelled.
• validateDecoration(view, …) validates presets in situ:
  • A models[…] list is checked at every element scope the lens reaches through a list relation.
  • A model that is never an element scope is reported.
• RuleBuilderSource.narrowing may be a list of layers, outermost first.
• withAllRelations(source) turns every relation on in the source's first layer.
• rawView(source) is the raw record that permissions and transitions gate: the view of withAllRelations over the record (model defaults grow json-rules' tree; the anchor's own relations are spelled, so self-relations are on).
• lensValuePicker / lensScopeSurface now start at { at }. Loop portals carry their own at.
• Fields whose map entry declares options keep their labels and groups. (The path projection rebuilds them from the allowed values alone, which drops both.)
• Example app:
  • authors against the ref's layered source;
  • vip-active and a new with-orders narrowing turn relations on;
  • grant editors turn every relation on in their menu.

Breaking API

• buildRoot(cond, view, …).
• Decoration functions take a ViewAt scope where they took a Lens; validateDecoration and useFacetFields take the view.
• buildActionRoot({ view }).
• useRuleBuilder returns lens (the narrowed lens) and view.
• lensValuePicker and lensScopeSurface take at in place of mapName/model.
• describeScopeFields sits beside describeModelFields.

Downstream: template, Kingdom and Tribe useEmailVariableScope call lensScopeSurface(resolve(source)) and re-anchor with { mapName, model }. They need lensScopeSurface(composeNarrowed(source), { at: frame.loop.at }) when they adopt 0.30.

Tests

New test/relations.test.tsx covers these cases. A narrowed lens with relations on lets the builder offer a relation rule, validate it (including two levels deep and a dotted to-one path), and coerce and describe it. Presets through a relation work, including per-model presets checked in situ. A relation that is off is not offered, and a saved rule that crosses it is invalid. The edge-once rule holds. test/resolve.test.ts covers the view, layered narrowings, withAllRelations and rawView against the json-rules gate. Existing fixtures were moved to sources that turn relations on.

An adversarial review found three gate problems, all fixed in 5b8a365: a per-model fold of fetched values onto the maps, a stale model-repeat cut in the pickers, and dotted list fields built without their subtree.

Updated to the final 3.4 in 11f1e10: views read lensVisit (no duplicated policy logic, no eager projection); model defaults grow a tree; the declared-options patch is dropped because projectLens now keeps them.

🤖 Generated with Claude Code