docs: BACKLOG + ARCH-BINDINGS appendix + RFC v1.2 for registry alignment (WS-6)

Two new BACKLOG entries capture the deliberate v1 deferrals:

  - ARTIST-ADV-BINDING-MODEL — design how artist_advance form data
    relates to Artist + AdvanceSection entities (when, if ever, an
    Eloquent Artist class is needed, and whether bindings are even
    the right abstraction for OUTPUT-shaped advance forms).

  - FORM-BINDING-JSON-PATH — extend binding registry to support
    JSON-path attributes (custom_fields.dietary_preferences etc).
    For v1 the recommendation is TAG_PICKER + tag_categories config.

ARCH-BINDINGS.md gets an appendix explaining the v1 scope decisions
explicitly: why 'artist' has no registry entries (model class
absent + advance forms are OUTPUT-shaped, not provisioning-shaped),
why JSON-path attributes are out of scope (v1 is column-level only),
and how BindingTypeRegistryConsistencyTest prevents future drift.

RFC-WS-6.md → v1.2 with a §3 Q9 addendum tracking the registry
alignment + the 3 renames, 5 removals, and 1 new column landed in
this branch.

Refs: WS-6 sessie 3a binding-target drift audit, sessie 3a.5 cleanup

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-04-28 20:32:35 +02:00
parent d48d91bba7
commit 8a4682ab35
3 changed files with 137 additions and 2 deletions

View File

@@ -4,6 +4,7 @@
- v0.1 (skeleton) — 2026-04-25
- v0.4 — 2026-04-28 — § 8.2 IDOR class tests (sessie 3a backend hardening)
- v0.5 — 2026-04-28 — Appendix on v1 registry scope (sessie 3a.5 model alignment)
- Owner: Bert
- Authoritative for the binding pipeline architecture, complementing
ARCH-FORM-BUILDER.md §17 and §31.
@@ -594,6 +595,57 @@ might never persist on rollback — fixed in WS-6.
- **Daily failure digest mailable** — depends on notification framework
- **Wall-clock concurrent load testing** — BACKLOG: `LOAD-TEST-FOUNDATION`
## Appendix — v1 binding registry scope
The `App\FormBuilder\Bindings\BindingTypeRegistry` covers the four
binding-target entities active in WS-6 v1: `person`, `company`,
`user`, and an intentionally-empty `artist` (omitted from registry).
### Why `artist` has no registry entries in v1
The `artists` table exists (since 2026-04-08) and `subject_type='artist'`
is a valid `form_submissions` value. But:
1. No Eloquent `Artist` model class exists yet. Polymorphic subject
relations work via the morph map (string → table) but cannot be
Eloquent-loaded without a class.
2. The `artist_advance` purpose is OUTPUT-shaped: the advance form
**gathers** information FROM the artist (rider, hospitality,
technical needs) — it does not provision Artist attributes the way
`event_registration` provisions Person attributes.
3. Bindings as a concept may not be the correct abstraction for advance
forms. v2 work tracked via BACKLOG `ARTIST-ADV-BINDING-MODEL`.
In v1: `artist_advance` schemas may exist with `required_bindings: []`.
PublishGuards enforce only the cross-cutting invariants (no identity
key conflicts, no append-on-scalar, etc). The applicator runs (per
RFC §3 Q4 two-transaction pattern) but resolves bindings to an empty
list, completing in COMPLETED state with zero applications. The
Person/Company/User-level effects of WS-6 (apply_status, action_failures,
retry/dismiss workflows) all apply uniformly.
### Why JSON-path attributes are not in v1
`persons.custom_fields` is a JSON column; semantically a Person can
have `dietary_preferences` (etc.) inside that column. But binding
targets in v1 are **column-level** scalars, lists, and relations —
not JSON-path. Adding JSON-path support is tracked via BACKLOG
`FORM-BINDING-JSON-PATH`.
For v1 the recommendation: model `dietary_preferences` (and similar
`custom_fields` properties) as a `TAG_PICKER` form_field with a
`tag_categories` config. The TAG_PICKER → user_organisation_tags sync
(per ARCH-FORM-BUILDER §31.10) handles this without requiring
binding-target column mapping.
### Drift prevention
`BindingTypeRegistryConsistencyTest::test_every_registry_entity_maps_to_an_eloquent_model_with_the_attribute`
asserts that every registry entry corresponds to a real Eloquent model
class plus a real column on that model's table. Future drift (renamed
column without registry update, or registry entry without column)
becomes a test failure, not a runtime surprise.
## 11. Related docs
- `RFC-WS-6.md` — design decisions