ecoportal-api-graphql 1.3.13 → 1.3.16

data/.ai-assistance/code/diff_as_input.md

@@ -1,234 +0,0 @@
-# Code Spec: `as_update` / `as_input` Pipeline
-
-**Scope:** `Common::GraphQL::Model::Diffable`, `Common::GraphQL::Model::AsInput`,
-`DiffService`, `ClassicDiffService`, `HashDiffNesting`
-**Last updated:** 2026-06-05
-
----
-
-## What This Pipeline Does
-
-Models that include `AsInput` (via `Model < DoubleModel`) can:
-1. **Diff themselves** against their original document via `#as_update` → returns a Hash
-   of only the changed properties.
-2. **Convert that diff** to mutation input via `#as_input` → returns a Hash ready to be
-   passed as the `input:` variable to a GraphQL mutation.
-
----
-
-## Class Hierarchy
-
-```
-Common::GraphQL::Model < Common::Content::DoubleModel
-  includes Diffable         → provides #as_update, #dirty?
-  includes AsInput          → provides #as_input, .as_input(hash)
-
-Diffable::DiffService < ClassicDiffService
-  includes HashDiffNesting  → change_diff, patch_update, patch_new, patch_delete, ...
-  includes HashHelpers
-
-Diffable::ClassicDiffService
-  includes HashDiffNesting
-  provides #diff, #classic_diff, #curr_doc, #prev_doc
-```
-
----
-
-## Current Output Format of `DiffService#diff` — KNOWN ISSUE
-
-**`#as_update` calls `DiffService#diff` which calls `classic_diff(flat: true)`, which calls
-`change_diff(curr_doc, prev_doc)`.**
-
-`change_diff` routes through `patch_update` for any Hash that has an `:id` key, producing:
-
-```ruby
-{
-  id:            "abc123",
-  api_operation: :update,
-  change_data:   { name: "New Name", status: "active" }
-}
-```
-
-**This is WRONG for GraphQL mutations.** The GraphQL mutation input should be flat:
-
-```ruby
-{ id: "abc123", name: "New Name", status: "active" }
-```
-
-**Why it's wrong:** GraphQL mutation inputs (`UpdateActionInput`, `UpdatePageInput`, etc.)
-do not have `api_operation` or `change_data` fields — they expect changed properties directly
-at the top level alongside `id`.
-
-**Root cause:** `HashDiffNesting` was ported from `ecoportal-api-v2`'s `HashDiffPatch`.
-The v2 gem uses JSON Patch semantics (`api_operation`, `change_data`). GraphQL mutations
-do not — they use direct property assignment.
-
-**Decision (2026-06-04):** GraphQL `as_update` must produce changed-props-only output with
-no patch-operation wrapper. See `DECISIONS.md` ("as_update diff: changed props only").
-
-**Fix required (TODO 4.2/4.3):** Either:
-- Override `classic_diff` in `DiffService` to call `change_data(curr, prev)` directly
-  (returns just the changed fields, no wrapper), and re-add `id` separately; or
-- Have `AsInput#as_input` detect and unwrap the patch-op structure before building input.
-The preferred approach per the DECISIONS is to fix `DiffService` itself.
-
-### Nested objects
-
-`diff_reduce` cascades through nested model objects (those that respond to `#as_update`)
-and replaces the nested path in the result with each nested model's own `as_update` output.
-These nested diffs also currently produce `api_operation`/`change_data` wrappers if the
-nested object has an `id`.
-
-For GraphQL, nested arrays of objects with IDs (e.g. `locations`, `associatedPeople`)
-are expressed differently per mutation — sometimes as `[ID]` arrays, sometimes as
-`IdDiffInput` (add/remove deltas), sometimes as full nested input objects. The `InputClass`
-(per the `from_model` pattern, TODO 4.3) is responsible for reshaping nested diffs into
-the correct format for each mutation.
-
----
-
-## `AsInput` Current Behavior
-
-### Instance method `#as_input(clientMutationId: '')`
-
-1. Calls `as_update` → gets the diff hash (currently with patch-op wrapper, see above).
-2. Calls `self.class.as_input(diff, clientMutationId: ...)`.
-
-### Class method `.as_input(hash, clientMutationId: '')`
-
-1. Deep-converts hash keys to symbols.
-2. Merges `clientMutationId:`.
-3. Calls `remove_nil_keys_deep(hash, target: :id)` — removes nil-valued `:id` keys
-   (keeps `id:` only when it has a value; removes nil ids from nested objects so they
-   don't confuse the server).
-
-**Current output (wrong):**
-```ruby
-{
-  id:            "abc123",
-  api_operation: :update,
-  change_data:   { name: "New Name" },
-  clientMutationId: ""
-}
-```
-
-**Desired output (target):**
-```ruby
-{ id: "abc123", name: "New Name", clientMutationId: "" }
-```
-
----
-
-## `patch_ver` — Concurrency Control
-
-**Schema:** `patchVer: Int!` (non-null) on `BasePageInterface`. Present on all Page types.
-`BasePage` in the gem maps it as `passthrough :patchVer`.
-
-**How it works:**
-- Every Page response includes `patchVer` (an incrementing Integer).
-- On `UpdatePage` mutation, the caller may pass `patchVer:` (optional).
-- The server checks that the submitted `patchVer` matches the current value; if not,
-  the update is rejected (optimistic locking / last-write-wins prevention).
-
-**Current gap (TODO 4.2):** `AsInput#as_input` does not inject `patchVer` into the
-output. The subject model (`BasePage` subclass) holds `patchVer` via `passthrough :patchVer`
-but it is never extracted and included in the mutation input hash.
-
-**Fix required:** In `AsInput#as_input` (instance method), read `self.patchVer` if the
-model responds to it, and include it in the input hash at the top level:
-
-```ruby
-def as_input(clientMutationId: '')
-  diff = as_update  # TODO: once fixed, returns flat changed props
-  diff[:patchVer] = patchVer if respond_to?(:patchVer) && !patchVer.nil?
-  self.class.as_input(diff, clientMutationId: clientMutationId)
-end
-```
-
----
-
-## `from_model` Pattern (TODO 4.3)
-
-**Decision (2026-06-04):** Conversion from model diff to mutation-specific input shape is
-owned by the `Input` class, not the model. Each mutation's input class implements
-`InputClass.from_model(model)`.
-
-**Why:** The model (`BasePage`, `Base::Action`, etc.) should not know which mutation it
-feeds. The input class knows its own schema shape (field names, nested structure, ID vs
-IdDiff arrays, etc.).
-
-**Pattern:**
-```ruby
-class Input::Action::Update < Logic::Input
-  def self.from_model(action_model)
-    diff = action_model.as_update  # after fixing: flat {name:, status:, ...}
-    new(
-      id:         action_model.id,
-      patchVer:   action_model.patchVer,  # if applicable
-      **map_fields(diff)
-    )
-  end
-
-  private_class_method def self.map_fields(diff)
-    # rename, reshape, filter fields as needed for this specific mutation input
-    diff.slice(:name, :description, :status, :dueDate, :assignedPersonMemberIds, ...)
-  end
-end
-```
-
-**The `as_input` instance method becomes a convenience delegator:**
-```ruby
-def as_input(target_class: default_input_class, **kargs)
-  target_class.from_model(self, **kargs)
-end
-```
-
----
-
-## `root?` Objects in the Diff
-
-Models marked `root!` (via `Ecoportal::API::Common::GraphQL::ClassHelpers`) are excluded
-from cascaded diffs. These are typically "lookup" objects that are referenced but not
-owned — e.g. `Base::Organization` (root!), `Base::Action` (root!). Their nested presence
-in a model's JSON will not generate diff entries.
-
-This is correct behaviour: you don't diff a referenced Organization when updating a Page;
-you only diff properties the Page itself owns.
-
----
-
-## Key Files
-
-| File | Role |
-|------|------|
-| `lib/.../model.rb` | `Model < DoubleModel`, includes `Diffable` and `AsInput` |
-| `lib/.../model/diffable.rb` | `#as_update`, `#dirty?`, `DIFF_CLASS` |
-| `lib/.../model/diffable/diff_service.rb` | Main diff logic, `#diff`, `#diff_reduce` |
-| `lib/.../model/diffable/classic_diff_service.rb` | Base: `#curr_doc`, `#prev_doc`, `change_diff` dispatch |
-| `lib/.../model/diffable/hash_diff_nesting.rb` | `change_diff`, `patch_update/new/delete`, array diffing |
-| `lib/.../model/as_input.rb` | `#as_input`, `.as_input(hash)` class method |
-| `lib/.../interface/base_page.rb` | `passthrough :patchVer` — Page models carry this |
-
----
-
-## Backend Reference (ecoPortal_master)
-
-- `app/graphql/types/pages/interfaces/base_page_interface.rb` — `patchVer: Int!` (non-null)
-- `app/graphql/mutations/pages/update.rb` — `argument :patch_ver, Integer, required: false`
-- `app/graphql/types/fill_in_page/inputs/page_input.rb` — Page update input fields:
-  `locations`, `other_tags`, `time_zone`, `state`, `task_priority`, `name`, `external_id`
-- `app/graphql/types/fill_in_page/inputs/data_field_input.rb` — DataField inputs (complex)
-
-**UpdatePage mutation shape:**
-```graphql
-mutation UpdatePage($id: ID!, $patch_ver: Int, $page: PageInput, $data_fields: [DataFieldInput], ...) {
-  updatePage(id: $id, patchVer: $patch_ver, page: $page, dataFields: $data_fields, ...) {
-    item { ...BasePageInterface }
-    errors { ... }
-  }
-}
-```
-
-Note: `id`, `patchVer`, and `page` (the input object) are separate top-level arguments —
-not nested under a single `input:` object like Action mutations. This is a structural
-difference that the `from_model` pattern must account for per mutation type.

data/.ai-assistance/code/diff_pairing_engine.md

@@ -1,243 +0,0 @@
-# Diff — Command Synthesis, Deploy & Pairing Engine
-
-**Area:** `lib/ecoportal/api/graphql/diff/` · **Status:** built (gem branch
-`feature/template-diff-deploy-pairing`) · **Domain reference (read first):**
-`template_diff_pairing_domain.md`.
-
-This doc covers the diff → command → deploy pipeline and the cross-object pairing engine + learning
-ledger. `VersionDiff`/`Change` (the self-version structural diff) are covered inline in their files.
-
----
-
-## 1. The pipeline
-
-```
-pair (id | genome | type+label | ledger)          Diff::Pairing::Engine (+ Ledger)
-     └─► diff on paired model                       Diff::VersionDiff  → [Change]
-             └─► delta as WorkflowCommands           Diff::CommandSynthesizer (+ IdResolver)
-                     └─► apply (gated on unsupported) Diff::Deploy#execute!
-```
-
-Self-version (same object, retained ids) needs NO pairing — `VersionDiff` matches by id and the
-synthesiser replays as-is. Cross-object (UAT↔PROD) needs pairing to translate the ids first.
-
----
-
-## 2. Classes
-
-| Class | File | Role |
-|---|---|---|
-| `Diff::Strategy` | `diff/strategy.rb` | Composable diff config (pairing × scope × move-sensitivity × intent); `#filter(changes)` |
-| `Diff::VersionDiff` | `diff/version_diff.rb` | Self-version (`:id` pairing) front-end → `[Change]`; accepts `strategy:` |
-| `Diff::CrossObjectDiff` | `diff/cross_object_diff.rb` | Cross-object front-end: pairs fields via `Pairing::Engine`, emits same `[Change]` |
-| `Diff::Change` | `diff/change.rb` | One change (op/kind/id/before/after/parent_id) (unchanged) |
-| `Diff::CommandSynthesizer` | `diff/command_synthesizer.rb` | `[Change]` → ordered built `WorkflowCommand` batch + `unsupported` |
-| `Diff::IdResolver` | `diff/id_resolver.rb` | Maps `resolve(kind, human-key) => id` (stage name / section heading → target id) |
-| `Diff::Deploy` | `diff/deploy.rb` | Orchestrates diff → commands → apply; gates on `unsupported` |
-| `Diff::Pairing::Signals` | `diff/pairing/signals.rb` | Weak signals (genome/type/label/options), each 0.0..1.0 or nil |
-| `Diff::Pairing::Candidate` | `diff/pairing/candidate.rb` | Scored source↔target proposal (`score`, `signals`, `matched_by`) |
-| `Diff::Pairing::Engine` | `diff/pairing/engine.rb` | Multi-signal equivalence matcher → accepted / ambiguous / unmatched |
-| `Diff::Pairing::Ledger` | `diff/pairing/ledger.rb` | Persisted confirmed equivalences (JSON); consulted first |
-
----
-
-## 3. CommandSynthesizer — edit mode
-
-`CommandSynthesizer.new(changes, resolver: nil)`. Emits in a dependency-safe order (stages → sections
-→ fields → options; within a kind removes → adds → moves → edits). A `command_for` result may be a
-single hash, an **Array** of hashes (a move that emits remove+add), or nil (unsupported); `build_all`
-normalises via `wrap` (NOT `Kernel#Array`, which would splat a Hash).
-
-| Change | Command(s) | Notes |
-|---|---|---|
-| stage added/removed/moved | `addStage`/`removeStage`/`moveStage` | |
-| stage `name` changed | `editStage(stageId, name)` | |
-| section added/removed | `addSection`/`removeSection` | |
-| section `heading` changed | `editSectionHeader(sectionId, header)` | |
-| **section `stage` moved** | `removeStageSection` + `addStageSection` | **needs resolver** for stage ids; else UNSUPPORTED |
-| field added/removed | `addField`/`removeField` | |
-| field `label` changed | `editFieldConfiguration(dataFieldId, label)` | |
-| **field `section` moved** | `moveField(id, sectionId)` | **needs resolver** for section id; else UNSUPPORTED |
-| field `type` changed | — | **UNSUPPORTED** (no `editFieldType`; a rebuild would drop data) |
-| option added/removed/changed(label,weight) | `add/remove/editSelectFieldOption` | uses `change.parent_id` (field id); nil → UNSUPPORTED |
-| **field_config changed** (typed byType) | `editFieldConfiguration(byType: { <key> => { <attr> => after } })` | `change.by_type` names the sub-hash (`:gauge`/`:select`/`:date`); nil by_type → UNSUPPORTED. Emitted only for confirmed read↔write-key matches (see VersionDiff) |
-| **gauge_stop added** | `addGaugeFieldStop(dataFieldId, threshold, color)` | threshold+color carried on `change.after`; `parent_id` = gauge field id |
-| **gauge_stop removed** | `removeGaugeFieldStop(dataFieldId, stopId)` | `parent_id` = gauge field id |
-| **gauge_stop changed** (threshold\|color) | `editGaugeFieldStop(dataFieldId, stopId, <attr>)` | one command per changed attr |
-
-**Resolver contract:** any object answering `resolve(kind, key) => id | nil`. Without one, moves stay
-UNSUPPORTED — the synthesiser NEVER guesses a target id. `IdResolver.from_doc(target_doc)` builds one
-by indexing stage names + section headings; **ambiguous keys (duplicates) resolve to nil** (safe).
-
----
-
-## 4. Deploy
-
-```ruby
-plan = Diff::Deploy.from_versions(before_doc, after_doc)                    # self-version replay
-plan = Diff::Deploy.from_versions(uat_v1, uat_v2, target_doc: prod_doc)     # cross-object: moves resolve vs PROD
-plan.commands        # ordered built command hashes, ready for executeWorkflowCommands
-plan.unsupported     # [Change] needing human handling (never guessed)
-plan.changelog       # human one-liners
-plan.execute!(page)  # sends via page.execute_workflow_commands; RAISES if unsupported unless allow_partial: true
-```
-
-Inert until `execute!` with an explicit executor. `from_versions` derives an `IdResolver` from
-`target_doc:` (override with `resolver:`).
-
----
-
-## 5. Pairing engine (equivalence matching)
-
-Cross-object pairing is entity-resolution, not lookup (no shared Mongo ids). `Engine#pair(sources,
-targets)` returns `Result(accepted, ambiguous, unmatched)`:
-
-1. **Ledger first** — a previously-confirmed pair auto-resolves (`matched_by: :ledger`, score 1.0),
-   consuming the target so it can't be re-assigned. Pairing improves over time.
-2. **Score the rest** — every remaining source×target via `Signals`, weighted mean over the signals
-   that APPLY (nil signals excluded so a select field isn't penalised for absent genome).
-3. **Greedy one-to-one assignment**, strongest links first.
-4. **Classify:** `accepted` (score ≥ `accept_threshold` 0.85 AND not within `tie_margin` 0.1 of the
-   runner-up) · `ambiguous` (0.5–0.85, or a near-tie) · `unmatched` (< 0.5 review_threshold).
-
-**Signals + weights:** genome 0.5, type 0.2, label 0.2, options 0.1.
-- **genome** — match 1.0, mismatch 0.0 (does NOT veto — a field may be re-purposed keeping its
-  genome, or genome may be absent on newer types), nil when neither side carries one. Strong but
-  **fallible** (6 documented failure modes — see domain ref §5).
-- **type** — `__typename` equality (a type change disqualifies a data pairing).
-- **label** — case/space-insensitive exact = 1.0, else token Jaccard (partial credit for a re-purpose
-  candidate like `Date logged` → `Date of sign-off`).
-- **options** — select options overlap by **value** (primary) / label — the correct option identity,
-  never genome; nil for non-select fields.
-
-**Never guesses:** only `accepted` is safe to auto-apply/record; `ambiguous`+`unmatched` are surfaced
-for a human. A same-label/type field whose genome CONTRADICTS is pulled below accept (→ ambiguous or
-unmatched), never auto-paired.
-
----
-
-## 6. Learning ledger (first-class artifact)
-
-`Ledger` records only CONFIRMED equivalences (auto-accepted high-confidence or human-adjudicated),
-keyed by `(kind, source_id)`, storing `target_id` + `matched_by` + `confidence` + `signals` +
-`recorded_at`. `Engine#confirm!(candidate, matched_by: :human)` writes back. JSON round-trips via
-`Ledger.load(path)` / `#save`; a missing file yields an empty writable ledger; a later record
-supersedes an earlier one (human corrects an auto-accept). The how-resolved log is the interim bridge
-data Product's Field-ID / template-entity-id effort needs.
-
-> Note the struct member is `matched_by`, NOT `method` — `method` would shadow `Object#method`
-> (`Lint/StructNewOverride`). The `Ledger#record` / `Engine#confirm!` keyword is likewise `matched_by:`.
-
----
-
-## 7. Gauge stops + typed byType config emission (round #3 — DONE)
-
-`VersionDiff` now emits two new `Change` kinds (id-paired, self-version):
-
-- **`:gauge_stop`** — diffs each Gauge field's `stops` list (`{ id, threshold, color }`, matched by
-  retained stop id): added (carries `after: { threshold:, color: }`), removed, changed
-  (`threshold`/`color`). `parent_id` = the gauge field id.
-- **`:field_config`** — typed per-field configuration changes, `parent_id` = field id and `by_type`
-  = the `editFieldConfiguration.byType` sub-hash key. Emission is **data-driven + conservative**
-  (`VersionDiff::BYTYPE_CONFIG`): only where the READ doc property name matches the WRITE byType
-  input key EXACTLY. Currently confirmed against the schema + input classes:
-  - `Gauge` → `{ gauge: [max] }`
-  - `Select` → `{ select: [dataType, multiple, flat, other, otherDesc] }`
-  - `Date` → `{ date: [showTime, pastOnly, todayButton] }`
-  Anything else (e.g. PlainText `multiline` — not a `plainText` byType key; `required` — no
-  editFieldConfiguration key at all) is **not emitted** (unmappable → never fabricated).
-
-`Stop` shape and the gauge byType `max` verified against
-`.ai-assistance/tmp/20260605T101224_live_ep_graphql_schema.graphql.json` (`Stop { id, threshold: Float,
-color: String }`; `WorkflowEditFieldConfigurationGaugeInput { max: Float }`).
-
-## 7b. placeholderId threading (dependent intra-batch creates — round #3 — DONE)
-
-`CommandSynthesizer.new(changes, thread_placeholders:)` (Deploy passes `true` by default). When on,
-every ADDED structural node (stage/section/field) is assigned a deterministic client-chosen
-`placeholderId` keyed by its source id; `addStage`/`addSection`/`addField` emit that placeholder, and
-any later command in the SAME batch that references such a node (`addSelectFieldOption` /
-`add/edit/removeGaugeFieldStop` / `editFieldConfiguration` dataFieldId) is rewritten to the
-placeholder instead of the target-invalid source id (`ref(id)` helper). References to pre-existing
-nodes keep their real id. Threading OFF → empty map → the source ids pass through unchanged (the
-prior self-version behaviour). This makes add-then-reference sequences self-consistent within one
-`executeWorkflowCommands` call. The placeholderId inputs are native to the command modules
-(`addStage`/`addSection`/`addField` all list `placeholderId` in VALID_KEYS; `addGaugeFieldStop`
-accepts an optional one too).
-
-**Note on self-version scope:** a self-version `VersionDiff` subsumes a NEW field's options/config
-into its single `added`-field change (children are not separately emitted when the parent is brand
-new), so the natural self-version batch has no add-then-reference pair. Threading is therefore
-latent for pure self-version replay and load-bearing for the CROSS-OBJECT / assembled change-set
-replay (a field created in the batch referenced by later commands). Deploy is proven end-to-end
-against such an assembled change-set.
-
-## 7c. What remains UNSUPPORTED / deferred
-
-- **Field type change** — no schema command; would need remove+add (drops data) → always UNSUPPORTED.
-- **Moves without a resolver** — field/section moves need a target id; nil resolver → UNSUPPORTED.
-- **Non-confirmed byType config props** — anything outside `BYTYPE_CONFIG` (PlainText `multiline`,
-  `required`, RichText `markdown`/`content`, People/Table/CrossReference/etc. bodies): the read
-  fragment and/or the byType input keys were not confirmed to line up 1:1, so they are NOT emitted
-  (never fabricated). Extend `BYTYPE_CONFIG` per type once the read shape is confirmed.
-- **Gauge stop reordering** — stops are matched by id (add/remove/attr change) but a pure reorder is
-  not modelled (no ordering field surfaced on `Stop`); left UNSUPPORTED.
-- **Structural cross-references in emitted adds** — `addField`/`addSection` still emit only
-  label/placeholder (not `stageId`/`sectionId` back-refs to their added parent). Once those refs are
-  emitted, placeholder threading will thread them too (the primitive is already in place).
-- **Interactive assisted-resolution UX + `TypedFieldsPairing` as an extra signal** — eco-helpers layer.
-
-## 8. Diff modalities — `Strategy` + `CrossObjectDiff` (Phase 4 — DONE)
-
-Diffing is a COMPOSABLE FAMILY (domain ref §8), not one diff. `Diff::Strategy` is the value object
-over four axes:
-
-- **pairing** `:id` (self-version, default) · `:genome` · `:type_label` · `:assisted` (full engine).
-  `:id` needs no pairing map; the other three are `cross_object?` (need one).
-- **scope** `:structural` (all) · `:config_only` (field_config/option/gauge_stop) · `:data_migration`
-  (field changes only).
-- **move_sensitive** — false suppresses `:moved` changes; config_only/data_migration never emit moves.
-- **intent** `:changelog` · `:deploy` · `:sync_readiness` (documentation; `:deploy` keeps threading on).
-
-`Strategy#filter(changes)` applies scope + move-sensitivity to a computed change-set. `Strategy.default`
-is `{id, structural, move-aware, changelog}` — EXACTLY the pre-Phase-4 `VersionDiff` behaviour (BC).
-
-`VersionDiff.new(before, after, strategy:)` is the `:id` front-end: it computes the full id-paired
-change-set once (`all_changes`) and returns `strategy.filter(all_changes)`. Default = unchanged.
-
-`CrossObjectDiff.new(source, target, engine:, strategy:)` is the cross-object front-end for two docs
-with NO shared ids:
-1. flatten each doc's data-fields; `engine.pair(source_fields, target_fields)` (genome+type+label+
-   options, ledger-first);
-2. for each ACCEPTED pair emit `:changed(label|type)` keyed by the **source** id; target-only field →
-   `:added`; a source with no accepted target AND not in the review set → `:removed`;
-3. **never guesses** — ambiguous + unmatched sources/targets are held in `#unresolved` (surfaced for a
-   human), NOT auto-paired / auto-added / auto-removed. A same-genome RELABEL is ambiguous by design
-   (could be a re-purpose) → not auto-emitted unless the ledger/human confirms the pair.
-
-The emitted `[Change]` feeds the EXISTING `CommandSynthesizer` / `Deploy` unchanged (one emission
-layer). `Deploy.from_cross_object(source, target, engine:, strategy:)` + `Deploy#pairing` expose the
-accepted/ambiguous/unmatched for adjudication before apply.
-
-## 9. Unified BUILD emitter — `Builder::TemplateBuilder` (shares the emission layer)
-
-`lib/ecoportal/api/graphql/builder/template_builder.rb`. Turns a declarative template spec
-(stages→sections→fields→options→config→gauge-stops) into an ordered `WorkflowCommand` batch for
-`Builder::Template#create/update(commands:)`. Order: addStage → addSection → addStageSection →
-editSectionHeader → addField → addSelectFieldOption / addGaugeFieldStop / editFieldConfiguration(byType:).
-
-It uses the SAME `placeholderId` id-threading primitive as `CommandSynthesizer`: every created node
-gets a deterministic client-chosen `placeholderId` and later same-batch commands reference it (stage
-placeholder ← addStageSection.stageId + addField.stageId; section placeholder ← addStageSection.sectionId
-+ addField.sectionId; field placeholder ← option/stop/config dataFieldId). So BUILD (add everything)
-and DIFF-DEPLOY (add/remove/edit the delta) emit through ONE layer. Only VALID command-input keys are
-emitted (input classes slice + compact); config is passed through under its byType sub-hash exactly as
-supplied — nothing is fabricated. UNSUPPORTED in a build spec (deferred): forces/strategies/callbacks/
-tasks/recipients (shape unconfirmed); `field_type` enum not schema-validated (passed through as given).
-
-## 10. Related
-
-- `template_diff_pairing_domain.md` — the full problem space (READ FIRST).
-- `lib/.../input/workflow_command.rb` — the command vocabulary both emitters target.
-- `.ai-assistance/projects/template-automatic-build-maintenance/{INTENT,TODO}.md` (the merged plan;
-  `template-diff-deploy/` + `template-maintenance/` are now pointers).

