expressir 2.4.29-arm-linux-musl

data/TODO.parity-ee/11-import-eeng-tests.md

@@ -0,0 +1,79 @@
+# 11 — Import the Express Engine test suite
+
+**Status: NOT STARTED**
+
+## Goal
+
+Fully import eeng's tests — their release-suite scripts, the bug
+corpus, and the reference documents that define pass/fail — as
+executable RSpec feature specs and regression fixtures in expressir.
+Nothing in their suite should remain unrepresented.
+
+## Inventory (verified 2026-09-21)
+
+eeng has no formal test framework (`tests/` is a README describing an
+unrealized Makefile suite); the suite is:
+
+### CLI drivers — `scripts/*.sh` (14)
+
+| script | drives | our target operation |
+|---|---|---|
+| `qual-arm.sh`, `qual-mod.sh` | per-module qualification loop (arm/mim × every qualify.sh op) | 04, 05, 07-10 end-to-end specs |
+| `qual-res.sh` | same over `qualify-res.txt` resources | idem, resource side |
+| `pretty-test.sh` | `--pretty` ap209/ap210/ap242 × {arm,mim} × {shortform,longform} | 08 formatter specs |
+| `ap210.sh` | the 2.5MB long-form giant, pretty × 4 modes | 08 scale spec |
+| `test-tt.sh`, `test-tt1.sh` | `--xml` arm/mim shortform + Saxon HTM conversion + regenerate-exp compare | 09 (XML chain) |
+| `build-xml.sh` | XML builds over the whole `modules.lst` + `resources.lst` | 09 corpus spec |
+| `test.sh` | ad-hoc resource XML/HTM driver (kinematic schema) | 09 |
+| `scan-res.lisp` | resource corpus scan | 07 check corpus |
+| `kevin.sh`, `veronique.sh`, `copy-mod-xml.sh` | person-named scratch drivers | triage: keep as scenarios or drop with rationale |
+
+Each script's eeng CLI matrix (`-mode {arm,mim}_{shortform,longform,
+concatenated}` `-stepmod` `-schema` `--pretty/--xml/--flat/--dot
+--check`) maps 1:1 onto our planned operations — the flag matrix
+becomes our spec matrix.
+
+### Bug corpus — `docs/issues/`
+
+- `bug39-Greedy-Parens.txt` — **shtolo fixture**: contains "results
+  of old shtolo and stepcode exppp" vs "results of new shtolo"
+  outputs; doubles as a differential vs stepcode exppp.
+- `bug40-Pretty-Expressions.txt` — pretty-printer expression cases.
+Both become regression specs with the literal inputs embedded.
+
+### Reference documents — `docs/` (define pass/fail)
+
+- `shtolo_converting_STEP_short_listings_to_annotated_listings_libes.pdf`
+  — the SHTOLO paper (short listings → annotated listings); required
+  reading for 01/05 semantics.
+- BNF grammars: `iso-10303-11--2004{,-raw}.bnf`, `iso-10303-14*.bnf`,
+  **`iso-10303-21--{1994,2002}.bnf`** (Part 21!), `xml.bnf`,
+  `patch_schema.bnf` — grammar cross-checks (05's 1994 profile; the
+  Part 21 BNFs feed the future p21 parser).
+- `express_model.dtd`, `module.dtd` — the DTDs their XML emits (09's
+  structural contract).
+- `qualify.txt`, `interfaces.txt`, `interface-notes.pdf` —
+  qualification + interface semantics notes.
+- `00check.txt` (repo root) — check.lisp design notes → 07.
+
+## Steps
+
+1. Copy the durable assets into the repo: scripts verbatim under
+   `spec/fixtures/eeng/scripts/` (provenance header), bug corpus under
+   `spec/fixtures/eeng/issues/`, DTDs + BNFs under
+   `spec/fixtures/eeng/grammar/` (license is MIT-style per eeng
+   headers — verify and record attribution).
+2. Translate the CLI matrix into RSpec feature specs
+   (`spec/expressir/eeng_parity/`): one describe per driver family,
+   one example per (schema × mode × operation), corpus-scaled ones
+   tagged `smrl`.
+3. Port bug39/bug40 as literal regression specs now (they need only
+   parser + formatter, both of which exist).
+4. Extend 03's oracle harness to emit/refresh the expected outputs
+   these specs consume.
+
+## Acceptance
+
+Every driver row and both bugs have a corresponding spec (or a
+documented drop rationale); `smrl`-tagged parity suite green against
+the 03 golden corpus.

data/TODO.parity-ee/12-full-check-catalog.md

@@ -0,0 +1,67 @@
+# 12 — Full check-p11 catalog port (eeng `kernel/check.lisp`)
+
+## Goal
+
+Bring `Expressir::Express::Checker` from the current documented subset
+to the full eeng check-p11 catalog: every note eeng 5.1.0 emits over
+the SRL/SMRL corpora, with note ids and severities aligned so oracle
+differentials stay cross-referenceable.
+
+## Current subset (shipped)
+
+check-schema-interface-redundant, check-schema-iface-resource-duplicate,
+check-subtype-ref, check-subtype-cycle (path-tracked DFS),
+check-duplicate-declaration, check-where-name-pattern,
+check-unique-name-pattern, check-unresolved-ref,
+check-select-extended-type, check-enumeration-extended-type,
+check-self-schema-reference (#125), parse-failure → nonzero exit.
+
+## Sources
+
+- `~/src/external/exp-engine-engine/kernel/check.lisp` (835 lines,
+  `check-p11` generic + per-node-type methods) and
+  `kernel/check-notes.lisp` (note catalog).
+- ISO 10303-11:2004 clause text — `~/src/mn/iso-10303-11/sources/sections/`
+  (each ported check cites its clause).
+- Existing plan: `07-semantic-checks-port.md`; current impl
+  `lib/expressir/express/checker.rb`.
+
+## Design
+
+1. **Catalog extraction**: enumerate every `post-message` site in
+   check.lisp/check-notes.lisp → (note-id, severity, node type,
+   message shape). Commit as `spec/fixtures/eeng/check-catalog.md`
+   with our coverage column; CI gate diffs the catalog against the
+   oracle so new eeng notes surface.
+2. **Port order** (by eeng's own walk): schema-level (interfaces,
+   constants) → entity (supertype/subtype-of, attributes, derives,
+   inverses, uniques, wheres) → type (select/enumeration/aggregate
+   bounds) → function/procedure/rule bodies (expression typing lite:
+   arity/name resolution of called functions, built-ins from BUILTINS,
+   variable scoping via ScopeResolver) → attribute-level
+   redeclaration consistency (redispatches, `SELF\` qualifiers).
+3. **Differential gate**: run eeng `--validate` and our `validate
+   check` over the SRL corpus + module arm/mim set; every corpus file
+   must produce the SAME note-id multiset (message text may differ).
+   Land as `checker_eeng_full_catalog_differential_spec`
+   (production_scale-tagged for the big corpus; small fixtures in the
+   default suite).
+4. **Severity mapping** table: eeng `:error/:warning` → ours verbatim.
+
+## Acceptance
+
+- Catalog file lists 100% of eeng note ids with status columns.
+- SRL differential: zero unexplained note-id mismatches.
+- `validate check` docs updated (README table).
+
+## Test cases
+
+- eeng `docs/issues/` corpus inputs; qualify loops
+  (`scripts/qual-*.sh`) over resources.lst/modules.lst.
+- Per-clause unit fixtures citing ISO 10303-11 clause numbers.
+
+## Release checkpoint
+
+PR + expressir patch release once the entity/type/schema tiers land
+(expression-tier notes may follow in a second PR — keep the catalog
+honest about which tier each note belongs to).

data/TODO.parity-ee/13-population-p21.md

@@ -0,0 +1,54 @@
+# 13 — Population / Part 21 instance validation
+
+## Goal
+
+Validate STEP Part 21 instance data (.stp/.p21) against a loaded
+schema — eeng's core strength (`--validate` with population), absent
+from expressir today.
+
+## Sources
+
+- ISO 10303-21: exchange structure grammar — BNF in
+  `~/src/mn/iso-10303-detached-docs/sources/iso-10303-21*/` (and
+  eeng's copy under `plugins/p21/`, incl. its parser + validation).
+- eeng: `plugins/p21/` (p21 reader, population), `--validate`
+  (`run-op` population path), `wo-xml.lisp` instance-side references.
+- eeng banner: population validation "not fully supported" upstream —
+  our target is the supported subset, documented precisely.
+
+## Design (scope ladder; each step ships)
+
+1. **P21 reader**: parsanol grammar for the exchange structure
+   (header entities + DATA section: complex entity `(`name(...)`)`,
+   entity instances, list/set values, typed refs `#1`, enums `.T.`,
+   binary `\"..."`, redefines `/`). Emit a Population model
+   (`Model::Population`): instances with entity name + attribute
+   values keyed by explicit attribute position.
+2. **Structural validation**: every instance maps to a known entity
+   in the schema closure (complex entities → all parts); attribute
+   arity matches; value kinds match declared types (aggregate bounds,
+   select members, string/binary widths, REAL precision) — the
+   aggregate of eeng's population notes.
+3. **Constraint validation**: UNIQUE rules (per-entity + inherited),
+   WHERE rules — evaluation needs an EXPRESS expression interpreter;
+   reuse/extend the `benchmark`/expression-walk machinery, evaluate
+   over instance bindings (scope: no INVERSE/derives first).
+4. **CLI**: `expressir validate population SCHEMA -p DATA.p21`,
+   JSON/plain reports aligned with Checker notes.
+
+## Acceptance
+
+- Official Part 21 test corpora parse + validate (see tests).
+- Differential vs eeng `--validate` on shared fixtures: same
+  accept/reject decision and note ids.
+
+## Test cases
+
+- ISO 10303-21 validation suite files from detached-docs where
+  available; else eeng `tests/` + `scripts/test-tt*.sh` fixtures.
+- Hand fixtures: arity mismatch, bad enum, UNIQUE collision, WHERE
+  failure, complex-entity mismatch.
+
+## Release checkpoint
+
+Steps 1–2 = first release (structural validator); step 3 second.

