openehr-rails 0.6.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69d9f917d3eb32a92e7d47aeb3f43bf8992a6a44f8ceb49320a1e5a6130ecebf
-  data.tar.gz: 1f39015dbd51241ea4dca624bd89e988a82bf62ef3a02964e54a343b6e8ccbf1
+  metadata.gz: cf0122af26f620b3082c006c5d469fdf3710c5dd1647b856c9024c8e4e3f7c66
+  data.tar.gz: b54d925956180cd9baffab027d42564ecd55864f839698952ed2bfbfdfb9356d
 SHA512:
-  metadata.gz: 5acec88b6d3dee1ab32167080639a81052911eee90043ae09474e083fa0c92e081da69dade909848da04743cffc96603e887765a8efaff29d6172f873e93a074
-  data.tar.gz: 1c134c5a1147f54ee8628b62efdcfcb867f257f634a5094a4f0aacb2af460ac28cfcaa011457017610262686437041ec85045186f9c05acb034ed4080e6ec793
+  metadata.gz: 90fadabcf5f3215e6c24f4c75f5bef98e38b831286e0f0da33d6d67ae6743937d7958d286384c85042830452e47fe08e22eca6dce72541ab7bfb5395cc029ef2
+  data.tar.gz: 700d4afc6e60805cc76c478035131d0aa62b5f0decc09d44c67f0ac1bb4e8181500de65ba56b40f2974a0e24259945fb26285a6b3eac0ebe3ca394656cdc1c56

data/CHANGELOG.md

