ibex 0.2.0 → 0.3.0

data/docs/ielr.md

@@ -0,0 +1,92 @@
+---
+title: IELR(1) construction
+description: The opt-in IELR construction strategies and their verification boundary.
+---
+
+# IELR(1) construction
+
+Ibex exposes IELR(1) as an opt-in parser-construction algorithm. It keeps the
+same Grammar IR, Automaton IR, conflict resolver, table generator, and runtime
+as SLR, LALR, and canonical LR(1). The default remains the compatible LALR
+path; selecting IELR does not change generated parser APIs.
+
+## Strategies
+
+`--algorithm=ielr` accepts two construction strategies:
+
+- `partition` (the default) constructs canonical LR(1) states and partitions
+  compatible isocores. It is the conservative reference strategy and remains
+  the release baseline.
+- `direct` starts with LR(0), computes LALR lookaheads and goto-follow
+  relations, traces grammar-relative inadequacies, splits only affected
+  isocores, and recalculates lookaheads on the split graph. It does not build a
+  canonical collection in the normal construction path.
+
+The direct strategy is deliberately not a claim of globally minimal state
+count. Its benefit is bounded construction work and phase-level evidence, not
+an unconditional reduction in the final table. `--remove-unreachable` is
+available as an explicit post-resolution compaction; it is off by default so
+state numbers used by diagnostics and generated artifacts remain stable.
+
+```sh
+ibex --algorithm=ielr --ielr-strategy=direct grammar.y
+ibex --algorithm=ielr --ielr-report grammar.y
+ibex --algorithm=ielr --ielr-strategy=direct --remove-unreachable grammar.y
+```
+
+`--ielr-report` is diagnostic-only. It constructs a canonical reference and
+reports action differences; it must not be confused with the direct build
+path. The report is useful for review and regression tests, but it is not a
+proof that every viable prefix has a unique state correspondence.
+
+## Construction phases
+
+The direct path is organized as the following explicit boundaries:
+
+1. `LR0Collection`, `LookaheadPropagation`, and `GotoFollows` build the LR(0)
+   collection, direct reads, successor/internal/includes relations, and LALR
+   lookaheads. `DirectLookaheads` remains the existing compatibility-path
+   cross-check.
+2. `IELR::Annotator` and `ItemLookaheads` classify conflicts and propagate
+   annotations over predecessor lanes. `SplitStability` discards annotations
+   whose resolved action cannot change under a split.
+3. `IELR::StateSplitter` copies transition tables for incompatible isocores and
+   preserves deterministic construction order.
+4. `LookaheadPropagation` reruns item-level propagation over the split graph.
+5. The existing `Builder` phase resolves conflicts and applies error/default
+   reductions, preserving the common Automaton IR contract.
+
+All lookahead sets are integer bitsets. `Analysis::Digraph` computes the
+successor, always, and includes closures with an iterative worklist so deep
+grammars do not depend on Ruby recursion depth.
+
+## Metrics and reports
+
+Profiled builds expose `ielr_annotations`, `ielr_annotated_states`,
+`ielr_inadequacies`, `ielr_split_stable_discarded`, `ielr_lalr_states`,
+`ielr_split_states`, `ielr_unreachable_removed`,
+`ielr_remergeable_candidates`, and the existing partition counts. Use
+`tool/construction_profile.rb --ielr-strategy=direct` to capture the direct
+measurements. Wall-clock values remain observations, not release gates.
+
+The phase implementation is covered by the paper-derived fixtures in
+`test/fixtures/ielr` and the structural tests in
+`test/lalr/ielr_direct_test.rb`. The direct strategy remains experimental
+until representative real-workload evidence and an independent adequacy
+review satisfy the direct-IELR decision dossier.
+
+## Verification boundary
+
+`Verify::ActionCorrespondence` and `LALR::InadequacyReport` are explicit
+diagnostic tools. They compare resolved actions and preserve a bounded search
+budget, but canonical-vs-target state pairing is not assumed to be a function.
+`Verify::LanguageWitness` supplies the strict IELR V9 bounded acceptance
+comparison; it reports token-level acceptance witnesses and fails closed when
+its finite case budget is exhausted. It does not prove unbounded equivalence,
+conflict preservation, or split correctness. Normal parser construction never
+invokes these diagnostics. Existing canonical-core verification remains the
+trusted boundary for release decisions.
+
+The implementation is independently derived from the published IELR paper and
+the repository's parser specifications. GNU Bison or another GPL
+implementation is not a design input.

