expressir 2.4.1 → 2.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 887f5f7d9c3e1b78d4f14496e63e003282622e779c675cccfd4a4623ce282efd
-  data.tar.gz: dc7294598d88c408e1eea276c85410ffe7b9f98bf94ab5da6cb0ae9daa9d58f7
+  metadata.gz: 0f786a7123d34be8bada764d132f213c09f229d5f94046509dbdbfc37a0d4279
+  data.tar.gz: 9b32c54df109ca8e6945ab03d2b7e3697d2b0bce3afbb67476bfe1510e0eb2fe
 SHA512:
-  metadata.gz: 7eaaadb131e964d12220a52d875b1ba77b1046d8dd4ca72e2c1362c2dfb7b66b36b4abc7f18fadae48878adced6362fe9f9d6ef3d0b51f5b73cf33e4c9227f53
-  data.tar.gz: 7c0decaf0a828843633e14a976a8f5aac0570e5d25e0e0023a02dc003463eedddd30ece51200fa40d4940fcb0f174bcbbdec5981970b2c0eadd8a881644d6108
+  metadata.gz: 5225e02955f94be94f71e9005330d1c58173ebd9cb5aa97956abfa9b8b8f3f2e964f25648d8074ad8ba41fb678530dad4348570ed8c697c6445224fe77c1514f
+  data.tar.gz: f97f4c7be51de8b6c5e4e71301555f20d05bdb268b61ef7df2e7be4bd06796af255b1f2cc362e6a25a61867fd62ab0b3610eb25683d57d6b36401c9a338598f5

data/TODO.max-perf/01-restore-ci-green.md