@@ -7,8 +7,107 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-09-25
+
+> **Upgrade note.** AQL now skips a stored composition that holds an RM type
+> `RmObjectBuilder` cannot rebuild, with a warning
+> (`openehr-rails AQL: skipping composition uid=...`), instead of failing every
+> query in the store. No host-app change is needed; if that line appears in
+> your log, the composition is a #45 case (SECTION / INSTRUCTION / ACTIVITY
+> read-back, next minor release).
+
+### Fixed
+- A single-leaf entry mapped to a resource other than `Observation` and without a
+  `TypeMap::ENTRY_ELEMENT_MAPS` row no longer produces `<Resource>.value[x]`, which
+  `Condition`/`ServiceRequest`/`Procedure`/`Encounter` do not have; it is skipped and
+  reported through `#skipped` like the multi-leaf case since 0.7.0 (#38). The
+  `UnsupportedProfileError` message now names both missing elements.
+- AQL no longer fails for the whole store when one stored composition cannot be
+  rebuilt as RM objects (a node type outside `RmObjectBuilder::TYPE_CLASSES`,
+  such as `SECTION`/`INSTRUCTION`, or an RM constructor rejecting stored data).
+  `DatasetAdapter` now warns (`Rails.logger` when present, else stderr), naming
+  the composition uid and the cause, and skips that composition; queries on the
+  rest of the store return their rows. `RmObjectBuilder` raises
+  `OpenehrRails::Rm::UnsupportedRmTypeError` (composition uid, node path,
+  rm_type) instead of an accidental `NoMethodError` (#44).
+
+## [0.7.0] - 2026-09-10
+
+> **Upgrade note.** Regenerate `app/fhir/profiles/*.json`. `Condition.component`
+> slices are gone; anything reading them must move to the mapped elements
+> (`category` slice `ckm`, `code`, `onsetDateTime`, `recordedDate`,
+> `abatementDateTime`, `verificationStatus`), and an entry with no mapping onto
+> a non-`Observation` resource now appears in the generator's `#skipped` list
+> instead of producing a profile.
+
+### Changed
+- **Breaking for consumers of generated FHIR profiles.** `EVALUATION` entries no
+  longer produce `Condition.component` slices, which FHIR R5 `Condition` does not
+  have. Each leaf now maps onto the real `Condition` element that means the same
+  thing — `code` (bound to the leaf's value set), `onsetDateTime`,
+  `recordedDate`, `abatementDateTime`, `verificationStatus` — and the archetype
+  anchor moves from `Condition.code` to a `Condition.category` slice (`ckm`,
+  `1..1`, pattern-discriminated on `$this`, so an instance keeps room for its
+  other categories), since `code` is now the diagnosis itself. `recordedDate`
+  carries an `ElementDefinition.comment` stating that it approximates at0003
+  (date/time clinically recognised). `ProfileGenerator` (JSON) and
+  `FshGenerator` generate from one table in `TypeMap`, so the two outputs cannot
+  disagree. Generated FSH for `problem_list.opt` goes from 29 Sushi errors to 0.
+  Host apps must regenerate cached `app/fhir/profiles/*.json`; anything reading
+  the old `Condition.component` slices must be updated (#33). Currently mapped:
+  `openEHR-EHR-EVALUATION.problem_diagnosis.v1`. A multi-leaf entry mapped to
+  `ServiceRequest`/`Procedure`/`Encounter` without a mapping-table row is now
+  skipped and reported (see Added) instead of producing `component` constraints
+  those resources do not have; its mapping table remains reserved as #35.
+- Value-set canonicals on mapped leaves no longer carry OPT's `terminology:`
+  prefix, in either output.
+
+### Added
+- `ProfileGenerator#skipped` and `FshGenerator#skipped`: the entries left out of
+  `#profiles` / `#to_fsh_files`, each as an
+  `OpenehrRails::Fhir::UnsupportedProfileError` (`archetype_id`,
+  `resource_type`, `leaf_count`) in template order. An entry is skipped when it
+  has more than one leaf, maps to a resource without `component`, and has no row
+  in `TypeMap::ENTRY_ELEMENT_MAPS`; the rest of the template still generates.
+  `rails g openehr:fhir_profile` and `openehr:scaffold --fhir` print each skip
+  (#33).
+
+### Removed
+- `TypeMap.value_element`, dead since it was added — its ternary returned the
+  same string on both branches and nothing called it. Its intended
+  resource-type branch is now the mapping table (#33).
+
+### Fixed
+- `templates/openehr_template.rb` pins `json < 3` in the generated app's
+  `Gemfile`. `json` 3.0 (2026-09-08) changed `JSON.parse`'s arity and
+  `ActiveSupport::JSON.decode` as of activesupport 8.1.3.1 still passes options
+  positionally, so a freshly generated host app failed at `db:seed` on its first
+  json-column write (`ArgumentError: wrong number of arguments (given 2, expected
+  1)`). Temporary: remove once a Rails patch release carries the fix. This
+  repo's own `Gemfile` and `script/build_demo.sh` carry the same dev-only pin.
+- `release:check` now fails when a tag matching the gemspec version exists and
+  `HEAD` is not that tag's commit. `gem.files` comes from `git ls-files`, so a
+  gem built at a later commit ships different bytes under the same version
+  number — the defect that let 0.6.0 be published as a `master`-HEAD build
+  (#34). The check stays silent when the version has no tag yet, so ordinary
+  pre-release development is unaffected.
+
 ## [0.6.0] - 2026-08-26
 
+> **Published artifact note.** The gem published to RubyGems for this version
+> was built from `master` HEAD rather than the `v0.6.0` tag, so it contains the
+> tagged tree plus two documentation files added after the tag
+> (`docs/design/multi-leaf-non-observation-plan.md`, and this project's
+> `docs/reports/fsh-generator-log.md` carrying its R6 entry). `lib/` is
+> byte-identical to the tag artifact and version, runtime dependencies and
+> `required_ruby_version` are unchanged, so the published gem is functionally
+> identical to what CI built and verified at the tag; it was accepted rather
+> than yanked. Published sha256
+> `223e3b3897f85c38eaffe7ea39bd7c2acf4c5de9cab7d50fe38f754ff9d65db6`; tag-build
+> sha256 `08cdd14ab1f3890b0c6b5f0ae0d5ca55615f0b4874ed5efb0cd4d7bda9e573ca`.
+> Full measurements: `docs/reports/fsh-generator-log.md` R8. Prevention:
+> `skoba/openehr-rails#34`.
+
 ### Added
 - `OpenehrRails::Fhir::FshGenerator` renders one FHIR Shorthand profile per
   openEHR entry, including metadata, archetype codes, value constraints,

data/CLAUDE.md

@@ -46,6 +46,37 @@ Before tagging, make the final semver determination from the actual content of
 `[Unreleased]`, not from a pre-assigned version number. If the instructed version number
 contradicts the actual content, stop instead of tagging and ask for re-arbitration.
 
+**Publish only the CI artifact itself.** `gem push` takes the `.gem` downloaded
+from the tag's Release run (`gh run download <run-id> -n gem`), after its sha256
+has been compared against the value recorded for that run - never a locally built
+`pkg/*.gem`. `gem.files` comes from `git ls-files`, so a build made at any commit
+other than the tag ships different bytes under the same version number, and a
+stale `pkg/` artifact from unrelated local work is indistinguishable by filename
+from a release build.
+
+(Added 2026-08-27, from the 0.6.0 publish: the gem that reached RubyGems was a
+`master`-HEAD build left in `pkg/` by an unrelated verification run, not the
+CI-verified `v0.6.0` artifact. Accepted rather than yanked - the delta was two
+documentation files and `lib/` was byte-identical - but nothing in the release
+path caught it. Measurements in `docs/reports/fsh-generator-log.md` R8; the
+matching `release:check` guard is `skoba/openehr-rails#34`.)
+
+**Confirm publication by checksum, not by version number.** RubyGems publishes
+the sha256 it recorded at push time (`/api/v1/gems/openehr-rails.json` `sha`, and
+the `checksum:` field in `https://index.rubygems.org/info/openehr-rails`). The
+post-push confirmation compares that value against the sha256 the tag's Release
+run recorded for its artifact - the same value already compared before the push.
+Seeing the version number appear is not the check; it only shows that *a* gem
+landed under that number. (Ported 2026-09-10 from openehr-ruby's 2.4.3 release,
+where CI run, downloaded artifact and published gem all agreed on one sha256.)
+
+**RubyGems API propagation lag.** `/api/v1/versions/openehr-rails.json` can lag
+the push by minutes; do not read the new version's absence there as a failed
+publish, and do not re-push. Confirm with
+`/api/v1/versions/openehr-rails/latest.json`, `/api/v1/gems/openehr-rails.json`,
+or the compact index `https://index.rubygems.org/info/openehr-rails`, which
+updated first in that same 2.4.3 run.
+
 ## Verification
 
 - **Verify against the repo before recording a fact in it**, even when a prompt or an
@@ -119,7 +150,8 @@ name explicitly a distinction that the existing repository-context rule left
 implicit: it governs *how* to target a cross-repo command correctly, not *whether*
 crossing into implementation work on another repository has actually been
 authorized for the task at hand. A matching line is planned for `anlage`'s own
-`CLAUDE.md` in a later batch - not yet added there as of this entry.)
+`CLAUDE.md` in a later batch - not yet added there as of this entry. Update
+2026-09-04: added there as 絶対規律 item 9.)
 
 ## Project Overview
 
@@ -200,4 +232,4 @@ This is `openehr-rails`, a Rails engine gem that turns an openEHR Operational Te
 - Guard setup available for TDD workflow
 - RuboCop Rails linting configured
 - SimpleCov for test coverage
-- `openehr` gem dependency; see the gem's own README/CHANGELOG for OPT-parser and AQL-engine capabilities and known gaps before relying on either.
+- `openehr` gem dependency; see the gem's own README/CHANGELOG for OPT-parser and AQL-engine capabilities and known gaps before relying on either.

data/Gemfile

@@ -1,3 +1,10 @@
 source 'https://rubygems.org'
 
 gemspec
+
+# json 3.0 (released 2026-09-09) changed JSON.parse's arity; ActiveSupport::JSON.decode
+# as of activesupport 8.1.3.1 still passes its options positionally, so reading any
+# json column raises ArgumentError (wrong number of arguments (given 2, expected 1)).
+# Dev/test-only pin -- the gemspec is untouched, host apps resolve their own json.
+# Drop once a Rails patch release carries the fix (docs/backlog.md, "Dependencies").
+gem 'json', '< 3'

data/docs/backlog.md

@@ -74,6 +74,15 @@ that verification is deferred to the next real release (>= 0.5.0), not simulated
 
 ## Release automation
 
+- **`release.yml` records no sha256 of the built `.gem`** (found at the 0.7.0
+  release, 2026-09-10, `docs/reports/fsh-generator-log.md` R14). The only digest in
+  the run log is `actions/upload-artifact`'s "SHA256 digest of uploaded artifact",
+  which hashes the uploaded archive, not the gem file, so `CLAUDE.md`'s "compare
+  against the value recorded for that run" cannot be followed literally; the
+  tag-rebuild cross-check is what pins the bytes today. Add a "Record sha256" step
+  after `rake build` (`sha256sum pkg/*.gem`), as openehr-ruby's `release.yml` has.
+  CI-only change; needs a PR, no Issue.
+
 **Done (2026-08-23, PR #28)** — kept below for the original rationale; see the CI
 status entry above for verification details.
 
@@ -90,6 +99,13 @@ status entry above for verification details.
   docs-only pass — implementing the workflow change goes through an Issue (once
   ticket-driven work applies to it) plus the normal explore → plan → approval gate,
   not a direct docs commit.
+  - A point in Trusted Publishing's favour, measured 2026-08-27: the gem build is
+    byte-identical across machines and Ruby installs for a given commit — `4080053`
+    (the `v0.6.0` tag) produced sha256 `08cdd14a…` from CI, from the old machine
+    (R5), and from a rebuild on the replacement machine under local ruby 4.0.6 vs
+    CI's `ruby/setup-ruby@v1` ruby 4.0. So a CI- or Trusted-Publishing-published
+    artifact stays independently verifiable against a local rebuild
+    (`docs/reports/fsh-generator-log.md` R8).
 
 ## From #25 / PR #26 (FieldExtractor terminology scope fix, 2026-08-22)
 
@@ -115,6 +131,14 @@ status entry above for verification details.
 
 ## Fixture conventions
 
+- **`spec/templates/sample_blood_pressure.opt` does not parse** -- `OpenehrRails::Opt.parse`
+  raises `ArgumentError: invalid archetype id form` from
+  `OpenEHR::RM::Support::Identification::ArchetypeID` under openehr 2.4.2 *and* 2.4.3
+  (measured 2026-09-10 while checking fixtures for #38), and no spec, script or
+  generator references the file. Orphan fixture: either find which archetype id in
+  it is malformed and decide whether that is an openehr-ruby parser gap worth an
+  upstream Issue, or delete the file. Not touched in 0.7.0.
+
 - **Licensed terminology-code literals in spec expectations: keep minimal, cite the
   source fixture's file:line.** Adopted from Anlage's C2 firewall precedent (SNOMED
   CT is a licensed terminology; reproducing its codes verbatim in more places than
@@ -155,3 +179,18 @@ status entry above for verification details.
   duplicate-method inventory being produced first.
 - **#2** (constraint -> HTML attribute mapping extraction): gated on a generality decision
   after Anlage Slice 4; whether to even start is undecided.
+
+## Dependencies
+
+- **Remove the `json < 3` pins once Rails ships the fix.** Added 2026-09-10 in
+  three places: `Gemfile` (dev/test), `script/build_demo.sh` (the demo app's
+  Gemfile), `templates/openehr_template.rb` (the generated host app's Gemfile).
+  Cause: `json` 3.0 (3.0.1 on 2026-09-08, 3.0.2 on 2026-09-09) changed
+  `JSON.parse`'s arity and `ActiveSupport::JSON.decode` as of activesupport
+  8.1.3.1 still passes options positionally, so every json-column read raises
+  `ArgumentError: wrong number of arguments (given 2, expected 1)`. Measured on
+  PR #39's CI run `34423912397` (62 failures, all RM-graph/AQL specs) and
+  reproduced locally with `bundle update` on `master`; with the pin and a fresh
+  resolve, 295 examples / 0 failures. Removal condition: an activesupport release
+  whose `JSON.decode` accepts json 3 (check the Rails CHANGELOG), then delete the
+  three pins in one docs+tooling commit and let CI resolve fresh.

data/docs/design/multi-leaf-non-observation-plan.md

@@ -1,6 +1,6 @@
 # Fix: multi-leaf non-Observation entries constrain a nonexistent `component`
 
-- Status: draft, awaiting approval
+- Status: **ruled 2026-08-27 — option (d), proper mapping, adopted. §§2-6 below are superseded; §8 is the normative spec, as corrected by §9 (the ruling's four corrections, applied 2026-09-10).**
 - Target: `openehr-rails` (this repo). No cross-repo work.
 - Issue: [#33](https://github.com/skoba/openehr-rails/issues/33)
 - Log: `docs/reports/fsh-generator-log.md` (continuing R1-R5)
@@ -178,3 +178,221 @@ this repo's division of labor, or directly if the change is judged small enough
 skip that split — decide at approval time), Claude Code review, full
 `bundle exec rspec` + full-repo `rubocop` + `sushi` re-verification for
 `bmi_calculation.opt`, commit(s), `docs/reports/fsh-generator-log.md` entry.
+
+
+---
+
+# 8. RULING (2026-08-27): option (d), proper mapping to `Condition`
+
+The recommendation in §3 — option (c), restrict multi-leaf non-`Observation`
+entries and raise — **was not adopted**. The ruling directs a *proper mapping*:
+`problem_diagnosis`'s leaves land on the real `Condition` elements that mean the
+same thing. §§2-6 are kept for the record but are superseded by this section.
+
+**This table is the single specification for both outputs.** `ProfileGenerator`
+(the JSON facade) and `FshGenerator` both generate from it; neither may carry a
+mapping decision the other doesn't.
+
+## 8.1 Mapping table — `openEHR-EHR-EVALUATION.problem_diagnosis.v1` → `Condition` (FHIR R5)
+
+Measured, not assumed: leaves are `FieldExtractor#entries` output for
+`spec/templates/problem_list.opt`; every target element was compiled against
+`hl7.fhir.r5.core#5.0.0` with `sushi` 3.16.0 (**0 Errors**) before this table was
+written.
+
+| openEHR leaf | Label (fixture, ja) | RM type | → `Condition` element | Rationale |
+|---|---|---|---|---|
+| *(archetype anchor)* | — | — | `category` — fixed coding `CKM#openEHR-EHR-EVALUATION.problem_diagnosis.v1` | The anchor cannot stay on `code`: under a proper mapping `code` is claimed by at0002, the diagnosis itself. `category` is R5's 0..* CodeableConcept for "what kind of Condition record is this", with an *example* binding, so a fixed archetype coding is legal there. |
+| `at0002` | プロブレム・診断名 | `DV_CODED_TEXT`, value set `http://id.who.int/icd/release/11/mms` | `code` 0..1, `only CodeableConcept`, `from <ICD-11 MMS> (required)` | `Condition.code` is "identification of the condition, problem or diagnosis" — the direct counterpart. Its base binding is *example*, so a profile may tighten it to *required*. |
+| `at0077` | 発症日時 | `DV_DATE_TIME` | `onsetDateTime` 0..1, `only dateTime` | `onset[x]` is the date/time the condition began; the `dateTime` choice matches `DV_DATE_TIME` exactly. (`sushi` normalises the path to `Condition.onset[x]` with `type: [dateTime]` — that is the shape the JSON facade emits.) |
+| `at0003` | 臨床的に認識された日時 | `DV_DATE_TIME` | `recordedDate` 0..1, `only dateTime` | Nearest R5 element. **Approximation, recorded as such**: `recordedDate` is "when this Condition record was created in the system", which is not a synonym for "clinically recognised". No closer element exists in R5; the gap is written down here rather than implied by the mapping. |
+| `at0030` | 治癒日時 | `DV_DATE_TIME` | `abatementDateTime` 0..1, `only dateTime` | `abatement[x]` is "the date the condition resolved or went into remission" — the direct counterpart. |
+| `at0073` | 診断確度 (`at0074` 疑い / `at0075` 推定 / `at0076` 確定) | `DV_CODED_TEXT`, `terminology_id = "local"` | `verificationStatus` 0..1, `only CodeableConcept`, **no value-set binding emitted** | `verificationStatus` (unconfirmed \| provisional \| differential \| confirmed \| refuted \| entered-in-error) is the semantic counterpart of 診断確度. See 8.2 for why the local codes are deliberately *not* bound. |
+
+**Nothing in this archetype is unmappable** — all five leaves land. What is
+deliberately *not* emitted is in 8.2.
+
+## 8.2 Deliberate omissions
+
+- **`at0073`'s local code list (`at0074`/`at0075`/`at0076`) is not bound.**
+  `Condition.verificationStatus` has a **required** binding to
+  `http://hl7.org/fhir/ValueSet/condition-ver-status`; binding an archetype's
+  local at-codes there would be invalid. Translating 疑い/推定/確定 into
+  `provisional`/`confirmed`/etc. is a `ConceptMap` concern, outside what a
+  `StructureDefinition` can express. The profile therefore constrains the
+  element's cardinality and type only. This means the current
+  `apply_value_constraints` behaviour — emitting
+  `binding: { strength: 'required' }` for any `DV_CODED_TEXT` carrying a local
+  `code_list` — must **not** apply to a mapped leaf.
+- **Multi-leaf non-`Observation` entries with no mapping table entry keep their
+  current behaviour.** The ruling scopes this fix to `problem_diagnosis`; the
+  `INSTRUCTION`→`ServiceRequest` case (`request-referral`, arriving with
+  referral v2) is reserved as its own Issue rather than generalised here.
+
+## 8.3 Where the table lives
+
+In `TypeMap`, next to `ENTRY_RESOURCES`, keyed by archetype id — the existing
+RM-type→FHIR-resource mechanism, not a new conditional scattered across the two
+generators. Both generators ask `TypeMap` the same question. The dead
+`TypeMap.value_element` (§1) is removed as part of this: it was a stub for
+exactly this resource-type branch and never implemented it.
+
+## 8.4 TDD
+
+- **Red**: `problem_list.opt`'s generated FSH under `sushi` 3.16.0 — measured
+  **29 Errors** today (all `No element found at path component…`). Pinned as the
+  starting measurement.
+- **Green**: the same fixture compiles with **0 Errors**. The exact rule set the
+  implementation must emit was pre-verified against
+  `hl7.fhir.r5.core#5.0.0` before implementation began.
+- **JSON facade**: `profile_generator_spec.rb` gains expectations for the mapped
+  `Condition` elements, and asserts no `Condition.component` element is produced
+  — the original complaint in #33.
+- **Regression pin**: `bmi_calculation.opt` (multi-leaf `Observation`) is
+  untouched by the new branch and must stay green, `component` slicing intact.
+
+## 8.5 Semver
+
+**Minor.** The JSON facade's output shape changes for `EVALUATION` entries
+(`Condition.component` slices disappear, real `Condition` elements appear), which
+is observable to any host app consuming `app/fhir/profiles/*.json`. Ships with
+`#34`'s `release:check` change; version finalised at release inventory, 0.7.0
+expected.
+
+# 9. RULING FOLLOW-UP (2026-09-10): the four corrections to §8, applied
+
+The 2026-08-27 ruling approved §8 **with four corrections**: (1) the archetype
+anchor is a *slice* of `category`, (2) `at0003`'s approximation is stated on the
+element as a `^comment`, (3) unmapped multi-leaf non-`Observation` entries are
+*skipped and reported* per entry, (4) through a named exception class. The
+implementation commit `01f31f3` (2026-08-27 12:38 JST) landed 21 minutes after §8
+itself (`07767cc`, 12:17 JST) and carries none of them; this repository held no
+record of the four points until this section. Applied under the reopened #33.
+Everything below was measured against `hl7.fhir.r5.core#5.0.0` with `sushi`
+3.16.0 before the code was written, as §8 was.
+
+## 9.1 Correction 1 — the anchor is a slice of `category`
+
+- **Before**: `* category.coding.system = "…"` / `* category.coding.code = #…`
+  (JSON: one `Condition.category` element with `patternCodeableConcept`).
+- **Why that was wrong**: `Condition.category` is `0..*`. Fixing the coding on the
+  element constrains *every* repetition, so a conforming instance could not also
+  carry e.g. `problem-list-item` beside the archetype coding.
+- **After**: pattern slicing on `$this`, `rules = #open`, `contains ckm 1..1`,
+  `category[ckm] = http://openehr.org/ckm/archetypes#<archetype id>` (FSH
+  assignment to a `CodeableConcept` is a `patternCodeableConcept`, the same shape
+  the JSON facade emits). JSON: two `Condition.category` elements — the slicing
+  root (`discriminator: [{type: pattern, path: $this}]`, `rules: open`) and the
+  `ckm` slice (`min 1`, `max "1"`, `patternCodeableConcept`). The slice name
+  reuses the name the FSH output already gives the CKM coding slice on
+  `code.coding`; it is `TypeMap::ANCHOR_SLICE` so both generators share it.
+- **Measured**: the candidate rule set compiled to **0 Errors** before
+  implementation; the generator's own output afterwards byte-matches the golden
+  and compiles to **0 Errors** together with `bmi_calculation.opt`.
+
+## 9.2 Correction 2 — `at0003` carries a `^comment`
+
+§8.1 records `at0003` → `recordedDate` as an approximation in this document only;
+the profile now says so itself. `ENTRY_ELEMENT_MAPS` gains a `:comment` key on
+the leaf, emitted as `* recordedDate ^comment = "…"` (FSH) and
+`ElementDefinition.comment` (JSON) — table-driven, so the two outputs cannot
+differ on the wording. Text: *Approximation: openEHR at0003 (Date/time clinically
+recognised) has no exact counterpart in FHIR R5 Condition; recordedDate is when
+this Condition record was created in the system. See
+docs/design/multi-leaf-non-observation-plan.md section 8.1.*
+
+## 9.3 Corrections 3 and 4 — skip-and-report, `UnsupportedProfileError`
+
+These answer §6's open questions 2 and 3.
+
+- **Condition**: an entry with **more than one leaf**, whose base resource is
+  **not `Observation`**, and which has **no row** in `ENTRY_ELEMENT_MAPS`. Before
+  this section such an entry silently took the `component` path — the original
+  #33 defect, still live for `ServiceRequest`/`Procedure`/`Encounter` (the
+  `[Unreleased]` CHANGELOG said as much).
+- **One decision point** (§3): `TypeMap.assert_supported!(entry)` raises
+  `OpenehrRails::Fhir::UnsupportedProfileError` (`archetype_id`, `resource_type`,
+  `leaf_count`, and a message naming all three plus #33/#35). Both generators
+  call it; neither carries its own conditional.
+- **Skip-and-report per entry, not raise-through** (Q2): `ProfileGenerator` and
+  `FshGenerator` partition entries at construction, generate for the supported
+  ones, and expose the errors in template order through `#skipped`. The batch
+  never aborts on one bad entry. The Rails generators (`openehr:fhir_profile`,
+  `openehr:scaffold --fhir`) print each skip as `say_status :skip, …, :yellow` —
+  the report reaches the person running the generator, and a library caller that
+  wants a hard failure re-raises from `#skipped`.
+- **Class** (Q3): `OpenehrRails::Fhir::UnsupportedProfileError < StandardError`,
+  in `lib/openehr_rails/fhir/unsupported_profile_error.rb`, required before
+  `type_map`.
+- **Not covered, deliberately**: single-leaf entries. The ruling's wording is
+  多葉 (multi-leaf); the single-leaf non-`Observation` path has its own defect,
+  recorded in 9.5 rather than folded in here.
+
+## 9.4 TDD (resolution shape (b) enhancement for all four)
+
+- **Red**: specs written first in `fsh_generator_spec.rb` and
+  `profile_generator_spec.rb` (slice, `^comment`/`comment`, skip-and-report,
+  `#skipped` empty for an all-`Observation` template) plus the regenerated
+  golden: **36 examples, 12 failures** on the pre-correction code.
+- **Green**: `spec/openehr_rails/fhir/`: **48 examples, 0 failures**; full suite
+  **304 examples, 0 failures** (295 before).
+- **Synthetic entry, spec-level, not a fixture file**: no real multi-leaf
+  `INSTRUCTION` OPT exists in this repo (#35 is blocked on exactly that), so the
+  skip-and-report specs stub `FieldExtractor` to return `problem_list.opt`'s real
+  entry plus one invented `INSTRUCTION` entry
+  (`openEHR-EHR-INSTRUCTION.synthetic_unmapped_test.v1`, two of the real leaves
+  relabelled). The id is self-evidently invented; the spec comment says so and
+  points here.
+- **Golden**: regenerated from the corrected generator, diffed against the
+  pre-verified candidate (identical), then compiled again: **0 Errors**.
+
+## 9.5 Residual found while measuring 9.1 — not fixed here
+
+A single-leaf non-`Observation` entry still takes the legacy path and emits
+`* value[x] 0..1` (FSH) / `<Resource>.value[x]` (JSON). `Condition` has no
+`value[x]` either: a hand-written probe (`Parent: Condition`, `* value[x] 0..1`)
+compiled under the same `sushi` run to **1 Error**, `No element found at path
+value[x] for CardRule`. No fixture in this repository reaches that path
+(`problem_list.opt` is 5-leaf; every single-leaf fixture entry is
+`OBSERVATION`), so nothing observable regressed. Outside the ruling's scope
+(多葉); filed as its own bug Issue rather than widened into #33 — the natural fix
+is to extend `assert_supported!` to it, but that is a second contract change and
+gets its own red spec.
+
+## 9.6 Semver
+
+Still **minor**, on top of §8.5: `#skipped` and `UnsupportedProfileError` are
+new public API; the `category` anchor and the `comment` change the JSON facade's
+shape again for `EVALUATION` entries. `CHANGELOG.md` `[Unreleased]` updated in
+the same change.
+
+## 9.7 #38 (2026-09-10 ruling): the decision point widened to any leaf count
+
+The ruling on 9.5 allowed #38 to ride in 0.7.0 if it stayed on the same
+decision point, small, and green. It does: `TypeMap.assert_supported!` drops
+its `fields.size <= 1` early return, so *any* entry whose base resource is not
+`Observation` and which has no `ENTRY_ELEMENT_MAPS` row is skipped and
+reported -- a single leaf would have produced `<Resource>.value[x]`, which
+`Condition` / `ServiceRequest` / `Procedure` / `Encounter` lack just as they
+lack `component` (measured: 1 sushi Error on the 9.5 probe). The error message
+now names both missing elements and the leaf count in the singular where it is
+one. Resolution shape (a) bug.
+
+- **Fixture check before widening**: every OPT under `spec/templates/`,
+  `spec/generators/templates/` and `demo_assets/templates/` was listed with
+  `FieldExtractor#entries` -- all single-leaf entries are `OBSERVATION`
+  (`height.v2`, `body_weight.v2`, `heart_rate-pulse.v1`); the only
+  non-`Observation` entry is `problem_diagnosis.v1` (5 leaves, mapped). So no
+  fixture's output changes. (`spec/templates/sample_blood_pressure.opt` does not
+  parse at all -- `ArgumentError: invalid archetype id form` -- under openehr
+  2.4.2 *and* 2.4.3, and no spec references it; pre-existing, noted in
+  `docs/backlog.md`, not touched here.)
+- **Red**: 4 new examples (two per generator, synthetic single-leaf
+  `EVALUATION` entry `openEHR-EHR-EVALUATION.synthetic_single_leaf_test.v1`):
+  **40 examples, 4 failures** across the two spec files.
+- **Green**: the same files 40/0; `spec/openehr_rails/fhir/` 52/0; full suite
+  308/0. Regenerated FSH for `problem_list.opt` + `bmi_calculation.opt`
+  byte-identical to before and **0 Errors** under `sushi` 3.16.0 -- the pin.
+- **Semver**: 0.7.1 (0.7.0 shipped before PR #43 was merged; see log R13); a bug fix (patch) that changes no
+  fixture output, only what an unmapped single-leaf non-`Observation` entry
+  yields (invalid FHIR before, a `#skipped` entry now).

data/docs/design/rm-object-builder-section-instruction-plan.md

@@ -0,0 +1,134 @@
+# Plan: `RmObjectBuilder` reads back SECTION / INSTRUCTION / ACTIVITY
+
+- Status: **explore + plan, awaiting approval** (2026-09-25). No code written.
+- Issue: [#45](https://github.com/skoba/openehr-rails/issues/45) (anlage upstream candidate 15)
+- Log: `docs/reports/referral-upstream-log.md` R1
+- Prerequisite landed as its own fix: #44 / PR #50 (a failing `to_rm` no longer
+  fails the whole store; unknown types raise `UnsupportedRmTypeError`).
+
+## 1. Current behaviour (measured, `file:line` on `master` after PR #50)
+
+**Write side accepts the types.** `Rm::TypeMap::NODE_TYPES`
+(`lib/openehr_rails/rm/type_map.rb:9-26`) lists SECTION, INSTRUCTION, ACTION,
+ACTIVITY (and ITEM_SINGLE, ITEM_TABLE); the STI classes exist
+(`lib/openehr_rails/rm/nodes.rb:10,14,15,18`). `GraphBuilder#infer_type`
+(`lib/openehr_rails/rm/graph_builder.rb:111-122`) maps `activities` -> ACTIVITY and
+`protocol` / `description` -> ITEM_TREE for `_type`-less hashes. `build_children`
+(`:64-79`) persists Hash-valued attributes as child nodes or data-value rows and
+Array-valued ones as ordered children; **String-valued attributes are dropped** --
+so `ACTIVITY.action_archetype_id` never reaches the graph. `INSTRUCTION.narrative`
+(DV_TEXT), `ACTIVITY.timing` (DV_PARSABLE: `text_value` + `formalism`, `:180-181`)
+and `INSTRUCTION.expiry_time` (DV_DATE_TIME) are stored as data-value rows keyed by
+`rm_attribute_name`.
+
+**Read side does not.** `RmObjectBuilder::TYPE_CLASSES`
+(`lib/openehr_rails/rm/rm_object_builder.rb`, 10 entries) has none of them;
+`build_node` sets entry defaults only for Observation / Evaluation / AdminEntry,
+`data` only for `EntryNode`, and never `protocol`, `narrative`, `activities`,
+`description`. After PR #50 such a node raises `UnsupportedRmTypeError` and the
+composition is skipped from AQL with a warning; before it, the whole store failed
+(anlage referral-intake-log R6).
+
+**What the openehr gem (2.4.3) demands of the objects** (`openehr-ruby`
+`lib/openehr/rm/composition/content/`):
+
+| class | mandatory | optional / notes |
+|---|---|---|
+| `Navigation::Section` (`navigation.rb:12-27`) | -- | `items` must be nil or non-empty; `path_attribute :items` |
+| `Entry::Instruction` (`entry.rb:112-138`) | Entry: `language`, `encoding`, `subject`; `narrative` | `activities` nil or non-empty; `expiry_time`, `wf_definition`; CareEntry `protocol`, `guideline_id` (`entry.rb:69-78`); `path_attribute :activities, :protocol` |
+| `Entry::Activity` (`entry.rb:140-171`) | `description`, `action_archetype_id` (non-empty String) | `timing` optional since RM 1.1.0; `path_attribute :description` |
+| `Entry::Action` (`entry.rb:173-204`) | Entry attrs; `time`, `description`, `ism_transition` (with `current_state` validated against the openEHR terminology, `:236-275`) | out of scope here, see section 5 |
+
+`OpenEHR::RM::Composition::Composition` has `path_attribute :content, :context`,
+so objects built with the attributes above are navigable by the AQL engine's
+path evaluator without engine changes.
+
+## 2. Design -- phase A, no schema change
+
+1. `TYPE_CLASSES` gains `SECTION`, `INSTRUCTION`, `ACTIVITY`.
+2. `build_node` gains, per type (each in its own small private helper, because
+   `build_node` already sits at rubocop's AbcSize/complexity limits -- PR #50 had to
+   extract `node_class` for a one-line change):
+   - **Section**: `items` = children built in position order; `nil` when there
+     are none (the constructor rejects `[]`).
+   - **Instruction**: the same entry defaults as the other entries
+     (`language` / `encoding` / `subject`; extend the `is_a?` list);
+     `narrative` = the `narrative` data-value row as DvText, **defaulting to the
+     node's name** when the row is absent (an injected default, documented like
+     `language`); `activities` = children with `rm_attribute_name == 'activities'`,
+     `nil` when none; `expiry_time` when its row exists.
+   - **Activity**: `description` = the `description` child (ITEM_TREE) -- no
+     default: a missing description is an RM-conformance failure and surfaces
+     through #44's warning; `timing` = the `timing` row as
+     `OpenEHR::RM::DataTypes::Encapsulated::DvParsable` when present;
+     `action_archetype_id` = the injected default `'/.*/'` (the RM's "any ACTION
+     archetype" pattern) because the graph cannot carry it yet (section 5).
+   - **`protocol` for every CareEntry** (Observation, Evaluation, Instruction):
+     `attrs[:protocol] = build_node(protocol child)` when present. Same
+     mechanism, and it is where `jp_referral` keeps 紹介先/紹介元
+     (`service_request` `protocol[at0008]`, anlage memory of 2026-09-25) -- without
+     it the INSTRUCTION would be readable but its most-queried data not.
+3. `UnsupportedRmTypeError` keeps covering ACTION, ITEM_SINGLE, ITEM_TABLE.
+
+Injected defaults are listed in the class comment next to the existing ones.
+
+## 3. Spec plan (t-wada: red before green), resolution shape (b) enhancement
+
+- **Fixture**: a spec-level synthetic canonical hash (invented ids, stated in the
+  comment with this section as design authority; no real canonical JSON with
+  SECTION/INSTRUCTION exists in this repo -- anlage's is hand-mapped and outside):
+  COMPOSITION whose `content` is `[SECTION { items: [EVALUATION { data: ITEM_TREE {
+  items: [ELEMENT DV_TEXT] } }] }, INSTRUCTION { narrative, protocol: ITEM_TREE {
+  items: [ELEMENT DV_TEXT] }, activities: [ACTIVITY { description: ITEM_TREE {
+  items: [ELEMENT DV_TEXT] }, timing: DV_PARSABLE }] }]`, committed with
+  `CompositionCommitter`.
+- `rm_object_builder_spec.rb`: **red** today = `UnsupportedRmTypeError`; green =
+  `Section` with one `Evaluation` item; `Instruction` with the stored narrative,
+  one `Activity` whose `description.items.first.value` is the DvText,
+  `action_archetype_id == '/.*/'`, `protocol.items` present; entry defaults on the
+  Instruction.
+- `executor_spec.rb`: AQL through the new objects --
+  `SELECT i/activities[at0001]/description[at0009]/items[at0121]/value/value ...
+  CONTAINS INSTRUCTION i[<synthetic id>]` and
+  `SELECT i/protocol[at0008]/items[at0010]/value/value`, plus
+  `... CONTAINS SECTION s[<id>] CONTAINS EVALUATION ev[<id>]`. Whether the
+  engine's CONTAINS chain accepts SECTION/ACTIVITY is **unknown until measured**;
+  if it does not, that becomes an openehr-ruby item and the spec pins the `i/...`
+  path form only.
+- `dataset_adapter_spec.rb` / `executor_spec.rb` (#44): switch the "to_rm fails"
+  fixture from SECTION to ITEM_TABLE, which stays unsupported.
+- Regression pins: `bmi_calculation` / `problem_list` specs unchanged; full suite
+  green; `CanonicalSerializer` round-trip of the new fixture is checked and, if it
+  does not survive (`narrative` / `timing` rows), recorded as its own issue rather
+  than fixed here.
+
+## 4. Size and schedule
+
+Estimate: +3 map entries; ~50 lines of new helpers plus splitting `build_node`'s
+existing per-type `if` blocks into helpers (~80 lines moved, behaviour-neutral,
+needed to stay inside the rubocop limits); ~130 lines of specs across three files;
+no migration, no generator template change, no dependency change. **Small** by the
+ruling's criterion (same builder, one file of runtime code, existing test
+infrastructure). Recommendation: **implement before the freeze**, in one PR,
+`Fixes #45`, after this plan is approved.
+
+## 5. Out of scope (phase B, December unless pulled forward)
+
+- **Persisting `action_archetype_id`**, `narrative`, `timing` as columns instead
+  of injected defaults / data-value rows: needs a migration in
+  `lib/generators/**/templates/` (shipped product, host apps migrate) -- its own
+  issue and plan.
+- **ACTION**: `ism_transition` is persisted today as a generic CLUSTER node
+  (`infer_type` falls through), and rebuilding it needs codes valid against the
+  terminology; separate design.
+- **ITEM_SINGLE / ITEM_TABLE**: no consumer yet.
+
+## 6. Semver
+
+New read-side capability, observable through AQL and `to_rm`: **minor**. If it
+lands with #38 (PR #43) and #44 (PR #50), the next release is **0.8.0**, not 0.7.1
+-- to be decided at the inventory.
+
+## 7. Stop point
+
+Explore + plan only. Implementation starts on approval.