data/docs/ja/bison-import.md

@@ -0,0 +1,51 @@
+# Bison 文法の解析用インポート
+
+`ibex import bison` は Bison 形式の文法構造を、解析専用の extended Ibex
+ソースへ一方向に変換します。互換パーサを生成するモードではありません。C
+アクションは不透明なまま保持され、解析中には実行されず、Ruby 生成はコードを
+出力する前に拒否されます。
+
+```sh
+ibex import bison parser.y -o parser.analysis.y
+ibex import bison --format=json parser.y > import-report.json
+ibex explain --state=STATE parser.y
+ibex metrics parser.y
+```
+
+2 個の `%%` 区切りを持つファイルは `explain` や `metrics` から直接解析
+できます。修復差分は変換後ソースのバイト位置に対するものなので、修復には
+明示的に出力した canonical 解析ファイルが必要です。
+
+対応指令は次の3種類です。
+
+- `%token`、結合規則、`%start`、`%expect`、`%empty`、`%prec` は既存の
+  Ibex 構文へ変換します。
+- `%type`、`%union`、printer/destructor、parameter、`%define`、`%code`
+  は位置付き metadata として報告します。
+- GLR、`%dprec`、`%merge`、生成制御、未知の指令は、出現ごとに元の行・列を
+  付けて未対応として報告します。
+
+`$$`、`$1`、型付き参照、`@$` は機械的に変換されますが、C の意味を Ruby
+として解釈しません。大文字の非終端、予約語、正規化後の名前衝突も、
+`bison_nt_*` / `BISON_T_*` と決定的な suffix で分離します。
+
+レポートと生成ソースは、単なる未対応と「生成規則を完全には復元できない」
+構造的不完全を区別します。後者には
+`ibex-bison-structural-status: incomplete` が付き、`ibex fix` は安全な
+同値修復を主張せず拒否します。
+
+既定上限は入力 20 MiB、構造 token 1,000,000、rule group 50,000、action
+100,000 です。`--max-*` は正の整数だけを受け付け、上限超過は JSON で明示し
+終了コード 2 になります。`-o` は原子的に書き込み、入出力 alias、symlink、
+複数 hard link を拒否します。
+
+外部 CI は5個の checksum 固定 GNU Bison 文法を一時取得し、成果物には含め
+ません。Bison 時代の CRuby `parse.y` では production 781 と未解決競合 0 が
+一致し、Bison 1,304 state と Ibex 1,303 state の差は、Bison が EOF shift
+専用 accept state を持つためです。
+
+現行 CRuby `parse.y` は Lrama 拡張を含み、GNU Bison の生入力ではありません。
+Ibex は `%rule` などを構造的不完全として全列挙し、限定した `explain` は
+近似文法の証拠としてのみ提示します。この状態で `fix` を提案しないことが安全
+契約です。固定 revision、license、取得元は
+[`gallery/EXTERNAL.md`](../../gallery/EXTERNAL.md) にあります。

data/docs/ja/stable-api.md

