expressir 2.3.7 → 2.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecbd13317e56cc0139eb317331134c80ba9f5ae95eaf221f2f5e2046ebe95387
-  data.tar.gz: 86dbdfe6818f5c751d11c6fc4cd81e53a60b38145d3f7d80f5bd1b5ff6869815
+  metadata.gz: 887f5f7d9c3e1b78d4f14496e63e003282622e779c675cccfd4a4623ce282efd
+  data.tar.gz: dc7294598d88c408e1eea276c85410ffe7b9f98bf94ab5da6cb0ae9daa9d58f7
 SHA512:
-  metadata.gz: b3b26b8456c55b2a5b342d508a2af8f1e3c46ed23f78b96b5900a036292533c33b68f140248f6c8b552f5ed571adc245fe71acf1159b21feca3aa6c0b7bb354f
-  data.tar.gz: 3d33e2d5c850898a8b451a91cd76a9a85736b7e4c6d846c29e1652dc5e8fbb080bec35b2c55a908c7da68bdb32c5b7940162ea88cd811a519643a5f97db65fcf
+  metadata.gz: 7eaaadb131e964d12220a52d875b1ba77b1046d8dd4ca72e2c1362c2dfb7b66b36b4abc7f18fadae48878adced6362fe9f9d6ef3d0b51f5b73cf33e4c9227f53
+  data.tar.gz: 7c0decaf0a828843633e14a976a8f5aac0570e5d25e0e0023a02dc003463eedddd30ece51200fa40d4940fcb0f174bcbbdec5981970b2c0eadd8a881644d6108

data/TODO.bugs/01-stale-transformer-autoload.md

