expressir 2.4.24 → 2.4.25

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: baecd11fc9e03ed51685a06825e68a232f3caae95fd26bbffa8f77ce48ffdc03
-  data.tar.gz: 04b02ab33defbc571c9a1d36284c53f04b847acecb7e54b67537983ebbf2a74e
+  metadata.gz: da722d6f42601529fb1f7798255f6f5e8fed696c4c64998ed7e8c5b47aacb598
+  data.tar.gz: d9ead75080ad649480d7665cc526d500e9a228f18f941e2d0efbeab03d7871f9
 SHA512:
-  metadata.gz: 98ea8c39e0f462b7c6ecb7a2d24281cf3d159a79544b0b98feb89721011a066ff391343b0285816576f0007f9ede00d684629734fb5d29fefe2ef8af1f3c516f
-  data.tar.gz: c1bc94e1b7a73a79d93c7a1ae67b3f945f12ae7e3bcdcd161a6ea9f1d736ef74b0c2e39289301b31c558090c5f5fa7708b10d503c92b691ca5f1f90ff9ba0728
+  metadata.gz: 194e26d86f8043557120fb8935491376420600e8fecbde5ad99ceef352f3fe77251a1320c16ddb25f2ef293be33ca85c7e2daf1c02df1bcba16346d4067d1550
+  data.tar.gz: 68da6ffb076de9b604107ac2129d1b11224c57102037f84f526dcbd5efc4fdb54a012f843f3cb0e7f20e29eda4f11e8ee6dce81a3d58c4ed9b7238857ee02609