@@ -0,0 +1,53 @@
+# v1 安定 API
+
+この文書は v1 で Stable と判定された公開契約の日本語案内です。詳細な
+構文表や全メソッド一覧はリンク先の英語リファレンスを正本としますが、
+下記の契約、互換性、失敗条件は日本語でも同じ意味を持ちます。
+
+## racc 互換パーサ生成
+
+<!-- stable:compatible-parser:v2 -->
+
+既定モードは racc 互換の文法を読み、Pure Ruby の LR パーサを生成します。
+生成クラスは `do_parse` と `yyparse` を提供します。既定の直接 LALR 構築、
+plain/compact 表、yacc `error` 回復、コールバック、観測イベント、
+`ResourceLimits`、移行検査、境界付きの競合反例解析が Stable です。
+互換モードを明示せずに拡張構文へ切り替えることはありません。構文と CLI
+の詳細は [`grammar-reference.md`](../grammar-reference.md) を参照してください。
+
+`ibex fix` が検証済み修復として出すのは、対象競合を除去し、独立検証と
+有界同値検査を通った提案だけです。`%expect` と回復品質の設定は競合を
+除去しないため、修復や `--apply` 対象ではなく未検証の助言として分離して
+表示します。
+
+## Current IR と表
+
+<!-- stable:current-ir:v1 -->
+
+Grammar IR と Automaton IR は一つの current closed schema を使い、Lexer IR は
+独立した schema を持ちます。検証器は未知フィールド、不正な参照、schema の
+不一致を拒否します。dump → load → dump は決定的です。v1.0 前の互換性のない
+変更は writer、reader、schema、fixture、利用側を同じ変更で更新します。詳しい境界は
+[`architecture.md`](../architecture.md) にあります。
+
+## バッチ Red/Green CST
+
+<!-- stable:batch-cst:v1 -->
+
+format v6 のバッチ CST は、損失のない Green 値と位置・親参照を持つ Red
+ビューを分離します。typed syntax view、永続編集、差分、`ibex_cst` schema
+v1 の直列化が Stable です。エラー入力も `Error` / `Missing` 要素として木に
+残ります。syntax-only incremental session は Experimental であり、この
+Stable 契約には含まれません。API 例は [`cst.md`](../cst.md) を参照してください。
+
+## 互換性と非推奨化
+
+<!-- stable:compatibility-policy:v1 -->
+
+Stable API は semantic versioning に従います。v1.0 以降の削除や意味変更は、
+少なくとも2回の minor release にわたって移行警告、代替手段、最短削除版を
+文書化します。v1.0 前の Preview は固定された後方互換性契約ではなく、変更時に
+release note、移行メモ、回帰テスト、maturity evidence を同じ変更で更新します。
+v1.0 以降の Preview は少なくとも1回の minor release で予告し、Experimental は
+予告なく変わる可能性があります。正確な在庫と昇格条件は
+[`stability.md`](../stability.md) にあります。

data/docs/lexer-construction-profile.md

