ecoportal-api-graphql 1.3.12 → 1.3.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74b442ca224440bee94f3f88522a4233b995d187db1b70ba31a0801e0691d3eb
-  data.tar.gz: 5d5d05fdf46fac5a32a12c5d4c8e47c21b913332bbe04c40a3ab81beeacbab9a
+  metadata.gz: fba9a366d06303f179c6b7d841930a66a29b6cc3fe836e06b218b95873bbe77e
+  data.tar.gz: 6114ba779317ec55b649e1f7df685c0140573cea073aa07c04b9e4cfa20b433a
 SHA512:
-  metadata.gz: 7d667e7ed09fc6ed6fd200695567eb25a8bb5f4f41b3b98882e04d84acd1775c1a17dc7d424e82f26b7f89d4f826bb46c25fddc0ef5fc526e8731aaccd73193b
-  data.tar.gz: 324b54e96de9f7ae82e71bf1b2c0427fa6fd4ed99d0153ec836a85cf68d76d5ce8f8462865b29cddd446015caa2b4a5fcaf940c5c2866970d7814a2d0495a73b
+  metadata.gz: d867c896796e9107870a2a49e3cdc75275b0a96559a9b8fe47fedea407ef639f7ff558ce22de798f79f3f011c7d4464a3eacd01a63e764778d2e0359cd8ed4ad
+  data.tar.gz: c29f555f19fc3d679f51cb512c417caca1e7e5f0006e9ac35a7ccf4d7f074095011ad4a59128a458b69c178dd538d79bf952d1b26b1557397e0d5fc4c41274d4

data/.ai-assistance/projects/compat-layer-audit/COMPAT_AUDIT.md

