openehr-rails 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49c5536ccdf6abee6fb03aea4a4ed6002fc6402e6551d6f234b0e6a1a7b9200c
-  data.tar.gz: c36b2b1b58f60d22c2cbbbcb5754108bb3235f12737bd573103d2a3463a70618
+  metadata.gz: 69d9f917d3eb32a92e7d47aeb3f43bf8992a6a44f8ceb49320a1e5a6130ecebf
+  data.tar.gz: 1f39015dbd51241ea4dca624bd89e988a82bf62ef3a02964e54a343b6e8ccbf1
 SHA512:
-  metadata.gz: 0651aa4386933ccff02d230ab06d1eda996ca102da9b99ba2ebf09d3fde233ce7f08cea00b26644b744b92b647f917fe0e80dd6169fa158d9af19759c7db7f1b
-  data.tar.gz: 4358f499a80546004d5ca80b1ec542f2fe2d977a674461be36ee1afb288322717b71507978a50b1f7560edf1248835783f29e60b0bc874f164d8c4141bcc06a8
+  metadata.gz: 5acec88b6d3dee1ab32167080639a81052911eee90043ae09474e083fa0c92e081da69dade909848da04743cffc96603e887765a8efaff29d6172f873e93a074
+  data.tar.gz: 1c134c5a1147f54ee8628b62efdcfcb867f257f634a5094a4f0aacb2af460ac28cfcaa011457017610262686437041ec85045186f9c05acb034ed4080e6ec793

data/.github/ISSUE_TEMPLATE/bug_report.md

@@ -16,6 +16,9 @@ assignees: ''
 - `openehr` version: <!-- e.g. ~> 2.3 -->
 - Rails version: <!-- e.g. 8.1 -->
 - Ruby version: <!-- e.g. 3.3, 3.4, 4.0 -->
+- If the report involves an OPT/ADL file: the generating tool and its
+  version (e.g. Better Archetype Designer / Ocean Template Designer 2.6 /
+  ADL Workbench / LinkEHR / HMC).
 
 ## Reproduction
 

data/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-08-26
+
+### Added
+- `OpenehrRails::Fhir::FshGenerator` renders one FHIR Shorthand profile per
+  openEHR entry, including metadata, archetype codes, value constraints,
+  component slicing, quantity units, fixed terminology codes, and required
+  external value-set bindings. Observation-mapped output is Sushi-verified;
+  multi-leaf non-Observation entries have a known structural gap tracked as #33.
+
+### Changed
+- `FshGenerator` no longer depends on `active_support/core_ext/string`; the
+  three String helpers it used are now small plain-Ruby private methods,
+  verified byte-identical output. Restores the Rails-independence this class
+  was designed for (see `anlage`'s `docs/design/fsh-plan.md`), so it can move
+  wholesale to a future satellite gem without a Rails dependency riding along.
+
 ## [0.5.0] - 2026-08-25
 
 ### Added

data/CLAUDE.md

@@ -102,6 +102,25 @@ lasting effect, but the near-miss is what prompted this generalization. See
 logging the underlying structural fix under consideration - one
 worktree/session per repo instead of per-command vigilance.)
 
+## Cross-repository implementation work needs its own authorization gate
+
+The moment it becomes clear that the actual implementation target for a piece of
+work is a repository other than this one, stop before starting that work and insert
+a gate report confirming the implementation target, rather than sliding from
+read-only cross-repo reference (already permitted for design/evidence-gathering)
+into cross-repo write work on the strength of that same permission. Correctly
+targeting a command once you've decided to cross the boundary (the previous
+section's `cd`/`-C`/`-R` discipline) is a different concern from being authorized to
+cross it at all - following the operational convention precisely does not retroactively
+authorize the crossing.
+
+(Added 2026-08-26, alongside the `#32`/`#33` FSH-generator work continuation, to
+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.)
+
 ## Project Overview
 
 This is `openehr-rails`, a Rails engine gem that turns an openEHR Operational Template (`.opt`, ADL2/XML) into a working Rails resource in one command: `rails generate openehr:scaffold path/to/template.opt --fhir` emits a model, migration, controller, views, i18n locale, and (with `--fhir`) HL7 FHIR R5 `StructureDefinition` profiles. Generated models persist both as typed columns (for forms/search) and as full openEHR RM data (canonical JSON + a typed node graph with immutable-append versioning), and are queryable via a growing AQL surface. A mountable admin engine (`/openehr`) provides template upload/management, runtime scaffolding, and a FHIR R5 facade. Legacy ADL-archetype-only generators (model/controller/migration/helper/assets/i18n/template/template_model, based on `Openehr::Generators::ArchetypedBase`) have been removed — OPT is the only supported input format for scaffolding.

data/docs/backlog.md

@@ -34,6 +34,23 @@ actually running, not just present:
   push will reproduce the same red run. See "Release automation" below.
 - Most recent `master` push at the time of this record (`4055ec3`): CI run
   `32569774700`, success.