@@ -0,0 +1,109 @@
+# Generated lexer behavior and automaton decision
+
+H006 profiles the generated lexer that exists today. It does not replace that
+lexer, add an automaton implementation, or claim that the two lexical models
+are interchangeable. The machine-readable authority is
+[`lexer-profile-v1.json`](../tool/profile/evidence/lexer-profile-v1.json),
+validated by
+[`lexer-profile-v1.schema.json`](../schema/lexer-profile-v1.schema.json).
+
+Run and verify the profile with:
+
+```sh
+bundle exec ruby tool/lexer_profile.rb \
+  --output=tool/profile/evidence/lexer-profile-v1.json
+bundle exec rake quality:lexer_profile
+```
+
+The profiler generates parsers from committed grammar sources and executes
+their lexer and parser actions. It is therefore limited to trusted repository
+sources. It never downloads or executes the registered third-party grammars.
+
+## Semantics are different
+
+The current `regexp` profile anchors one Ruby `Regexp` per declared rule. Ruby
+chooses alternatives left-to-right inside that rule. Ibex then compares the
+lexemes returned by every active rule, chooses the longest byte length, and
+uses declaration order for a tie. These are two separate selection steps.
+
+For example, `/a|ab/` returns `a` for input `ab` inside its one Ruby rule. A
+regular-language automaton using maximal munch would select `ab`. Calling the
+second result a faster implementation of the first would hide a tokenization
+change.
+
+The conditional `automaton` profile described by the design has maximal munch,
+a declaration-order tie, declarative transitions, and bounded construction. It
+also excludes arbitrary Ruby actions and unspecified parser-to-lexer feedback.
+Those exclusions are a semantic boundary, not an implementation detail.
+
+## Workloads and provenance
+
+The evidence keeps source classes separate:
+
+- `synthetic` contains all eight required adversarial fixtures plus the three
+  registered gallery grammars. Every grammar and input has an exact Git
+  revision, path, byte digest, and derivation. The chunk fixture expands its
+  committed 128-byte seed 129 times, producing a 16,512-byte single token that
+  crosses the 16KiB streaming boundary.
+- `public_real` contains the exact BCDice, Namae, and Nokogiri CSS registry
+  identities. They use external application lexers and have no verified Ibex
+  generated-lexer port, so their status is `not_run`, their result is `null`,
+  and they contribute no inferred measurements.
+
+Synthetic success is not evidence that public-real lexers are suitable for an
+automaton migration. Evidence is generated from a clean exact revision, and
+that revision must be the first parent of the commit that records the evidence.
+The capture identity covers that revision, clean/status provenance, the complete
+bound execution-source closure, implementation subset, deterministic report
+input, measurement policy, and heuristic policy. The verifier locates the same
+identity in committed evidence history instead of accepting any ancestor with
+rewritten derived fields. A shallow checkout that lacks the evidence commit's
+parent or pinned fixture revisions fails closed; CI must fetch full history
+rather than treating missing provenance as a match.
+
+The capture command deliberately loads only the frontend, Grammar/Automaton IR,
+normalizer, analysis/LALR construction, Ruby code generator, and generated
+runtime graph. It does not load the public `ibex` aggregate, CLI, or configuration
+graph. Every repository Ruby source reachable from that measurement graph is a
+bound path, and capture aborts if another repository source is loaded. The public
+schema and this document are explicit generator-gem packaging expectations.
+
+## Measurements and limits
+
+Each measured workload records states, rules per state, token byte lengths,
+action-bearing rules, direct lexer/parser state mutation, parser feedback,
+Regexp warnings, streaming peak buffer bytes, and incremental bytes read from
+offset zero. Elapsed time and `GC.total_allocated_objects` deltas are retained
+only as host-bound diagnostics. Both the schema and semantic validator require
+`release_gate: false`; the quality comparison removes their values.
+
+The alternation, lazy-quantifier, and direct `lexer_state =` inventories are
+source-text heuristics over normalized rules and actions. They do not form a
+complete Ruby or Regexp semantic analysis. Aliases, helper calls,
+metaprogramming, indirect mutation, or dynamically composed behavior can be
+missed. A zero count is not proof of absence.
+
+The Unicode-property fixture uses String input. The current incremental
+`SourceText` path stores binary bytes, so this profile does not claim that
+Unicode-property matching works through that incremental path. The
+parser-feedback fixture is semantically parsed successfully, but its
+syntax-only incremental scan is `not_measured`: suppressing the parser action
+also suppresses the state change needed before the next token.
+
+Peak buffer bytes cover only `LexerInput`, not whole-process memory. The
+incremental full-scan share covers generated-lexer bytes read after a committed
+identity edit; it does not measure CST subtree reuse.
+
+## Decision
+
+| Scope | Decision | Reason |
+| --- | --- | --- |
+| Automatic replacement of the current Regexp lexer | **NO-GO** | `/a|ab/` proves different token boundaries; arbitrary actions and parser-driven state changes have no specified semantic translation. |
+| A separately named automaton lexer profile | **MORE DATA** | All adversarial fixtures are measured, but there are zero verified public-real generated-lexer workloads, no standalone semantic contract, and no verified adoption trigger. |
+
+Timing and allocation observations are not thresholds for either decision.
+Reconsidering automatic replacement requires an explicit compatibility model,
+an action/feedback contract, and differential evidence on verified real
+generated lexers. Reconsidering the separate profile requires at least two such
+public-real workloads, a bounded declarative semantics, and demonstrated user
+pressure that the design addresses.

data/docs/lexer-migration.md

@@ -1,3 +1,8 @@
+---
+title: Lexer migration
+description: Move a handwritten lexer or adopt the explicit generated lexer contract.
+---
+
 # Migrating a handwritten lexer
 
 The generated lexer uses the same `next_token` contract as a handwritten pull

data/docs/maturity.md