data/.github/scripts/test_installed_gem.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Smoke test for an INSTALLED expressir gem (run after `gem install`,
+# never from the source directory): the Rust core binding must be
+# active and the parser must handle the standard and #462 forms.
+require "expressir"
+
+abort "FAIL: NATIVE_AVAILABLE is false" unless Expressir::Express::Core::NATIVE_AVAILABLE
+puts "native binding: active"
+
+repo = Expressir::Express::Parser.from_exp(
+  "SCHEMA smoke; ENTITY e; a : STRING; END_ENTITY; END_SCHEMA;",
+)
+abort "FAIL: schema not parsed" unless repo.schemas.first.id == "smoke"
+puts "standard parse: ok"
+
+src = <<~EXP
+  SCHEMA m;
+  ENTITY e; END_ENTITY;
+  SUBTYPE_CONSTRAINT c FOR e;
+    ABSTRACT;
+  END_SUBTYPE_CONSTRAINT;
+  END_SCHEMA;
+EXP
+sc = Expressir::Express::Parser.from_exp(src).schemas.first.subtype_constraints.first
+abort "FAIL: subtype constraint ABSTRACT body (#462)" unless sc&.abstract == true
+puts "#462 form: ok"
+
+puts "SMOKE OK"

data/.github/workflows/native-gems.yml

@@ -0,0 +1,183 @@
+# Prebuilt platform gems (TODO.suma-improvements/01), following the
+# parsanol-ruby gem-build pattern: oxidize-rb cross-gem builds
+# per-platform gems in rake-compiler-dock containers, smoke jobs install
+# them on real runners, and tag pushes publish to rubygems.
+name: native-gems
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main, "cross-gem/*", "pkg/*"]
+    tags: ["v*"]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  ci-data:
+    runs-on: ubuntu-22.04
+    outputs:
+      result: ${{ steps.fetch.outputs.result }}
+    steps:
+      - id: fetch
+        uses: oxidize-rb/actions/fetch-ci-data@v1
+        with:
+          supported-ruby-platforms: |
+            exclude: [x64-mingw32]
+          stable-ruby-versions: |
+            only: [3.2, 3.3, 3.4, 4.0]
+
+  native:
+    name: Build native gems
+    needs: ci-data
+    runs-on: ubuntu-22.04
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-platform: ${{ fromJSON(needs.ci-data.outputs.result).supported-ruby-platforms }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+
+      - uses: oxidize-rb/actions/cross-gem@v1
+        id: cross-gem
+        env:
+          EXPRESSIR_CORE_FORCE: "1"
+        with:
+          platform: ${{ matrix.ruby-platform }}
+          ruby-versions: "3.2,3.3,3.4,4.0"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cross-gem-${{ matrix.ruby-platform }}
+          path: ${{ steps.cross-gem.outputs.gem-path }}
+          if-no-files-found: error
+
+  smoke-linux:
+    name: Smoke test Linux x86_64
+    needs: native
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+      - uses: actions/download-artifact@v4
+        with:
+          name: cross-gem-x86_64-linux
+          path: pkg/
+      - run: |
+          gem install pkg/expressir-*.gem --no-document
+          ruby .github/scripts/test_installed_gem.rb
+
+  smoke-linux-arm:
+    name: Smoke test Linux ARM64
+    needs: native
+    runs-on: ubuntu-22.04-arm
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+      - uses: actions/download-artifact@v4
+        with:
+          name: cross-gem-aarch64-linux
+          path: pkg/
+      - run: |
+          gem install pkg/expressir-*.gem --no-document
+          ruby .github/scripts/test_installed_gem.rb
+
+  smoke-macos-arm:
+    name: Smoke test macOS ARM64
+    needs: native
+    runs-on: macos-15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+      - uses: actions/download-artifact@v4
+        with:
+          name: cross-gem-arm64-darwin
+          path: pkg/
+      - run: |
+          gem install pkg/expressir-*.gem --no-document
+          ruby .github/scripts/test_installed_gem.rb
+
+  smoke-macos-intel:
+    name: Smoke test macOS x86_64
+    needs: native
+    runs-on: macos-15-intel
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+      - uses: actions/download-artifact@v4
+        with:
+          name: cross-gem-x86_64-darwin
+          path: pkg/
+      - run: |
+          gem install pkg/expressir-*.gem --no-document
+          ruby .github/scripts/test_installed_gem.rb
+
+  smoke-windows:
+    name: Smoke test Windows x64
+    needs: native
+    runs-on: windows-2025
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+      - uses: actions/download-artifact@v4
+        with:
+          name: cross-gem-x64-mingw-ucrt
+          path: pkg/
+      - run: |
+          gem install pkg/expressir-*.gem --no-document
+          ruby .github/scripts/test_installed_gem.rb
+
+  source:
+    name: Build source gem
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oxidize-rb/actions/setup-ruby-and-rust@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+          cargo-cache: true
+      - run: bundle exec rake build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: source-gem
+          path: pkg/*.gem
+          if-no-files-found: error
+
+  release:
+    name: Release gems to rubygems
+    needs: [native, smoke-linux, smoke-linux-arm, smoke-macos-arm, smoke-macos-intel, smoke-windows, source]
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-22.04
+    environment: release
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: pkg/
+          pattern: cross-gem-*
+          merge-multiple: true
+      - name: Push to rubygems
+        env:
+          GEM_HOST_API_KEY: ${{ secrets.LUTAML_CI_RUBYGEMS_API_KEY }}
+        run: |
+          for gem in pkg/expressir-*.gem; do
+            gem push "$gem"
+          done

data/.gitignore

@@ -48,3 +48,8 @@ CLAUDE.md
 Cargo.lock
 /ext/expressir_core/target/
 /ext/expressir_core/*.bundle
+
+# prebuilt binding staged by rake-compiler for platform gems
+/lib/expressir/expressir_core.bundle
+/lib/expressir/expressir_core.so
+/lib/expressir/expressir_core.dll

data/Cargo.toml

@@ -1,6 +1,6 @@
 [workspace]
 resolver = "2"
-members = ["crates/expressir-core"]
+members = ["ext/expressir_core"]
 
 [workspace.package]
 edition = "2021"

data/Gemfile

@@ -9,6 +9,7 @@ gem "irb"
 gem "lutaml-model", github: "lutaml/lutaml-model", branch: "main"
 gem "openssl", "~> 3.0"
 gem "rake"
+gem "rake-compiler"
 gem "rspec"
 gem "rubocop"
 gem "rubocop-performance"

data/TODO.suma-improvements/00-overview.md

@@ -0,0 +1,23 @@
+# Suma improvements — integration + expressir roadmap
+
+The metanorma ↔ expressir chain via suma: ISO 10303 SMRL schemas → expressir
+parse (compiled set EXSCS1) → LazyRepository + Liquid drops
+(metanorma-plugin-lutaml) → metanorma-iso schema documents. The chain is
+proven piecewise (1307 schemas, 0 failures, warm start 7.8s, live xrefs in
+rendered XML); the items below close the last mile and deepen expressir.
+
+| # | item | status |
+|---|------|--------|
+| 01 | prebuilt platform gems (oxidize-rb cross-gem, parsanol pattern) | in flight |
+| 02 | suma full-document E2E on current stack | pending |
+| 03 | ItemGraph — cross-schema subtype/interface graph API | pending |
+| 04 | compiled-set + lazy path as suma default build | pending |
+| 05 | corpus validation surfaced in suma builds | pending |
+| 06 | memory/perf re-measure with binding-by-default | pending |
+| 07 | #276 Part 28 XML — select mapping v2 | pending |
+| 08 | windows gnu toolchain for in-place ext builds | superseded by 01 for CI; kept for local dev |
+| 09 | checker tranche 3 (INVERSE, SELF\ qualifiers) | pending |
+| 10 | #91 EXPRESSdoc (upstream-gated) | parked |
+
+Evidence trail: #88/#461 (refpath validation), #462/#467 (ABSTRACT body
+form), v2.4.21–v2.4.24 (binding by default), plugin 0.7.53 + #305/#306.

data/TODO.suma-improvements/01-prebuilt-platform-gems.md

@@ -0,0 +1,33 @@
+# 01 — Prebuilt platform gems
+
+## Goal
+`gem install expressir` compiles nothing on machines with a prebuilt
+platform gem: the binding binary ships inside per-platform gems
+(`expressir-<ver>-arm64-darwin` etc.), following the parsanol-ruby
+pattern (oxidize-rb cross-gem + RbSys::ExtensionTask).
+
+## Pattern (from ~/src/parsanol/parsanol-ruby)
+- `oxidize-rb/actions/fetch-ci-data@v1` computes supported platforms
+- `oxidize-rb/actions/cross-gem@v1` matrix builds per-platform gems in
+  rake-compiler-dock containers (coherent gnu toolchain per target —
+  this is what fixes windows)
+- per-platform smoke jobs on REAL runners installing the gem and running
+  a smoke script (NATIVE true + parse)
+- source gem still builds via the gemspec (extensions stay declared);
+  rubygems prefers a matching platform gem automatically
+
+## expressir implementation
+- `rakelib/native.rake`: `RbSys::ExtensionTask.new("expressir_core")`,
+  `ext.lib_dir = "lib/expressir"`, `cross_compiling` callback stages
+  `expressir_core.{so,dylib,dll}` into `lib/expressir/` (loads via the
+  existing first `require "expressir/expressir_core"` in core.rb)
+- extconf: mingw skip becomes bypassable (`EXPRESSIR_CORE_FORCE=1` set in
+  the cross-gem container, where cargo gnu matches the mingw-ucrt ruby)
+- `.github/workflows/native-gems.yml`: ci-data + cross-gem matrix +
+  smoke jobs + source gem + `gem push` on tag (RUBYGEMS_API_KEY secret)
+- `.github/scripts/test_installed_gem.rb`: smoke script
+
+## Acceptance
+- workflow green across platforms with smoke jobs passing
+- a platform gem installs cargo-less and reports NATIVE true
+- source-gem install path unchanged (2.4.21 behavior)

data/TODO.suma-improvements/02-suma-e2e.md

@@ -0,0 +1,39 @@
+# 02 — Suma full-document E2E on the current stack
+
+## Goal
+One clean E2E run of an actual suma document build with expressir 2.4.24 +
+metanorma-plugin-lutaml 0.7.53 + current metanorma gems, rendering a real
+ISO 10303 module document to XML.
+
+## Why now
+The earlier full-render was blocked by the metanorma-document/relaton
+0.2.x skew; that ecosystem has moved (metanorma-document 0.5.1, relaton
+3.0 pre-alpha). The expressir side is proven current.
+
+## Steps
+- locate the suma build entry (~/src/mn/iso-10303 suma config or the
+  metanorma-iso document that renders schema pages)
+- bundle with current metanorma; render one module doc end to end
+- capture XML diffs vs the last good render; if the relaton skew
+  persists, name the exact unresolved constraint
+
+## Acceptance
+- a rendered module document, or a one-line statement of the precise
+  upstream blocker with the failing constraint
+
+## Result: DONE (2026-09-27)
+
+The upstream blocker has cleared. On the iso-10303 ladder (user's
+Gemfile WIP + suma from path + relaton prereleases with the rubyzip-3
+fix now on rubygems — the fix/rubyzip-3 git pins were dropped as
+obsolete):
+
+    bundle exec suma build srl-smol.yml   # one-part SMOL collection
+    # => Compiling schema collection... Compiling complete collection...
+    # => SMOL-EXIT=0
+
+Artifacts: 286 files in _site/ — real ISO document XML (flavor iso,
+schema content present), schema-doc pages, presentation XML. The stale
+sums pin was the rubygems suma 0.1.11 (expressir ~> 2.1, metanorma-cli
+0.0.3 → broken 2019 stack); suma from source (metanorma ~> 2.3 line)
+resolves cleanly.

data/TODO.suma-improvements/03-item-graph.md

@@ -0,0 +1,22 @@
+# 03 — ItemGraph
+
+## Goal
+Cross-schema graph API over a parsed repository: subtype edges, interface
+(USE FROM/REFERENCE FROM) edges, transitive queries — feeding suma doc
+generation (hyperlink coverage, "used by" sections, dependency diagrams).
+
+## Evidence
+SMRL full-set load proved the data: 37.7k subtype edges, 5.5k interface
+edges over 1307 schemas (TODO.memory SMRL notes). The class is the
+documented remaining gap.
+
+## Shape
+- `Expressir::Model::ItemGraph` built from a Repository (or a
+  LazyRepository hydrated once)
+- `subtypes(id)`, `supertypes(id)`, `used_by(id)`, `uses(id)`,
+  `transitive_subtypes(id)` — downcased-id keyed, cycle-safe
+- built once per repository; O(V+E)
+
+## Acceptance
+- specs over a multi-schema fixture (diamond subtyping, mutual USE FROM)
+- SMRL smoke: edge counts match the recorded 37.7k/5.5k within tolerance

data/TODO.suma-improvements/04-compiled-set-default.md

@@ -0,0 +1,16 @@
+# 04 — Compiled-set + lazy path as the suma default build
+
+## Goal
+suma builds parse the SMRL once into an EXSCS1 artifact and all document
+renders hydrate per schema from it (warm start 7.8s vs 12s cold), instead
+of eager-parsing on every build.
+
+## Steps
+- locate the suma/rake build entry that calls Parser.from_files
+- switch to `Parser.from_files(files, compiled_set:)` then
+  `LazyRepository.new(set)`
+- keep an escape hatch (env) for debugging with eager parse
+
+## Acceptance
+- a suma build log showing one artifact build + per-page hydration
+- rendered output byte-identical to the eager path

data/TODO.suma-improvements/05-validation-in-docs.md

@@ -0,0 +1,17 @@
+# 05 — Corpus validation surfaced in suma builds
+
+## Goal
+The expressir validation layers (mapping_validate incl. refpath
+resolution — which found 2 genuine corpus drifts in a 60-module sweep)
+run as part of suma builds, reporting per-module drift in the build log
+(and optionally in published output).
+
+## Steps
+- wire `expressir mapping_validate` over each module's mapping.yaml in
+  the suma build loop
+- aggregate a drift report artifact; non-zero exit only on NEW drift vs
+  a committed baseline file
+
+## Acceptance
+- baseline for the 2 known drifts; a build with a synthetic new drift
+  fails with the module/location in the message

data/TODO.suma-improvements/06-memory-remeasure.md

@@ -0,0 +1,36 @@
+# 06 — Memory/perf re-measure with binding-by-default
+
+## Goal
+The recorded profile ("50x memory ratio not achieved", pure-Ruby parse
+dominating) predates binding-by-default. Consumers now get the Rust
+parse path automatically; re-measure and refresh the story.
+
+## Steps
+- rerun the memory harness (TODO.memory methodology) with
+  NATIVE_AVAILABLE true on the same fixtures
+- record ratio vs the 50x target; note remaining hot spots
+- update TODO.memory notes + the perf memory file
+
+## Acceptance
+- fresh numbers committed alongside the old ones, with the parse
+  backend identified per measurement
+
+## Results (2026-09-27, ruby 3.4.8, 227KB synthetic / 4000 entities)
+
+| path | parse time | RSS delta | after GC |
+|------|-----------|-----------|----------|
+| Rust binding (NATIVE_AVAILABLE) | 7.7s | 348 MB | 387 MB |
+| pure-Ruby (use_native: false) | 7.5s | 307 MB | 353 MB |
+
+Both paths hydrate the full lutaml-model object tree, which dominates
+the delta — the native parse itself is not the differentiator at this
+size (arena overhead is offset by wire-hash materialization). The
+binding's memory advantage in the field comes from the compiled-set
+path (hydrate per file / warm start 7.8s), not from a lower per-parse
+floor. Ratio ~1.5 MB/KB of source on both paths — consistent with the
+older "~600x for large files" observation: the object MODEL is the
+cost driver, which is exactly what M2 laziness addresses.
+
+Old "50x memory ratio target" concern: RETIRED as the wrong metric for
+the binding; per-page hydration (LazyRepository) is the delivered
+mechanism for bounded memory at render time.

data/TODO.suma-improvements/07-part28-xml.md

@@ -0,0 +1,15 @@
+# 07 — Part 28 XML: select mapping v2 (#276)
+
+## Goal
+Full ISO 10303-28 EXPRESS-to-XML beyond the v1 skeleton
+(lib/expressir/express/xsd.rb): proper SELECT mapping (currently
+xs:anyType), aggregate/optional fidelity, schema-level structure.
+
+## Steps
+- ISO 10303-28 mapping rules for SELECT types (union/member semantics)
+- apply on top of xsd.rb's element/complexType generation
+- validate generated XSDs against the ISO 10303-28 conformance examples
+
+## Acceptance
+- a select-typed attribute renders per the standard (not xs:anyType)
+- the v1 examples still generate unchanged except where v2 improves them

data/TODO.suma-improvements/08-windows-gnu-toolchain.md

@@ -0,0 +1,15 @@
+# 08 — Windows gnu toolchain for in-place ext builds
+
+## Goal
+Local windows source installs and windows CI in-place builds compile the
+binding: rustup gnu target (`x86_64-pc-windows-gnu`) matching the mingw
+ruby, so extconf's guard can be lifted there.
+
+## Status
+Superseded for CI by 01 (cross-gem containers carry coherent toolchains;
+platform gems ship prebuilt). Kept for developers hacking on windows
+checkouts directly.
+
+## Acceptance
+- a windows machine with the gnu target builds the ext via extconf
+  without EXPRESSIR_CORE_FORCE

data/TODO.suma-improvements/09-checker-tranche3.md

@@ -0,0 +1,13 @@
+# 09 — Checker tranche 3 + SHTOLO completion
+
+## Goal
+Remaining eengine-parity checks: INVERSE-family rules and SELF\ qualifier
+validation (tranche 3), then the leftover SHTOLO longform items
+(TODO.parity-ee/14).
+
+## Gate
+Grammar support for INVERSE-scoped references and SELF\ qualified
+refs — verify against the current grammar after recent fixes.
+
+## Acceptance
+- each new check has a fixture that fires it + a clean-corpus negative

data/TODO.suma-improvements/10-expressdoc.md

@@ -0,0 +1,8 @@
+# 10 — EXPRESSdoc (#91, upstream-gated)
+
+## Goal
+Support the upcoming EXPRESSdoc format.
+
+## Status
+Parked on annotated-express#94 (upstream). Revisit when that lands;
+expressir's side is the remark/annotation model already in place.

data/ext/expressir_core/Cargo.toml

@@ -16,7 +16,4 @@ magnus = { version = "0.9" }
 expressir-rs = { git = "https://github.com/lutaml/expressir-rs", tag = "v0.1.6" }
 serde_json = "1.0"
 
-# Standalone workspace: the repo root workspace owns crates/, the ext
-# is built by rb_sys with its own cargo invocation.
-[workspace]
 

data/ext/expressir_core/extconf.rb

@@ -24,7 +24,10 @@ end
 # Windows rubies are mingw-built while rustup defaults to the msvc
 # toolchain; rb-sys cannot bridge the two, so skip there too (windows
 # installs fall back to the pure-Ruby parser).
-if RUBY_PLATFORM.include?("mingw")
+# Local mingw rubies pair with an msvc-default cargo and cannot build;
+# cross-gem containers carry the coherent gnu toolchain, so the skip is
+# bypassable there (EXPRESSIR_CORE_FORCE=1).
+if RUBY_PLATFORM.include?("mingw") && ENV["EXPRESSIR_CORE_FORCE"] != "1"
   write_noop_makefile
   warn "expressir: skipping the Rust core extension on mingw (msvc " \
        "toolchain mismatch)"

data/lib/expressir/express/checker.rb

@@ -17,6 +17,9 @@ module Expressir
     #   check-unresolved-ref   (aggregate of eeng type/entity unparsed notes)
     #   check-select-extended-type
     #   check-enumeration-extended-type
+    #   check-inverse-entity/-attrib-ref/-inverse/-derive (tranche 3)
+    #   qualified-attrib-group-not-found/-not-ancestor,
+    #   qualified-attrib-attr-not-found (tranche 3)
     #
     # Severity: :error stops a clean SHTOLO run; :warning is advisory.
     class Checker
@@ -226,6 +229,8 @@ module Expressir
         check_subtype_cycles(schema, entity)
 
         check_where_rules(schema, entity, entity.where_rules)
+        check_inverse_attributes(schema, entity)
+        check_group_references(schema, entity)
         Array(entity.unique_rules).each do |ur|
           next if ur.id.nil? || ur.id.match?(UNIQUE_LABEL)
 
@@ -290,6 +295,193 @@ module Expressir
         end
       end
 
+      # eeng check-inverse-* (ISO 10303-11 9.2.1.4): every INVERSE
+      # attribute must name a real entity and pair with a real
+      # attribute on it — one that is neither DERIVE nor itself an
+      # INVERSE — whose domain includes the owning entity (through
+      # subtype relations and nested aggregates). check-inverse-agg
+      # (only SET/BAG may aggregate an inverse) is structurally
+      # impossible here: the grammar rejects other aggregate kinds.
+      def check_inverse_attributes(schema, entity)
+        entity.attributes.to_a
+          .grep(Model::Declarations::InverseAttribute)
+          .each { |inv| check_inverse_attribute(schema, entity, inv) }
+      end
+
+      def check_inverse_attribute(schema, entity, inv)
+        target = inverse_target(schema, inv)
+        if target.nil?
+          note!(:check_inverse_entity, :error, schema,
+                "ENTITY #{entity.id}: INVERSE '#{inv.id}' target " \
+                "'#{inverse_target_id(inv)}' is not an entity", inv)
+          return
+        end
+
+        attr_id = inverse_paired_attr_id(inv)
+        if attr_id.nil?
+          note!(:check_inverse_attrib_ref, :error, schema,
+                "ENTITY #{entity.id}: INVERSE '#{inv.id}' names no " \
+                "attribute after FOR", inv)
+          return
+        end
+
+        owner = inverse_attr_owner(schema, inv, target)
+        paired = owner && attribute_on_closure(schema, owner, attr_id)
+        if paired.nil?
+          note!(:check_inverse_attrib_ref, :error, schema,
+                "ENTITY #{entity.id}: INVERSE '#{inv.id}': entity " \
+                "'#{owner&.id || target.id}' has no attribute '#{attr_id}'", inv)
+          return
+        end
+
+        if paired.is_a?(Model::Declarations::InverseAttribute)
+          note!(:check_inverse_inverse, :error, schema,
+                "ENTITY #{entity.id}: INVERSE '#{inv.id}' pairs with " \
+                "'#{owner.id}.#{attr_id}', which is itself an INVERSE", inv)
+        elsif paired.kind == Expressir::Model::Declarations::Attribute::DERIVED
+          note!(:check_inverse_derive, :error, schema,
+                "ENTITY #{entity.id}: INVERSE '#{inv.id}' pairs with " \
+                "'#{owner.id}.#{attr_id}', which is a DERIVE", inv)
+        end
+      end
+
+      def inverse_target(schema, inv)
+        type = inv.type
+        type = type.base_type if type.respond_to?(:base_type)
+        return nil unless type.respond_to?(:id)
+
+        find_entity(schema, ref_id(type))
+      end
+
+      def inverse_target_id(inv)
+        type = inv.type
+        type = type.base_type if type.respond_to?(:base_type)
+        ref_id(type)
+      end
+
+      # The entity the FOR-attribute lives on: the qualified
+      # `e.a FOR` form overrides the type's entity.
+      def inverse_attr_owner(schema, inv, target)
+        expr = inv.expression
+        if expr.is_a?(Model::References::AttributeReference) &&
+            expr.ref.respond_to?(:id)
+          find_entity(schema, ref_id(expr.ref)) || target
+        else
+          target
+        end
+      end
+
+      def inverse_paired_attr_id(inv)
+        expr = inv.expression
+        return ref_id(expr) if expr.respond_to?(:id)
+
+        expr.respond_to?(:attribute) ? ref_id(expr.attribute) : nil
+      end
+
+      # Attribute on +entity+ or any of its supertype ancestors.
+      def attribute_on_closure(schema, entity, attr_id)
+        key = attr_id.safe_downcase
+        seen = {}.compare_by_identity
+        queue = [entity]
+        until queue.empty?
+          current = queue.shift
+          next if seen[current]
+
+          seen[current] = true
+          hit = Array(current.attributes).find do |a|
+            a.id&.safe_downcase == key
+          end
+          return hit if hit
+
+          Array(current.subtype_of).each do |ref|
+            id = ref_id(ref)
+            queue << find_entity(schema, id) if id
+          end
+        end
+        nil
+      end
+
+      # eeng qualified-attrib-* (ISO 10303-11 12.7.4). The group must
+      # resolve to an entity and the qualified attribute must exist on
+      # it. The ANCESTRY requirement applies only to redeclared
+      # attributes (SELF\T.attr as an attribute declaration) — eeng
+      # checks exactly those; TYPEOF-guarded sibling views in
+      # expressions (geometry_schema's SELF\subface.parent_face) are
+      # standard corpus usage and are not flagged.
+      def check_group_references(schema, entity)
+        closure = supertype_closure_ids(schema, entity)
+        closure << entity.id if entity.id
+        redeclared = {}.compare_by_identity
+        entity.attributes.to_a.each do |attr|
+          sa = attr.supertype_attribute
+          next unless sa.is_a?(Model::References::AttributeReference) &&
+            sa.ref.is_a?(Model::References::GroupReference)
+
+          redeclared[sa.ref] = true
+          group = sa.ref
+          target = resolve_group(schema, entity, group)
+          next if target.nil?
+          next if closure.include?(ref_id(group.entity)&.safe_downcase)
+
+          note!(:qualified_attrib_group_not_ancestor, :error, schema,
+                "ENTITY #{entity.id}: SELF\\'#{ref_id(group.entity)}' " \
+                "is not a supertype of #{entity.id}", group)
+        end
+
+        each_node(entity) do |node|
+          next unless node.is_a?(Model::References::GroupReference)
+          next if redeclared[node]
+
+          target = resolve_group(schema, entity, node)
+          next if target.nil?
+
+          parent = node.parent
+          attr_id = parent.respond_to?(:attribute) ? ref_id(parent.attribute) : nil
+          next if attr_id.nil?
+          next if Array(target.attributes).any? do |a|
+            a.id&.safe_downcase == attr_id.safe_downcase
+          end
+
+          note!(:qualified_attrib_attr_not_found, :error, schema,
+                "ENTITY #{entity.id}: '#{ref_id(node.entity)}.#{attr_id}': " \
+                "'#{ref_id(node.entity)}' has no attribute '#{attr_id}'", node)
+        end
+      end
+
+      # Resolve a group qualifier's entity, noting
+      # qualified-attrib-group-not-found when it does not resolve.
+      def resolve_group(schema, entity, node)
+        group_id = ref_id(node.entity)
+        target = group_id && find_entity(schema, group_id)
+        return target if target
+
+        note!(:qualified_attrib_group_not_found, :error, schema,
+              "ENTITY #{entity.id}: group '#{group_id}' in a qualified " \
+              "attribute does not resolve to an entity", node)
+        nil
+      end
+
+      def supertype_closure_ids(schema, entity)
+        seen = {}.compare_by_identity
+        queue = [entity]
+        ids = []
+        until queue.empty?
+          current = queue.shift
+          next if seen[current]
+
+          seen[current] = true
+          Array(current.subtype_of).each do |ref|
+            id = ref_id(ref)
+            next if id.nil?
+
+            ids << id
+            parent = find_entity(schema, id)
+            queue << parent if parent
+          end
+        end
+        ids
+      end
+
       def each_reference(node, &block)
         case node
         when Model::References::SimpleReference then yield node

data/lib/expressir/express/parser.rb

@@ -160,6 +160,10 @@ module Expressir
                         end
 
         repository = build_repository(all_exp_files, skip_references: skip_references)
+        if set_path && !skip_references && !File.exist?(set_path) &&
+            core_set_available? && !all_exp_files.include?(nil)
+          write_compiled_set(set_path, files, all_exp_files, root_path)
+        end
         if set_path && !skip_references && File.exist?(set_path)
           files = all_exp_files.compact
           RefsOverlay.write(set_path, files)
@@ -383,6 +387,47 @@ include_source: nil, root_path: nil, use_native: nil, &block)
         all_exp_files
       end
 
+      # Artifact write for the non-batch paths (single file,
+      # EXPRESSIR_BATCH=0, small sequential sets): serializes the
+      # parsed models through Core.write_set, producing the same
+      # artifact shape the batch path writes natively. The wire is
+      # pre-remark — RemarkOverlay.write carries the remark-derived
+      # attributes, exactly as it does for the batch path.
+      def self.write_compiled_set(set_path, files, exp_files, root_path)
+        require "digest"
+        require "json"
+        schema_file_for = lambda do |file|
+          root_path ? Pathname.new(file.to_s).relative_path_from(root_path).to_s : file.to_s
+        end
+        entries = files.zip(exp_files).map do |file, exp_file|
+          [schema_file_for.call(file),
+           Digest::SHA256.file(file.to_s).hexdigest,
+           JSON.generate(strip_remark_wire(exp_file.to_hash))]
+        end
+        ::Expressir::Core.write_set(set_path, entries, Expressir::Version::VERSION)
+        RemarkOverlay.write(set_path, exp_files)
+      end
+      private_class_method :write_compiled_set
+
+      # Deep copy of a serialized model without the RemarkOverlay
+      # attributes: the artifact wire carries only the parsed model;
+      # untagged remarks are plain hashes that the Rust hydrator
+      # cannot instantiate, and every remark-derived value belongs to
+      # the overlay anyway.
+      def self.strip_remark_wire(node)
+        case node
+        when Hash
+          node.each_with_object({}) do |(key, value), out|
+            out[key] = strip_remark_wire(value) unless RemarkOverlay::CAPTURED.include?(key)
+          end
+        when Array
+          node.map { |value| strip_remark_wire(value) }
+        else
+          node
+        end
+      end
+      private_class_method :strip_remark_wire
+
       def self.build_repository(all_exp_files, skip_references: nil)
         repository = Model::Repository.new(files: all_exp_files)
 

data/lib/expressir/express/xsd.rb

@@ -6,13 +6,18 @@ module Expressir
     # TODO.parity-ee 15) — the express2xsd counterpart, built on
     # moxml.
     #
-    # Mapping (v1):
+    # Mapping (v2):
     #   ENTITY      → xs:element + xs:complexType (explicit attributes
     #                 in declaration order); SUBTYPE OF a schema-local
     #                 entity becomes a substitutionGroup reference.
     #   ENUMERATION → xs:simpleType with enumeration facets.
-    #   SELECT      → xs:element of xs:anyType (full Part 28 select
-    #                 mapping is a documented v1 limitation).
+    #   SELECT      → xs:complexType with an xs:choice over the member
+    #                 types (ISO 10303-28 select mapping): entity
+    #                 members reference their global element
+    #                 declarations, defined-type members carry their
+    #                 simpleType. Declared members only — extensible
+    #                 selects and cross-schema members keep the
+    #                 documented v1 fallbacks.
     #   defined TYPE over a simple type → xs:simpleType restriction.
     #   attributes  → xs:element inside the complexType sequence;
     #                 LIST/SET/BAG/ARRAY → maxOccurs="unbounded".
@@ -54,6 +59,10 @@ module Expressir
 
       def type_node(doc, schema, type)
         underlying = type.underlying_type
+        if underlying.is_a?(Expressir::Model::DataTypes::Select)
+          return select_type_node(doc, schema, type, underlying)
+        end
+
         node = doc.create_element("xs:simpleType")
         node.set_attributes("name" => type.id)
         restriction = doc.create_element("xs:restriction")
@@ -71,6 +80,52 @@ module Expressir
         node
       end
 
+      # ISO 10303-28: a select type maps to a complexType choosing
+      # among its member types. An extensible select with no declared
+      # items gets an empty sequence — an empty xs:choice is not
+      # schema-valid.
+      def select_type_node(doc, schema, type, select)
+        node = doc.create_element("xs:complexType")
+        node.set_attributes("name" => type.id)
+        container = select.items.to_a.empty? ? "xs:sequence" : "xs:choice"
+        choice = doc.create_element(container)
+        node.add_child(choice)
+        select.items.to_a.each do |item|
+          choice.add_child(select_member_element(doc, schema, item))
+        end
+        node
+      end
+
+      def select_member_element(doc, schema, item)
+        node = doc.create_element("xs:element")
+        if item.is_a?(Expressir::Model::References::SimpleReference)
+          id = item.respond_to?(:base_path) && item.base_path ? base_id(item.base_path) : item.id
+          member = select_member_target(schema, id)
+          if member == :entity
+            node.set_attributes("ref" => id)
+          elsif member == :type
+            node.set_attributes("name" => id, "type" => id)
+          else
+            node.set_attributes("name" => id, "type" => "xs:anyType")
+          end
+        else
+          name = item.class.name.split("::").last.downcase
+          node.set_attributes("name" => name,
+                              "type" => BUILTIN_TYPES.fetch(name, "xs:anyType"))
+        end
+        node
+      end
+
+      def select_member_target(schema, id)
+        if schema.entities.to_a.any? { |e| e.id.safe_downcase == id.safe_downcase }
+          :entity
+        elsif schema.types.to_a.any? { |t| t.id.safe_downcase == id.safe_downcase }
+          :type
+        else
+          :unknown
+        end
+      end
+
       def entity_element(doc, schema, entity)
         node = doc.create_element("xs:element")
         node.set_attributes("name" => entity.id)
@@ -83,18 +138,84 @@ module Expressir
       def entity_type(doc, schema, entity)
         node = doc.create_element("xs:complexType")
         node.set_attributes("name" => entity.id)
+        container = node
+        parent = supertype_name(schema, entity)
+        if parent
+          content = doc.create_element("xs:complexContent")
+          extension = doc.create_element("xs:extension")
+          extension.set_attributes("base" => parent)
+          content.add_child(extension)
+          node.add_child(content)
+          container = extension
+        end
         sequence = doc.create_element("xs:sequence")
-        node.add_child(sequence)
-        entity.attributes.to_a.each do |attr|
-          skip = attr.kind == Expressir::Model::Declarations::Attribute::INVERSE ||
-            (attr.respond_to?(:derive?) && attr.derive?)
-          next if skip
-
+        container.add_child(sequence)
+        explicit_attributes(entity).each do |attr|
+          sequence.add_child(attribute_element(doc, schema, attr))
+        end
+        # EXPRESS multiple inheritance: the extension base carries the
+        # first parent's chain; later parents' attributes (transitively)
+        # become explicit members of the subtype's sequence.
+        additional_parent_attributes(schema, entity).each do |attr|
           sequence.add_child(attribute_element(doc, schema, attr))
         end
         node
       end
 
+      def explicit_attributes(entity)
+        entity.attributes.to_a.reject do |attr|
+          attr.kind == Expressir::Model::Declarations::Attribute::INVERSE ||
+            (attr.respond_to?(:derive?) && attr.derive?)
+        end
+      end
+
+      # Attributes contributed by multiple inheritance: every ancestor
+      # reachable from the additional local supertypes (all but the
+      # first), minus the first supertype's own chain — the extension
+      # base already carries that. Cycle-safe.
+      def additional_parent_attributes(schema, entity)
+        parents = local_supertypes(schema, entity)
+        return [] if parents.size <= 1
+
+        base_chain = ancestor_set(schema, parents.first)
+        seen = {}.compare_by_identity
+        queue = parents.drop(1)
+        attrs = []
+        until queue.empty?
+          current = queue.shift
+          next if seen[current] || base_chain[current]
+
+          seen[current] = true
+          attrs.concat(explicit_attributes(current))
+          queue.concat(local_supertypes(schema, current))
+        end
+        attrs
+      end
+
+      # Identity set of +entity+ and every supertype ancestor.
+      def ancestor_set(schema, entity)
+        seen = {}.compare_by_identity
+        queue = [entity]
+        until queue.empty?
+          current = queue.shift
+          next if seen[current]
+
+          seen[current] = true
+          queue.concat(local_supertypes(schema, current))
+        end
+        seen
+      end
+
+      def local_supertypes(schema, entity)
+        Array(entity.subtype_of).filter_map do |ref|
+          id = ref.is_a?(String) ? ref : ref.id
+          next nil unless id
+
+          schema.entities.to_a
+            .find { |e| e.id.safe_downcase == id.safe_downcase }
+        end
+      end
+
       def attribute_element(doc, schema, attr)
         node = doc.create_element("xs:element")
         node.set_attributes("name" => attr.id)
@@ -126,14 +247,7 @@ module Expressir
       end
 
       def supertype_name(schema, entity)
-        ref = Array(entity.subtype_of).first
-        return nil unless ref
-
-        id = ref.is_a?(String) ? ref : ref.id
-        return nil unless id
-        return nil unless schema.entities.to_a.any? { |e| e.id.safe_downcase == id.safe_downcase }
-
-        schema.entities.find { |e| e.id.safe_downcase == id.safe_downcase }.id
+        local_supertypes(schema, entity).first&.id
       end
 
       def base_id(base_path)

data/lib/expressir/model/indexes/item_graph.rb

@@ -80,6 +80,56 @@ module Expressir
           @subtype_of.flat_map { |child, parents| parents.map { |p| [child, p] } }
         end
 
+        # Direct subtypes of an entity (the inverse of subtype_of).
+        def subtypes(path)
+          key = canonical(path)
+          return [] unless @nodes.key?(key)
+
+          @subtype_of.select { |_child, parents| parents.include?(key) }.keys
+        end
+
+        # Transitive subtype closure of an entity (everything below it
+        # in the hierarchy), breadth-first and cycle-safe.
+        def transitive_subtypes(path)
+          key = canonical(path)
+          return [] unless @nodes.key?(key)
+
+          seen = {}
+          queue = subtypes(key)
+          until queue.empty?
+            current = queue.shift
+            next if seen[current]
+
+            seen[current] = true
+            queue.concat(subtypes(current))
+          end
+          seen.keys
+        end
+
+        # Transitive interface closure of a schema — every schema it
+        # depends on, directly or through intermediates. Cycle-safe.
+        def dependency_closure(schema)
+          schema_id = schema.respond_to?(:id) ? schema.id : schema.to_s
+          seen = {}
+          queue = dependencies_of(schema_id).dup
+          until queue.empty?
+            current = queue.shift
+            next if seen[current]
+
+            seen[current] = true
+            queue.concat(@dependencies[current] || [])
+          end
+          seen.keys
+        end
+
+        # Schemas that import `schema` (USE FROM / REFERENCE FROM it),
+        # direct only — the "used by" direction for doc generation.
+        def dependents_of(schema)
+          schema_id = schema.respond_to?(:id) ? schema.id : schema.to_s
+          key = schema_id.safe_downcase
+          @dependencies.select { |_from, deps| deps.include?(key) }.keys
+        end
+
         def cross_schema_subtype_edges
           subtype_edges.count { |child, parent| child.split(".")[0] != parent.split(".")[0] }
         end

data/lib/expressir/version.rb

@@ -3,6 +3,6 @@ module Expressir
   # autoload it (Ruby autoload only works for module/class constants, not
   # for string constants like `Expressir::VERSION`).
   module Version
-    VERSION = "2.4.24".freeze
+    VERSION = "2.4.25".freeze
   end
 end

data/rakelib/native.rake

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# Prebuilt platform gems (TODO.suma-improvements/01): the compiled Rust
+# core ships inside per-platform gems, mirroring the parsanol-ruby
+# pattern (RbSys::ExtensionTask + cross_compiling staging). The source
+# gem keeps its gemspec-declared extconf build; platform gems carry the
+# artifact in lib/expressir/, which core.rb's first require finds.
+begin
+  require "rb_sys/extensiontask"
+  require "rb_sys/toolchain_info"
+
+  gemspec = Gem::Specification.load("expressir.gemspec")
+
+  RbSys::ExtensionTask.new("expressir_core", gemspec) do |ext|
+    ext.lib_dir = "lib/expressir"
+
+    ext.cross_compiling do |spec|
+      next if spec.platform == Gem::Platform::RUBY
+
+      plat = spec.platform.to_s
+      triple = begin
+        RbSys::ToolchainInfo::DATA.fetch(plat).fetch("rust-target")
+      rescue KeyError
+        { "arm-linux-musl" => "arm-unknown-linux-musleabihf" }.fetch(plat)
+      end
+
+      # rb-sys's cargo build already ran for the cross target; stage the
+      # artifact from the tree (rake-compiler stages callback-added files).
+      # rb_sys uses a per-package target dir unless the crate is a
+      # workspace member (then the root target/ holds artifacts) — glob
+      # both layouts.
+      art = Dir["target/#{triple}/release/expressir_core.{so,dylib,dll}",
+                "target/#{triple}/release/libexpressir_core.{so,dylib}",
+                "ext/expressir_core/target/#{triple}/release/expressir_core.{so,dylib,dll}",
+                "ext/expressir_core/target/#{triple}/release/libexpressir_core.{so,dylib}"].first
+      raise "binding artifact not found for #{plat} (#{triple})" unless art
+
+      cp art, "lib/expressir/"
+      spec.files << "lib/expressir/#{File.basename(art)}"
+    end
+  end
+rescue LoadError
+  # rake-compiler/rb_sys not installed (consumer checkouts); the native
+  # gem tasks are a maintainer/CI concern only.
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: expressir
 version: !ruby/object:Gem::Version
-  version: 2.4.24
+  version: 2.4.25
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-26 00:00:00.000000000 Z
+date: 2026-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys
@@ -251,9 +251,11 @@ extensions:
 extra_rdoc_files: []
 files:
 - ".cargo/config.toml"
+- ".github/scripts/test_installed_gem.rb"
 - ".github/workflows/codeql.yml"
 - ".github/workflows/docs.yml"
 - ".github/workflows/links.yml"
+- ".github/workflows/native-gems.yml"
 - ".github/workflows/rake.yml"
 - ".github/workflows/release.yml"
 - ".github/workflows/rust-ext.yml"
@@ -336,6 +338,17 @@ files:
 - TODO.parity-ee/18-mim-mapping.md
 - TODO.parity-ee/19-architecture.md
 - TODO.parity-ee/parity-matrix.md
+- TODO.suma-improvements/00-overview.md
+- TODO.suma-improvements/01-prebuilt-platform-gems.md
+- TODO.suma-improvements/02-suma-e2e.md
+- TODO.suma-improvements/03-item-graph.md
+- TODO.suma-improvements/04-compiled-set-default.md
+- TODO.suma-improvements/05-validation-in-docs.md
+- TODO.suma-improvements/06-memory-remeasure.md
+- TODO.suma-improvements/07-part28-xml.md
+- TODO.suma-improvements/08-windows-gnu-toolchain.md
+- TODO.suma-improvements/09-checker-tranche3.md
+- TODO.suma-improvements/10-expressdoc.md
 - benchmark/srl_benchmark.rb
 - benchmark/srl_native_benchmark.rb
 - benchmark/srl_ruby_benchmark.rb
@@ -657,6 +670,7 @@ files:
 - lib/expressir/schema_manifest_entry.rb
 - lib/expressir/version.rb
 - lib/tasks/verify_remarks.rake
+- rakelib/native.rake
 - rakelib/oracle.rake
 - rakelib/verify_remarks.rake
 homepage: https://github.com/lutaml/expressir