@@ -0,0 +1,244 @@
+# GraphQL COMPAT Layer Audit — contract fidelity vs ecoportal-api-v2
+
+> READ-ONLY audit. No code changed, no git touched. Date: 2026-07-08.
+> Scope: every place the GraphQL gem re-expresses a v2 public API, measured against the
+> v2 contract as source of truth. Consumers surveyed: `multi_org_api/*/config/ooze_cases`,
+> eco-helpers `usecases/graphql` + `OozeRedirect` + `ooze_samples`.
+
+---
+
+## 1. Executive verdict — AD-HOC PATCH, not a faithful mirror
+
+Oscar is **right**. The compat layer is a set of reactive, per-symptom patches, not a
+contract-faithful mirror of the v2 API. Concrete evidence:
+
+1. **Same method, three different return-type decisions, no shared contract.** `get_by_name`
+   is a COLLECTION in v2 for components, forces, and bindings, but a SINGLE for stages. The
+   gem got forces (`base/force/collection.rb:16` → `select`), bindings
+   (`base/force/binding_collection.rb:19` → `select`), and stages
+   (`compat/stage_collection.rb:34` → `find`, correct) right — but got **components wrong**
+   (`base/page/data_field/collection.rb:35` → `find`) and **sections' `get_by_heading` wrong**
+   (`base/page/section_collection.rb:31` → `find`, v2 is `select`). Three files, four
+   independent return-type choices. A faithful mirror would have one rule per v2 method; this
+   has ad-hoc choices that happen to match in some files and not others.
+
+2. **The downstream consumer already contains a workaround for the gem's wrong return type.**
+   eco-helpers `OozeRedirect#with_fields` wraps the component lookup:
+   `[collection.get_by_name(label)].compact` (`ooze_redirect.rb:187`) — i.e. it treats
+   `get_by_name` as returning a SINGLE and re-wraps it into an array to fake the v2 collection
+   contract. That is a patch compensating for a patch. When the gem is made faithful (returns a
+   collection), this line double-wraps → `[[Field]]`. Whack-a-mole in the flesh.
+
+3. **Two conflicting `#components` definitions on the same object.** `Concerns::PageCompat#components`
+   returns `dataFields || []` (`page_compat.rb:22`); `Concerns::DataFieldAccess#components`
+   returns `field_collection` (`data_field_access.rb:22`). Both are `include`d in
+   `Interface::BasePage` (`base_page.rb:6-7`), DataFieldAccess second so it wins — but the dead
+   PageCompat version returning a raw array is a fossil of an earlier, incompatible attempt.
+
+4. **Methods the v2 contract guarantees are simply absent** (not deliberately dropped —
+   nobody enumerated the contract): `DataField::Collection` has no `get_by_id`, no
+   `get_by_type` returning a `reference?`-style API, no `unattached`/`multi_section`;
+   `SectionCollection` has no `get_by_id`, no `ordered`-by-weight, no `between`. Consumers call
+   `components.get_by_id` and `sections.get_by_id` today (§3).
+
+5. **`components.add` has different semantics** — v2 `upsert!`s into the live collection so a
+   later `get_by_name` finds it; the gem stashes into a private `@additions` array
+   (`collection.rb:53-60`) that `each`/`get_by_name` never see.
+
+The through-line: each method was added when a specific script broke, choosing whatever return
+shape that one script needed — never derived from the v2 method's documented contract. That is
+the definition of ad-hoc.
+
+---
+
+## 2. Divergence catalog
+
+Severity: **S1** = silent wrong result / breaks live consumers; **S2** = raises / missing method;
+**S3** = latent (no current consumer but contract-divergent).
+
+| # | Method | v2 contract (file:line) | gem compat (file:line) | Divergence | Sev | Affected consumers |
+|---|--------|-------------------------|------------------------|------------|-----|--------------------|
+| C1 | `components.get_by_name(name, type:)` | `select` → **Array** (`v2/page/components.rb:37`) | `find` → **single DataField** (`base/page/data_field/collection.rb:35`) | Return type: collection vs single | **S1** | act-gov `.first`/`.last`, farmers `.first`, and ~120 `components.get_by_name(...).first` call-sites across multi_org_api (twg, tng, briscoes, alexander, argenta, whittlesea…); eco-helpers `ooze_redirect.rb:184,187` |
+| C2 | `sections.get_by_heading(h, mild:)` | `ordered.select` → **Array** (`v2/page/sections.rb:61`) | `find` → **single Section** (`base/page/section_collection.rb:31`) | Return type + drops `mild:` + no weight-ordering | **S1** | `tng_env_update_case.rb:19` (`.get_by_heading("Details").first`) |
+| C3 | `components.get_by_id(id)` | `find` → single (`v2/page/components.rb:21`) | **absent** on `DataField::Collection` | Missing method → `NoMethodError` | **S2** | `event_changes_case.rb:50` (`components.get_by_id(fld.reference_id)`); eco-helpers `ooze_update_case.rb:10` |
+| C4 | `sections.get_by_id(id)` | `find` → single (`v2/page/sections.rb:46`) | **absent** on `SectionCollection` | Missing method → `NoMethodError` | **S2** | `TnG_Active_sitefix_part2_case.rb:106` |
+| C5 | `components.add(...)` | `upsert!` into live collection; found by later `get_by_name`/`each` (`v2/page/components.rb:53`) | stashes in private `@additions`; NOT in `@fields`; later `get_by_name`/`each` miss it (`collection.rb:53-60`) | Mutation semantics diverge | S2 | any multi-step add-then-read script; `add` kwargs also differ (`id:` required, `doc:` shape) |
+| C6 | `sections.get_by_type(t)` | `ordered.select` → Array (`v2/page/sections.rb:53`) | `select` → Array but **not weight-ordered** (`section_collection.rb:25`) | Ordering: v2 orders by weight, gem uses response order | S3 | ordering-sensitive section scripts (latent) |
+| C7 | `components.get_by_type(t)` | `select` → Array, no ordering (`v2/page/components.rb:28`) | `select` → Array (`collection.rb:27`) | **Match** (return type) | ok | argenta `remove_edit_events_case.rb:21,29` (uses `.select` on result — works only because both are Arrays) |
+| C8 | `forces.get_by_name(name)` | `select` → Array (`v2/page/forces.rb:36`) | `select` → Array (`base/force/collection.rb:16`) | **Match** | ok | all `forces.get_by_name(...).first` sites |
+| C9 | `force.bindings.get_by_name(name, type:)` | `select` → Array (`v2/page/force/bindings.rb:102`) | `select` → Array but **drops `type:` kwarg** (`binding_collection.rb:19`) | Partial: arity narrower | S3 | bindings callers pass name only today; `type:` unused |
+| C10 | `stages.get_by_name(name)` | `find` → single (`v2/page/stages.rb:17`) | `find` → single (`compat/stage_collection.rb:34`) | **Match** | ok | eco-helpers `ooze_base_case.rb:109,144`, `register_export_case.rb:137` |
+| C11 | `stages[id_or_name]` | v2 CollectionModel `[]` by key (id) | id **or** name (`stage_collection.rb:27-30`) | Superset (name-fallback) — benign but non-contract | S3 | eco-helpers `stages[id] || stages.get_by_name` (belt-and-braces) |
+| C12 | `forces.get_by_id`, `.ordered`, `.bindings_by_reference` | present (`v2/page/forces.rb:29,64,20`) | **absent** on gem `Force::Collection` | Missing methods | S3 | not called by surveyed consumers (latent) |
+| C13 | `bindings.get_by_id / get_by_type / get_by_reference / reference? / by_name / by_reference` | present (`v2/page/force/bindings.rb:82,92,68,61,26,42`) | **absent** on gem `BindingCollection` | Missing methods | S3 | not called by surveyed consumers (latent) |
+| C14 | `sections.ordered` (by weight) | `sort_by weight` (`v2/page/sections.rb:86`) | returns `@sections` as-is (`section_collection.rb:41`) | Ordering not applied | S3 | latent |
+| C15 | `page.components` (page-level) | v2 components collection | **two conflicting defs**: PageCompat returns `dataFields`/`[]` array (`page_compat.rb:22`), DataFieldAccess returns `Collection` (`data_field_access.rb:22`); include order (`base_page.rb:6-7`) makes DataFieldAccess win, PageCompat one is dead code | Latent footgun / dead code | S2 | any refactor reordering includes silently swaps behaviour |
+| C16 | `entry.components.get_by_name(...).detect{…}` | Array#detect works on v2 collection | gem returns single → `.detect` = `Enumerable#detect` on a **DataField** (iterates its doc?) | Return-type breakage | **S1** | `risks_migration_case.rb:89` (`.get_by_name("Review frequency:").detect{…}`) |
+| C17 | `force.bindings.get_by_name(x).empty?` | Array#empty? | gem Array → ok (C8/C9 correct) | ok | tng `tng_env_update_case.rb:112` |
+
+### Folded-in prior findings (verified against current code)
+
+These are not `get_by_name`-style return-type bugs but are part of the same "compat built ad hoc"
+thread — the read/write CONVERTER contract was never systematically mirrored. Cross-referenced
+against `.ai-assistance/code/model_input_mapping/SYNTHESIS.md` (2026-07-07). **Note:** SYNTHESIS
+marks several as FIXED on `feature/model-input-fixes` (current branch); status below reflects that.
+
+| # | Prior finding | Current status (verified) | File:line |
+|---|---------------|---------------------------|-----------|
+| P1 | `passarray`/`embeds_many` don't diff via `as_update` (otherTags, locations, filterTags) | **FIXED** — `DIFF_CLASS = Diffable::LeafDiffService` now on `Interface::BasePage` | `interface/base_page.rb:13` |
+| P2 | `IdDiff` set-diff machinery non-functional (ContractorEntity/Action) | Reported FIXED via `id_diff_fields` macro (SYNTHESIS §3.2); **not re-verified in this pass** — flagged for confirm | — |
+| P3 | File/Image/Contractor readers use write-key → `[]` | Reported FIXED (SYNTHESIS §3.3); Image fragment `images[].id` was the blocker | `base/page/data_field/{file_field,image_gallery,contractor_entities}.rb` |
+| P4 | DataField read-key ≠ write-key (shape asymmetry) | Partly FIXED (CrossReference was template); File/Image/Contractor per P3 | `.ai-assistance/code/refactoring/datafield-readwrite-shape-asymmetry.md` |
+| P5 | `SnakeCamelAccess` is a one-way method_missing shim, no specs | **STILL TRUE** — `concerns/snake_camel_access.rb`; no spec file exists (`Glob spec/**/snake_camel*` → none). One-way (snake→camel only); silently no-ops single-word methods (`parts.length < 2` → returns as-is) | `concerns/snake_camel_access.rb:50-54` |
+
+---
+
+## 3. Comprehensive fix plan (contract-faithful) + spec risk
+
+The organising principle: **derive each collection method from the v2 method it mirrors, not from
+the one script that broke.** Recommend a small shared helper module so components/sections/forces/
+bindings collections share one contract per method name.
+
+### Fix C1 — `DataField::Collection#get_by_name` → collection (`select`)
+
+Faithful fix: return `pool.select { … }` (mirror `v2/page/components.rb:37`), keeping `type:`.
+
+**Risks these EXISTING gem specs (they assume single return):**
+- `spec/.../base/page/data_field_spec.rb:397-399` — `coll.get_by_name('name').id` → must become `.first.id`
+- `data_field_spec.rb:408` — `coll.get_by_name('Name').value = 'Bob'` → `.first.value =`
+- `data_field_spec.rb:419` — same
+- `data_field_spec.rb:463` — `field = coll.get_by_name('Name')` → `.first`
+- `base/page/phased/stage_spec.rb:72` — `stage.components.get_by_name('Description').value` → `.first.value`
+- `compat/stage_collection_spec.rb:92` — `stage.components.get_by_name('Description').value` → `.first.value`
+- `compat/stage_view_spec.rb:57` — `view.components.get_by_name('Summary').value` → `.first.value`
+- `input/page/update_spec.rb:136` — `page_with_fields.components.get_by_name('Note').value = 'New'` → `.first.value =`
+- `integration/toocs_submit_replay_spec.rb:38` — `page.components.get_by_name('Coding completed by:')` → `.first`
+
+These 9 spec sites LOCK IN the wrong behaviour and must be updated in lockstep with the fix
+(add `.first`). They also confirm the gem's own test suite was written to the ad-hoc behaviour,
+not the v2 contract.
+
+**Also requires a coordinated eco-helpers change:** `ooze_redirect.rb:184-187` — line 187
+`[collection.get_by_name(label)].compact` must become `collection.get_by_name(label)` (already an
+Array), and line 184-185 `field = collection.get_by_name(label); … [field] : []` must select over
+the collection. This is the cross-repo lockstep the audit brief warns about: a "just remove
+`.first`" workaround in org scripts is itself a dirty patch that re-breaks here.
+
+### Fix C2 — `SectionCollection#get_by_heading` → collection (`select`), add `mild:`, order by weight
+
+Faithful: `ordered.select { same_string?(s.heading, h, mild: mild) }`. Add a `same_string?`
+helper (case-insensitive; `mild:` = alnum-only compare per v2). Requires §Fix-C14 (`ordered` by
+weight) for exact parity.
+
+**Spec risk:** no existing gem spec asserts `get_by_heading` (Grep found none) → **no green
+specs go red.** Add new specs (§4). Consumer `tng_env_update_case.rb:19` already does `.first`, so
+it starts working correctly.
+
+### Fix C3 / C4 — add `get_by_id` to `DataField::Collection` and `SectionCollection`
+
+`find { |x| x.id == id }` (mirror v2). **No spec risk** (new methods). Add coverage.
+
+### Fix C5 — `components.add` upserts into the live collection
+
+Faithful: push the built field into `@fields` (or an upsert-by-id) so later `get_by_name`/`each`
+find it, and keep `dirty_additions` sourced from those. **Spec risk:** check `data_field_spec.rb`
+add-section (`:451-465`) — the deletion test reads `get_by_name('Name')` (existing field, fine);
+the add tests assert `dirty_additions` only, so upserting into `@fields` needs a guard that
+`dirty_inputs` (updates) does not double-count additions. Design the split carefully; lock with a
+"add then get_by_name finds it" spec.
+
+### Fix C6 / C14 — order `get_by_type`/`ordered` by weight in `SectionCollection`
+
+Only if sections carry a weight in the GraphQL doc (verify fragment exposes it; if not, response
+order is the only signal and this stays a documented gap). **No current spec risk.**
+
+### Fix C9 / C12 / C13 — fill missing force/binding contract methods + `type:` on bindings
+
+Add `get_by_id`, `get_by_type`, `get_by_reference`, `reference?`, `by_name`, `by_reference`,
+`ordered`, `bindings_by_reference`, and honour `type:` in `binding.get_by_name`. These are S3
+(no live consumer) — do them to make the mirror complete, not urgently. **No spec risk.**
+
+### Fix C15 — delete the dead `PageCompat#components`
+
+Remove `PageCompat#components` (`page_compat.rb:21-24`); it is shadowed and returns the wrong
+shape if include order ever changes. `page_compat_spec.rb:39-43` asserts `components` is a
+`DataField::Collection` — that stays green (DataFieldAccess provides it). **No spec risk.**
+
+### Fix P5 — add specs (and ideally make two-way) for `SnakeCamelAccess`
+
+At minimum add characterization specs. Consider reusing eco-helpers' polished hash-level
+snake/camel module rather than the bespoke `method_missing` shim (per memory
+`project_snake_camel_access`). Scope decision for Oscar.
+
+### Recommended structural change (kills the class of bug)
+
+Extract a shared `Concerns::V2CollectionContract` (or a `Base::Page::CollectionModel`) that
+defines `get_by_id` (single), `get_by_name`/`get_by_heading`/`get_by_type` (collection, per v2),
+`ordered`, `same_string?(mild:)` **once**, and have DataField/Section/Force/Binding collections
+include it. This turns "one return-type decision per file" into "one contract, four includes" —
+the actual remedy for the ad-hoc philosophy.
+
+---
+
+## 4. Test strategy
+
+### Gem rspec additions (lock the CONTRACT, not the current behaviour)
+- **Return-type contract specs**, one per collection, asserting `get_by_name`/`get_by_heading`
+  return `Array` (C1, C2) and `get_by_id` return a single (C3, C4). Assert `.first` on a
+  multi-match returns the first; assert empty match returns `[]` (not nil) for the collection
+  methods — this is the exact shape act-gov `.first`/`.last` and farmers `.first` depend on.
+- **Add-then-find spec** (C5): `coll.add(id:…){…}; expect(coll.get_by_name(label)).to include(the added)`.
+- **`mild:` parity spec** for `get_by_heading` (C2).
+- **Cross-object consistency meta-spec:** a single spec that asserts all four collections agree
+  on the return type of `get_by_name` (guards against future drift — the root cause here).
+- Update the 9 spec sites listed under Fix-C1 to `.first` in the SAME commit as the fix.
+- Add `SnakeCamelAccess` characterization spec (P5).
+
+### eco-helpers spec additions
+- Update `OozeRedirect#with_fields` (`ooze_redirect.rb:184-189`) and add a spec proving it
+  returns the same shape (Array) whether the field exists or not, against a faithful collection.
+- Regression spec replaying an act-gov-style `get_by_name(...).first` / `.last` through the
+  OozeRedirect path.
+
+### Integration coverage (parity harness, training mini-site)
+- On the all-21-fields template mini-org, run the A/B parity harness (memory
+  `project_parity_test_plan`): execute one representative ooze case using `.get_by_name(...).first`
+  and `.get_by_heading(...).first` against BOTH v2 and GraphQL, assert identical selected field
+  IDs and identical emitted mutation input. **Needs live creds** (mini-site API token) — the only
+  part of this plan that cannot run in CI without secrets.
+- Replay act-gov `20240130_act_disease_title_update_case.rb` (`.first`+`.last`) and the farmers
+  case in `-simulate` mode post-fix to confirm no `.first`-on-single or double-wrap breakage.
+
+---
+
+## 5. Open questions / could not verify
+
+1. **P2/P3 fix status not re-verified.** SYNTHESIS says the IdDiff macro and File/Image/Contractor
+   readers were fixed on this branch; I did not re-open those files this pass. Confirm before
+   relying on them.
+2. **Section weight in the GraphQL fragment.** C6/C14 (order-by-weight) only achievable if the
+   section fragment actually returns a `weight`/ordering field — not confirmed. If absent, response
+   order is the contract and these stay documented gaps.
+3. **`components.add` write path.** Whether an added field can even be created via the current
+   `dataFields.updates`/additions mutation shape without a server-side `buildFromTemplate` ID is a
+   separate question (the collection comment at `collection.rb:47` says it "must reference an
+   existing server-side ID"). Faithful `add` semantics may be bounded by the mutation API.
+4. **Full green-suite baseline.** I did not run `bundle exec rspec`; the 9 spec sites are
+   identified statically. Run the suite before/after to get exact red counts.
+5. **`get_by_type` ordering for components (C7).** v2 does not order components by weight either,
+   so gem matches — but confirm no consumer relies on component order.
+
+---
+
+## Appendix — files inspected
+
+v2 contract: `ecoportal-api-v2/lib/ecoportal/api/v2/page/{components,forces,sections,stages}.rb`,
+`.../page/force/bindings.rb`.
+Gem compat: `lib/.../base/page/data_field/collection.rb`, `.../base/page/section_collection.rb`,
+`.../base/force/{collection,binding_collection,force}.rb`,
+`.../compat/{pages,registers,stage_collection,stage_view}.rb`,
+`.../concerns/{page_compat,data_field_access,snake_camel_access,deprecation}.rb`,
+`.../interface/base_page.rb`.
+Consumers: `multi_org_api/*/config/ooze_cases/*` (grep, ~120 sites),
+`eco-helpers/lib/eco/api/usecases/graphql/compat/ooze_redirect.rb`, `.../ooze_samples/*`.
+Prior findings: `.ai-assistance/code/model_input_mapping/SYNTHESIS.md`.

data/.ai-assistance/projects/template-model-logic/CATEGORY_CATALOG.md

@@ -0,0 +1,236 @@
+# Category Catalog — Composite Question Archetypes (FIRST DRAFT)
+
+> Companion to `DESIGN_NOTE.md`. This is the **closed first set** of concrete "category"
+> archetypes for ecoPortal templates. A category is a reusable composite question pattern —
+> a **parametrizable macro** authored once that compiles down into flat `fields + forces`.
+> Authoring-first (per DESIGN_NOTE §5b): every archetype here is expressible via the
+> shipped `WorkflowCommandInput` command bus write path.
+
+---
+
+## How archetypes compile to `fields + forces`
+
+An archetype is a macro. Given its parameters (labels, options, which effect), it emits an
+**ordered batch of `WorkflowCommand` inputs** — the same batch `Builder::TemplateBuilder`
+already produces. The expansion has two halves:
+
+1. **Structure** → `addField` (per dependent field, with `fieldType`/`label`/`stageId`/`sectionId`/`column`),
+   `addSelectFieldOption` (per option), `addGaugeFieldStop` (per gauge band),
+   `addSection`/`addStageSection` (when the archetype owns a whole revealable section),
+   and follow-up `editFieldConfiguration` for `description` (the identity/CSV token),
+   `tooltip`, and per-type `byType` config. Field structure is placeholder-threaded
+   (`placeholderId`) so intra-batch references resolve before the server assigns real ids.
+2. **Flow** → one or more **forces** bound to the dependent fields. A force is an AngularJS/Lisp
+   snippet (`addForce {name, customScript}`) plus `addBinding {forceId, fieldId, name}` per field
+   it reads or writes. The force encodes the answer→effect mapping: `show`/`hide`/`disable`/`clear`,
+   `select`/`set`, `add-tag`/`remove-tag`, `accent` (color), and matrix lookups. In the
+   **EPTIR flat IR** target this same flow is modelled declaratively as a JSON-Logic `when`
+   condition + a closed effect (`show_field`/`hide_field`/`show_section`/`set_required`/`set_value`/
+   `add_tag`), which is then lowered to a force snippet at compile time.
+
+> **Hard constraint (VERIFIED, `workflow-command-guide.md` §"Schema realities", `add_field.rb`):**
+> `required` cannot be set through the command bus **anywhere** — not on `addField`, not on
+> `editFieldConfiguration` top-level, not on any `byType` sub-input. So any archetype effect that
+> "makes a field required" MUST be realised as **force-level conditional-required** (the force
+> refuses to let the stage submit / flags the field), NOT as a static template `required` flag.
+> Every `required_when_shown` below means *force-enforced*, not *template-attribute*.
+
+---
+
+## Summary table
+
+| # | Name | Parent question | Core effect | Grounding |
+|---|------|-----------------|-------------|-----------|
+| 1 | `conditional-detail-select` | Select (single) | reveal + require detail field on chosen answer(s) | **Well-grounded** (DESIGN_NOTE worked example; `numeric_behaviour_select`, `Bay_change_options`) |
+| 2 | `yes-no-with-evidence` | Select (Yes/No) or Checklist | reveal File/ImageGallery (+ note) on "Yes" | **Well-grounded** (File/Image field types heavily used; special case of #1) |
+| 3 | `checklist-with-followup` | Checklist (multi) | each unchecked/"No" item reveals its own follow-up field | **Plausible** (Checklist type real; per-item force wiring inferred) |
+| 4 | `multi-select-fanout` | Select (multiple) | each selected option enables/disables its own section | **Well-grounded** (`replace_risk` `update-unit` per-`category` section enable/disable) |
+| 5 | `risk-matrix` | 2× Select (likelihood, consequence) | compute rating via lookup table → Gauge + level Select + color + risk tags | **Well-grounded** (`replace_risk_case.rb` production force; `update_severity_force`) |
+| 6 | `select-drives-gauge` | Select (single) | map chosen option → numeric Gauge value + band color | **Well-grounded** (Gauge stops in TemplateBuilder; simpler slice of #5) |
+| 7 | `computed-number` | Number(s) / Select | compute a Number/Gauge from arithmetic over inputs | **Well-grounded** (`overall-risk-mitigation` = arithmetic diff of ratings in `replace_risk`) |
+| 8 | `person-plus-role` | People | reveal a role/detail field per attached person or role Select | **Plausible** (People field + config real; pairing force inferred) |
+| 9 | `cross-reference-with-detail` | CrossReference | on attach, reveal detail/linked fields; optionally pull linked values | **Well-grounded** (CrossReference 2nd most-used; `risk_mapping` attaches hazards/controls; `addLinkedFieldConfig`) |
+| 10 | `select-drives-tags` | Select / Checklist | chosen answer(s) add/remove page tags (register membership) | **Well-grounded** (`update_severity_force` NOTIFIABLE; `tag-on-level` in `replace_risk`; memory: register membership via tags) |
+| 11 | `signoff-block` | Signature (+ People + Date) | reveal/require signature block when a gate answer is set | **Plausible** (Signature field real; conditional-required is force-level, see constraint) |
+
+Grounding legend: **Well-grounded** = the field shapes AND the force/flow behaviour were seen in
+production ooze scripts or are directly emitted by `TemplateBuilder`. **Plausible** = field types
+are real and the pattern is idiomatic, but the exact force wiring was inferred, not observed.
+
+---
+
+## 1. `conditional-detail-select`
+
+| Aspect | Spec |
+|---|---|
+| **Intent / when to use** | The canonical "if you picked X, tell us more". A single-select gate whose non-default answer(s) reveal and (force-)require a detail field. The workhorse archetype. |
+| **Parent question type** | `Select` (single; `config.select.multiple = false`) |
+| **Dependent fields** | 1+ detail fields — typically `PlainText` (free text) or `RichText` (formatted), hidden by default. Role: capture the "more info". |
+| **Flow / force behaviour** | On chosen answer(s): `show(detail)` + (force-enforced) required. On other answers: `hide(detail)` + `clear(detail)`. Mirrors `replace_risk`'s `(do fld (hide) (clear))` idiom. |
+| **`when` (JSON-Logic)** | `{"in": [{"var": "parent.selected"}, ["Yes"]]}` → effects `[{show_field: detail}, {set_required: detail}]`; else `[{hide_field: detail}, {set_value: {field: detail, value: null}}]` |
+| **Parameters** | `parent_label`, `options[]`, `reveal_on[]` (subset of options), `detail_fields[] {label, type, required_when_shown}` |
+| **Compiles to** | `addField(Select)` + `addSelectFieldOption`×N + `editFieldConfiguration(select.multiple=false)`; `addField(PlainText/RichText)` per detail (hidden); one `addForce` + `addBinding` for parent and each detail. |
+| **Notes / open Qs** | Default hidden state: is "hidden until shown" a template attribute or purely force-driven? `editFieldConfiguration` has `hideView` (base key) — likely the static default; force flips it. Needs confirmation. |
+
+## 2. `yes-no-with-evidence`
+
+| Aspect | Spec |
+|---|---|
+| **Intent / when to use** | "Did X happen? If yes, attach proof." Compliance/audit checks that need a photo, file, or short note only on the affirmative branch. |
+| **Parent question type** | `Select` (Yes/No) or a single `Checklist` item |
+| **Dependent fields** | `File` and/or `ImageGallery` (evidence) + optional `PlainText` (note). Hidden by default. |
+| **Flow / force behaviour** | `answer == "Yes"` → `show(evidence)` + force-required (at least one attachment); `"No"` → `hide` + `clear`. |
+| **`when` (JSON-Logic)** | `{"==": [{"var": "parent.selected"}, "Yes"]}` → `[{show_field: evidence}, {set_required: evidence}]` |
+| **Parameters** | `parent_label`, `evidence_kind` (`file`\|`image`\|`both`), `note?` (bool), `required_when_shown` |
+| **Compiles to** | Select + 2 options; `addField(File)` / `addField(ImageGallery)` + optional `PlainText`; force with bindings. |
+| **Notes / open Qs** | Specialisation of #1 with fixed Yes/No parent and attachment detail. File/Image field read/write key asymmetry is a known gem bug (memory `model_input_converter_mapping`) but does not affect **template-build** authoring. |
+
+## 3. `checklist-with-followup`
+
+| Aspect | Spec |
+|---|---|
+| **Intent / when to use** | An inspection checklist where any item marked non-compliant ("No"/unchecked) must open a corrective-detail field for that item. |
+| **Parent question type** | `Checklist` (multi-item, each item = label + checked) |
+| **Dependent fields** | One follow-up field per item (usually `PlainText`), hidden until its item triggers. |
+| **Flow / force behaviour** | For each item: `item.checked == false` (or a "fail" state) → `show(followup_i)` + force-required; else `hide` + `clear`. Iterated in the force the way `replace_risk`'s `map` over unit lists does. |
+| **`when` (JSON-Logic)** | per item: `{"==": [{"var": "checklist.items.i.checked"}, false]}` → `[{show_field: followup_i}, {set_required: followup_i}]` |
+| **Parameters** | `checklist_label`, `items[] {label}`, `followup_type`, `fail_state` (`unchecked`\|`checked`) |
+| **Compiles to** | `addField(Checklist)` (items are the checklist's own config); N `addField(PlainText)`; one force binding all items + all follow-ups. |
+| **Notes / open Qs** | Checklist item ids are instance-assigned; force must bind by ref/label. Whether "N follow-ups + 1 force" or "N small forces" is cleaner is an open authoring choice. |
+
+## 4. `multi-select-fanout`
+
+| Aspect | Spec |
+|---|---|
+| **Intent / when to use** | A multi-select "which of these apply?" where **each** selected option turns on a dedicated section/field-group; unselected ones are disabled/cleared. |
+| **Parent question type** | `Select` (multiple; `config.select.multiple = true`) or `Checklist` |
+| **Dependent fields** | One **section** (or field cluster) per option — e.g. the `replace_risk` per-`category` units (`equ`, `haz`, `cvp`, `env`, `peo`), each with its own like/consequence/gauge/rating fields. |
+| **Flow / force behaviour** | Directly from `replace_risk`'s `update-unit`: `(active (=sel category kind))` → if active, evaluate/show the section; if not, `(map-1 disable isec rsec)` + `(map-1 clear ...)`. |
+| **`when` (JSON-Logic)** | per option: `{"in": ["equ", {"var": "parent.selected"}]}` → `[{show_section: sec_equ}]`; else `[{hide_section: sec_equ}, {set_value: {field: sec_equ.*, value: null}}]` |
+| **Parameters** | `parent_label`, `options[]`, `section_template` (fields each option's section contains), `multiple: true` |
+| **Compiles to** | Select(multiple) + options; per option a `addSection`+`addStageSection`+ its `addField`s; one force reading the parent and binding every fanned-out section. |
+| **Notes / open Qs** | This is the compositional heart of the risk template — #5 is usually **nested inside** each fanned-out section. Section-level show/hide is the effect that most needs adding to EPTIR's grammar (DESIGN_NOTE §5a). |
+
+## 5. `risk-matrix`
+
+| Aspect | Spec |
+|---|---|
+| **Intent / when to use** | Classic likelihood × consequence risk rating. Two selects feed a lookup matrix that computes a rating, maps it to a level + color, and tags the page by severity. The single richest observed archetype. |
+| **Parent question type** | Two `Select` fields — `likelihood` and `consequence` (each single-select, ordered options 0..N). |
+| **Dependent fields** | `Gauge` (rating value + colored bands), a level `Select` (Low/Med/High/Very — auto-selected, locked), optional hidden `Number` rating field. |
+| **Flow / force behaviour** | Straight from `replace_risk_case.rb`: `(risk-rating con lik)` indexes a hard-coded matrix; `(risk-level rating)` buckets it; `set-risk` does `(do gau (lock) (set n))`, `(do lev (lock) (clear) (select level) (set-color level))`; `tag-on-level` adds `INHERENT HIGH`/`RESIDUAL HIGH` tags. |
+| **`when` (JSON-Logic)** | Not a boolean gate — a **computed** effect: `{set_value: {field: gauge, value: {"matrix_lookup": [{"var": "likelihood.weight"}, {"var": "consequence.weight"}, <matrix>]}}}` + threshold→level + threshold→tag rules. |
+| **Parameters** | `likelihood_options[]`, `consequence_options[]`, `matrix[][]` (rating table), `level_bands[] {min, label, color, tag?}`, `gauge_max` |
+| **Compiles to** | 2× Select+options; `addField(Gauge)` + `addGaugeFieldStop` per band (threshold+color); level Select+options; `editFieldConfiguration(gauge.max)`; one force encoding the matrix + level LUT + tag rules, bound to all fields. |
+| **Notes / open Qs** | Real forces support **inherent vs residual** pairs and `min-rating-difference` "uncontrolled risk" logic (`uncontrolled` fn) — a richer parametrization than a single matrix. Draft models one matrix; flag the inherent/residual variant as a parameter to add. Matrix values are the archetype's key parameter. |
+
+## 6. `select-drives-gauge`
+
+| Aspect | Spec |
+|---|---|
+| **Intent / when to use** | A single categorical answer maps to a numeric score shown on a colored gauge (severity score, maturity level). The 1-dimensional slice of #5. |
+| **Parent question type** | `Select` (single) with weighted options. |
+| **Dependent fields** | `Gauge` (score + bands). |
+| **Flow / force behaviour** | `set(gauge, selected_option.weight)` + gauge stops color it; lock the gauge. Same `(do gau (lock) (set n))` idiom. |
+| **`when` (JSON-Logic)** | `{set_value: {field: gauge, value: {"var": "parent.selected.weight"}}}` |
+| **Parameters** | `parent_label`, `options[] {label, weight}`, `gauge_max`, `bands[] {threshold, color}` |
+| **Compiles to** | Select + weighted options (`addSelectFieldOption {label, weight}`); `addField(Gauge)` + `addGaugeFieldStop`s + `editFieldConfiguration(gauge.max)`; force binding select→gauge. |
+| **Notes / open Qs** | Option `weight` is a real `addSelectFieldOption` key — the natural carrier of the numeric mapping, so the force may just read the weight. Confirm gauge can be force-`set` from weight without an explicit LUT. |
+
+## 7. `computed-number`
+
+| Aspect | Spec |
+|---|---|
+| **Intent / when to use** | A read-only field whose value is arithmetic over other fields (totals, differences, days-between, cost = qty × rate). |
+| **Parent question type** | None (no gate) — inputs are Number/Date/Select fields; the archetype is the **output** + its formula. |
+| **Dependent fields** | Output `Number` or `Gauge` (locked, hidden-from-edit). |
+| **Flow / force behaviour** | Force computes and `set`s the output, then `(lock)`. Grounded in `replace_risk`'s `overall-risk-mitigation` = `(- max-irating max-rrating)` written via `(do overall-risk-mitigation (lock) (set maxs-difference))`. |
+| **`when` (JSON-Logic)** | `{set_value: {field: out, value: {"-": [{"var": "a"}, {"var": "b"}]}}}` (or `*`, `+`, date-diff op) |
+| **Parameters** | `inputs[]` (field refs), `formula` (arithmetic expr), `output_type` (`number`\|`gauge`) |
+| **Compiles to** | `addField(Number/Gauge)` (output); force reads inputs, computes, sets+locks output. |
+| **Notes / open Qs** | Formula grammar needs bounding (arithmetic + date-diff only?). Overlaps #5 — a risk matrix is a specialised computed value; keep separate because #7 is gate-free and formula-driven. |
+
+## 8. `person-plus-role`
+
+| Aspect | Spec |
+|---|---|
+| **Intent / when to use** | "Who was involved, and in what capacity" — a People field paired with a role/relationship qualifier per person (witness/injured/first-aider). |
+| **Parent question type** | `People` (single or multi) |
+| **Dependent fields** | A role `Select` (or `PlainText`) capturing the capacity; optionally revealed only once a person is attached. |
+| **Flow / force behaviour** | `people.count > 0` → `show(role)`; optional force-required. |
+| **`when` (JSON-Logic)** | `{">": [{"var": "people.count"}, 0]}` → `[{show_field: role}, {set_required: role}]` |
+| **Parameters** | `people_label`, `singular` (bool), `role_options[]` (or free text), `person_schema_id?` |
+| **Compiles to** | `addField(People)` + `editFieldConfiguration(people.singular/personSchemaId)`; role Select/PlainText; force binding people→role. |
+| **Notes / open Qs** | **Plausible, not observed** — People fields are heavily used (40 hits) but a per-person role force wasn't seen. Per-person (vs per-field) role capture may need a repeating/table structure rather than a single Select; flag for design. |
+
+## 9. `cross-reference-with-detail`
+
+| Aspect | Spec |
+|---|---|
+| **Intent / when to use** | Attach related records from another register (hazards, controls, assets, permits) and reveal/pull detail once attached. The register-linking backbone. |
+| **Parent question type** | `CrossReference` (to a target register) |
+| **Dependent fields** | Detail fields shown on attach; and/or **linked fields** that mirror values from the referenced page (`addLinkedFieldConfig`). |
+| **Flow / force behaviour** | On attach → `show(detail)`; linked fields auto-populate from the source via linked-field config (not a force). `risk_mapping_case.rb` attaches "Associated hazard" + "Attach controls" cross-refs by id. |
+| **`when` (JSON-Logic)** | `{">": [{"var": "xref.count"}, 0]}` → `[{show_field: detail}]`; linked-field pull is config, not `when`. |
+| **Parameters** | `xref_label`, `register_id`, `single_select_mode`, `display_fields[]`, `linked_fields[] {source_field_key}`, `detail_fields[]` |
+| **Compiles to** | `addField(CrossReference)` + `editFieldConfiguration(crossReference {registerId, singleSelectMode, displayFields, hideCreate, hideAttach})`; `addLinkedFieldConfig {sourceFieldKey, crossReferenceId}` per linked field; optional detail fields + force. |
+| **Notes / open Qs** | Two distinct mechanisms here: **linked fields** (declarative config, pull values) vs **forces** (reveal detail). CrossReference is the 2nd most-used type (66 hits) so this archetype is high-value. Register membership interplay via tags overlaps #10. |
+
+## 10. `select-drives-tags`
+
+| Aspect | Spec |
+|---|---|
+| **Intent / when to use** | Answering a question changes the page's **tags**, which drives register membership, visibility, and policy routing (notifiable events, high-risk escalation, moving a record between registers). |
+| **Parent question type** | `Select` (single/multi) or `Checklist` |
+| **Dependent fields** | None structural — the effect is on page tags. May pair with a hidden marker. |
+| **Flow / force behaviour** | Chosen answer → `add-tag`/`remove-tag`. Directly from `update_severity_force` (severity → `NOTIFIABLE`) and `replace_risk`'s `tag-on-level` (`(tag-off ...) (tag-on tag)`). |
+| **`when` (JSON-Logic)** | `{"in": [{"var": "severity.selected"}, ["major", "critical"]]}` → `[{add_tag: "NOTIFIABLE"}]`; else `[{remove_tag: "NOTIFIABLE"}]` |
+| **Parameters** | `parent_label`, `option_to_tags` (map answer → tag set), `mutually_exclusive` (bool — clear siblings first) |
+| **Compiles to** | Select/Checklist + options; force reads answer, adds/removes tags. No new fields. |
+| **Notes / open Qs** | `add_tag`/`remove_tag` ARE in EPTIR's existing closed effect set (DESIGN_NOTE §5a) — this archetype compiles cleanly **today**, unlike the show/hide ones. Tag→register-membership is a platform rule (memory `register_membership_via_tags`), so this archetype has real downstream reach. |
+
+## 11. `signoff-block`
+
+| Aspect | Spec |
+|---|---|
+| **Intent / when to use** | A review/approval gate: capture signature + approver + date, revealed/required once the record reaches an approvable state. |
+| **Parent question type** | `Signature` (with companion `People` approver + `Date`) — often gated by a prior Select ("Ready for sign-off?"). |
+| **Dependent fields** | `Signature`, `People` (approver), `Date` (signed-on). |
+| **Flow / force behaviour** | Gate answer set → `show`/force-require the block; before that, hidden. Note the platform also has native stage sign-off (`editRequiredSignOffs`) — the archetype is the **in-form** variant. |
+| **`when` (JSON-Logic)** | `{"==": [{"var": "gate.selected"}, "Ready"]}` → `[{show_field: signature}, {set_required: signature}, {show_field: approver}, {show_field: date}]` |
+| **Parameters** | `gate_label?`, `require_approver` (bool), `require_date` (bool) |
+| **Compiles to** | Optional gate Select; `addField(Signature)` + `addField(People)` + `addField(Date)`; force binding gate→block. |
+| **Notes / open Qs** | **Plausible, not observed** in ooze scripts. Overlaps with native stage sign-off (`editRequiredSignOffs`, `editRequiredSignOffs` command) and workflow task sign-off — decide whether "sign-off" belongs at the **field/force** layer or the **stage/task** layer. Likely the latter for true approvals; keep this archetype for lightweight in-form acknowledgement. |
+
+---
+
+## Cross-cutting notes
+
+- **`required` is force-only.** Repeated because it shapes every reveal archetype: the template
+  cannot carry a `required` flag through the command bus, so "required when shown" is always the
+  force refusing submission / flagging the field. If the future Workflow Builder conditional-field
+  feature (in development, `10_forces_workflow_builder.md`) lands a native conditional-required,
+  these archetypes should retarget it and drop the hand-authored force.
+- **Effect grammar gap.** Of the effects these archetypes need — `show_field`, `hide_field`,
+  `show_section`, `hide_section`, `set_required`, `set_value`, `add_tag`, `remove_tag` — only
+  `set_value`/`add_tag`/`remove_tag` are in EPTIR's current closed set. #1–#9 and #11 depend on
+  adding the show/hide/require effects (DESIGN_NOTE §5a). #10 compiles today.
+- **Reverse-classification is blocked.** Clustering the ~300 existing templates back into these
+  archetypes needs reading forces off a page, which is the one blocked path
+  (`Query::PageWithForces`, DESIGN_NOTE §6). This catalog is therefore an **authoring-first**
+  taxonomy; treat archetype detection from existing forces as future work.
+- **Section vs field ownership.** #4 (fanout) and #11 (block) reveal whole **sections**;
+  #1/#2/#3/#8 reveal individual **fields**. The macro needs to know which it owns so it can emit
+  `addSection`/`addStageSection` vs plain `addField` and bind the force at the right granularity.
+
+## Patterns seen repeatedly in real ooze scripts
+
+- **Weighted single-selects feeding computed risk** is the dominant real pattern (`replace_risk`,
+  `update_severity_force`): likelihood/consequence selects → matrix → gauge + level + color + tags.
+- **`(do <field> (lock) (clear) (select ...) / (set ...) (deindex-empty) (hide))`** is the universal
+  force idiom for computed/reveal fields — lock, clear, write, (optionally) hide, and drop empties
+  from the index. Every archetype's expansion should assume outputs are locked.
+- **Tags as the escalation/routing mechanism** (`NOTIFIABLE`, `INHERENT HIGH`) appears in both
+  incident and risk templates — #10 is genuinely load-bearing, not decorative.
+- **Cross-reference attach + per-answer section enable/disable** (`risk_mapping`, `replace_risk`
+  per-`category` units) confirms #4 and #9 as real composite shapes, not just single fields.