@@ -0,0 +1,128 @@
+# Preview and Experimental maturity audit
+
+[`maturity.yml`](maturity.yml) and the validator-owned commit authorities in
+[`maturity_authority.rb`](../tool/quality/maturity_authority.rb) form the joint
+human-reviewed trust boundary for H001. The registry binds the current 18
+Preview and two Experimental features to the reviewed repository revision,
+source digests, activation, external-use status, specification-history
+confidence, issue audit, documentation and tooling gaps, performance and safety
+limits, decision, next trigger, and release gates. Neither file authenticates
+the other; changing a classification requires reviewing and updating both.
+
+## Result
+
+<!-- maturity-summary:start -->
+Inventory: **18 Preview, 2 Experimental**. Active new Preview tracks: **1/3** (grammar syntax: **1/1**). Experimental product features: **2/5**.
+Release dependency state: R001 **hold_external**; R002 **pending_exact_revision**; no feature is promoted by this audit.
+
+| Stable ID | Feature | Current maturity | Decision | External use | Release gate |
+| --- | --- | --- | --- | --- | --- |
+| `ebnf-groups` | EBNF groups | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `parameterized-rules` | parameterized rules | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `inline-rules` | inline rules | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `middle-actions` | middle actions | Preview | Redesign Preview | not demonstrated | Blocked: R001, R002 |
+| `multiple-entries` | multiple entries | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `canonical-imports` | canonical imports | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `generated-lexers` | generated lexers | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `semantic-locations-types` | semantic locations/types | Preview | Redesign Preview | not demonstrated | Blocked: R001, R002 |
+| `ast-generation` | AST generation | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `grammar-tests` | grammar tests | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `documentation-tooling` | documentation tooling | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `ielr` | IELR | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `lsp` | LSP | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `watch` | watch | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `debug` | debug | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `coverage` | coverage | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `browser-playground` | browser playground | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `action-shadow` | action-shadow | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `bounded-repair` | bounded repair | Experimental | Keep Experimental | not demonstrated | Blocked: R001, R002 |
+| `incremental-cst` | incremental CST | Experimental | Keep Experimental | not demonstrated | Blocked: R001, R002 |
+<!-- maturity-summary:end -->
+
+Every keep decision names unmet promotion evidence. Two rows record redesigns.
+Compatible/default Racc middle actions are already governed by the Stable
+compatibility contract, and no separable Preview activation currently exists;
+the redundant Preview classification must be split or removed at the next
+reviewed release unless a distinct opt-in extension is defined. Compatible-mode
+location APIs and extended-only type declarations also require separate
+inventory records and promotion gates. Passing repository tests is necessary,
+but cannot establish external field compatibility, complete R001's independent
+review, or replace R002 on the exact release revision.
+
+Activation and maturity are independent. Middle actions are accepted in
+compatible/default grammars when an action is embedded before the end of a
+production, so the Stable guarantee takes precedence over Preview notice.
+Compatible semantic actions can consume lexer locations; only grammar `type`
+declarations require extended mode. Preview therefore does not imply that every
+audited surface is disabled by default or may break under Preview policy.
+
+The active declarative-parser-construction track changes how the already
+Preview IELR and multiple-entry contracts can be activated: an extended root
+grammar may now own those settings. It consumes the grammar-syntax budget but
+does not add or promote a maturity-inventory row. Its source history and field
+experience must be incorporated into the next reviewed maturity audit.
+
+## Evidence boundaries
+
+External use is evaluated against the stable IDs and classifications in the
+[public workload registry](workloads.md). `repository_synthetic` gallery use
+supports correctness testing only. `external_real` Bison inputs support only
+their registered diagnostic scope. Neither class is reported as third-party
+Ibex adoption. The current `public_real` records exercise compatible-mode
+generation and runtime, not one of the audited Preview or Experimental
+features, so every external-use result is `not_demonstrated`.
+
+The issue audit ran the exact GitHub Search API query and command recorded in
+the YAML on 2026-08-04. It returned zero open issues with a complete result.
+That result expires after 30 days and means only that the public tracker had no
+open report matching the query; it is not a correctness proof. The validator
+fails after the recorded freshness deadline until the exact audit is rerun and
+reviewed.
+
+Each feature records its validator-owned first Git pickaxe introduction, first
+containing release, canonical-blob presence, and integrity snapshots at v0.1.0,
+v0.2.0, and the exact reviewed revision. Each release boundary separately
+records one assessment for every path-relevant commit. An assessment binds the
+full revision, exact Git subject, classification, and commit-specific public
+contract effect. The validator reconstructs the reviewed commits from Git,
+checks ancestry and changed-path relevance, and derives both the boundary's
+reviewed and semantic commit sets from those exhaustive assessments. The
+path match determines which commits require assessment, not whether they are
+semantic. `semantic_change` is reserved for an observable syntax, API, output,
+or runtime change when that inventory row's feature configuration is active;
+changes behind mutually exclusive guards or confined to adjacent features are
+classified as nonsemantic and name the relevant guard or code path. The
+remaining `unknowns` state what repository history cannot establish, such as
+downstream compatibility and field use; source age or a digest change alone
+receives no semantic or promotion credit.
+
+The introduction method is exactly
+`git log --reverse --format=%H -SQUERY REVIEWED_REVISION -- PATH`; the reviewed
+revision bound prevents later history from rewriting the audit result.
+Boundary review uses `git log --reverse --format=%H FROM..TO -- PATH...` over
+the validator-owned introduction and canonical paths. The first range starts at
+the introduction commit's parent so the introduction itself is reviewed through
+its first containing release; subsequent ranges join exact release and reviewed
+revisions. Each source-tree digest hashes sorted canonical paths as path, NUL,
+exact Git blob bytes (or the literal `<absent>`), NUL. Digests are integrity
+evidence only: they neither discover nor classify semantic changes. Tags
+resolve to full commit IDs, and introductions, releases, and reviewed commits
+must have the recorded ancestry and order.
+
+## Updating the audit
+
+Run:
+
+```sh
+bundle exec rake quality:maturity
+bundle exec ruby -Itest test/quality/maturity_test.rb
+```
+
+For history changes, update the exhaustive assessments in `maturity.yml` and
+the explicit per-feature/per-boundary semantic authority together after human
+review. Update source SHA-256 values only as integrity records; never use them
+to infer semantics. A promotion also requires the feature's next-review
+evidence, completed R001 and exact-revision R002 states, and a synchronized
+generated summary in this file and [`stability.md`](stability.md). A redesign
+or removal is visible in the same summary and still follows the applicable
+Preview or Experimental compatibility policy.