@@ -0,0 +1,29 @@
+# TODO.max-perf/01 — Restore CI green on main
+
+## Context
+
+CI on main (`0ef38e1`, 2026-09-17) fails on the Windows matrix: yeptris
+0.6.3.3's mingw build raises `NameError: uninitialized constant
+Yeptris::FFI::NODE_SCALAR` from `yeptris/node.rb` whenever `to_yaml` runs.
+Expressir's gemspec constraint (`~> 0.6.1`, from PR #346) allows it, and the
+Gemfile.lock is gitignored, so CI resolves the newest release at run time.
+
+yeptris has since released 0.6.4.1 and 0.6.5.1.
+
+## Work
+
+- [x] Reproduce the failing spec groups locally on the newest yeptris
+      (`package_fixtures_spec`, `package_spec`, `cache_spec`): 84/84 green on
+      0.6.5.1
+- [x] Re-run the failed rake workflow on main (resolves 0.6.5.1)
+- [ ] Confirm the rake workflow on main is green
+- [x] 0.6.5.1 does NOT fix mingw (same NameError, all Windows jobs) — filed
+      leptris/yeptris#318 with the CI repro
+- [x] expressir-side guard: `Expressir.select_serialization_engines` pins the
+      portable :standard YAML/JSON adapters on `Gem.win_platform?` at boot, so
+      lutaml-model's autodetection never loads the broken mingw build; Unix
+      keeps yeptris. Spec: spec/expressir/engine_selection_spec.rb
+
+## Acceptance
+
+rake workflow green on main across the full platform matrix.

data/TODO.max-perf/02-streaming-parse-path.md

@@ -0,0 +1,31 @@
+# TODO.max-perf/02 — Fix or retire the streaming parse path
+
+## Context
+
+`Parser.from_exp(use_streaming: true)` — documented as the maximum-performance
+path (construct-by-construct building via `Parsanol::Native.parse_with_builder`,
+no full intermediate AST) — fails on every schema tested with
+`Error::SchemaParseFailure` on parsanol 1.3.28 and 1.3.30. The feature is dead
+weight until it works: callers cannot opt into it, and it skews the perf
+picture (the fastest intended path is the broken one).
+
+## Work
+
+- [x] Reproduced on a 5-line schema: `parse_fresh(schema_grammar, block)` fails
+      at end-of-input — parse_fresh has no packrat memoization, which EXPRESS
+      requires (parsanol-ruby#52)
+- [x] The true streaming path (`from_exp_streaming_builder`) is unreachable:
+      its gate uses `defined?(Parsanol::Native.parse_with_builder)`, which is
+      always nil for the extension's dynamically-dispatched methods; calling it
+      directly yields empty models (builder protocol drift vs parsanol 1.3.30)
+- [x] Removed both dead paths; `use_streaming: true` now raises
+      `Error::StreamingUnsupportedError` with a precise message
+- [x] Spec: spec/expressir/express/streaming_spec.rb
+- [x] Upstream: covered by parsanol-ruby#59 roadmap (ractor-safe / stable
+      parse_with_builder unlocks a rewrite of this path)
+
+## Acceptance
+
+Either `use_streaming: true` produces an equal model with a green spec, or
+the breakage is precisely documented upstream and the path is explicitly
+marked unsupported.

data/TODO.max-perf/03-cli-parallel-opt-in.md

@@ -0,0 +1,27 @@
+# TODO.max-perf/03 — CLI parallel opt-in and multi-file loader consolidation
+
+## Context
+
+The fork worker pool (PRs #349/#351) is strictly opt-in for library users.
+The expressir CLI is application mode — our process — so it can opt in.
+Today `commands/coverage.rb` calls `Parser.from_files` without
+`max_processes` (sequential), and `commands/package.rb` calls
+`Model::Repository.from_files` — a *second* multi-file loading path
+duplicating the same orchestration (MECE violation).
+
+## Work
+
+- [x] `--max-processes` on `coverage` (default 4, Thor layer in cli.rb) and
+      `package build` (default 1 — strict error semantics preserved)
+- [x] `ParallelFiles.run` gained `strict:` — re-raises SchemaParseFailure,
+      preserving Repository.from_files' fail-fast contract
+- [x] `Model::Repository.from_files` now delegates its parse loop to
+      ParallelFiles (shared orchestration, strict mode); tolerant
+      Parser.from_files behavior unchanged
+- [x] Specs: repository parallel == sequential (ids + order), strict raise,
+      coverage/package suites green (57 + 57 examples)
+
+## Acceptance
+
+One multi-file loading pipeline; CLI bulk loads parse in parallel by
+default; library default remains sequential.

data/TODO.max-perf/04-benchmark-harness.md

@@ -0,0 +1,28 @@
+# TODO.max-perf/04 — Repair the SRL benchmark harness
+
+## Context
+
+`benchmark/srl_benchmark.rb` has two defects found during the Sept 2026
+validation:
+
+1. The "Ruby Parser" pass calls `from_file(file, skip_references: true)`
+   without `use_native: false`. Since native-became-default (2026-03-25),
+   both passes run the native parser — the head-to-head comparison is
+   mislabeled and meaningless.
+2. Per-file `Timeout.timeout(30)` cannot interrupt the native FFI parse
+   (GVL held), so pathological files hang the benchmark instead of timing
+   out — observed as a 25-minute stall on an 8.6KB schema.
+
+## Work
+
+- [x] Ruby-parser pass (and warmup) now pass `use_native: false`
+- [x] `parse_file_isolated`: per-file fork, length-prefixed Marshal results,
+      TERM→KILL wall-clock escalation — pathological files terminate
+- [x] `SRL_PATH` env override for reproducible smoke runs
+- [x] Verified: 3-fixture run prints genuine Ruby-vs-Native numbers with
+      truthful labels and terminates cleanly
+
+## Acceptance
+
+A short benchmark run prints genuine Ruby-vs-Native numbers, terminates on
+pathological files, and labels passes truthfully.

data/TODO.max-perf/05-parallel-fidelity-specs.md

@@ -0,0 +1,22 @@
+# TODO.max-perf/05 — Parallel-parsing fidelity specs
+
+## Context
+
+Parallel `from_files` equality is currently asserted on schema ids only.
+The pool crosses a fork boundary via Marshal; deep structural equality is
+the real contract. The progress-block regression merged in #349 (double
+`schemas` extraction) proved the block/caller paths need dedicated specs.
+
+## Work
+
+- [x] Deep-equality spec: `to_hash` of parallel repository == sequential
+- [x] Progress-block contract specs on both paths (schemas is an Array of
+      Declarations::Schema)
+- [x] Error-path specs: skip-vs-raise by mode (tolerant/strict), including
+      the strict-mode re-raise of SchemaParseFailure
+- [x] Gate specs: nil/1/<3 files and fork-less platforms never fork
+
+## Acceptance
+
+All fidelity specs green; `to_hash` of a parallel repository equals the
+sequential one for a multi-fixture corpus.

data/TODO.max-perf/06-builder-cpu-audit.md

@@ -0,0 +1,41 @@
+# TODO.max-perf/06 — Ruby-side (Builder) CPU audit on the current stack
+
+## Context
+
+After parsanol 1.3.30 (~2.5x further parse speedup), the native parse share
+collapsed and the Ruby side — AstTransformer → Builder → lutaml-model
+instantiation → remark attachment — is now the dominant parse cost
+(sampled 2026-09-17: 72/28 Rust/Ruby on 1.3.28; native got ~2.5x faster
+afterwards). March data ("removing Ruby transform: 2.5%") is obsolete.
+
+Related landed work: f32f85f "eliminate allocation storms in remark
+attachment" (another session, on main), 4c49e3a per-remark rescan guards.
+
+## Work
+
+Results (CPU-time, parsanol 1.3.30, 4 mid-size SRL schemas):
+
+| phase | total | share |
+|---|---:|---:|
+| native parse (parse_native) | 1.595s | 50% |
+| Builder.build_with_remarks | 1.530s | 48% |
+| reference resolution | 0.080s | 2% |
+
+Builder split: model build (`Builder.build`) 1.12s vs remark attachment
+0.06s — remark attachment is already cheap (f32f85f); the cost is
+AST-hash → lutaml-model instantiation.
+
+- [x] Phase timing recorded (above)
+- [x] Builder sub-phase split recorded (above)
+- [x] Next target identified precisely: `Builder.build` per-node path —
+      `cached_snake_case` / `fast_convert_keys` string allocations and
+      lutaml-model constructor overhead (thousands of attribute setters).
+      C stack sampling cannot name Ruby methods (vm_exec_core only);
+      instrument inside Builder.build or add stackprof as a dev dependency
+      before optimizing. Not refactored blindly — no safe evident win
+      without that instrumentation.
+
+## Acceptance
+
+A numbers table attributing Ruby-side parse CPU to phases, plus either a
+measured improvement or a precise, evidence-backed next target.

data/TODO.max-perf/07-upstream-parsanol-roadmap.md

@@ -0,0 +1,27 @@
+# TODO.max-perf/07 — Upstream parsanol roadmap (research 2022–2026)
+
+## Context
+
+The field's fastest grammar engines compile grammars instead of interpreting
+them. Mapping to parsanol (all upstream work; expressir only consumes):
+
+| Technique | Precedent | parsanol mapping |
+|---|---|---|
+| JIT grammar compilation + tag-dispatched structure switching + cross-grammar cache reuse (6x) | XGrammar-2 (arXiv:2601.04426) | BYTE_DISPATCH is conceptually TagDispatch; compile to a dispatch table per atom |
+| Grammar → generated code (production precedent) | tree-sitter (precompiled C, incremental reparse), CPython's generated PEG parser | generate Rust from the EXPRESS grammar instead of walking atom structs |
+| Skip packrat tables via automata | Pest discussion #1081 | memoization-free automata for the deterministic fragments; keep packrat only where ambiguity needs it |
+| SIMD byte classification (GB/s lexing) | simdjson, Lemire's vectorized classification (arXiv:2503.01662) | vectorize keyword/delimiter classification in the lexer tier |
+| Incremental re-parse | tree-sitter, gpeg (SLE'21) | re-parse only dirty schema blocks — pairs with expressir's SchemaBlockScanner |
+
+## Work
+
+- [x] Filed parsanol-ruby#59 with the mapping, profile evidence, citations,
+      and the Ractor-safe entry point item (the only parallelism option on
+      Windows MRI and fork-hostile embedders)
+- [x] Consumer unlocks noted: incremental reparse pairs with expressir's
+      SchemaBlockScanner; compiled grammar cuts cold-start (~2,300 atoms
+      serialized per boot); ractor-safe parse replaces the fork pool
+
+## Acceptance
+
+Upstream issue filed; expressir-side dependencies on each technique noted.

data/TODO.max-perf/08-builder-build-perf.md

@@ -0,0 +1,45 @@
+# TODO.max-perf/08 — Instrument and optimize Builder.build internals
+
+## Context
+
+TODO.max-perf/06 established the split (CPU-time, parsanol 1.3.30, 4 mid-size
+SRL schemas): native parse 50%, `Builder.build_with_remarks` 48%, references
+2%; within the builder, model build is 1.12s vs remark attachment 0.06s.
+`fast_convert_keys`/`cached_snake_case` are already single-pass and
+allocation-avoiding. The unmeasured stages inside `Builder.build`:
+
+1. `builder.call(snake_data)` — registered handler → lutaml-model
+   instantiation (thousands of attribute setters per schema)
+2. `attach_source_info` → `extract_source_info` → `find_slice` — a
+   depth-capped recursive scan of each node's data subtree; nested data can
+   be re-scanned by ancestors, which is quadratic-ish on deep nesting
+3. The `when Array` recursion
+
+## Work
+
+Findings: fast_convert_keys ran 172k–266k times per schema (~60 calls per
+model node): build() descends into subtrees the parent's deep conversion
+already scanned, so every subtree was re-scanned once per ancestor level.
+attach_source_info is negligible (0.02–0.07s instrumented upper bound);
+the remaining unoptimized share is lutaml-model instantiation inside
+builder.call (upstream territory).
+
+- [x] Instrumented (counters + timers) over topology / presentation /
+      measure / action schemas; split recorded above
+- [x] Implemented the evidenced win: fast_convert_keys marks scanned or
+      converted Hash/Array containers with an invisible ivar and skips
+      them on re-visits
+- [x] Before/after (CPU-time, warm): topology 0.42→0.25s (−40%),
+      presentation 0.27→0.22s (−19%), measure 0.43→0.30s (−30%),
+      action 0.11→0.06s (−48%)
+- [x] Full suite green (1551 examples) including golden-file parser specs;
+      to_hash equality verified against pre-change output on all four
+      schemas
+
+- [x] Handler-level audit (TODO 14 overlap): `expression` 25.8% / `syntax` 15.4% of builder self-CPU — structural dispatch cost (per-level key cascades + build_node wrapper-hash allocations) spread across ~20k nodes; no single fixable waste. Architectural cure = skip the intermediate Hash AST via parsanol's stable parse_with_builder (blocked upstream, TODO 02 / parsanol#59).
+
+## Acceptance
+
+Numbers table for the three stages; either a measured improvement merged or
+the cost definitively attributed to lutaml-model instantiation (which moves
+the next step upstream to lutaml-model).

data/TODO.max-perf/09-grammar-cold-start.md

@@ -0,0 +1,25 @@
+# TODO.max-perf/09 — Grammar cold-start cost and disk cache
+
+## Context
+
+Every process boot builds the parsanol grammar and serializes ~2,300 atoms to
+JSON (`Grammar::Parser.cached_parser` / `cached_grammar_json`) before the
+first parse. Short-lived processes (CLI invocations, tests) pay this on every
+run. parsanol-ruby#59 tracks upstream grammar-to-code compilation; an
+expressir-side JSON disk cache would help regardless.
+
+## Work
+
+Measured (fresh process, 3 runs): boot (require expressir) 161–181ms,
+grammar build ~28ms, JSON serialization ~30ms (83KB), first parse ~25ms.
+Grammar-related cold cost is ~58ms — below the 100ms bar; a disk cache
+would save ~50ms per process at the cost of temp-file staleness machinery.
+
+- [x] Cold-start measured and recorded (above)
+- [x] Documented as negligible — no cache implemented (the larger cold
+      cost is the 161ms require boot, a separate lazy-loading concern)
+
+## Acceptance
+
+Cold-start number recorded; cache implemented with specs if the number
+justifies it, otherwise documented as negligible.

data/TODO.max-perf/10-parser-facade-hygiene.md

@@ -0,0 +1,23 @@
+# TODO.max-perf/10 — Parser facade API hygiene
+
+## Context
+
+The `Parser` facade accumulated internal helpers with public visibility
+during the parallel work: `parse_files_sequentially` and `build_repository`
+are implementation details of `from_files`. `Commands::Coverage` defines a
+`DEFAULT_MAX_PROCESSES` constant that duplicates
+`ParallelFiles::DEFAULT_MAX_PROCESSES` (the CLI option default already
+references the latter directly) — a DRY violation with a dead constant.
+
+## Work
+
+- [x] `parse_files_sequentially` and `build_repository` are now
+      `private_class_method` (no external callers existed)
+- [x] Dead `Coverage::DEFAULT_MAX_PROCESSES` removed; the CLI option
+      default references `ParallelFiles::DEFAULT_MAX_PROCESSES` directly
+- [x] Rubocop clean; full suite green (1551 examples, 40s)
+
+## Acceptance
+
+Facade exposes only the public contract; single source for the worker-cap
+constant.

data/TODO.max-perf/11-ci-green-closeout.md

@@ -0,0 +1,25 @@
+# TODO.max-perf/11 — CI green close-out
+
+## Context
+
+TODO 01's final checkbox. Main carries the Windows fork guard (#353), the
+engine-selection guard pinning :standard adapters on `Gem.win_platform?`
+(#354), and the builder memoization (#355). yeptris mingw remains broken
+upstream (leptris/yeptris#318); the guard must keep it unloaded.
+
+## Work
+
+- [x] Confirmed locally via full `bundle exec rake` (CI-equivalent):
+      1558 examples, 0 failures, rubocop clean across 325 files
+- [x] If red: diagnose the failing job, fix in expressir if the defect is
+      here, escalate upstream otherwise
+
+- [x] Root causes of the red run on 35c1f62 found and fixed: (1) rubocop offenses in the committed benchmark harness + a directive typo in another session's remark perf spec — fixed; (2) sequential-path nil-pad parity bug in from_files — fixed with regression spec; (3) strict-mode spec unguarded on fork-less platforms — guarded; (4) yeptris still loading on Windows: root cause is lutaml-model#798 (configured adapter fell through to detection, loading yeptris before any expressir pin could apply) — fixed upstream + expressir spec_helper now pins json too, with a temporary require-spy proving zero yeptris loads in the suite
+
+- [x] Landed on main via #357 (the #356 merge had gone to its stale base
+      branch `feat/max-perf-todos`; cherry-picked 17aa264 onto main and
+      re-landed as 0576a08)
+
+## Acceptance
+
+rake green on main; TODO 01's checkbox ticked.

data/TODO.max-perf/12-require-boot-profile.md

@@ -0,0 +1,25 @@
+# TODO.max-perf/12 — Require-boot profile and deferrable loads
+
+## Context
+
+TODO 09 measured the cold start: grammar work is only ~58ms; the dominant
+cold cost is `require "expressir"` itself at 161–181ms. Short-lived
+processes (CLI, CI) pay it per invocation. expressir.rb eagerly requires
+`lutaml/model` and `liquid` (for Lutaml::Model::Liquefiable); the gemspec
+also pulls csv, benchmark-ips, ruby-progressbar, nokogiri-adjacent moxml,
+thor — some needed only by CLI commands, not by library consumers.
+
+## Work
+
+- [x] Profiled: per-gem load times via a require-timing probe in a fresh
+      process (results below)
+- [x] Evaluated deferrals: nothing safely deferrable (results below)
+- [x] Full suite green (no deferred loads introduced)
+
+- [x] Per-gem boot profile (fresh process, 2 runs): liquid 172-207ms, lutaml/model 327-559ms (includes moxml chain), thor 19-40ms, expressir own lib ~1ms (autoloads already optimal)
+- [x] Documented as not safely deferrable: liquid backs Lutaml::Model::Liquefiable used by expressir models in metanorma rendering; lutaml-model's boot is upstream (its lazy-loading is tracked there). expressir's own load adds ~1ms — nothing to defer.
+
+## Acceptance
+
+Per-gem boot profile recorded; measured reduction if safely deferrable,
+otherwise documented why not.

data/TODO.max-perf/13-key-conversion-specs.md

@@ -0,0 +1,26 @@
+# TODO.max-perf/13 — Unit specs for the key-conversion memoization
+
+## Context
+
+PR #355 optimized `Builder.fast_convert_keys` with an invisible-ivar marker
+so re-visited containers are skipped. The optimization is currently covered
+only indirectly by golden-file parser specs. The memoization's own contract
+needs pinning so future edits cannot silently break it.
+
+## Work
+
+- [x] Unit specs for the converter (renamed `AstKeyConverter.convert`):
+      - converts CamelCase keys at every depth; untouched data keeps object
+        identity
+      - idempotence: converted results convert to themselves
+      - marked containers are skipped on re-visits (marker on both paths)
+      - frozen input hashes do not raise
+- [x] Marker invisibility: marked hashes remain == to unmarked copies and
+      survive Marshal round-trip without affecting content
+
+- [x] All contract specs written against the extracted public Expressir::Express::AstKeyConverter (key conversion was promoted from a private Builder helper to its own class — MECE: converting AST keys is not building models)
+- [x] Depth conversion, identity preservation, idempotence, marker set on both paths, frozen-hash safety, marker invisibility (== and Marshal), snake_case behavior — spec/expressir/express/ast_key_converter_spec.rb
+
+## Acceptance
+
+Dedicated spec file green; the optimization's behavior is pinned.

data/TODO.max-perf/14-builder-call-handler-audit.md

@@ -0,0 +1,28 @@
+# TODO.max-perf/14 — Per-handler builder.call audit
+
+## Context
+
+TODO 08 attributed the remaining (post-memoization) builder cost to model
+instantiation inside `builder.call` — but that was inferred, not measured
+per handler. ~200 registered handlers exist (builders/*.rb); expressir-side
+waste in the hottest handlers (e.g., redundant intermediate arrays, repeated
+`build()` calls, hash re-shaping) would be ours to fix.
+
+## Work
+
+- [x] Instrumented per handler via a self-time build wrapper (child CPU
+      subtracted) over representative schemas; top handlers recorded below
+- [x] Inspected the top handlers' source (expression_builder.rb et al.)
+- [x] No evident expressir-side waste to fix (see verdict below); the
+      optimization taken instead was the fast_convert_keys memoization
+      (merged in #355) after TODO 08's stage instrumentation
+- [x] Full suite green
+
+- [x] Handler-level instrumentation via a self-time build wrapper (child-time subtracted): 20,270 nodes, 1.58s self CPU over 3 schemas
+- [x] Top handlers: expression 25.8% (3,184 calls), syntax 15.4%, entity_ref 7.7%, simple_expression 6.0%, entity_decl 5.1% — long tail of leaf handlers below 4% each
+- [x] Verdict: no single expressir-side waste; `expression`'s share is structural dispatch (if/elsif key cascades + per-call build_node wrapper-hash allocations). The architectural fix is bypassing the intermediate Hash AST entirely — blocked on parsanol's stable parse_with_builder (TODO 02, parsanol#59). Recorded; not refactored blindly.
+
+## Acceptance
+
+Handler-level numbers table; either a merged improvement or the cost
+definitively attributed to lutaml-model constructors (upstream follow-up).

data/benchmark/srl_benchmark.rb

@@ -17,7 +17,8 @@ require "parsanol/native"
 require "expressir"
 
 # Configuration
-SRL_PATH = "/Users/mulgogi/src/mn/iso-10303/schemas/resources"
+SRL_PATH = ENV["SRL_PATH"] ||
+  "/Users/mulgogi/src/mn/iso-10303/schemas/resources"
 ITERATIONS = (ENV["ITERATIONS"] || 1).to_i
 TIMEOUT_SECONDS = (ENV["TIMEOUT"] || 30).to_i # Timeout per file
 
@@ -104,6 +105,69 @@ def find_exp_files
   end
 end
 
+# Parse one file in a forked child with a hard wall-clock kill.
+# Ruby's Timeout cannot interrupt the native parser (the GVL is held
+# for the whole FFI call), so process isolation is the only reliable
+# guard against pathological backtracking hangs.
+def parse_file_isolated(file, use_native:, timeout: TIMEOUT_SECONDS)
+  rd, wr = IO.pipe
+  pid = fork do
+    rd.close
+    t = Time.now
+    result = { status: "ok", elapsed: 0.0, error: nil }
+    begin
+      if use_native
+        content = File.read(file)
+        Expressir::Express::Parser.from_exp(content, skip_references: true,
+                                                     use_native: true)
+      else
+        Expressir::Express::Parser.from_file(file, skip_references: true,
+                                                   use_native: false)
+      end
+    rescue StandardError => e
+      result[:status] = "err"
+      result[:error] = "#{e.class}: #{e.message[0..60]}"
+    end
+    result[:elapsed] = Time.now - t
+    data = Marshal.dump(result)
+    wr.write([data.bytesize].pack("N"))
+    wr.write(data)
+    wr.close
+    exit!(0)
+  end
+  wr.close
+
+  deadline = Time.now + timeout
+  timed_out = false
+  loop do
+    done = Process.waitpid(pid, Process::WNOHANG)
+    break if done
+
+    if Time.now > deadline
+      Process.kill("TERM", pid)
+      sleep 1
+      begin
+        Process.kill("KILL", pid) if Process.waitpid(pid, Process::WNOHANG).nil?
+      rescue StandardError
+        nil
+      end
+      timed_out = true
+      break
+    end
+    sleep 0.1
+  end
+
+  if timed_out
+    rd.close
+    { status: "timeout", elapsed: timeout.to_f, error: "Timeout after #{timeout}s" }
+  else
+    header = rd.read(4)
+    payload = header && Marshal.load(rd.read(header.unpack1("N"))) # rubocop:disable Security/MarshalLoad
+    rd.close
+    payload
+  end
+end
+
 def count_lines(files)
   files.sum { |f| File.read(f).lines.count }
 end
@@ -176,28 +240,22 @@ class ParserBenchmark
       file_start = Time.now
       schema_lines = File.read(file).lines.count
 
-      begin
-        require "timeout"
-        Timeout.timeout(TIMEOUT_SECONDS) do
-          if @use_native
-            content = File.read(file)
-            Expressir::Express::Parser.from_exp(content, skip_references: true,
-                                                         use_native: true)
-          else
-            Expressir::Express::Parser.from_file(file, skip_references: true)
-          end
-        end
+      result = parse_file_isolated(file, use_native: @use_native)
+      result[:elapsed]
+
+      case result[:status]
+      when "ok"
         iteration_results[:success] += 1
         status = "#{BRIGHT_GREEN}✓#{RESET}"
-      rescue Timeout::Error
+      when "timeout"
         iteration_results[:failed] += 1
         iteration_results[:errors] << { file: File.basename(file),
-                                        error: "Timeout after #{TIMEOUT_SECONDS}s" }
+                                        error: result[:error] }
         status = "#{BRIGHT_YELLOW}⏱#{RESET}"
-      rescue StandardError => e
+      else
         iteration_results[:failed] += 1
         iteration_results[:errors] << { file: File.basename(file),
-                                        error: e.message[0..60] }
+                                        error: result[:error] }
         status = "#{BRIGHT_RED}✗#{RESET}"
       end
 
@@ -346,7 +404,8 @@ print_warmup_start
 warmup_file = files.first
 
 begin
-  Expressir::Express::Parser.from_file(warmup_file, skip_references: true)
+  Expressir::Express::Parser.from_file(warmup_file, skip_references: true,
+                                                    use_native: false)
 rescue StandardError => e
   puts "#{BRIGHT_YELLOW}⚠️  Ruby warmup warning: #{e.message[0..40]}#{RESET}"
 end

data/expressir.gemspec

@@ -42,7 +42,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "paint"
   spec.add_dependency "parsanol", "~> 1.3.9", ">= 1.3.9"
   spec.add_dependency "ruby-progressbar", "~> 1.11"
-  spec.add_dependency "rubyzip", "~> 3.4"
+  spec.add_dependency "rubyzip"
   spec.add_dependency "table_tennis"
   spec.add_dependency "thor", "~> 1.0"
   # Native YAML/JSON engine (lutaml-model opt-in by bundle contents)

data/lib/expressir/cli.rb

@@ -67,6 +67,9 @@ module Expressir
                            desc: "Output file path for JSON/YAML formats (defaults to coverage_report.json/yaml)"
     method_option :ignore_files, type: :string,
                                  desc: "Path to YAML file containing array of files to ignore from overall coverage calculation"
+    method_option :max_processes, type: :numeric,
+                                  default: Expressir::Express::ParallelFiles::DEFAULT_MAX_PROCESSES,
+                                  desc: "Parallel parse workers (1 = sequential; falls back to sequential where fork is unavailable)"
     def coverage(*paths)
       Expressir::Commands::Coverage.new(options).run(paths)
     end

data/lib/expressir/commands/coverage.rb

@@ -73,7 +73,9 @@ module Expressir
 
         # Parse all files and create a repository with progress tracking
         begin
-          repository = Expressir::Express::Parser.from_files(exp_files) do |filename, _schemas, error|
+          repository = Expressir::Express::Parser.from_files(
+            exp_files, max_processes: options[:max_processes]
+          ) do |filename, _schemas, error|
             if error
               say "  Error processing #{File.basename(filename)}: #{error.message}"
             end
@@ -125,7 +127,9 @@ module Expressir
             )
 
             # Process files with progress tracking
-            repository = Expressir::Express::Parser.from_files(schema_files) do |filename, _schemas, error|
+            repository = Expressir::Express::Parser.from_files(
+              schema_files, max_processes: options[:max_processes]
+            ) do |filename, _schemas, error|
               if error
                 say "  Error processing #{File.basename(filename)}: #{error.message}"
               end

data/lib/expressir/commands/package.rb

@@ -91,9 +91,12 @@ module Expressir
                            desc: "Skip manifest verification (may result in incomplete packages)"
       option :verbose, type: :boolean, default: false,
                        desc: "Enable verbose output"
+      option :max_processes, type: :numeric, default: 1,
+                             desc: "Parallel parse workers for schema loading (1 = sequential)"
       def build(root_schema = nil, output = nil)
         schema_files, output = resolve_schema_files(root_schema, output)
-        repo = Expressir::Model::Repository.from_files(schema_files)
+        repo = Expressir::Model::Repository.from_files(schema_files,
+                                                       max_processes: options[:max_processes])
         validate_repository(repo) if should_validate?
         create_package(repo, output)
       rescue Expressir::Error