+- **Tag `v0.5.0` (2026-08-25, #30): `release.yml` run
+  [32831263811](https://github.com/skoba/openehr-rails/actions/runs/32831263811) --
+  overall conclusion **success**, all 12 jobs green (9 reused `ci.yml` spec-matrix
+  jobs, `demo smoke`, `application template smoke test`, `Build gem artifact`).**
+  First fully-green tag-push run on record -- confirms the "Release automation fix
+  landed (2026-08-23, PR #28)" note below actually fixed the structural red
+  described above, not just that the workflow file changed (`v0.4.1`/`v0.4.0`/`v0.3.0`
+  were all red at the now-removed RubyGems-publish step; `v0.5.0` has no such step to
+  fail at). Downloaded the run's `gem` artifact and independently built
+  `pkg/openehr-rails-0.5.0.gem` locally at the same tagged commit (`69db63f`): both
+  197632 bytes, identical sha256
+  `e07815bd1c86736403cbb558fec869fbe04666f695e6cc12a41dad9be77230e6`. RubyGems
+  publish (human `gem push`, per "Release automation" below) confirmed complete via
+  `https://rubygems.org/api/v1/versions/openehr-rails.json`: version `0.5.0`,
+  `created_at: 2026-08-25T09:26:15.342Z`, published `sha` field matches the same
+  sha256 above exactly -- local build, CI artifact, and the published gem are all
+  byte-identical.
 
 Recorded here after this file previously claimed "this repo currently has no CI
 workflow gating pull requests" — wrong on both existence and execution. This file is

data/docs/design/fsh-generator-plan.md

@@ -0,0 +1,113 @@
+# Enhancement: FshGenerator (FSH output alongside ProfileGenerator)
+
+- Status: draft, approved-by-citation (design decisions made upstream in
+  `skoba/anlage#17`, not re-litigated here)
+- Target: `openehr-rails` (this repo)
+- Issue: [#32](https://github.com/skoba/openehr-rails/issues/32)
+- Log: `docs/reports/fsh-generator-log.md`
+- Design authority: `skoba/anlage`'s `docs/design/fsh-plan.md` (2026-08-26
+  ruling, all 4 judgments approved) and `docs/reports/fsh-log.md` R1-R4.
+  This doc translates that already-approved plan into this repo's
+  file:line reality; it does not re-decide source/scope/output-form.
+
+## 1. Summary
+
+Add `OpenehrRails::Fhir::FshGenerator`, a sibling to
+`OpenehrRails::Fhir::ProfileGenerator` that renders FSH (FHIR Shorthand)
+text instead of a JSON StructureDefinition Hash, from the exact same
+input: `OpenehrRails::Opt::FieldExtractor#entries`. No independent OPT
+walk — this is the "share the intermediate representation" design
+anlage's plan settled on (rejecting a pathcards-based or
+independently-walking alternative as violating the no-double-derivation
+constraint).
+
+## 2. Input contract (already shipped, `skoba/openehr-rails#30` / 0.5.0)
+
+`FieldExtractor#entries[].fields[]` now always carries (verified live
+in `field_extractor.rb:160-177`, doc comment `field_extractor.rb:1-23`):
+
+- `value_set_uri`: `C_CODE_REFERENCE#reference_set_uri`, else `nil`
+- `code_bindings`: `[{system_uri:, code:}]`, else `[]` — not limited to
+  `DV_CODED_TEXT` (BMI's LOINC binding sits on a `DV_QUANTITY` element,
+  `CHANGELOG.md` [0.5.0] Added note)
+
+No further gem work is a prerequisite for this Issue.
+
+## 3. v1 scope (per the approved anlage plan, §"v1サブセットの範囲確定")
+
+Mirror exactly what `ProfileGenerator` already emits, in FSH syntax,
+plus binding writes (now unblocked):
+
+| JSON (`profile_generator.rb`) | FSH form |
+|---|---|
+| `build_profile` metadata (`:33-50`) | `Profile:`/`Parent:`/`Id:`/`Title:` header lines |
+| `code_element` (`:62-69`) | `* code.coding.system = ...` / `* code.coding.code = ...` (or a `patternCodeableConcept`-equivalent assignment — pick whichever Sushi compiles identically to the JSON shape; verify by comparing compiled output, not by assumption) |
+| `value_elements` (`:71-80`) | `* value[x] <min>..<max>` + `* value[x] only <Type>` |
+| `component_elements`/`component_slice` (`:82-113`) | slicing declaration (`^slicing.discriminator...`) + `* component contains <slice> <card>` + per-slice `code`/`value[x]` assignment (see anlage's `docs/reports/fsh-log.md` R1 for a working Sushi-verified example of this exact shape) |
+| `DV_QUANTITY` unit (`apply_value_constraints`, `:117-124`) | `* value[x].unit = "..."` (or equivalent fixed-value rule) |
+| `DV_CODED_TEXT` binding (`:125-131`, now includes `valueSet`) | `field[:value_set_uri]` present → `* value[x] from <uri> (required)`. `field[:code_bindings]` present (any rm_type) → fixed `patternCodeableConcept`-equivalent assignment per binding entry |
+
+Explicitly out of scope for v1 (matches the JSON facade's own gaps, not
+new ones introduced here): `magnitude_range` (extracted but never
+emitted by `ProfileGenerator` either — a separate, pre-existing gap).
+`mml_referral`-scale templates are out of v1's verification scope per
+the approved plan (size cap); this Issue's fixtures stay to the 3 small
+ones listed below.
+
+## 4. Fixtures (no new SNOMED literal budget — reuse what's already here)
+
+- `spec/generators/templates/bmi_calculation.opt` — single-leaf,
+  `DV_QUANTITY`, real SNOMED-CT (`60621009`) + LOINC `code_binding` on
+  `at0004` (`spec/templates/bmi_calculation_without_uid.opt:1683-1697`
+  for the byte-identical sibling with visible XML)
+- `spec/templates/problem_list.opt` — `C_CODE_REFERENCE`/ICD-11
+  `value_set_binding` on `at0002`, local `code_list` contrast on
+  `at0073` (byte-identical copy of anlage's `ProblemList.opt`,
+  provenance comment already in the file per `0bbbc47`)
+
+Both are already indexed by existing specs
+(`spec/openehr_rails/fhir/profile_generator_spec.rb`,
+`spec/openehr_rails/opt/field_extractor_binding_spec.rb`) — reuse the
+same `template` `let` pattern.
+
+## 5. TDD (t-wada, per this repo's CLAUDE.md)
+
+1. Red/Green: `FshGenerator` non-binding v1 subset against
+   `bmi_calculation.opt` — metadata, single-leaf `value[x]`, unit. Fix
+   the exact FSH text with a golden spec (string equality or a small
+   set of `include` assertions on stable substrings — match whichever
+   style `profile_generator_spec.rb` already uses for the JSON side)
+2. Red/Green: `code_binding` write against `bmi_calculation.opt`'s
+   `at0004` (SNOMED-CT `60621009` and/or the LOINC binding — pick
+   whichever demonstrates the fixed-value FSH form most clearly)
+3. Red/Green: `value_set_binding` write against `problem_list.opt`'s
+   `at0002` (ICD-11) — fix the `from <uri> (required)` line
+4. Red/Green: multi-leaf `component` slicing — `bmi_calculation.opt`'s
+   `openEHR-EHR-OBSERVATION.body_mass_index.v2` entry already has 2 leaf
+   fields (verified: `bundle exec ruby` with `FieldExtractor#entries`,
+   2026-08-26), and `at0004`'s SNOMED/LOINC `code_binding` sits inside
+   this same multi-leaf entry — one fixture covers both slicing and
+   binding for this case. No new fixture needed (`problem_list.opt` also
+   has 5 leaf fields, `lab_result_report_reduced.opt` has 3, for
+   reference)
+5. Manual verification (not part of this Issue's automated suite,
+   done once locally before closing): pipe generated FSH through
+   `fsh-sushi` and confirm 0 Errors, matching the shapes anlage already
+   verified by hand (`docs/reports/fsh-log.md` R1 in `skoba/anlage`)
+
+## 6. Structural note
+
+`FshGenerator` takes only `FieldExtractor#entries` (or a `template` it
+extracts from, same as `ProfileGenerator.new(template)`) — no
+`ActiveRecord::Base`/`Rails` dependency. This keeps it relocatable if a
+future `openehr-fhirbridge` satellite gem is split out (anlage
+`docs/backlog.md` item 5, not a decision made in this Issue).
+
+## 7. Out of scope here
+
+- CI wiring for Sushi verification (anlage-side decision, ruled out for
+  v1 — `docs/design/fsh-plan.md`'s 判断3 in `skoba/anlage`)
+- The `rake fsh:export` output path (anlage-side, `skoba/anlage`'s own
+  Issue #17 scope)
+- Any RubyGems release/publish step (human-gated per this repo's
+  `docs/backlog.md` "Release automation" / `skoba/openehr-rails#27`)

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

@@ -0,0 +1,180 @@
+# Fix: multi-leaf non-Observation entries constrain a nonexistent `component`
+
+- Status: draft, awaiting approval
+- 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)
+
+## 1. Bug summary (from the issue, re-confirmed directly)
+
+`TypeMap::ENTRY_RESOURCES` (`type_map.rb:12-18`) maps openEHR ENTRY types to five
+different FHIR R5 resources: `OBSERVATION`→`Observation`, `EVALUATION`→`Condition`,
+`INSTRUCTION`→`ServiceRequest`, `ACTION`→`Procedure`, `ADMIN_ENTRY`→`Encounter`.
+Only `Observation` has a `component` element in FHIR R5 — confirmed against the
+[FHIR R5 Observation resource definition](http://hl7.org/fhir/R5/observation.html);
+`Condition`/`ServiceRequest`/`Procedure`/`Encounter` have no equivalent repeatable
+slot for arbitrary additional codings/values. `ProfileGenerator#differential_elements`
+(`profile_generator.rb:52-60`) and `FshGenerator#build_profile`
+(`fsh_generator.rb:26-42`) both choose between a single-leaf `value[x]` path and a
+multi-leaf `component` path purely on `entry[:fields].size`, with no check for
+whether `resource_type` actually supports `component`. Confirmed via `sushi`:
+`problem_list.opt`'s 5-leaf `EVALUATION`→`Condition` entry produces 29
+`"No element found at path component..."` errors (matches the issue's own
+citation).
+
+This is **not EVALUATION-specific** — it affects any multi-leaf entry mapped to any
+of the four non-`Observation` resources. No existing fixture currently has a
+multi-leaf `INSTRUCTION`/`ACTION`/`ADMIN_ENTRY` entry, so those paths are untested
+today, but the same defect applies to them by construction.
+
+### Related latent dead code, found during this investigation
+
+`TypeMap.value_element(resource_type)` (`type_map.rb:53-58`):
+```ruby
+def value_element(resource_type)
+  resource_type == 'Observation' ? 'value[x]' : 'value[x]'
+end
+```
+Its own comment says "Single-leaf Observations use `value[x]`; everything else hangs
+off a component" — but the ternary returns the identical string on both branches, so
+it implements none of that. Confirmed via `grep`: **called nowhere in `lib/`** (the
+only other hits are unrelated local-variable names in `profile_generator_spec.rb`).
+This is exactly the resource-type branch this issue needs, stubbed and never wired
+up. Recommend removing it as part of this fix rather than leaving dead, misleading
+code that describes behavior it doesn't implement — see §3.
+
+## 2. Options considered
+
+**(a) FHIR Extension-based encoding for non-Observation multi-leaf entries.**
+Define a custom complex extension (its own `StructureDefinition`) to carry
+additional leaf values on `Condition`/`ServiceRequest`/`Procedure`/`Encounter`,
+sliced under `resource_type.extension`. This is the FHIR-canonical way to add
+structured data beyond a base resource's element set, and is the only option that
+actually *represents* the extra leaves rather than dropping or refusing them.
+**Rejected for this issue**: it requires designing and shipping a second
+`StructureDefinition` (the extension itself) with its own cardinality/binding/typing
+decisions that no prior art in this repo or `anlage`'s design docs addresses (checked
+directly: `anlage/docs/design/fsh-plan.md` only says "multi-leaf `component`
+slicing" as v1 scope, never anticipates the non-Observation case). Getting an
+extension's shape right is a real FHIR-modeling decision with downstream
+consequences for anyone consuming these profiles — not something to decide
+unilaterally inside a bug-fix issue. Worth a future issue of its own if a real
+`EVALUATION`/`INSTRUCTION`/`ACTION`/`ADMIN_ENTRY` multi-leaf template is actually
+needed by a consumer (none is, today — see §5).
+
+**(b) Split into multiple linked FHIR resources** (e.g. a primary `Condition` plus
+separate `Observation` resources per extra leaf, linked via `Observation.focus`).
+**Rejected**: changes the "one profile per ENTRY" architecture
+(`profile_generator.rb:8-11`'s own doc comment) into "one-to-many," a much larger
+structural change than this issue's scope, and duplicates concerns `#33`'s own
+"needs its own explore/plan" framing already flags as too large for this pass.
+
+**(c) Restrict multi-leaf profile generation to `Observation`-mapped entries; raise
+a clear, documented error for multi-leaf entries mapped elsewhere.** No data is
+silently dropped (an error beats silent corruption) and no unvetted FHIR-modeling
+decision is made. The limitation is explicit and testable end-to-end today.
+**Recommended** — see §3.
+
+## 3. Recommended fix: (c), restrict + explicit error
+
+- `TypeMap` gains a way to answer "does this resource type support `component`?" —
+  replace the dead `value_element` method (§1) with what it should have been:
+  ```ruby
+  COMPONENT_CAPABLE_RESOURCES = %w[Observation].freeze
+
+  def component_capable?(resource_type)
+    COMPONENT_CAPABLE_RESOURCES.include?(resource_type)
+  end
+  ```
+  (A one-element array reads oddly today, but names the actual FHIR fact this repo
+  has verified — `Observation` is the only R5 resource among the five in
+  `ENTRY_RESOURCES` with a `component` element — and gives future resource-type
+  additions one place to declare the same fact, rather than re-deriving it.)
+- `ProfileGenerator#differential_elements` (`profile_generator.rb:52-60`): when
+  `entry[:fields].size > 1` **and** `!TypeMap.component_capable?(resource_type)`,
+  raise a new `OpenehrRails::Fhir::UnsupportedProfileError` (or similar; exact class
+  name/placement to be finalized in implementation, not a design-doc-blocking
+  detail) with a message naming the entry's archetype id, resource type, and leaf
+  count — not a silent skip, not a partial/wrong profile.
+- `FshGenerator#build_profile` (`fsh_generator.rb:26-42`): same branch, same error
+  class — one shared decision point, not two independently-drifting ones. Consider
+  whether the check belongs in a shared location both classes call (e.g. a small
+  module method) rather than duplicated inline logic, to avoid the exact kind of
+  two-copies drift `#33` itself was born from (`ProfileGenerator` and
+  `FshGenerator` independently duplicating the same `size == 1` branch that neither
+  originally checked `resource_type` for).
+- **Where the error surfaces to a caller**: `ProfileGenerator#profiles` and
+  `FshGenerator#to_fsh_files` currently map over `@entries` unconditionally
+  (`profile_generator.rb:23-24`, `fsh_generator.rb:17-22`) — a raised error on one
+  entry would currently abort the whole batch, silently dropping profiles for
+  *other*, unaffected entries in the same template. Decide during implementation
+  whether that's acceptable (single-entry templates are today's only real fixtures)
+  or whether `profiles`/`to_fsh_files` should skip-and-report per-entry instead of
+  raising through the whole batch — flagging this as a design question for
+  approval, not deciding it here, since it changes both public methods' contracts
+  either way.
+
+## 4. Spec plan (t-wada: red before green)
+
+- New spec (both `ProfileGenerator` and `FshGenerator`, or a shared example group if
+  the check ends up in one shared place per §3): parsing `problem_list.opt`
+  (5-leaf `EVALUATION`→`Condition`) and calling `.profiles`/`.to_fsh_files` raises
+  the new error, with a message that names the archetype id. **Red** today: no
+  error is raised; instead a differential/FSH referencing a nonexistent `component`
+  path is silently produced. **Enhancement** resolution kind (new documented
+  behavior, not a pre-existing property being pinned).
+- Regression pin: `bmi_calculation.opt`'s multi-leaf `Observation`-mapped entry
+  (`body_mass_index.v2`, 2 leaves) is unaffected — existing
+  `profile_generator_spec.rb`/`fsh_generator_spec.rb` coverage of this fixture
+  already exercises it; confirm those specs still pass unchanged (they should, this
+  fix only adds a new branch for the non-capable-resource case).
+- FSH-side confirmation per the issue's own acceptance criteria: after the fix,
+  regenerate FSH for `bmi_calculation.opt` and pipe through `sushi` again — expect
+  the same 0 Errors/0 Warnings as R2/R3 already established, unchanged.
+  `problem_list.opt` no longer produces any FSH to compile (it raises instead), so
+  there's nothing left to feed `sushi` for that fixture — satisfies the acceptance
+  criterion's spirit (no invalid FSH exists for a case that can't be represented
+  correctly yet) without a false claim of validity.
+
+## 5. Compatibility, scope, and semver
+
+- **No existing fixture regresses**: no repo fixture has a multi-leaf
+  `INSTRUCTION`/`ACTION`/`ADMIN_ENTRY` entry today, and `problem_list.opt`'s
+  `EVALUATION` entry going from "silently wrong" to "clear error" is a bug fix, not
+  a behavior anyone could have been relying on (the prior output was invalid FHIR).
+- **Host-app impact**: any host app that scaffolded `--fhir` output from a
+  multi-leaf `EVALUATION`/`INSTRUCTION`/`ACTION`/`ADMIN_ENTRY` template today has a
+  silently-broken generated profile already (confirmed for `EVALUATION` via
+  `sushi`; the other three are the same code path). This fix surfaces that as a
+  loud error on regeneration rather than continuing to ship invalid output.
+  `CHANGELOG.md` should say this plainly.
+- **Semver**: raising a new, previously-unraised exception for input that already
+  produced semantically-invalid output is a bug fix — **patch**, not minor (no new
+  public API surface is added for callers to use; `UnsupportedProfileError`, if
+  it becomes part of the public interface at all, is something callers only see
+  when hitting the previously-broken case, not a new capability to opt into).
+- **`docs/reports/fsh-generator-log.md`** continues as this fix's progress log
+  (already tracking `#32`/`#33` as one continuing thread).
+
+## 6. Open questions for approval
+
+1. Confirm option (c) (restrict + explicit error) over (a)/(b) — recommended, but
+   this is the actual FHIR-modeling judgment call this design doc exists to get
+   signed off on.
+2. Per-entry error handling in `profiles`/`to_fsh_files` (§3's last bullet): raise
+   through the whole batch, or skip-and-report per entry? No existing fixture has
+   more than one entry per template that would surface this distinction today, so
+   either choice is currently unobservable in this repo's own fixtures — pick the
+   simpler one (raise-through) unless there's a reason to prefer graceful
+   degradation now.
+3. Exact error class name/namespace (`OpenehrRails::Fhir::UnsupportedProfileError`
+   suggested, not fixed).
+
+## 7. Stop point
+
+Explore + design only, per this repo's ticket-driven workflow. Do not implement
+until this document is approved. Next steps after approval: implement (Codex per
+this repo's division of labor, or directly if the change is judged small enough to
+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.

data/docs/reports/binding-extraction-log.md

@@ -343,3 +343,69 @@ section). So tagging `v0.5.0` and pushing the tag is lower-risk than it might so
 publishing to RubyGems is a distinct, later, human-executed step. This would also be
 the **first real tag to exercise PR #28's fixed release path end-to-end** -- its own
 body deferred that verification to "the next real release (>= 0.5.0)," which this is.
+
+## R8 -- v0.5.0 tagged, release.yml verified green, artifact reproducibility confirmed
+
+User approved tagging. Executed:
+
+1. `lib/openehr_rails/version.rb` bumped `0.4.1` -> `0.5.0`; `CHANGELOG.md`'s
+   `[Unreleased]` retitled to `## [0.5.0] - 2026-08-25` (fresh empty `[Unreleased]`
+   left above it), matching the exact pattern the `0.4.1` release-bump commit used
+   (`2cddb0d`, verified by reading its diff directly rather than guessing the
+   convention). Full suite re-run after the bump: 275 examples, 0 failures.
+   `bundle exec rake release:check` failed first (dirty tree, expected -- the check
+   requires a clean tree), then passed clean after committing (`69db63f`, pushed).
+   `git tag -a v0.5.0` (annotated, full CHANGELOG-derived message) and
+   `git push origin v0.5.0`.
+
+2. **`release.yml` run verified green end-to-end** -- GitHub Actions run
+   [32831263811](https://github.com/skoba/openehr-rails/actions/runs/32831263811),
+   triggered by the `v0.5.0` tag push. Overall conclusion: **success** (confirmed via
+   the run's own `conclusion` field, not inferred from individual step icons). All 12
+   jobs green: the 9 reused `ci.yml` spec-matrix jobs, `demo smoke`, `application
+   template smoke test`, and `Build gem artifact` (its `release:check`, `Build gem`,
+   and `Upload gem artifact` steps all succeeded). This is the **first tag-push run
+   with a fully green overall conclusion** -- `v0.4.1`
+   (`32550344344`) and `v0.4.0` (`31660884406`) were both structurally red at the
+   now-removed RubyGems-publish step (`docs/backlog.md` "CI status" section); that
+   step no longer exists in `release.yml` (PR #28), and this run empirically confirms
+   its removal actually fixed the red -- not just that the workflow file changed.
+
+3. **Artifact/local-build reproducibility confirmed** -- downloaded the run's `gem`
+   artifact (`gh run download 32831263811 -n gem`):
+   `openehr-rails-0.5.0.gem`, 197632 bytes, sha256
+   `e07815bd1c86736403cbb558fec869fbe04666f695e6cc12a41dad9be77230e6`. Ran
+   `bundle exec rake build` locally at the same tagged commit (`69db63f`, clean
+   tree): `pkg/openehr-rails-0.5.0.gem`, same size, **identical sha256**. CI's
+   built artifact and a local build from the same commit are byte-identical --
+   confirms build reproducibility, not just "both builds succeeded."
+
+RubyGems publish is next: per condition, that remains a deliberate human `gem push`
+step (established operating model, `docs/backlog.md` "Release automation"), not
+something this session executes -- the sha256 above is the value to check the
+locally-published gem against before/after `gem push`, and after publish confirms.
+Awaiting that confirmation before the final backlog/CHANGELOG follow-up (condition 5)
+and returning to dormancy.
+
+## R9 -- RubyGems publish confirmed, backlog updated, dormant
+
+User reported publish complete. Verified directly rather than trusting the report at
+face value: queried `https://rubygems.org/api/v1/versions/openehr-rails.json`.
+`openehr-rails` `0.5.0` is listed, `created_at: 2026-08-25T09:26:15.342Z`, and its
+published `sha` field (`e07815bd1c86736403cbb558fec869fbe04666f695e6cc12a41dad9be77230e6`)
+matches R8's CI-artifact and local-build sha256 exactly -- full chain confirmed
+byte-identical: local build == CI artifact == published gem.
+
+Added a bullet to `docs/backlog.md`'s "CI status" section recording the `v0.5.0`
+tag run (first fully-green tag-push run, confirming PR #28's release-path fix)
+and the three-way sha256 match including the now-confirmed RubyGems listing.
+Verified `CHANGELOG.md`'s `[0.5.0] - 2026-08-25` section is correctly finalized
+with a fresh empty `[Unreleased]` above it -- no further edit needed. Full suite
+re-confirmed green (275 examples, 0 failures) before this commit.
+
+**Issue #30 fully closed out**: filed, designed, implemented (Codex + independent
+review), merged, released as `0.5.0`, published to RubyGems, and the upstream
+knowledge shared back to `skoba/openehr-ruby#31`. `anlage`'s FSH export
+(`skoba/anlage#17`) can now pick up `field[:value_set_uri]`/`field[:code_bindings]`
+via a normal `bundle update` -- the consumption prerequisite flagged in R7 is
+satisfied. Returning to dormancy.

data/docs/reports/fsh-generator-log.md

@@ -0,0 +1,317 @@
+# FshGenerator progress log
+
+R1〜.
+
+---
+
+## R1 -- Filing and design doc (Step 0-1)
+
+Filed `skoba/openehr-rails#32` (goal Issue). Design authority is
+`skoba/anlage`'s already-approved `docs/design/fsh-plan.md`
+(2026-08-26 ruling) -- this Issue implements that plan's gem-level
+commit split, not a fresh design.
+
+Confirmed the input contract this Issue depends on is already live
+(`skoba/openehr-rails#30`, shipped 0.5.0): `FieldExtractor#entries[].
+fields[]` always carries `value_set_uri` and `code_bindings`
+(`field_extractor.rb:160-177`).
+
+Checked fixture leaf-field counts directly (`bundle exec ruby` with
+`require 'active_record'; require 'openehr_rails'` -- `openehr_rails`
+needs ActiveRecord loaded first, this repo has no `bin/rails`):
+
+- `bmi_calculation.opt` / `bmi_calculation_without_uid.opt`: `height.v2`
+  (1 leaf), `body_weight.v2` (1 leaf), `body_mass_index.v2` (**2
+  leaves** -- and `at0004` already carries real SNOMED-CT (`60621009`)
+  + LOINC `code_binding`, so this one entry covers both multi-leaf
+  `component` slicing and code_binding in a single fixture)
+- `problem_list.opt`: `problem_diagnosis.v1`, 5 leaves;
+  `value_set_binding` (ICD-11) on `at0002`
+- `lab_result_report_reduced.opt`: `laboratory_test_result.v1`, 3 leaves
+- `sample_blood_pressure.opt`: crashes on parse (`ArgumentError:
+  invalid archetype id form`, pre-existing and unrelated to this
+  Issue -- not investigated further, not needed for this fixture set)
+
+No new SNOMED literal budget needed -- all binding demonstrations reuse
+codes already checked into this repo's fixtures.
+
+Design doc written: `docs/design/fsh-generator-plan.md`. Proceeding to
+implementation (Codex, reviewed and committed by Claude Code per this
+repo's division of labor).
+
+---
+
+## R2 -- Implementation, two correction rounds, commit `5f669af` (2026-08-26)
+
+### Round 0: Codex's first delivery
+
+Codex implemented `FshGenerator` covering the full v1 scope table.
+Self-reported: "SUSHI 3.16.0 was present, but could not finish loading
+its R5 package under restricted network access" -- Codex's own sandbox
+could not actually verify the generated FSH compiles. Claude Code has
+unrestricted network access in this session and re-verified directly.
+
+### Round 1 finding: conflicting CodeableConcept assignments
+
+Regenerated FSH from Codex's actual committed code (not a
+paraphrase) and piped it through `sushi` (v3.16.0, real local install)
+myself. `bmi_calculation.opt`'s `body_mass_index.v2` (2 code_bindings
+on `at0004`: SNOMED-CT + LOINC) produced:
+
+```
+error Cannot assign http://snomed.info/sct to this element; a different
+uri is already assigned: "http://openehr.org/ckm/archetypes".
+error Cannot assign http://loinc.org to this element; a different uri
+is already assigned: "http://openehr.org/ckm/archetypes".
+```
+
+Root cause: the original `binding_rules` wrote one `* path =
+SYSTEM#code` fixed-value assignment per `code_bindings` entry, stacked
+after the archetype_id anchor's `.coding.system`/`.coding.code` pair.
+`* path = SYSTEM#code` is FSH shorthand for fixing an *entire*
+CodeableConcept to one coding -- writing it twice (or after an
+existing `.coding.system`/`.coding.code` pair) is a conflicting
+reassignment of the same slot, not an append.
+
+Explored the fix space empirically (all runs actually compiled with
+`sushi`, not assumed):
+- `code.coding[0]`/`code.coding[1]` explicit indexing without a prior
+  slicing declaration: **fails** ("No element found at path
+  code.coding[0]") -- FHIR profile differentials don't support
+  indexing into an un-sliced repeating element this way.
+- `code.coding[+]`/`[=]` append syntax, same issue: **fails**,
+  identical error.
+- Unindexed `code.coding.system = X` / `code.coding.code = Y` alone
+  (no second coding attempted): **compiles** (0 Errors) -- but this
+  form sets a *pattern* on the coding sub-elements
+  (`patternUri`/`patternCode` in the resulting differential), not an
+  indexed instance value, which is why indexing on top of it doesn't
+  work.
+- **Slicing `code.coding` by the `system` value discriminator, one
+  named slice per source** (`ckm` for the archetype_id anchor, one per
+  `code_bindings` entry, using the terminology alias downcased as the
+  slice name): **compiles, 0 Errors**, both standalone (`code.coding`)
+  and nested inside a `component[slice].code.coding` path. This is the
+  fix that shipped.
+
+Sent Codex the exact verified-working FSH pattern (both the standalone
+and nested-in-component forms, copy-pasteable) plus the failing
+pattern and its error, and asked for a rewrite -- not a vague "fix the
+conflict" instruction. Codex's fix matches: `code_rules` now branches
+on whether `bindings` is empty (`simple_code_rules`, unchanged
+unindexed form) vs non-empty (new sliced form via `binding_slices`).
+
+### Round 2 finding: `component` doesn't exist on `Condition`
+
+Re-verified again after the round-1 fix -- `bmi_calculation.opt`
+(all-`Observation` entries) now compiles with **0 Errors**, confirmed
+independently (regenerated from the committed code, not from Codex's
+pasted example). `problem_list.opt` (single `EVALUATION` entry, 5
+leaves) does not: **29 errors**, all `"No element found at path
+component..."` for `Condition`.
+
+Root cause: `TypeMap::ENTRY_RESOURCES` maps `EVALUATION` → `Condition`
+(`type_map.rb:14`). `Condition` has no `component` element -- that's
+`Observation`-specific in FHIR R5. `FshGenerator`'s multi-leaf branch
+(mirroring `ProfileGenerator#component_elements`) always emits
+`component`-path rules whenever `entry[:fields].size > 1`, with no
+check for whether the target `resource_type` actually has a
+`component` slot. This is a **pre-existing gap**, not something this
+Issue introduced -- `ProfileGenerator`'s JSON output for the same
+fixture almost certainly has the identical semantic defect, just never
+caught (JSON isn't schema-validated the way FSH is by Sushi, and
+`profile_generator_spec.rb` only exercises all-`Observation` fixtures).
+
+Filed separately: `skoba/openehr-rails#33`. Out of scope for `#32` --
+needs its own explore/plan (candidate directions: an extension,
+restricting multi-leaf support to `Observation`-mapped entries with an
+explicit documented limitation, or something else not yet decided).
+
+Narrowed `#32`'s scope to match reality rather than over-claim: added
+a 2-line code comment on the multi-leaf branch citing `#33`, and a
+CHANGELOG note distinguishing "Observation-mapped output is
+Sushi-verified" from "multi-leaf non-Observation entries have a known
+gap tracked as #33". The `value_set_binding` spec assertion for
+`problem_list.opt` stays as a text-level substring check (the `from
+<uri> (required)` write itself is correct FSH, verified in isolation
+in `docs/reports/fsh-log.md` R1 in `skoba/anlage`) -- it does not claim
+whole-document Sushi compilation, which would be false for this
+fixture.
+
+### Final verification (Claude Code, independent of Codex's own reports)
+
+- Regenerated FSH from the final committed `fsh_generator.rb` for both
+  `bmi_calculation.opt` and `problem_list.opt`, piped each through
+  `sushi` directly: **0 Errors** for `bmi_calculation.opt` (3
+  profiles), **29 errors** for `problem_list.opt` (expected, tracked
+  as `#33`, not a regression from anything this Issue claims)
+- `bundle exec rspec spec/openehr_rails/fhir/`: 28 examples, 0 failures
+- `bundle exec rspec` (full suite, this session's own environment, not
+  Codex's more restricted sandbox): **281 examples, 0 failures** --
+  the 18 failures Codex reported (`Errno::EPERM`/`getifaddrs` in
+  remote-fetch specs) did not reproduce here, consistent with this
+  project's prior observation that this class of sandbox network
+  restriction doesn't reproduce on GitHub Actions runners either
+- `bundle exec rubocop`: 108 files, no offenses
+- Committed `5f669af`, pushed, CI run verified green (see bundle
+  report for run ID)
+
+### Closure
+
+`#32`'s acceptance criteria are met for the scope that's actually
+Sushi-clean (`Observation`-mapped entries). `#33` tracks the
+`Condition`/`component` gap as separate follow-up work, not a blocker
+for closing `#32`.
+
+---
+
+## R3 -- Remove active_support from FshGenerator (0.6.0 task, condition 1)
+
+Codex's `#32` delivery required `active_support/core_ext/string` for three
+`String` methods (`camelize`, `humanize`, `parameterize.dasherize`),
+violating the structural clause `anlage`'s `docs/design/fsh-plan.md`
+already committed to (追記1, 2026-08-26): FshGenerator must depend on
+`openehr` only (Rails-independent), so it can move wholesale to the
+future `openehr-fhirbridge` satellite gem -- explicitly named review
+criterion: no dependency on `ActiveRecord::Base` or the `Rails`
+namespace. `require 'active_support/core_ext/string'` doesn't touch
+either directly, but ActiveSupport is Rails-family tooling, not
+`openehr`-only; the clause's spirit is what's being restored here, not a
+literal `ActiveRecord::Base`/`Rails` grep hit.
+
+Measured exact behavior before replacing anything (not guessed): ran the
+three ActiveSupport methods against representative inputs directly, then
+cross-checked plain-Ruby candidate replacements against every entry from
+every fixture this generator is exercised against (`bmi_calculation.opt`,
+`bmi_calculation_without_uid.opt`, `problem_list.opt`,
+`lab_result_report_reduced.opt`) -- all matched exactly, including the
+one non-obvious case: `.parameterize` alone leaves internal underscores
+intact (`"OBSERVATION.body_mass_index.v2".parameterize` =>
+`"observation-body_mass_index-v2"`); `.dasherize` afterward is doing real
+work (not redundant), converting those to `"observation-body-mass-index-v2"`.
+
+Replaced with three small private helpers (`camelize`, `humanize`,
+`parameterize`) matching the measured behavior. Re-verified with `sushi`
+after the change, not just `rspec`: `bmi_calculation.opt` still 0
+Errors/0 Warnings (3 profiles), `problem_list.opt` still exactly 29
+errors (unchanged `#33` gap). Full suite: 281 examples, 0 failures.
+RuboCop clean. Committed directly to `master` (`0181f7f`, tiny/self-
+contained per the task's own "極小コミット" framing -- no separate
+issue/branch/PR, matching this repo's docs-and-tooling-adjacent-fix
+precedent for changes that don't touch public API or behavior).
+
+`ProfileGenerator` still requires `active_support/core_ext/string` --
+explicitly out of scope: it isn't planned for extraction to
+`openehr-fhirbridge` on its own, so the structural clause doesn't bind it.
+
+---
+
+## R4 -- Release inventory (v0.5.0..master) and 0.6.0 proposal (condition 3)
+
+Classified every non-merge commit since `v0.5.0` (8 commits; per-commit
+file lists pulled via `git log --name-only`, not asserted from memory):
+
+- **Neutral (6 commits)**: `19c905f`, `0d2a8ce` (docs, #30 closeout),
+  `ec019b4` (`.github/ISSUE_TEMPLATE/bug_report.md` only -- dev-tooling
+  config), `f7cc0eb` (design doc + report log), `a996ef4` (report log),
+  `7e8014f` (`CLAUDE.md` + report log).
+- **`5f669af`** (adds `FshGenerator`): new file, new public class
+  (`OpenehrRails::Fhir::FshGenerator`, public `to_fsh_files`), touches
+  `lib/openehr_rails.rb` to require it. New backward-compatible public
+  API surface -- **minor**.
+- **`0181f7f`** (drops `active_support` from `FshGenerator`): touches
+  `lib/` directly but verified byte-identical output (R3 above) -- no
+  new capability, no behavior change, no public API change, no gemspec
+  dependency change. Per this repo's own release convention ("a commit
+  touching shipped runtime code is at minimum patch, even when its
+  observable behavior is unchanged"), classified **patch**.
+
+Overall: the range's highest-level commit dominates -- **minor**, i.e.
+`v0.5.0 -> v0.6.0`. No breaking changes; `FshGenerator` is net-new so
+there's no existing consumer to break. `CHANGELOG.md`'s `[Unreleased]`
+content matches (Added: FshGenerator; Changed: the active_support
+removal -- the latter's entry was missing and added in `4b595ca` while
+preparing this inventory, since this repo's convention writes CHANGELOG
+entries at merge/commit time and it had been skipped when `0181f7f`
+landed).
+
+No downstream-consumption blocker analogous to R7's anlage-FSH note is
+outstanding for this release -- `anlage`'s FSH work is what's consuming
+`FshGenerator` itself, and per condition 4 of this task, the immediate
+next step after this release is `#33`'s own explore/plan, not a
+release-gated anlage dependency.
+
+Proceeding to version bump, CHANGELOG finalization, and tag per the
+task's condition 3 -- same mechanical process as R8/R9 for `v0.5.0`,
+already reused rather than re-derived.
+
+## R5 -- v0.6.0 tagged, release.yml verified green, artifact reproducibility confirmed
+
+Caught and fixed a missing `CHANGELOG.md` entry for `0181f7f` (the
+active_support removal) while preparing the version bump -- added a
+`### Changed` note (`4b595ca`), full suite re-confirmed green first.
+
+`lib/openehr_rails/version.rb` bumped `0.5.0` -> `0.6.0`;
+`CHANGELOG.md`'s `[Unreleased]` retitled `## [0.6.0] - 2026-08-26` (fresh
+empty `[Unreleased]` left above). Full suite: 281 examples, 0 failures.
+Full-repo RuboCop (not just the touched files): 108 files, no offenses.
+`bundle exec rake release:check`: OK on the first try (tree was already
+clean from the prior commit). Committed (`4080053`), pushed, annotated
+tag `v0.6.0` pushed.
+
+`release.yml` run [32915373663](https://github.com/skoba/openehr-rails/actions/runs/32915373663):
+overall conclusion **success** (confirmed via the run's own `conclusion`
+field), all 12 jobs green -- second consecutive fully-green tag-push run,
+same as `v0.5.0`'s (R8), confirming the release-path fix (PR #28) holds
+across releases, not just as a one-off.
+
+Artifact/local-build reproducibility, same method as R8: downloaded the
+run's `gem` artifact (`gh run download 32915373663 -n gem`):
+`openehr-rails-0.6.0.gem`, sha256
+`08cdd14ab1f3890b0c6b5f0ae0d5ca55615f0b4874ed5efb0cd4d7bda9e573ca`. Built
+`pkg/openehr-rails-0.6.0.gem` locally at the same tagged commit
+(`4080053`, clean tree): **identical sha256**. CI artifact and local
+build byte-identical, second release in a row.
+
+RubyGems publish is the human's step next (established operating model,
+unchanged from `v0.5.0`) -- the sha256 above is what to check the
+published gem against. Awaiting that confirmation, then per condition 4
+of the task moving on to `#33`'s explore/plan (already directed, not a
+new decision to make here) and returning to dormancy in the meantime.
+
+## R6 -- #33 explore + design doc (condition 4)
+
+Read the issue directly (`gh issue view 33 --json ...`, not summarized
+from memory) and the current `type_map.rb`/`profile_generator.rb`/
+`fsh_generator.rb` source. Confirmed independently against the FHIR R5
+spec: only `Observation` has a `component` element among the five
+resources `TypeMap::ENTRY_RESOURCES` maps to -- the bug is not
+`EVALUATION`-specific, it affects any multi-leaf entry mapped to
+`Condition`/`ServiceRequest`/`Procedure`/`Encounter` (no existing
+fixture exercises the latter three multi-leaf, so only `EVALUATION` is
+empirically confirmed today, but the defect applies by construction).
+
+Found a related dead-code smell while reading `type_map.rb`:
+`TypeMap.value_element(resource_type)` has a comment describing exactly
+the resource-type branch `#33` needs, but its ternary returns the same
+string on both branches and the method is called nowhere in `lib/`
+(confirmed via `grep`) -- a stub for this exact check that was never
+wired up. Recommending its removal/replacement as part of this fix
+rather than leaving misleading dead code.
+
+Checked `anlage`'s `docs/design/fsh-plan.md` directly for prior art on
+this exact problem before designing from scratch -- none exists; the v1
+scope only anticipated `component` slicing, never the non-Observation
+resource-type mismatch.
+
+Design doc written: `docs/design/multi-leaf-non-observation-plan.md`.
+Three options considered (FHIR extension encoding / split into linked
+resources / restrict-to-Observation with an explicit error);
+**recommending the third** -- no unvetted FHIR-modeling decision made
+unilaterally, no silent data loss, verifiable end-to-end today with the
+tools already in hand (`sushi`). Two genuine judgment calls flagged for
+approval rather than decided here: the option choice itself, and whether
+`profiles`/`to_fsh_files` should raise through the whole batch or
+skip-and-report per entry when one entry hits the restriction.
+
+Gate: reporting to the user for approval before implementation.

data/lib/openehr_rails/fhir/fsh_generator.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module OpenehrRails
+  module Fhir
+    # Generates one FHIR Shorthand profile per openEHR ENTRY.
+    class FshGenerator
+      ARCHETYPE_SYSTEM = 'http://openehr.org/ckm/archetypes'
+      TERMINOLOGY_ALIASES = {
+        'SNOMED-CT' => ['SNOMEDCT', 'http://snomed.info/sct'],
+        'LOINC' => ['LOINC', 'http://loinc.org']
+      }.freeze
+
+      def initialize(template)
+        @entries = OpenehrRails::Opt::FieldExtractor.new(template).entries
+      end
+
+      def to_fsh_files
+        @entries.to_h do |entry|
+          id = profile_id(entry[:archetype_id])
+          [id, build_profile(entry, id)]
+        end
+      end
+
+      private
+
+      def build_profile(entry, id)
+        resource_type = TypeMap.resource_for_entry(entry[:rm_type])
+        lines = alias_rules(entry[:fields])
+        lines << '' unless lines.empty?
+        lines.concat(metadata(entry, id, resource_type))
+        if entry[:fields].one?
+          field = entry[:fields].first
+          lines.concat(code_rules(entry[:archetype_id], 'code', field[:code_bindings]))
+          lines.concat(value_rules('value[x]', field))
+        else
+          # Multi-leaf non-Observation resources may not expose component;
+          # this pre-existing ProfileGenerator structural gap is tracked in #33.
+          lines.concat(code_rules(entry[:archetype_id]))
+          lines.concat(component_rules(entry[:fields]))
+        end
+        "#{lines.join("\n")}\n"
+      end
+
+      def alias_rules(fields)
+        bindings = fields.flat_map { |field| field[:code_bindings] }
+        return [] if bindings.empty?
+
+        aliases = [['CKM', ARCHETYPE_SYSTEM]]
+        aliases.concat(bindings.filter_map { |binding| TERMINOLOGY_ALIASES[binding[:system_uri]] })
+        aliases.uniq.map { |name, uri| "Alias: #{name} = #{uri}" }
+      end
+
+      def metadata(entry, id, resource_type)
+        [
+          "Profile: #{camelize(id.tr('-', '_'))}",
+          "Parent: #{resource_type}",
+          "Id: #{id}",
+          "Title: \"openEHR #{humanize(entry[:concept])} (#{entry[:archetype_id]})\"",
+          ''
+        ]
+      end
+
+      # Plain-Ruby equivalent of ActiveSupport's String#camelize on an
+      # underscore-separated input: "foo_bar" -> "FooBar".
+      def camelize(str)
+        str.split('_').map { |word| word[0].upcase + word[1..].to_s }.join
+      end
+
+      # Plain-Ruby equivalent of ActiveSupport's String#humanize on an
+      # already-lowercase, underscore-separated input: "foo_bar" -> "Foo bar".
+      def humanize(str)
+        spaced = str.tr('_', ' ')
+        spaced[0] ? spaced[0].upcase + spaced[1..].to_s.downcase : spaced
+      end
+
+      def code_rules(archetype_id, path = 'code', bindings = [])
+        return simple_code_rules(archetype_id, path) if bindings.empty?
+
+        coding_path = "#{path}.coding"
+        slices = ['ckm 1..1', *binding_slices(bindings).map { |slice, _| "#{slice} 0..1" }]
+        [
+          "* #{coding_path} ^slicing.discriminator.type = #value",
+          "* #{coding_path} ^slicing.discriminator.path = \"system\"",
+          "* #{coding_path} ^slicing.rules = #open",
+          "* #{coding_path} contains #{slices.join(' and ')}",
+          "* #{coding_path}[ckm] = CKM##{archetype_id}",
+          *binding_slices(bindings).map do |slice, binding|
+            alias_name = TERMINOLOGY_ALIASES.fetch(binding[:system_uri]).first
+            "* #{coding_path}[#{slice}] = #{alias_name}##{bare_code(binding[:code])}"
+          end
+        ]
+      end
+
+      def simple_code_rules(archetype_id, path)
+        [
+          "* #{path}.coding.system = \"#{ARCHETYPE_SYSTEM}\"",
+          "* #{path}.coding.code = ##{archetype_id}"
+        ]
+      end
+
+      def component_rules(fields)
+        rules = [
+          '* component ^slicing.discriminator.type = #pattern',
+          '* component ^slicing.discriminator.path = "code"',
+          '* component ^slicing.rules = #open'
+        ]
+        fields.each do |field|
+          slice_name = field[:name].downcase.gsub(/[^a-z0-9]/, '')
+          path = "component[#{slice_name}]"
+          rules << "* component contains #{slice_name} #{field[:required] ? 1 : 0}..1"
+          rules.concat(
+            code_rules(
+              "#{field[:archetype_id]}##{field[:node_id]}",
+              "#{path}.code",
+              field[:code_bindings]
+            )
+          )
+          rules.concat(value_rules("#{path}.value[x]", field))
+        end
+        rules
+      end
+
+      def binding_slices(bindings)
+        bindings.filter_map do |binding|
+          terminology = TERMINOLOGY_ALIASES[binding[:system_uri]]
+          next unless terminology
+
+          [terminology.first.downcase, binding]
+        end
+      end
+
+      # OPT term bindings wrap codes as `[TERMINOLOGY(version)::code]` (the
+      # version is optional). FSH needs only the code after the final `::`.
+      def bare_code(raw_code)
+        raw_code.to_s.sub(/\A\[.*::/, '').delete_suffix(']')
+      end
+
+      def value_rules(path, field)
+        rules = [
+          "* #{path} only #{TypeMap.datatype_for(field[:rm_type])}"
+        ]
+        rules.unshift("* #{path} #{field[:required] ? 1 : 0}..1") if path == 'value[x]'
+        rules << "* #{path}.unit = \"#{field[:units]}\"" if field[:rm_type] == 'DV_QUANTITY' && field[:units]
+        rules << "* #{path} from #{value_set_uri(field[:value_set_uri])} (required)" if field[:value_set_uri]
+        rules
+      end
+
+      # C_CODE_REFERENCE uses `terminology:<canonical>` in OPT; FSH binding
+      # targets use the canonical itself.
+      def value_set_uri(uri)
+        uri.delete_prefix('terminology:')
+      end
+
+      def profile_id(archetype_id)
+        "openehr-#{parameterize(archetype_id.delete_prefix('openEHR-EHR-'))}"
+      end
+
+      # Plain-Ruby equivalent of ActiveSupport's String#parameterize.dasherize:
+      # downcase, collapse every run of non-alphanumeric characters to a
+      # single "-", and strip any leading/trailing "-".
+      def parameterize(str)
+        str.downcase.gsub(/[^a-z0-9]+/, '-').gsub(/\A-+|-+\z/, '')
+      end
+    end
+  end
+end

data/lib/openehr_rails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenehrRails
-  VERSION = '0.5.0'
+  VERSION = '0.6.0'
 end

data/lib/openehr_rails.rb

@@ -32,6 +32,7 @@ require 'openehr_rails/template_importer'
 require 'openehr_rails/runtime_scaffolder'
 require 'openehr_rails/fhir/type_map'
 require 'openehr_rails/fhir/profile_generator'
+require 'openehr_rails/fhir/fsh_generator'
 require 'openehr_rails/fhir/resource_registry'
 require 'openehr_rails/fhir/serializer'
 require 'openehr_rails/fhir/deserializer'

data/spec/openehr_rails/fhir/fsh_generator_spec.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'openehr_rails'
+
+describe OpenehrRails::Fhir::FshGenerator do
+  let(:opt_file) do
+    File.expand_path('../../generators/templates/bmi_calculation.opt', __dir__)
+  end
+  let(:template) { OpenehrRails::Opt.parse(opt_file) }
+  let(:generator) { described_class.new(template) }
+
+  describe '#to_fsh_files' do
+    subject(:files) { generator.to_fsh_files }
+
+    it 'builds one FSH profile per OBSERVATION entry' do
+      expect(files.keys).to contain_exactly(
+        'openehr-observation-height-v2',
+        'openehr-observation-body-weight-v2',
+        'openehr-observation-body-mass-index-v2'
+      )
+    end
+
+    describe 'the height profile' do
+      subject(:fsh) { files.fetch('openehr-observation-height-v2') }
+
+      it 'emits metadata and slices codings by system' do
+        expect(fsh).to include(
+          "Alias: CKM = http://openehr.org/ckm/archetypes\n",
+          "Alias: LOINC = http://loinc.org\n",
+          "Profile: OpenehrObservationHeightV2\n",
+          "Parent: Observation\n",
+          "Id: openehr-observation-height-v2\n",
+          "Title: \"openEHR Height (openEHR-EHR-OBSERVATION.height.v2)\"\n",
+          "* code.coding ^slicing.discriminator.type = #value\n",
+          "* code.coding ^slicing.discriminator.path = \"system\"\n",
+          "* code.coding ^slicing.rules = #open\n",
+          "* code.coding contains ckm 1..1 and loinc 0..1\n",
+          "* code.coding[ckm] = CKM#openEHR-EHR-OBSERVATION.height.v2\n",
+          "* code.coding[loinc] = LOINC#8302-2\n"
+        )
+      end
+
+      it 'constrains value[x] to an optional Quantity with a fixed unit' do
+        expect(fsh).to include(
+          "* value[x] 0..1\n",
+          "* value[x] only Quantity\n",
+          '* value[x].unit = "cm"'
+        )
+      end
+    end
+
+    describe 'a multi-element entry (body_mass_index)' do
+      subject(:fsh) { files.fetch('openehr-observation-body-mass-index-v2') }
+
+      it 'slices component by code and constrains each slice value' do
+        expect(fsh).to include(
+          "* component ^slicing.discriminator.type = #pattern\n",
+          "* component ^slicing.discriminator.path = \"code\"\n",
+          "* component ^slicing.rules = #open\n",
+          "* component contains bodymassindex 0..1\n",
+          '* component[bodymassindex].code.coding ' \
+          "^slicing.discriminator.type = #value\n",
+          '* component[bodymassindex].code.coding ' \
+          "^slicing.discriminator.path = \"system\"\n",
+          "* component[bodymassindex].code.coding ^slicing.rules = #open\n",
+          '* component[bodymassindex].code.coding contains ' \
+          "ckm 1..1 and snomedct 0..1 and loinc 0..1\n",
+          '* component[bodymassindex].code.coding[ckm] = ' \
+          "CKM#openEHR-EHR-OBSERVATION.body_mass_index.v2#at0004\n",
+          "* component[bodymassindex].value[x] only Quantity\n",
+          '* component[bodymassindex].value[x].unit = "kg/m2"'
+        )
+      end
+
+      it 'writes each ontology code binding into its coding slice' do
+        expect(fsh).to include(
+          "Alias: CKM = http://openehr.org/ckm/archetypes\n",
+          "Alias: SNOMEDCT = http://snomed.info/sct\n",
+          "Alias: LOINC = http://loinc.org\n",
+          '* component[bodymassindex].code.coding[snomedct] = ' \
+          "SNOMEDCT#60621009\n",
+          '* component[bodymassindex].code.coding[loinc] = ' \
+          "LOINC#39156-5\n"
+        )
+      end
+    end
+  end
+
+  describe 'value-set bindings' do
+    let(:opt_file) { File.expand_path('../../templates/problem_list.opt', __dir__) }
+
+    it 'emits a required binding for a C_CODE_REFERENCE constraint' do
+      fsh = generator.to_fsh_files.fetch('openehr-evaluation-problem-diagnosis-v1')
+
+      expect(fsh).to include(
+        '* component[problemdiagnosisat0002].value[x] from ' \
+        'http://id.who.int/icd/release/11/mms (required)'
+      )
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openehr-rails
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Shinji KOBAYASHI
@@ -258,7 +258,10 @@ files:
 - docs/backlog.md
 - docs/design/binding-extraction-plan.md
 - docs/design/fix-terminology-scope-plan.md
+- docs/design/fsh-generator-plan.md
+- docs/design/multi-leaf-non-observation-plan.md
 - docs/reports/binding-extraction-log.md
+- docs/reports/fsh-generator-log.md
 - docs/reports/institutionalization-log.md
 - gemfiles/rails_7_2.gemfile
 - gemfiles/rails_8_0.gemfile
@@ -292,6 +295,7 @@ files:
 - lib/openehr_rails/engine.rb
 - lib/openehr_rails/fhir/capability_statement.rb
 - lib/openehr_rails/fhir/deserializer.rb
+- lib/openehr_rails/fhir/fsh_generator.rb
 - lib/openehr_rails/fhir/profile_generator.rb
 - lib/openehr_rails/fhir/profile_repository.rb
 - lib/openehr_rails/fhir/resource_registry.rb
@@ -342,6 +346,7 @@ files:
 - spec/openehr_rails/aql/model_api_spec.rb
 - spec/openehr_rails/aql/query_validator_spec.rb
 - spec/openehr_rails/authentication_spec.rb
+- spec/openehr_rails/fhir/fsh_generator_spec.rb
 - spec/openehr_rails/fhir/profile_generator_spec.rb
 - spec/openehr_rails/fhir/serializer_spec.rb
 - spec/openehr_rails/naming_spec.rb