data/docs/project-site-strategy.md

@@ -0,0 +1,54 @@
+---
+title: Project site strategy
+description: Information architecture and implementation boundaries for the Ibex public site.
+---
+
+# Project site strategy
+
+The public site is an adoption path rather than a catalogue of every internal
+feature. The intended sequence is:
+
+```text
+understand → try → install → investigate → verify → contribute
+```
+
+## Information architecture
+
+- The README answers the installation and first-parser decision in roughly 90
+  seconds.
+- Pages provides the task-oriented documentation hub, with Getting Started,
+  Guides, Reference, Concepts, Examples, Playground, API, and Project areas.
+- Compatibility, Extensions, Experimental, Gallery, Playground, and API keep
+  their existing URLs. They are canonical landing pages or redirects, not
+  discarded history.
+- Stable, Preview, and Experimental are feature metadata. They do not become
+  separate product versions or imply multiple persisted IR versions.
+
+## Content rules
+
+Public copy must distinguish racc migration compatibility from a claim of
+byte-for-byte replacement, bounded evidence from proof, and trusted generated
+Ruby from sandboxed execution. Comparative claims link to their complete
+evidence record. Maturity is read from `docs/maturity.yml`; prose does not
+duplicate a second feature registry.
+
+## Build and safety rules
+
+`tool/build_site.rb` is the canonical static builder. It reads docs source,
+renders the selected documentation pages, copies the canonical landing pages,
+and emits the Playground bundle into `tmp/site`. The builder must remain
+reproducible, self-hosted, and free of runtime gem dependencies. Every page
+uses a strict same-origin CSP, has a skip link and canonical metadata, and
+does not send grammar source to a third party. Playground actions remain
+non-executing, bounded, and worker-isolated.
+
+The implementation is intentionally framework-free. A framework migration is
+only worth revisiting if versioned documentation, multilingual content, large
+faceted search, or builder maintenance becomes a demonstrated cost.
+
+## Operational review
+
+Review the site with keyboard navigation, narrow viewports, zoom, reduced
+motion, link/anchor checks, and a clean rebuild. New feature claims must point
+to the maturity registry and evidence rather than being inferred from a
+landing-page badge.

data/docs/racc-migration-evidence.md