@@ -0,0 +1,39 @@
+# 01 — Delete stale `Transformer` autoload and legacy `transformer/remark_handling.rb`
+
+**Priority:** P0 (load-time failure waiting to happen)
+
+## Problem
+
+`lib/expressir/express.rb:28` declares:
+
+```ruby
+autoload :Transformer, "#{__dir__}/express/transformer"
+```
+
+But `lib/expressir/express/transformer.rb` does not exist. Only the directory
+`lib/expressir/express/transformer/` exists, containing `remark_handling.rb`
+(195 lines). Any code path that references `Expressir::Express::Transformer`
+raises `LoadError`.
+
+The `transformer/remark_handling.rb` module duplicates remark scanning and
+attachment logic that has been superseded by `RemarkScanner`, `RemarkAttacher`,
+`ScopeResolver`, and `NodePositionIndex` (PR lutaml/expressir#314). It uses
+`Parsanol::Slice`-based AST walking rather than source-text scanning, and its
+`attach_untagged_remarks` is explicitly stubbed as "skip for now."
+
+## Fix
+
+1. Delete `lib/expressir/express/transformer/` directory entirely.
+2. Delete the stale `autoload :Transformer` line in `lib/expressir/express.rb`.
+3. Verify no callers reference `Expressir::Express::Transformer` anywhere.
+
+## Files affected
+
+- `lib/expressir/express.rb` (delete one line)
+- `lib/expressir/express/transformer/remark_handling.rb` (delete file)
+- `lib/expressir/express/transformer/` (delete directory)
+
+## Acceptance
+
+- `grep -rn "Expressir::Express::Transformer" lib/ spec/` returns nothing.
+- Full test suite passes.

data/TODO.bugs/02-parser-class-instance-vars.md

@@ -0,0 +1,36 @@
+# 02 — Replace class-level `@exp_file`/`@repository` mutation in `Parser` with locals
+
+**Priority:** P0 (state leak across sequential calls)
+
+## Problem
+
+`lib/expressir/express/parser.rb` outer `Parser` class stores parse results
+as class-level instance variables:
+
+- Line 723: `@exp_file = ::Expressir::Express::Builder.build_with_remarks(...)`
+- Line 735: `@resolve_references_model_visitor = ResolveReferencesModelVisitor.new`
+- Line 774: `@repository = Model::Repository.new(files: all_exp_files)`
+- Line 778: `@resolve_references_model_visitor = ResolveReferencesModelVisitor.new`
+
+These are `class << self` instance variables. Sequential or concurrent calls
+to `Parser.from_file` / `Parser.from_files` overwrite each other's state.
+The visitor is only used inside the method body — there is no reason to
+retain it on the class.
+
+## Fix
+
+Return local variables from `from_file` and `from_files` instead of mutating
+class state. Replace `@exp_file` with `exp_file`, `@repository` with
+`repository`, `@resolve_references_model_visitor` with `visitor`. Delete any
+`attr_reader` declarations that expose these.
+
+## Files affected
+
+- `lib/expressir/express/parser.rb` (rewrite `from_file` and `from_files`)
+
+## Acceptance
+
+- `grep -n "@exp_file\|@repository\|@resolve_references" lib/expressir/express/parser.rb`
+  returns nothing.
+- All parser specs pass.
+- `Parser.from_file` returns the same value it did before.

data/TODO.bugs/03-builder-mutable-state.md

@@ -0,0 +1,43 @@
+# 03 — Thread `BuilderContext` through `Builder.build` instead of mutating `@source`/`@include_source`
+
+**Priority:** P1 (architectural friction)
+
+## Problem
+
+`lib/expressir/express/builder.rb` is a `module` (not a class) that stores
+per-call state as class-level instance variables:
+
+```ruby
+@source = source unless source.nil?
+@include_source = include_source unless include_source.nil?
+```
+
+Lines 10, 49-50, 112-113. The `unless source.nil?` guard admits that this is
+fragile — recursive `build` calls pass `nil` to avoid clobbering, which creates
+an implicit ordering dependency between caller and callee. The module is not
+reentrant: concurrent or nested builds would corrupt state.
+
+## Fix
+
+Introduce a `BuilderContext` value object that carries `source` and
+`include_source`. Thread it through the recursive `build` call chain as a
+keyword arg. Remove the `attr_reader :source, :include_source` on the
+metaclass. Builders that need access read from the context.
+
+Alternative considered: thread `source:` and `include_source:` as separate
+keyword args through every `build_*` method. Rejected because the arg list
+grows with every new context field, and the two values always travel together.
+
+## Files affected
+
+- `lib/expressir/express/builder.rb` (rewrite)
+- `lib/expressir/express/builders/*.rb` (update call sites — most already
+  receive `source` via `slice` or `node`; verify each)
+- New file `lib/expressir/express/builder_context.rb`
+
+## Acceptance
+
+- `grep -n "@source\|@include_source" lib/expressir/express/builder.rb`
+  returns nothing.
+- All parser and builder specs pass.
+- `Builder.build_with_remarks` is reentrant (a fresh `BuilderContext` per call).

data/TODO.bugs/04-formatter-public-send-dispatch.md

@@ -0,0 +1,53 @@
+# 04 — Replace `public_send(handler, node)` in `Formatter#format` with conventional override
+
+**Priority:** P1 (architectural friction)
+
+## Problem
+
+`lib/expressir/express/formatter.rb:85` dispatches formatting by looking up a
+method name in a class-level registry and calling it via `public_send`:
+
+```ruby
+def format(node)
+  return "" if node.nil?
+  handler = self.class.format_registry[node.class]
+  return public_send(handler, node) if handler
+  warn "#{node.class.name} format not implemented"
+  ""
+end
+```
+
+Issues:
+- `public_send` forces the format methods to be public on the including class,
+  defeating encapsulation.
+- A typo in a registered method name surfaces only at runtime, when that model
+  type is formatted.
+- IDE navigation and static analysis are defeated.
+- The `format_registry` hash is a parallel dispatch table that must be kept in
+  sync with the actual method definitions.
+
+## Fix
+
+Replace the registry dispatch with conventional Ruby method override. Each
+formatter module defines `format_<node_class>(node)` methods, and the base
+`Formatter#format` dispatches via a `case node` statement. Format methods
+remain private.
+
+This is a larger change touching 9 formatter modules. If full restructure is
+too risky for a single PR, a smaller win is to add a registration-time guard
+in `Formatter.included` that asserts the registered method exists via
+`method_defined?` — at least typos fail at load time.
+
+## Files affected
+
+- `lib/expressir/express/formatter.rb` (rewrite `format` and the registration hook)
+- `lib/expressir/express/formatters/*.rb` (8 modules — update registration calls)
+- `lib/expressir/express/pretty_formatter.rb`
+- `lib/expressir/express/schema_head_formatter.rb`
+- `lib/expressir/express/hyperlink_formatter.rb`
+
+## Acceptance
+
+- `grep -n "public_send" lib/expressir/express/formatter.rb` returns nothing.
+- All formatter specs pass.
+- A typo in a registered method name fails at load time, not at runtime.

data/TODO.bugs/05-anonymous-formatter-subclass.md

@@ -0,0 +1,45 @@
+# 05 — Cache the `Class.new(Formatter) { include HyperlinkFormatter }` in `ModelElement#source` as a constant
+
+**Priority:** P1 (wasteful per-call allocation)
+
+## Problem
+
+`lib/expressir/model/model_element.rb:100-105`:
+
+```ruby
+def source
+  formatter = Class.new(Expressir::Express::Formatter) do
+    include Expressir::Express::HyperlinkFormatter
+  end
+  formatter.format(self)
+end
+```
+
+Every call to `source` on any model element allocates a fresh anonymous class,
+runs the `self.included` hook, builds the `format_registry` hash, instantiates
+the class, and formats the tree. The result is identical across calls.
+
+`source` is a getter that may be invoked frequently during serialization and
+inspection. Wasteful.
+
+## Fix
+
+Define a single named class once, e.g. `Expressir::Express::SourceFormatter`,
+that subclasses `Formatter` and includes `HyperlinkFormatter`. `ModelElement#source`
+instantiates it (cheap) instead of allocating a new class.
+
+The class lives in `lib/expressir/express/source_formatter.rb` (autoloaded),
+breaking the model→express dependency at the source-text level — but the model
+already depends on express for serialization, so this just makes it explicit.
+
+## Files affected
+
+- `lib/expressir/model/model_element.rb` (use the constant)
+- New file `lib/expressir/express/source_formatter.rb`
+- `lib/expressir/express.rb` (add autoload)
+
+## Acceptance
+
+- `grep -n "Class.new" lib/expressir/model/model_element.rb` returns nothing.
+- All model_element specs pass.
+- `ModelElement#source` no longer allocates a class per call (benchmark optional).

data/TODO.bugs/06-collection-registry-single-source.md

@@ -0,0 +1,53 @@
+# 06 — Consolidate `SCHEMA_DECL_COLLECTIONS` into `COLLECTION_REGISTRY`
+
+**Priority:** P1 (DRY violation — two sources of truth for the same fact)
+
+## Problem
+
+`lib/expressir/express/scope_resolver.rb:46` declares:
+
+```ruby
+SCHEMA_DECL_COLLECTIONS = %i[functions procedures rules entities types].freeze
+```
+
+This is a hard-coded subset of what `NodePositionIndex::COLLECTION_REGISTRY`
+already knows for `Model::Declarations::Schema`:
+
+```ruby
+Model::Declarations::Schema => %i[
+  constants types entities subtype_constraints
+  functions rules procedures remark_items
+]
+```
+
+`ScopeResolver` only needs the "named scope declarations" subset (it skips
+`constants`, `subtype_constraints`, `remark_items` because they aren't scopes).
+But the subset is implicit — a change to Schema's collection attrs in
+`COLLECTION_REGISTRY` will not propagate.
+
+## Fix
+
+Define the subset once, either:
+- (a) Filter `COLLECTION_REGISTRY[Model::Declarations::Schema]` against a
+  constant of scope-capable attr names, OR
+- (b) Lift `SCHEMA_DECL_COLLECTIONS` to a shared location and document it as
+  "the scope-capable subset of Schema's collections."
+
+Option (b) is simpler and more honest about the intent. Move
+`SCHEMA_DECL_COLLECTIONS` to `Model::Declarations::Schema` as a class-level
+constant, since the subset is a fact about Schema.
+
+## Files affected
+
+- `lib/expressir/express/scope_resolver.rb` (reference the model constant)
+- `lib/expressir/model/declarations/schema.rb` (add `SCOPE_DECL_COLLECTIONS`)
+- `spec/expressir/express/scope_resolver_spec.rb` (add a spec asserting the
+  subset is a subset of `COLLECTION_REGISTRY`)
+
+## Acceptance
+
+- `ScopeResolver` no longer hard-codes a list that duplicates `COLLECTION_REGISTRY`.
+- All scope_resolver specs pass.
+- A new spec asserts the invariant: every entry in
+  `Schema::SCOPE_DECL_COLLECTIONS` is also in
+  `NodePositionIndex::COLLECTION_REGISTRY[Schema]`.

data/TODO.bugs/07-require-relative-cleanup.md

@@ -0,0 +1,42 @@
+# 07 — Replace `require_relative` for `version` and `errors` in `lib/expressir.rb` with autoload
+
+**Priority:** P2 (cleanup; project rule violation)
+
+## Problem
+
+`lib/expressir.rb:1-2`:
+
+```ruby
+require_relative "expressir/version"
+require_relative "expressir/errors"
+```
+
+Project rule: never use `require_relative` for internal library code — use
+Ruby `autoload` (defined in the immediate parent namespace's file).
+
+`lib/expressir/express.rb:33` also has `require_relative "express/builder_registry"`
+with a comment about eager-load for self-registration. The eager load is
+justified for the builder self-registration pattern, but the rule still
+applies — convert to autoload and require explicitly only in the entry point
+that triggers registration (or restructure to lazy registration).
+
+## Fix
+
+1. Convert `version` and `errors` to autoload entries in `lib/expressir.rb`.
+2. For `builder_registry`: convert to autoload, and explicitly trigger
+   registration in `Builder.build_with_remarks` (the only entry point that
+   needs builders loaded). Move the eager-load justification into a comment
+   on that explicit require, or restructure builders to self-register lazily
+   via `Kernel.singleton_class.include` at the top of each builder file.
+
+## Files affected
+
+- `lib/expressir.rb` (use autoload for Version, Errors)
+- `lib/expressir/express.rb` (autoload BuilderRegistry; remove `require_relative`)
+
+## Acceptance
+
+- `grep -rn "require_relative" lib/` returns only justified entries (ideally zero).
+- `Expressir::VERSION` still resolves.
+- `Expressir::Errors::*` still resolves.
+- Builder registration still happens before any `Builder.build_with_remarks` call.

data/TODO.bugs/08-require-expressir-in-commands.md

@@ -0,0 +1,34 @@
+# 08 — Remove `require "expressir/changes"` from `commands/*.rb`
+
+**Priority:** P2 (cleanup; project rule violation)
+
+## Problem
+
+Four call sites inside `lib/expressir/commands/`:
+
+- `changes_import_eengine.rb:15, 27, 54`
+- `changes_validate.rb:8`
+
+All use `require "expressir/changes"` instead of relying on autoload.
+
+The lazy requires inside method bodies suggest an attempt to defer loading,
+but autoload already provides that — and the project rule says no `require`
+with code within our library.
+
+## Fix
+
+Replace `require "expressir/changes"` with a direct reference to the
+`Expressir::Changes` constant (which triggers autoload). If the require is
+truly defensive (e.g., guarding against a load-order bug), delete it; the
+autoload on `Expressir::Changes` in `lib/expressir.rb` covers it.
+
+## Files affected
+
+- `lib/expressir/commands/changes_import_eengine.rb` (delete 3 requires)
+- `lib/expressir/commands/changes_validate.rb` (delete 1 require)
+
+## Acceptance
+
+- `grep -rn 'require "expressir/' lib/` returns nothing.
+- All command specs pass.
+- `Expressir::Commands::ChangesImportEengine` and `ChangesValidate` still work.

data/TODO.bugs/09-parser-split.md

@@ -0,0 +1,53 @@
+# 09 — Split `parser.rb` (1048 lines) into grammar + I/O service + schema-block scanner
+
+**Priority:** P2 (architectural friction — file too large to navigate)
+
+## Problem
+
+`lib/expressir/express/parser.rb` is 1048 lines with three distinct
+responsibilities crammed into one file:
+
+- Lines 5-688: inner `Parser < Parsanol::Parser` class — 250 grammar
+  `rule()` definitions plus keyword helpers.
+- Lines 690-920: outer `Parser` class — `from_file`, `from_files`,
+  `from_exp`, `from_exp_streaming_builder`, `from_exp_streaming`,
+  `extract_schema_blocks` (file I/O orchestration).
+- Lines 921-1046: `parse_schema_block`, `skip_spaces`, `skip_ws_and_comments`
+  — a hand-rolled state machine for splitting multi-schema files.
+
+The grammar rules, I/O orchestration, and schema-block scanning are three
+distinct concerns. The current nested `Expressir::Express::Parser::Parser`
+namespacing is also confusing — outer class wraps inner class with the same
+name.
+
+## Fix
+
+Split into three files:
+
+1. `lib/expressir/express/parser/grammar.rb` — the inner grammar class as
+   `Expressir::Express::Grammar::Parser` (renamed).
+2. `lib/expressir/express/parser/service.rb` — the outer class as
+   `Expressir::Express::ParserService` with the I/O methods.
+3. `lib/expressir/express/parser/schema_block_scanner.rb` — the
+   `parse_schema_block` / `skip_spaces` / `skip_ws_and_comments` helpers as
+   `Expressir::Express::SchemaBlockScanner`.
+
+Keep `Expressir::Express::Parser` as a thin facade that delegates to
+`ParserService`, for backward compatibility with all existing call sites.
+
+This is a large mechanical change. Run the full test suite after each file
+move to catch missing references.
+
+## Files affected
+
+- `lib/expressir/express/parser.rb` (becomes a thin facade)
+- New: `lib/expressir/express/parser/grammar.rb`
+- New: `lib/expressir/express/parser/service.rb`
+- New: `lib/expressir/express/parser/schema_block_scanner.rb`
+- `lib/expressir/express.rb` (update autoloads)
+
+## Acceptance
+
+- No file under `lib/expressir/express/` exceeds ~400 lines.
+- All parser specs pass without modification.
+- `Expressir::Express::Parser.from_file`, `from_exp`, etc. still work.

data/TODO.bugs/10-to-s-override.md

@@ -0,0 +1,42 @@
+# 10 — Rename `ModelElement#to_s(no_remarks:, formatter:)` to `format`
+
+**Priority:** P2 (surprising API; violates Liskov with core `to_s`)
+
+## Problem
+
+`lib/expressir/model/model_element.rb:191`:
+
+```ruby
+def to_s(no_remarks: false, formatter: nil)
+  ...
+end
+```
+
+Ruby's core `Object#to_s` takes zero arguments. Overriding it with keyword
+args means `node.to_s` works (defaults kick in), but `node.to_s(no_remarks: true)`
+is surprising — callers expect `to_s` to be a no-arg method.
+
+The implementation also mutates the formatter after construction
+(`f.no_remarks = no_remarks` at line 194), which is a post-construction
+mutation of an option that should have been set at construction.
+
+## Fix
+
+1. Rename `to_s` to `format(no_remarks: false, formatter: nil)`.
+2. Pass `no_remarks` through the formatter constructor instead of mutating
+   after the fact.
+3. Update all callers (search for `.to_s(no_remarks:`).
+4. Optionally: keep a no-arg `to_s` that delegates to `format` for any code
+   that expects string conversion (e.g. string interpolation).
+
+## Files affected
+
+- `lib/expressir/model/model_element.rb` (rename, update body)
+- All callers — `grep -rn "\.to_s(no_remarks:"`
+
+## Acceptance
+
+- `grep -rn "def to_s" lib/expressir/model/` returns nothing (or returns a
+  thin no-arg delegator).
+- All specs pass.
+- Callers use `.format(no_remarks: ...)` instead of `.to_s(no_remarks: ...)`.

data/TODO.bugs/11-parser-class-variables.md

@@ -0,0 +1,39 @@
+# 11 — Replace `@@cached_*` in `Parser` inner class with class instance variables
+
+**Priority:** P3 (Ruby pitfall — `@@` vars shared across hierarchy)
+
+## Problem
+
+`lib/expressir/express/parser.rb:10-18`:
+
+```ruby
+@@cached_parser = nil
+@@cached_syntax = nil
+@@cached_exp_file_parser = nil
+@@cached_grammar_ast = nil
+@@parser_mutex = Mutex.new
+```
+
+Ruby `@@` class variables are shared across the entire class hierarchy, not
+scoped to the defining class. If `Parser` is ever subclassed, the subclass
+shares these caches — a footgun.
+
+Currently not a bug (no subclassing), but fragile. Idiomatic Ruby uses
+class instance variables (`@cached_parser` on the metaclass via `class << self`).
+
+## Fix
+
+Convert each `@@cached_*` to a class instance variable accessed via
+`class << self` blocks or singleton method definitions. The mutex can stay
+as `@@parser_mutex` since mutexes are typically process-global, but it's
+cleaner to make it a class instance variable too.
+
+## Files affected
+
+- `lib/expressir/express/parser.rb` (or the split grammar.rb after TODO 09)
+
+## Acceptance
+
+- `grep -n "@@" lib/expressir/express/parser.rb` returns nothing.
+- All parser specs pass.
+- Cache behavior unchanged.

data/TODO.bugs/12-marker-modules-vs-registry.md

@@ -0,0 +1,64 @@
+# 12 — Generate `COLLECTION_REGISTRY` entries from marker-module declarations
+
+**Priority:** P3 (architectural; large change, defer unless time allows)
+
+## Problem
+
+`lib/expressir/model/concerns.rb` defines six marker modules
+(`HasId`, `HasRemarkItems`, `HasRemarks`, `ScopeContainer`,
+`HasInformalPropositions`, `HasWhereRules`) used for `is_a?` type checks.
+
+`lib/expressir/express/node_position_index.rb` declares
+`COLLECTION_REGISTRY` — a hash mapping the same model classes to their
+collection attribute names.
+
+Two parallel type-classification systems must be kept in sync. Adding a new
+model type requires updating both. This is the same architectural smell that
+TODO 06 addresses for a subset (Schema), generalized.
+
+## Fix
+
+Two options:
+
+**Option A (declarative):** Each model class declares its own collection
+attributes via a class-level macro, e.g.
+
+```ruby
+class Schema
+  collection_attributes :constants, :types, :entities, ...
+end
+```
+
+`COLLECTION_REGISTRY` becomes `Model.klasses.map { |k| [k, k.collection_attributes] }.to_h`.
+
+**Option B (derived):** The marker modules carry the attribute list:
+
+```ruby
+module HasRemarkItems
+  def self.collection_attributes = [:remark_items]
+end
+```
+
+`COLLECTION_REGISTRY` is derived from `Model::Concerns.constants.flat_map { |c| ... }`.
+
+Option A is cleaner. Either way, the duplication is eliminated.
+
+## Out of scope for this PR
+
+This is a large architectural change that touches every model class. It
+warrants its own grill session to pick between Option A and Option B and
+to migrate incrementally.
+
+## Files affected
+
+- `lib/expressir/model/declarations/*.rb` (add `collection_attributes` macro)
+- `lib/expressir/express/node_position_index.rb` (derive `COLLECTION_REGISTRY`)
+- `lib/expressir/express/remark_attacher.rb` (update reference)
+- `lib/expressir/express/scope_resolver.rb` (update reference)
+- All model class specs
+
+## Acceptance
+
+- `COLLECTION_REGISTRY` is derived, not hand-maintained.
+- Adding a new model class with a `collection_attributes` macro automatically
+  makes it appear in the registry.

data/TODO.bugs/13-string-literal-scanner-limitation.md

@@ -0,0 +1,52 @@
+# 13 — Add `:in_string` state to `RemarkScanner` (issue lutaml/expressir#313)
+
+**Priority:** P1 (correctness limitation)
+
+## Problem
+
+`lib/expressir/express/remark_scanner.rb` runs a three-state machine
+(`:top`, `:in_tail`, `:in_embedded`) but has no `:in_string` state. A `--`
+inside an EXPRESS string literal is mistakenly treated as the start of a
+tail remark.
+
+Minimal reproduction:
+
+```
+SCHEMA string_tail_repro;
+CONSTANT
+  greeting : STRING := 'hello -- world';
+END_CONSTANT;
+END_SCHEMA;
+```
+
+Scanner returns 1 spurious `tail` remark: `"world';"`. Expected: zero remarks.
+
+Reference: ISO 10303-11 §7.1.6.5 (Simple string literal) — `'` ... `'`
+with `''` as the escape.
+
+Filed as issue lutaml/expressir#313.
+
+## Fix
+
+Add a `:in_string` state to the state machine:
+
+- At `:top`, when encountering `'`, enter `:in_string`.
+- At `:in_string`, look for the closing `'`. Handle the `''` escape (treat
+  as a single literal `'` inside the string, not a closer).
+- At `:in_string`, ignore `--` and `(*` — they are string content.
+
+Encoded string literals (`.X.` ... `.X.`) per §7.1.6.6 are rarer; defer to a
+follow-up if not exercised by the SRL test schemas.
+
+## Files affected
+
+- `lib/expressir/express/remark_scanner.rb` (add `:in_string` state)
+- `spec/expressir/express/remark_scanner_spec.rb` (add regression specs)
+
+## Acceptance
+
+- Scanner returns zero remarks for `'hello -- world'`.
+- Scanner handles `''` escape correctly (`'it''s'` does not close at the
+  middle `'`).
+- All existing scanner specs still pass.
+- The ISO §7.1.6.5 simple-string-literal case is covered.

data/TODO.bugs/14-model-formatting-leak.md

@@ -0,0 +1,30 @@
+# 14 — Model layer embeds EXPRESS formatting logic
+
+**Priority:** P1 (leaky seam)
+**Status:** ACCEPTED — design decision documented below
+
+## Problem
+
+`ModelElement#source`, `Schema#source`, `Schema#formatted`, `Schema#full_source`
+all call express-layer formatters, creating a dependency from model → express.
+
+## Decision
+
+This coupling is **accepted** as a domain-level design decision. The model
+IS the EXPRESS model — it is not a generic data layer that could exist
+without the EXPRESS-specific formatting. The `source`/`formatted`/`full_source`
+methods are domain behavior of an EXPRESS model element, not generic
+serialization.
+
+Attempting to uncouple would:
+1. Break dozens of callers (`schema.source`, `schema.formatted` are used
+   throughout commands, specs, and coverage code).
+2. Add indirection (a presenter/decorator layer) for no real benefit —
+   the model and express layers are always loaded together.
+3. Diverge from the "rich model" pattern where domain objects carry their
+   own domain-specific behavior.
+
+The `@source ||=` caching pattern on Schema already provides lazy
+computation: the stored source (from the parser) is returned if available;
+otherwise the formatter computes it on first access. This is efficient and
+semantically correct.

data/TODO.bugs/15-expression-children-macro.md

@@ -0,0 +1,27 @@
+# 15 — EXPRESSION_CHILDREN hash should be a model macro
+
+**Priority:** P1 (parallel registry)
+
+## Problem
+
+`lib/expressir/express/remark_attacher.rb:30-45` has an
+`EXPRESSION_CHILDREN` hash manually listing non-collection child attributes
+for 14 expression/statement types. This is a parallel registry to the
+`collection_attributes` macro and must be maintained separately.
+
+## Fix
+
+Add a `child_attributes` class-level macro on `ModelElement` (similar to
+`collection_attributes`) for single-value child attributes that are
+ModelElements but not collections. Register them the same way.
+
+Update each expression/statement model class to declare its child attrs.
+
+Replace `EXPRESSION_CHILDREN[...]` lookups in RemarkAttacher with
+`ModelElement.child_attributes_registry`.
+
+## Acceptance
+
+- `EXPRESSION_CHILDREN` constant removed from RemarkAttacher.
+- Each expression class declares its own child attributes.
+- All remark specs pass.