data/TODO.parity-ee/14-shtolo-completion.md

@@ -0,0 +1,44 @@
+# 14 — SHTOLO completion (expressir#32, Annex G)
+
+## Goal
+
+Finish `Expressir::Express::Shtolo` to full Annex G conformance and
+close the eeng differential over the whole corpus. Current state:
+G.1 + G.2 stages implemented (522 lines), suite green (10 examples),
+`extenders:` :all/:none matches the eeng-default split.
+
+## Remaining work
+
+1. **Rule audit**: walk `spec/fixtures/shtolo/annex-g-rules.md`
+   (G.NM.1-2, G.1.1-10, G.2.1-7) and mark every rule PASS/partial/✖
+   in the file; a fixture per rule. Known-thin areas from the audit:
+   - G.1.6 dependently-instantiable rule output (function + WHERE
+     wiring) — verify against Annex G text, not eeng (eeng ✖).
+   - name-munging policy (`_dot_` and friends) — eeng ✖; standard wins.
+   - prune pass reachability (unreachable subtype branches).
+2. **Corpus differential**: for every module arm/mim in modules.lst,
+   compare our flatten output to `eengine --flat` (eeng default =
+   `extenders: :none` shape); classify divergences
+   standard-conformant vs bug. Feed the mismatch corpus into specs.
+3. **Scale**: SMRL full set flatten over the compiled-set warm model;
+   memory ceiling documented.
+4. **CLI**: `expressir shtolo MANIFEST -o longform.exp` (root schema
+   + closure resolution reuses ParityInputs).
+
+## Acceptance
+
+- Every Annex G rule has a green fixture.
+- Corpus differential: zero unexplained diffs; every explained
+  divergence documented in `parity-matrix.md`.
+- SMRL flatten completes; output parses under the 1994 profile.
+
+## Test cases
+
+- annex-g-rules.md fixtures; eeng `docs/issues/bug39` shtolo outputs
+  (old-vs-new vs stepcode exppp); `scripts/qual-*.sh` loops;
+  `pretty-test.sh` ap209/210/242 × arm/mim shape checks.
+
+## Release checkpoint
+
+One PR per coherent slice (rule audit + fixtures; differential gate;
+CLI), patch releases as each merges.