@@ -0,0 +1,45 @@
+# Racc migration evidence
+
+This page is the H002 evidence index for the compatibility claims in
+[`racc-migration.md`](racc-migration.md). It records observable behavior only;
+it does not claim that a third party has adopted Ibex, and it is not a
+performance result.
+
+## Evidence boundary
+
+The three public migration suites are pinned in
+[`release-readiness.md`](release-readiness.md): Namae, BCDice, and Nokogiri.
+Their revisions, adapters, and observed test counts are release evidence.
+The rows below are repository-owned black-box probes that target compatibility
+risks which are easy to miss in a single arithmetic grammar. They run against
+the installed `racc` executable when it is available and skip otherwise; a
+skip is not reported as a pass.
+
+| Risk | Probe and observable contract | Reproduction |
+|---|---|---|
+| precedence and conflict accounting | arithmetic results match; resolved conflicts remain visible in Automaton IR but do not inflate the CLI conflict count or `expect` | `bundle exec ruby -Itest test/compat/black_box_test.rb` |
+| empty productions and string tokens | empty reductions and literal-token paths produce the same public result values | `bundle exec ruby -Itest test/compat/black_box_test.rb` |
+| `convert` and `no_result_var` | token conversion and result-variable suppression preserve the generated parser's public action behavior | `bundle exec ruby -Itest test/compat/black_box_test.rb` |
+| inline actions | action placement and returned semantic values are equivalent at the public parser boundary | `bundle exec ruby -Itest test/compat/black_box_test.rb` |
+| `expect` and dangling-else behavior | the expected conflict count and parse result remain stable for the ambiguous grammar | `bundle exec ruby -Itest test/compat/black_box_test.rb` |
+| error recovery and `on_error` | callback arguments and recovered result values are compared; the documented undeclared-token difference remains explicit | `bundle exec ruby -Itest test/compat/black_box_test.rb` |
+| source locations and line conversion | semantic action line mapping follows the documented default and `--line-convert-all` modes | `bundle exec ruby -Itest test/racc_migration_test.rb` |
+| runtime initialization and value-stack reads | an initializer that omits `super` retains application state while historical value-stack reads remain compatible | `bundle exec ruby -Itest test/racc_migration_test.rb` |
+| unqualified `ParseError` | parser methods and actions can retain the explicit rejection path through `Runtime::Parser` lookup | `bundle exec ruby -Itest test/racc_migration_test.rb` |
+| large grammar construction | a 500-production grammar completes with the recorded production/state bound and no conflicts | `bundle exec ruby -Itest test/compat/black_box_test.rb` |
+| push-parser runtime contract | push-session lifecycle, token feeding, acceptance, and cleanup remain stable within Ibex's public runtime API | `bundle exec ruby -Itest test/runtime/push_parser_test.rb` |
+
+The compatibility test files are the executable source of truth. The commands
+above were last run at the evidence refresh and produced zero failures and zero
+errors (black-box: 6 runs/33 assertions; migration: 5 runs/20 assertions;
+push-parser: 46 runs/183 assertions). The black-box suite reported no skip in
+that environment.
+
+## Interpretation
+
+These probes establish coverage of distinct compatibility risks, not a claim
+that every racc grammar is interchangeable. Generated source layout, internal
+table arrays, `require "racc/parser"` replacement, and previously generated
+racc table loading remain explicitly out of scope. Formal cross-project
+performance comparison is tracked separately in the release-readiness report
+and remains incomplete until a clean, exact-revision artifact is published.

data/docs/racc-migration.md

@@ -1,3 +1,8 @@
+---
+title: Migrating from racc
+description: Move a racc grammar to Ibex with explicit compatibility checks and runtime boundaries.
+---
+
 # Migrating from racc
 
 Ibex targets grammar-file compatibility, generated parser public API compatibility, and the main racc CLI options. It does not
@@ -49,6 +54,12 @@ generated parsers in bounded child processes. This is not a sandbox; use a conta
 
 ## Compatibility baseline
 
+The repository probes and their exact reproduction commands are recorded in
+[`racc-migration-evidence.md`](racc-migration-evidence.md). That matrix is an
+internal evidence index: it distinguishes self-authored black-box coverage
+from the separately pinned public-gem migration suites and does not turn either
+set into a claim of third-party adoption or performance parity.
+
 The compatibility claims above were checked on 2026-07-22 against racc 1.8.1 using only its public documentation, `racc --help`,
 and black-box execution. Ibex does not inspect racc implementation files or generated source. Self-authored probes compare
 observable results for arithmetic precedence, empty rules, string tokens, `convert`, `no_result_var`, inline actions,