data/.ai-assistance/code/diff_service_deep_dive.md

@@ -1,192 +0,0 @@
-# Code Spec: DiffService Deep Dive
-
-**Scope:** `DiffService`, `ClassicDiffService`, `HashDiffNesting`, `AsInput` — bugs discovered
-during 4.4 spec work, current state, and what still needs fixing.
-**Last updated:** 2026-06-05
-
----
-
-## Current State (post-4.2 / pre-4.4 completion)
-
-### What works
-- **Flat diffs on simple models** (no cascade): `change_data` produces correct output
-  after key normalisation fix (see below).
-- **`patchVer` injection** in `AsInput#as_input`.
-- **`from_model` delegation** via `Logic::Input.from_model`.
-- **`ContractorEntity::Update.from_model`** IdDiff reshaping.
-
-### What is still broken / incomplete
-See TODO 4.4 for the spec gaps. Key issues:
-
----
-
-## Bug 1 — String vs Symbol Keys in `change_data` (ROOT CAUSE OF MOST FAILURES)
-
-`ClassicDiffService#prev_doc` returns `model.original_doc` — a hash with **string keys**
-(set via `JSON.parse` in `DoubleModel#initialize`).
-
-`HashDiffNesting#change_data` converts each key to symbol via `key.to_sym` and then
-looks up the value in `b` (prev_doc) with:
-```ruby
-if b&.key?(key)   # key is now :name (symbol)
-  b_value = b[key]
-```
-
-Since `b` has `'name'` (string), `b.key?(:name)` is **always false**. Every field appears
-as "changed" (new value vs nil previous). The diff is wrong.
-
-### Fix needed in `DiffService#classic_diff`
-
-Normalise both docs to symbol keys before comparison:
-```ruby
-def classic_diff(flat: flat?, ignore: [])
-  curr = keys_to_sym_deep(curr_doc(flat: flat) || {})
-  prev = keys_to_sym_deep(prev_doc(flat: flat) || {})
-  
-  data = change_data(curr, prev, ignore: to_a(ignored, ignore))
-  return nil if data == NO_CHANGES
-  
-  id = get_id(curr, exception: false)
-  id ? { id: id }.merge(data) : data
-end
-```
-
-`keys_to_sym_deep` is available as an instance method via `include HashHelpers`.
-
----
-
-## Bug 2 — `dig_path?` Returns True for Any Single-Element Path
-
-The `DoubleModel::HashHelpers` implementation:
-```ruby
-def dig_path?(obj, keys)
-  return false unless obj.respond_to?(:[])
-  return true  if keys.length == 1   # ← BUG: doesn't check key existence
-  dig_path?(obj[keys.first], keys[1..])
-end
-```
-
-This always returns `true` for single-element key paths regardless of whether the key
-actually exists. For `diff_reduce`, this causes:
-- `dig_path?({id:, name:}, ['actionCategory'])` → **true** (wrong! actionCategory not present)
-- `dig_set!(result, ['actionCategory'], nil)` adds spurious nil entries to the diff
-
-**Fix in `HashDiffNesting#dig_path?`:**
-```ruby
-def dig_path?(obj, keys)
-  return false unless obj.is_a?(Hash)
-  return obj.key?(keys.first) if keys.length == 1   # check actual existence
-  return false unless obj.key?(keys.first)
-  dig_path?(obj[keys.first], keys[1..])
-end
-```
-
----
-
-## Bug 3 — `diff_reduce` Cannot Add New Cascade Keys
-
-`diff_reduce` was designed to REPLACE existing cascade keys in the flat diff. But
-cascade attributes are always STRIPPED from the flat diff (`doc_with_non_cascaded_attributes`).
-So the keys are never in the flat diff, and `diff_reduce` never adds them.
-
-### Current broken flow for nested change only:
-1. `dueDate` changed on an Action, nothing else changed
-2. `classic_diff(flat: true)` → `nil` (dueDate stripped, no flat-level changes)
-3. `diff_reduce(nil)` → all `dig_path?(nil, ...)` return `false` → cascade never processed
-4. Result: `nil` — the nested change is LOST
-
-### Current broken flow for mixed change:
-1. `name` changed AND `dueDate` changed
-2. `classic_diff(flat: true)` → `{id:, name: 'Updated'}` (flat change only)
-3. `diff_reduce({id:, name: 'Updated'})`:
-   - `dig_path?({id:, name:}, ['dueDate'])` → `false` (dueDate not in flat diff) → skip
-4. Result: `{id:, name: 'Updated'}` — dueDate change LOST
-
-### Fix needed in `diff_reduce`:
-
-Remove the `dig_path?` gate. Instead, ADD cascade diffs directly:
-```ruby
-def diff_reduce(init, ignore: [])
-  subject.cascaded_reduce(init, recurs: false) do |result, obj, _key, key_path, _trace|
-    next result if key_path.empty?
-    next result if obj == subject
-    next result if root?(obj)
-    next result unless obj.is_a?(Ecoportal::API::Common::GraphQL::Model)
-    
-    value = obj.as_update(ignore: ignore)
-    next result if value.nil?
-    
-    result ||= {}
-    dig_set!(result, key_path, value)
-    result
-  end
-end
-```
-
-Additionally, `diff` must ensure `id:` is present even when init was nil:
-```ruby
-def diff(flat: flat?, ignore: [])
-  flat_result = classic_diff(flat: true, ignore: ignore)
-  return flat_result if flat
-  
-  result = diff_reduce(flat_result, ignore: ignore)
-  return nil if result.nil?
-  
-  # Guarantee id: is in result when cascade added something
-  result[:id] ||= get_id(keys_to_sym_deep(curr_doc(flat: true) || {}), exception: false)
-  result
-end
-```
-
----
-
-## Bug 4 — `ecoportal-api-v2` `_cascaded_attributes_trace` (FIXED in 6a2b1b5)
-
-Block params were `|out, (attribute, obj_k)|` (swapped) — `attribute` received the
-trace hash instead of the attribute symbol, causing `TypeError: Hash is not a symbol`.
-Fixed to `|(attribute, obj_k), out|`. Requires rebuild of ecoportal-api-v2 gem.
-
----
-
-## Missing Methods in `DiffService` (FIXED in 0b68a6b)
-
-`diff_reduce` calls `dig_path?`, `dig_delete!`, `dig_set!` which are defined in
-`DoubleModel::HashHelpers` (ecoportal-api-v2) but NOT included in `DiffService`.
-
-Added these three methods to `HashDiffNesting::InstanceMethods`. See
-`lib/ecoportal/api/common/graphql/model/diffable/hash_diff_nesting.rb`.
-
----
-
-## `diff_reduce` — ArrayModel Safety (FIXED in 0b68a6b)
-
-`passarray :fieldName` creates `ArrayModel` subclasses inheriting from `DoubleModel`.
-These respond to `as_update` but use the ecoportal-api-v2 signature (no kwargs).
-
-Added guard: `next result unless obj.is_a?(Ecoportal::API::Common::GraphQL::Model)`.
-This limits cascade-diffing to GraphQL model objects only.
-
----
-
-## Recommended Implementation Order for 4.4 Completion
-
-1. Fix `DiffService#classic_diff` key normalisation (Bug 1 — most impactful)
-2. Fix `HashDiffNesting#dig_path?` to check key existence (Bug 2)
-3. Redesign `diff_reduce` to ADD rather than REPLACE cascade keys (Bug 3)
-4. Update `diff` to ensure `id:` presence and proper no-change return
-5. Update specs to pass for all scenarios
-
----
-
-## File Locations
-
-| File | Role |
-|------|------|
-| `lib/.../model/diffable/diff_service.rb` | Main DiffService — `classic_diff`, `diff`, `diff_reduce` |
-| `lib/.../model/diffable/classic_diff_service.rb` | Base: `curr_doc`, `prev_doc`, `change_diff` dispatch |
-| `lib/.../model/diffable/hash_diff_nesting.rb` | `change_data`, `patch_*`, `dig_*` helpers |
-| `lib/.../model/as_input.rb` | `as_input` instance + class methods, `patchVer` injection |
-| `lib/.../graphql/logic/input.rb` | `Logic::Input.from_model` base |
-| `lib/.../input/contractor_entity/update.rb` | `from_model` override with IdDiff reshaping |
-| `spec/.../model/diff_service_spec.rb` | DiffService specs (WIP — partial failures) |
-| `spec/.../model/as_input_spec.rb` | AsInput + from_model specs (WIP) |