data/TODO.parity-ee/15-part28-xml.md

@@ -0,0 +1,51 @@
+# 15 — EXPRESS → XML (ISO 10303-28 / eeng --xml)
+
+## Goal
+
+Generate XML Schema output for a schema (expressir#276): eeng's
+`--xml` (`wo-xml-p11.lisp`) plus the SMRL index listing
+(`wo-smrl-xml.lisp`, feeds the SMRL document set).
+
+## Sources
+
+- ISO 10303-28:2007 ( EXPRESS-driven XML representation) — detached
+  docs `~/src/mn/iso-10303-detached-docs/sources/iso-10303-28*/`;
+  eeng `docs/` carries `express_model.dtd` + module.dtd (legacy
+  forms).
+- eeng: `plugins/p11/wo-xml-p11.lisp` (schema → XSD),
+  `wo-smrl-xml.lisp` (SMRL index XML), `--xml` run-op.
+- Consumer: iso-10303 repo's `schemas/data/*.xml` SMRL pages
+  (rendered by metanorma today) — our output must be drop-in for
+  that pipeline.
+
+## Design
+
+1. **SMRL index XML first** (small, high value for iso-10303): the
+   index of all schemas in a repository (name, file, interfaces,
+   counts) as the repo's data-layer source — replaces the
+   hand-maintained entries.
+2. **express2xsd**: schema → XSD via a declarative mapping table
+   (entity → element+complexType, type → simpleType/complexType,
+   select → choice, explicit attrs in order, supertype substitution
+   groups for SUBTYPE OF, aggregates → minOccurs/maxOccurs). Emit
+   through a Nokogiri-free XML writer (ROXML via lutaml-model where
+   it fits; hand-rolled tree otherwise — the mapping is the product,
+   not the serialization).
+3. **CLI**: `expressir xml SCHEMA -o schema.xsd`;
+   `expressir xml-index REPO -o smrl.xml`.
+
+## Acceptance
+
+- Output validates against the Part 28 reference XSDs (detached
+  docs) for the fixture set; xsd diff vs eeng --xml on SRL corpus
+  classified standard-vs-eeng.
+- iso-10303 SMRL pages render from our generated index unchanged.
+
+## Test cases
+
+- eeng `scripts/build-xml.sh` full-corpus reference outputs;
+  `test-tt{,1}.sh` (XML + Saxon HTM chain) as end-to-end smoke.
+
+## Release checkpoint
+
+SMRL index first (unblocks iso-10303 pipeline), express2xsd second.

data/TODO.parity-ee/16-compare-patch.md

@@ -0,0 +1,48 @@
+# 16 — Schema compare & patch (eeng --compare / --patch)
+
+## Goal
+
+Structural diff of two schemata with a machine-applicable patch
+output — eeng `--compare` (+ `--concat_compare`, `--patch`,
+`--patch_schema_name`), used by WG12 to track schema revisions.
+
+## Sources
+
+- eeng `plugins/p11/wo-*.lisp` compare entry (`run-op (:compare)`
+  in top-level.lisp) and patch application paths; mode args:
+  `:trial_schema :reference_schema :xml-output :patch-output`.
+- Semantics baseline: declaration-level matching by id within the
+  flattened/concatenated form (eeng compares post-concat shapes for
+  shortforms).
+
+## Design
+
+1. **Model diff** on the resolved repositories: declarations matched
+   by canonical path (`schema.item`); kinds of delta — added,
+   removed, changed (per-attribute structural diff: types,
+   attribute lists, where/unique bodies via formatted-text
+   comparison first, structural second).
+2. **Outputs**: unified-ish text report (human), XML
+   (`--xml-output` parity), and patch script (the eeng patch
+   format: rename/redefine vocabulary it defines — ported from
+   wo-patch output shapes).
+3. **CLI**: `expressir compare TRIAL.exp REFERENCE.exp [--xml|--patch]`;
+   `concat-compare` rides the Concatenator for shortform pairs.
+4. **Patch application**: apply a patch file to a model (rename
+   declarations, remap interfaces) — the write-back side eeng uses
+   for round-trip patching.
+
+## Acceptance
+
+- SRL corpus self-compare = empty diff; mutated fixtures (rename,
+  add/remove attr, retype) produce the expected delta kinds.
+- Differential vs eeng `--compare` XML on the same pairs.
+
+## Test cases
+
+- eeng `docs/issues/` pairs; hand-mutated fixture ladder; the
+  `--concat_compare` module-vs-module pairs from scripts.
+
+## Release checkpoint
+
+Text+XML diff first release; patch apply second.

data/TODO.parity-ee/17-official-tests.md

@@ -0,0 +1,42 @@
+# 17 — Official test-case incorporation
+
+## Goal
+
+One place that maps every OFFICIAL/reference test corpus to our
+specs, and CI gates that run the tractable tier on every push.
+
+## Corpora
+
+1. **eeng suite** (already imported, `spec/fixtures/eeng/`):
+   `scripts/*.sh` 14 drivers (qual-arm/mod/res loops, pretty-test.sh
+   ap209/210/242 × arm/mim × shortform/longform, ap210 giant file,
+   test-tt{,1}.sh XML chain, build-xml.sh), `docs/issues/` bug
+   corpus (bug39 shtolo old-vs-new vs stepcode exppp; bug40 pretty
+   expressions), `qualify.txt`, `interfaces.txt`, `00check.txt`.
+2. **ISO 10303-11** grammar/conformance sources:
+   `~/src/mn/iso-10303-11/sources/sections/` — Annex G rules
+   (fixtures live in `spec/fixtures/shtolo/annex-g-rules.md`),
+   syntax annexes for negative/positive grammar tests.
+3. **ISO detached docs** `~/src/mn/iso-10303-detached-docs/sources/
+   iso-10303-*`: Part 21 exchange-structure fixtures (population),
+   Part 28 reference XSDs (XML), Part 22 (SDAI vocabulary, later).
+4. **SRL/SMRL corpora** (`resources.lst`/`modules.lst` names match
+   our checkout): the differential tier.
+
+## Structure
+
+- `spec/expressir/eeng_parity/` — one spec per capability matrix
+  row; each example tags its source corpus file in a comment.
+- Tiering: `:fast` (fixtures, every push) / `:corpus`
+  (SRL differential, nightly or manual tag `production_scale`) /
+  `:smoke_eeng` (runs the local eeng oracle when the binary exists —
+  skipped otherwise).
+- `rake parity:status` prints the capability × corpus matrix with
+  green/gray cells — the single progress view.
+
+## Rules
+
+- No test is added without its provenance row in the fixture dir's
+  PROVENANCE.md (established practice, keep it).
+- Oracle outputs are regenerated, never hand-edited; the regeneration
+  command lives next to each golden.

data/TODO.parity-ee/18-mim-mapping.md

@@ -0,0 +1,47 @@
+# 18 — EXPRESS MIM mapping parser (expressir#88)
+
+## Goal
+
+Parse and validate MIM "reference path" mappings — the application ↔
+interpretation mapping every STEP module carries — into a typed model,
+with the mapping paths validated against the ARM/MIM schemas.
+
+## Sources
+
+- This checkout's canonical form: `schemas/modules/*/mapping.yaml` —
+  structured ae/aimelt/aa records whose values use the
+  `<<express:SCHEMA.ITEM,ITEM>>` link markup (the same markup
+  `Suma::LinkValidation` validates today). Generated upstream from
+  module.xml.
+- Upstream SMRL module.xml: `mapping`/`ae`/`aimelt` elements with
+  `reference_path` bodies — the ISO 10303-1x mapping methodology
+  grammar: entity chains `A -> B -> C`, qualifiers `[attr => val]`,
+  `=>` derived references, `->>` subtype traversal, `<>` select
+  member. Port the grammar from the Part 1x mapping annex text
+  (detached docs) + existing module corpus as the oracle.
+- eeng has no counterpart — this is an expressir-first capability.
+
+## Design
+
+1. `Expressir::Model::Mapping` — MappingDocument →
+   ApplicationElements (entity, aimelt, attributes) and
+   ReferencePath nodes (path-expression AST: steps, qualifiers,
+   subtype traversals).
+2. `mapping.yaml` reader (lutaml-model typed) — yaml → MappingDocument.
+3. Reference-path expression parser — parsanol grammar over the path
+   syntax; AST reuses Model::References where shapes coincide.
+4. Validation: every path resolves against the resolved ARM+MIM
+   repository (rides SchemaIndex / ItemGraph); unknown step = error
+   note (Checker id `check-mapping-path`).
+5. CLI: `expressir mapping validate DIR|FILE` over module dirs.
+
+## Acceptance
+
+- All module mapping.yaml files in the SMRL parse; path validation
+  reports zero unknown steps (or a classified, explained residue).
+- Round-trip: MappingDocument → yaml byte-stable.
+
+## Test cases
+
+- module corpus (603 modules); hand fixtures for each path grammar
+  production; invalid-path fixtures.

data/TODO.parity-ee/19-architecture.md

@@ -0,0 +1,97 @@
+# 19 — End-state architecture: Expressir in Rust, bound to metanorma via lutaml-model
+
+**Question (2026-09-23): should Expressir ultimately be in Rust, bound to
+metanorma via lutaml-model?**
+
+**Answer: yes as a direction, no as a rewrite.** The end state is
+*Rust engine, Ruby presentation* — reached in three milestones, not by
+porting everything at once. The binding to metanorma goes through
+lutaml-model's Liquid Drop layer, which is exactly the seam that
+already works (expressir#255, #319, #421, #426).
+
+## Current state (v2.4.9, measured)
+
+```
+.exp ──► parsanol-rs 0.8.8 (parse, wire tree)
+          └─► expressir_core ext (batch, EXSCS1 artifact, warm start)
+                └─► instantiate → Expressir::Model (lutaml-model, Ruby)
+                      └─► Checker / Shtolo / formatters (Ruby semantics)
+                            └─► Liquid Drops ──► metanorma / suma
+```
+
+- Parse is Rust and fast (SRL cold 36 s CPU, SMRL 558 s CPU / 1448
+  schemas); parsanol 0.8.8's selective memoization is adopted.
+- The measured floor is now the **wire→Ruby-object hydration**
+  (71 % of warm CPU) and the overlays (29 %). Rendering (metanorma)
+  touches a small fraction of the model.
+- Semantics (Checker subset, SHTOLO with the 50-module eengine
+  differential, PrettyFormatter, SMRL XML) live in Ruby, eeng-parity
+  validated, with Ruby CI harnesses.
+
+## Options considered
+
+**A — Status quo+.** Rust keeps parse+artifact; all new semantics
+(Checker catalog, mapping validation) land in Ruby. No rewrite risk,
+parity harnesses stay, but the hydration floor remains and the Rust
+surface stays private.
+
+**B — Lazy binding (the recommended milestone).** Keep the Ruby model
+as the canonical object model for feature work, and add a READ path
+that serves metanorma directly from Rust-held compiled-set data:
+expressir_core exposes accessors over the loaded set (schema by id,
+kind listings, field reads), and a lutaml-model Drop proxies them on
+demand — rendering never instantiates the full object graph.
+lutaml-model keeps ownership of mappings/serialization/Drop
+integration; the Drop becomes the literal "Expressir in Rust bound to
+metanorma via lutaml-model".
+
+**C — Full Rust Expressir.** Model + semantics in Rust; Ruby keeps
+only Drops and CLI glue; publish expressir-rs on crates.io; unlock
+non-Ruby consumers (standalone binary, WASM). Rejected for now: it
+re-implements eeng-validated semantics with parity risk, doubles CI,
+and metanorma still needs a Drop/FFI layer — the boundary cost moves,
+it does not disappear.
+
+**Decision: B now; C deferred behind explicit triggers**
+(a non-Ruby consumer materializes; the Ruby semantic layers become a
+measured bottleneck — they are not today; or crate publishing is
+wanted for supply-chain reasons independent of consumers).
+
+## Milestones
+
+### M1 — rev-pinned core dependency (supply chain, one line)
+The ext pins `expressir-rs = { git …, branch = "main" }`; a released
+gem can pick up a shifted core. Pin `rev = "<sha>"` per expressir
+release (2.4.8 ↔ today's expressir-rs main), bump per release.
+
+### M2 — lazy Drops for the metanorma hot path
+1. expressir-rs: read accessors over the loaded compiled set
+   (`schema(id)`, kind listings, per-declaration field reads,
+   remark/refs overlay application in place).
+2. expressir_core: magnus wrappers returning primitives.
+3. Ruby: `LazySchemaDrop` (lutaml-model #319 custom Drop, the same
+   seam as #255/#426) implementing id / declaration listings / source
+   faces via the accessors.
+4. Gates: suma-style schema-doc pages render output-comparable with
+   the eager path on a fixture corpus; warm page-render benchmark;
+   SMRL warm-start CPU target ≤ 30 % of today's 128 s for the
+   read-only path.
+
+### M3 — semantics placement rule (standing)
+New semantic features land in Ruby **unless** they are
+parse-adjacent or graph-scale (then Rust in expressir-rs). The
+Checker catalog (12) and mapping validation (18) stay Ruby; SHTOLO
+stays Ruby with its eengine differential as the gate.
+
+### M4 — trigger review for option C
+Reassess on any of: a non-Ruby consumer request; hydrate/overlay CPU
+re-emerging as the top cost after M2; a crates.io publication ask.
+M2's accessors are exactly the seed of C's public API — nothing in B
+is throwaway.
+
+## What lutaml-model owns in every option
+
+The mapping DSL (yaml/json faces — incl. the #88 `mapping.yaml`
+reader), Liquid integration (#319 Drops), artifact serialization —
+the binding contract between the engine and metanorma. Rust never
+duplicates it.

data/TODO.parity-ee/parity-matrix.md

@@ -0,0 +1,108 @@
+# eeng ↔ expressir parity matrix (2026-09-21)
+
+Reference: `~/src/external/exp-engine-engine` (eengine-5.0.20-Beta1).
+Audited files: kernel/{find-declaration,find-entity,find-type,
+resolve-interface,resolve-object,resolve-ref,references,schema-search,
+interfaces,compute-inheritance,supertypes,derive-attrs,
+inverse-attrs,check,compare,dot-graph}.lisp; plugins/p11/{schedule-*
+,resolve-declaration,cleanup-interface,wo-*}.lisp.
+
+## 1. Name resolution ladder (kernel/find-declaration.lisp:125-172)
+
+eeng's schema-scope restriction ladder for `find-declaration`:
+
+```
+nil        = :use-from
+:local     → own declarations + constants only
+:use-from  → :local OR :use-only
+:use-only  → walk USE FROM interfaces only, transitively, each in
+             :use-from scope (so USE visibility is transitive)
+:all-iface → :local OR all interfaces (USE and REFERENCE), transitively
+cycle guard → *schema-path*: schema already on path ⇒ nil
+```
+
+Per-kind restrictions (`resolve-interface.lisp:30-66`):
+- USE FROM resolves **type + entity only**.
+- REFERENCE FROM resolves constant/entity/function/procedure/type.
+- Unresolved resource ⇒ hard **error** `"Resource '~A' not found"`.
+
+**expressir today:** `ModelElement#find` climbs parent scopes through
+`children_by_id`; `Schema#children` = `interfaced_items + safe_children`
+where `interfaced_items` is **single-hop** (own interfaces only, no
+transitivity), and the resolver never errors on unresolved resources.
+Our `find` also treats REFERENCE and USE identically (no visibility
+tiering), and has no cycle guard (schema interface cycles loop until
+the memo fills — the memo makes this safe in practice, not by design).
+
+**Gaps:** (a) transitive USE visibility — item visible through a chain
+of USEs is invisible to our single-hop lookup; (b) USE/REFERENCE
+visibility tiering absent; (c) no unresolved-resource diagnostics;
+(d) no cycle guard by construction. Fix tracked in TODO 06.
+
+## 2. Load scheduling (plugins/p11/schedule-*.lisp)
+
+eeng: `schedule-load` (two-pass parse), `schedule-interfaces`
+(one method per session kind: double-stepmod keeps trl/ref schema
+sets — schema1/schemata1 = trial, schemata2 = reference), recursing
+per interface symbol → find/load the foreign file via the stepmod
+directory layout, then `schedule-resolve` → `resolve-declaration` per
+schema with `*schema?*` dynamic scope (:trl-schema / :ref-schema).
+
+**expressir today:** `from_files` (batch + compiled set), repository
+flat over all files; no trl/ref duality (we never compare two
+specification universes); interface targets located by name at resolve
+time through the repository (single-hop, see §1).
+
+**Verdict:** structural difference, not a bug — our repository model
+subsumes their session model for everything except `--compare`
+(two-universe schema comparison, kernel/compare.lisp, unported; TODO
+07 candidate).
+
+## 3. Entity computations (kernel/compute-inheritance.lisp,
+derive-attrs.lisp, inverse-attrs.lisp, supertypes.lisp,
+explicit-attrs.lisp)
+
+eeng **materializes** inherited attributes onto entities:
+explicit attributes from the full supertype closure, derived attrs,
+inverse attrs, subtype/supertype links — used by `--validate`,
+population checks, and SHTOLO's generalized-attribute handling
+(Annex G.2.6 needs exactly these).
+
+**expressir today:** nothing materialized; consumers walk the
+supertype closure themselves (our item graph does this for edges, not
+attributes).
+
+**Gaps:** inherited-explicit-attribute flattening, derived/inverse
+closures. Needed by 05 (G.2.6 select synthesis) and 07 (checks).
+TODO 05 scope.
+
+## 4. Semantic checks (kernel/check.lisp, 835 lines)
+
+check-p11 methods per node type: schema-level (interface resource
+existence, per-kind resolution rules), entity (attribute redeclare
+compatibility, inverse target/entity/inverse-attr existence, derive
+aggregation rules), function/procedure/rule parameters, subtype
+constraints, types. Check severity/notes via check-notes.lisp.
+
+**expressir today:** `RepositoryValidator` (interface-level only) +
+`validate ascii` CLI. Gap tracked in TODO 07.
+
+## 5. Writers (plugins/p11/wo-*.lisp)
+
+| eeng | semantics | expressir |
+|---|---|---|
+| wo-pretty | normal encoding, 2-space indent | Formatter clean mode — parity specs landed (bug39/40) |
+| wo-flat | `:flat` encoding, downcased symbols, typeof-option banner | 05 (Annex G — note eeng's flat KEEPS 2003 constructs: partial) |
+| wo-list | declaration listing | 09 |
+| wo-smrl-xml | `<concatenated_express_file_content_list>` index for longform/concatenated modes | 09 |
+| wo-lexp | lisp S-expression dump | not planned (internal debugging) |
+
+## 6. Bugs found by this audit
+
+- **expressir#373** — Ruby parse path corrupts small USE FROM schemas
+  (<~70B, non-monotonic; core path correct). Found by the concatenator
+  fixtures; `dependency_resolver_spec` failures on main are the same
+  root cause. Fixed by the #371/#370 stack.
+- eeng partial Annex G coverage — documented in
+  `spec/fixtures/shtolo/annex-g-rules.md` (eeng is a partial oracle;
+  the annex is the contract).