ibex 0.2.0 → 0.3.0

data/docs/configuration-model.md

@@ -0,0 +1,59 @@
+---
+title: Configuration model
+description: Decide which parser settings belong to grammar source and which belong to an invocation.
+---
+
+# Configuration model
+
+Ibex keeps reproducible grammar intent in the grammar and keeps environment or
+review choices at the invocation boundary. This separation prevents a build
+flag from silently changing a source-owned parser contract.
+
+## Grammar-owned settings
+
+Declare settings in an extended grammar when every consumer should observe the
+same choice:
+
+```text
+class ExampleParser
+pragma extended
+parser
+  algorithm ielr
+  entries isolated
+end
+```
+
+The current grammar-owned parser block supports `slr`, `lalr`, `ielr`, or
+`lr1` construction and `shared` or `isolated` entry handling. The declaration
+is part of normalized Grammar IR and is visible in generated reports.
+
+## Invocation-owned settings
+
+Keep these choices at the CLI or API call site because they describe a local
+operation rather than the grammar's meaning:
+
+- output path and embedded-runtime selection (`-o`, `-E`);
+- table representation and diagnostic format;
+- warnings, verification strictness, resource budgets, and report output;
+- a temporary analysis algorithm used for comparison or investigation; and
+- external command execution for explicitly unsafe fuzz or reduction workflows.
+
+An invocation may select an analysis algorithm, but it must report that the
+selection is noncanonical when it differs from the grammar declaration. A
+conflicting canonical selection is rejected at the declaration location.
+
+## Review checklist
+
+When adding a setting, ask:
+
+1. Would two independent users of the same grammar need the same value? If so,
+   it is grammar-owned.
+2. Is the value about this run, host, output, or evidence capture? If so, it is
+   invocation-owned.
+3. Does changing it alter generated parser behavior, persisted IR, or runtime
+   ABI? Update the relevant schema, fixture, maturity entry, and migration note.
+4. Is the setting opt-in? Keep the compatible default unchanged and document
+   the activation boundary next to the option.
+
+See the [stability policy](stability.md), [grammar reference](grammar-reference.md),
+and [development guide](development.md) for contract and verification rules.

data/docs/configuration-report.md

@@ -0,0 +1,28 @@
+# Effective configuration reports
+
+`ibex config` explains every key in `Ibex::Configuration::Registry` without generating or loading a parser:
+
+```console
+ibex config grammar.y
+ibex config --format=json grammar.y
+ibex config --from=grammar-ir --format=json grammar.json
+```
+
+The command has a `static-no-user-code` trust boundary. For grammar source it uses the contained source resolver, so
+the root grammar and its import closure are parsed as data while parent traversal, absolute imports, glob imports,
+and symlink escapes are rejected. Parser actions, lexer actions, user-code sections, and generated parser classes are
+never executed or required. Grammar IR input is accepted only through the normal current-format validator.
+
+Each setting reports its effective value, owner, override policy, origin and source location when recorded,
+explicit or implicit selection, canonical or noncanonical conformance, recording status, and source evidence.
+Evidence is classified as `accepted`, `ignored`, `duplicate`, or `conflicting`. The JSON projection is deterministic,
+uses schema version 1, and always lists canonical keys in lexical order.
+
+The current Grammar IR `parser_contract` entries are authoritative for `parser.algorithm`, `parser.entries`, and `cst.trivia`.
+A matching command-line request is retained as accepted evidence. A contradictory request produces a positioned,
+structured conflict report and exits nonzero. An unspecified entry remains explicitly `unspecified`; a document without
+the current contract is rejected. A current builtin or CLI value is never presented as a historical fact.
+
+The source grammar syntax supports the root-only declarative parser block in extended mode. CST ownership is
+declared as `cst_trivia leading|balanced|drop` and requires `pragma cst`; `ibex config` reports the resulting
+value and source location without executing user code. It does not recognize generic or unknown settings.

data/docs/conflict-explanation-reviews/v1/records/README.md

@@ -0,0 +1,28 @@
+# H004 independent review records
+
+During blind collection, review only
+`docs/conflict-explanation-reviews/v1/blind-study-v1.json`. Do not inspect the
+source study, review registry, implementation, or repository history until the
+submission has been sealed. The blind artifact uses neutral IDs and excludes
+the source case ID, shape, grammar path, and maintainer hypothesis. For every
+case, use its state items, competing actions, bounded witness, and repair
+section to identify the cause and choose an edit without executing grammar
+actions.
+
+A record must match `schema/conflict-explanation-review-v1.schema.json`'s
+`review_record` definition and contain exactly one review for each of
+`H004-BLIND-01` through `H004-BLIND-04`. Copy the blind artifact SHA-256 into
+the record, set `submitted_before_reveal` to true only when accurate, record
+your own cause and edit text, and leave `reveal_comparison.status` as `pending`.
+If the machine artifact offers no verified repair, `chosen_edit` may describe a
+manual edit and `repair_usefulness` should remain `no_verified_repair` unless
+there is an actual proposal to assess.
+
+The registry remains in `blind_collection` and `HOLD` until it has at least two
+records from distinct reviewers. Only then may the source study be revealed.
+During `reveal_comparison`, map every neutral ID to its source case, bind the
+source study digest, and record cause/edit alignment plus notes without
+rewriting the original blind answers. The registry reaches `review_complete`
+and `PASS` only when every record has a completed reveal comparison. Do not
+collapse disagreements into a majority label; preserve them in each record and
+in the registry summary.

data/docs/conflict-explanation-study.md

@@ -0,0 +1,62 @@
+# Conflict-explanation usefulness study
+
+H004 separates reproducible machine evidence from subjective usefulness
+review. The committed version-1 corpus contains four grammar shapes and five
+conflicts:
+
+- an ambiguous expression and dangling `else` shift/reduce conflict;
+- an ambiguous reduce/reduce choice;
+- two nonunifying reduce/reduce conflicts introduced by LALR context merging.
+
+Each case binds its grammar bytes, Automaton IR digest, conflicting state items,
+competing actions, resolution, and bounded witness. It also runs the existing
+`fix` candidate search with fixed limits. Only the expression case currently
+has a machine-verified proposal: declaring right associativity for `PLUS`
+removes the conflict and finds no language or mapped-tree difference within the
+recorded bounds. The other cases truthfully record `no_safe_proposal`; advice
+that merely acknowledges a conflict or changes recovery is labeled as not a
+verified repair.
+
+Every witness records its typed search outcome, explored configuration count,
+exhaustion flag, and token/configuration bounds. A configuration-budget
+exhaustion is `inconclusive`; it is never relabeled as a nonunifying witness or
+accepted into the fixed study capture.
+
+Regenerate or verify the machine capture with:
+
+```sh
+bundle exec ruby tool/conflict_explanation_study.rb --write
+bundle exec rake quality:conflict_explanations
+```
+
+The normative machine artifact is
+[`study-v1.json`](../test/fixtures/conflict_explanations/study-v1.json),
+validated by the closed
+[`schema`](../schema/conflict-explanation-study-v1.schema.json). The capture
+uses repository-owned grammars and never executes grammar actions. Search,
+candidate, build, equivalence, and verifier limits are explicit; exhaustion is
+not success. The detailed pre-implementation contract and kill conditions are
+recorded in the [investigation](investigations/H004-conflict-explanation-study.md).
+
+## Independent human gate
+
+The machine capture proves reproducibility, not usefulness. Independent
+reviewers receive only the deterministic
+[`blind-study-v1.json`](conflict-explanation-reviews/v1/blind-study-v1.json)
+view. It uses neutral case IDs and omits the repository case ID, shape, grammar
+path, and `maintainer_hypothesis`. Reviewers use its state/items and witness to
+identify the cause, then choose an edit and explain whether the explanation and
+proposed repair helped. Each submission binds the blind artifact digest and is
+sealed before any expected answer is revealed.
+The [record instructions](conflict-explanation-reviews/v1/records/README.md)
+and [review schema](../schema/conflict-explanation-review-v1.schema.json)
+preserve per-case rationales and reviewer disagreement.
+
+The current subjective gate is **HOLD** with zero external records, as recorded
+in the [status registry](conflict-explanation-review-status-v1.json). Once at
+least two distinct blind submissions cover every neutral case, the repository
+case mapping and maintainer hypotheses may be revealed. Each reviewer record
+must then retain a per-case comparison against that revealed material. PASS is
+possible only after every comparison is complete; disagreement cannot be
+replaced with a majority percentage. Until then no usefulness rate,
+comparative superiority, or general conflict-repair claim is publishable.

data/docs/construction-profiling.md

@@ -0,0 +1,157 @@
+# IELR and multi-entry construction profiling
+
+This document closes H005's profiling work without selecting or implementing a
+new construction algorithm. The machine-readable authority is
+[`construction-profile-v1.json`](../tool/profile/evidence/construction-profile-v1.json),
+validated by
+[`construction-profile-v1.schema.json`](../schema/construction-profile-v1.schema.json).
+It is an `internal_local_observation`, not release or adoption evidence.
+
+## Public profiler
+
+Run the repository-owned and synthetic profiles with:
+
+```sh
+bundle exec ruby tool/construction_profile.rb \
+  --wall-seconds=60 \
+  --output=tool/profile/evidence/construction-profile-v1.json
+bundle exec rake quality:construction_profile
+```
+
+Third-party observations require a full checkout that the existing public
+workload manifest can verify. Each checkout must have the exact revision,
+origin, clean status, grammar digest, and structural baseline:
+
+```sh
+bundle exec ruby tool/construction_profile.rb \
+  --checkout=namae=/path/to/namae \
+  --checkout=bcdice_command=/path/to/BCDice \
+  --checkout=nokogiri_css=/path/to/nokogiri
+```
+
+Omitting a checkout records its exact registry metadata as `not_run`; it does
+not silently profile a cached file or substitute a synthetic grammar.
+
+The artifact separates reconstructible source provenance from host-bound
+observations. `provenance.base_revision` is only the Git base: when capture is
+dirty, every H005 contract path records its observed digest, base-object
+digest, and `base` / `modified` / `untracked` state. The clean flag is derived
+from the exact porcelain status; the status, bound-path set, implementation
+subset, host observation, and measurement policy each have an integrity
+digest. The evidence file is excluded from the source and implementation
+digests, so no digest refers to the bytes that contain itself.
+
+The quality gate reconstructs the base objects, requires the base to be an
+ancestor of the checked revision, verifies current contract bytes against the
+bound paths, and checks all derived digests and workload/run entry identities.
+Ruby version and options, kernel, CPU, and other host fields remain explicitly
+host-bound rather than cross-platform goldens, but their recorded values are
+validated against `environment_observation_sha256` before that observation is
+excluded from the deterministic structural comparison.
+
+Every construction has an explicit wall-time limit. Exceeding it records the
+resource and limit. `NoMemoryError` and `SystemStackError` are recorded as
+resource exhaustion. Those results establish only that a bound was observed;
+they are not negative proofs about the language or algorithm.
+
+## Counting contract
+
+The profiler records these structural quantities from the construction that
+already exists:
+
+| Field | Meaning |
+| --- | --- |
+| `lr0_states` | Distinct LR(0) cores materialized directly or represented by the canonical collection. |
+| `lr0_items` | Core-item occurrences across those distinct cores. |
+| `canonical_states` / `canonical_items` | Canonical LR(1) states and item triples, only when that collection completes. |
+| `final_states` / `final_items` | States and core-item occurrences after merge or IELR partitioning. |
+| `final_lookahead_items` | Lookahead memberships across final core items. |
+| `propagation_edges` | Deduplicated direct-LALR lookahead propagation edges; canonical paths report `not_applicable`. |
+| `ielr_initial_partitions` / `ielr_final_partitions` | Compatible partitions before and after transition refinement. |
+
+`not_applicable` is reserved for metrics that the selected construction path
+does not perform, such as canonical-state counts in direct LALR. A metric that
+would apply but could not be collected because construction timed out or
+failed is `not_measured`; failure never masquerades as algorithmic absence.
+
+Elapsed seconds are retained only as host-bound observations. The schema fixes
+`release_gate` to `false`, and the quality gate deliberately removes elapsed
+values before comparing evidence. Ruby's live-slot counters are neither a
+peak measurement nor reproducible retained-object accounting, so peak retained
+objects are truthfully `not_measured`. The current builders also expose no
+state budget or portable per-build heap limit; both omissions are explicit in
+the evidence.
+
+Profiling is opt-in through `Builder(profile: true)`. Ordinary generation does
+not calculate the additional item/core summaries. Parser tables, conflicts,
+generated source, runtime ABI, Grammar IR, and Automaton IR are unchanged.
+
+## Current observations
+
+Synthetic and real workloads are separate cohorts. All repository grammar
+revisions and SHA-256 digests come from the public workload registry. The
+multi-entry diagnostic is the existing representative matrix grammar at the
+recorded exact revision, not a new language fixture.
+
+| Workload | Class | LR(0) states/items | Direct propagation edges | Canonical LR(1) states/items | IELR partitions initial/final | Final states |
+| --- | --- | ---: | ---: | ---: | ---: | ---: |
+| `gallery-calc` | repository synthetic | 15 / 76 | 99 | 27 / 674 | 15 / 15 | 15 |
+| `gallery-json` | repository synthetic | 27 / 82 | 111 | 57 / 272 | 27 / 27 | 27 |
+| `gallery-sql-lite` | repository synthetic | 26 / 53 | 55 | 26 / 115 | 26 / 26 | 26 |
+| `matrix-multi-entry` | repository synthetic | 9 / 14 | n/a | 9 / 20 | 9 / 9 | 9 |
+| `ibex-frontend` | repository real | 227 / 633 | 749 | 456 / 10,482 | 227 / 227 | 227 |
+
+The table pairs direct-LALR edge counts with the canonical collection used by
+current IELR. The multi-entry row reports the shared result; its committed run
+records also contain isolated LALR and IELR. On this diagnostic all four
+shared/isolated combinations retain 9 states, 14 final core items, and 20 final
+lookahead memberships. That bounded synthetic equality is not evidence that a
+direct multi-entry implementation lacks value on real grammars.
+
+The three `public_real` identities—Namae, BCDice command, and Nokogiri CSS—are
+recorded as `not_run` because no checkout satisfying the public manifest was
+supplied for this evidence capture. They contribute no state, item, edge,
+partition, failure, or timing observation. The only measured real workload is
+the repository's production frontend; it has no unresolved conflict requiring
+IELR, and current IELR partitions its 456 canonical states back to the same 227
+final states as direct LALR.
+
+## Decisions
+
+Direct IELR is **NO-GO** under the current verifier and workload evidence.
+Direct multi-entry is **MORE DATA**.
+
+### Direct IELR — NO-GO
+
+The threshold is at least two verified representative real grammars that both
+show a practical canonical-collection cost and require IELR for semantically
+meaningful conflicts. The current artifact has one measured real grammar, zero
+real IELR-required conflict cases, and no verified public checkout.
+
+[V001](verifier-trust-boundary.md) is complete, so the trust-boundary threshold
+is satisfied. It also establishes a current NO-GO condition: default and
+strict `ielr1` verification both enumerate the full canonical LR(1)
+collection. A direct builder would therefore not remove canonical scale cost
+from the current verified workflow, and the verifier does not establish IELR
+adequacy or split witnesses. Together with no real IELR-required workload,
+that makes direct IELR unjustified now rather than merely unmeasured.
+
+Evidence that can change the decision must include verified real grammars,
+material canonical state/item cost or observed exhaustion, meaningful
+conflicts removed by IELR, a bounded verification plan that does not make full
+canonical enumeration mandatory, and an owner accepting the specification and
+maintenance budget. State-count vanity alone is insufficient.
+
+### Direct multi-entry — MORE DATA
+
+The threshold is at least two verified real multi-entry grammars plus either an
+observed construction bound or at least twofold structural overhead in the
+current shared path relative to an admitted direct plan. The registry contains
+zero real multi-entry workloads. The existing synthetic matrix exercises both
+shared and isolated modes, but neither its elapsed time nor its equal state
+counts justify a production algorithm.
+
+Evidence that can change the decision must add verified real multi-entry
+grammars, preserve entry dispatch and shared conflict attribution, demonstrate
+material structural cost, and identify an owner for the semantic and
+maintenance plan.

data/docs/cst-migration.md

@@ -1,10 +1,9 @@
 # CST Red/Green migration
 
 The runtime supports only the current format-v6 Red/Green representation for
-`pragma cst`. CST parser tables from formats v1 through v5, and boolean
-`cst: true` tables without structured metadata, fail before the first token is
-read and instruct the application to regenerate. Older non-CST parser tables
-remain executable.
+`pragma cst`. CST parser tables from formats v1 through v5, boolean
+`cst: true` tables without structured metadata, and all v1-v5 non-CST tables
+fail before the first token is read and instruct the application to regenerate.
 
 Regenerate with the same command used for the grammar, for example:
 

data/docs/cst.md

@@ -1,5 +1,12 @@
+---
+title: Concrete syntax trees
+description: Lossless Red/Green CSTs, typed views, editing, and incremental session boundaries.
+---
+
 # Red/Green concrete syntax trees
 
+<!-- stable:batch-cst:v1 -->
+
 `pragma cst` generates a lossless, error-tolerant syntax tree alongside the
 ordinary semantic result. Regenerate the parser with the current generator to
 receive parser-table format v6 and this API. Batch parsing, typed views,
@@ -32,6 +39,10 @@ root = result.syntax_root
 diagnostics = result.diagnostics
 ```
 
+This is a trusted application runtime path. Parser production actions and
+generated lexer actions execute, and loading the generated Ruby file may run
+`header`, `inner`, or `footer` code. `parse_with_syntax` is not a sandbox.
+
 `parse`, `do_parse`, and `yyparse` keep their semantic return values.
 `parser.syntax_root` exposes the most recent syntax root. Every successful root
 has this physical shape:
@@ -144,6 +155,13 @@ but no semantic value. Generated lexer actions still run because they define
 token emission and lexer-state changes. Run a normal parse separately when a
 semantic value or side effect is required.
 
+Consequently, `parse_syntax` and `incremental_session` are syntax-only but not
+"no user code" APIs. Loading the generated class may execute user sections,
+and lexer actions may perform arbitrary Ruby side effects. Treat the generated
+class as trusted application code. A future nonexecuting syntax profile would
+require a declarative built-in-only lexer and no `header`, `inner`, or `footer`
+sections; the current API does not provide that profile.
+
 Sessions require `SourceText`, a generated lexer, format-v6 CST metadata, and
 non-`drop` trivia. Handwritten token sources and push input are unsupported.
 Parser actions that alone switch lexer state are also unavailable because the
@@ -157,6 +175,12 @@ memo bytes; a bound failure deterministically falls back to the fresh token
 stream. Observe `cst_built`, `cst_reuse`, and `cst_fallback` runtime events for
 metrics.
 
+Applications that need an explicit generated-language service boundary can use
+the Experimental [`syntax_session` façade](syntax-sessions.md). It adds
+trust-profile acknowledgement, immutable operation snapshots, expected tokens,
+reuse/fallback metrics, cancellation, and service resource bounds while using
+this same incremental engine. It does not add LSP or workspace semantics.
+
 ## Serialization
 
 `ibex_cst` schema v1 is independent from Grammar IR:

data/docs/decisions/0000-template.md

@@ -0,0 +1,24 @@
+# ADR NNNN: Implementation decision title
+
+- Status: Proposed
+- Date: YYYY-MM-DD
+
+## Context
+
+Describe the concrete implementation question and its compatibility, data,
+runtime, or component constraints. Operational workflow and release policy do
+not belong in this directory; see [the scope](README.md).
+
+Name the credible alternatives. If there was no meaningful alternative, record
+the behavior in reference documentation instead of creating an ADR.
+
+## Decision
+
+Describe the durable boundary or architecture choice. Leave command syntax,
+field-by-field formats, test evidence, benchmark results, and migration steps
+in their authoritative documents.
+
+## Consequences
+
+Describe the important positive and negative trade-offs, including what would
+make this decision worth revisiting.

data/docs/decisions/0001-separate-ir-pipeline.md

@@ -0,0 +1,34 @@
+# ADR 0001: Separate pipeline stages with current IR
+
+- Status: Accepted
+- Date: 2026-07-28
+
+## Context
+
+Frontend parsing, normalization, automaton construction, and code generation
+must be independently testable and resumable. Passing frontend objects between
+all stages would couple later stages to source syntax and make serialized
+artifacts ambiguous.
+
+## Decision
+
+Normalization produces immutable Grammar IR. Parser construction consumes
+Grammar IR and produces immutable Automaton IR. Automaton IR embeds the Grammar
+IR required to resume code generation; later stages do not reach back into
+frontend AST objects.
+
+Both IRs have deterministic JSON encodings and shipped closed schemas. Their
+current schema contract is explicit and validated. Untrusted JSON crosses a
+validator that checks both shape and cross-record references before constructing
+Ruby objects. A pre-v1 change that alters the meaning or required shape is
+coordinated across writers, readers, schemas, fixtures, and downstream
+consumers; no legacy reader is retained solely to preserve an obsolete format.
+
+## Consequences
+
+- Source, resumed Grammar IR, and resumed Automaton IR use the same downstream
+  implementations.
+- Incompatibility is detected at the document boundary rather than deep in
+  generation.
+- Presentation views and operational reports are not additional IRs unless
+  another tool must consume them as durable data.

data/docs/decisions/0002-opaque-user-code-boundary.md

@@ -0,0 +1,32 @@
+# ADR 0002: Keep grammar-embedded Ruby opaque until code generation
+
+- Status: Accepted
+- Date: 2026-07-28
+
+## Context
+
+Semantic actions and user-code sections contain Ruby constructs whose braces,
+quotes, regular expressions, interpolation, and heredocs overlap grammar
+delimiters. Parsing Ruby in the grammar frontend would add a second language
+implementation and would still not validate parser-local bindings correctly.
+
+## Decision
+
+The grammar lexer delegates action bodies to a balanced source scanner. That
+scanner recognizes only the Ruby lexical structure needed to find the matching
+grammar boundary and preserves the original bytes and source location.
+User-code sections are likewise retained as ordered opaque chunks.
+
+The frontend, normalizer, IR tools, reports, and static analysis never evaluate
+or rewrite the opaque body. Ruby compilation occurs only when generated parser
+methods are loaded. Tools that promise not to execute application code must
+operate entirely before that boundary.
+
+## Consequences
+
+- Grammar parsing is independent of a Ruby parser and preserves exact user
+  source for mapping and generation.
+- The balanced scanner has an explicit lexical coverage obligation; unsupported
+  Ruby syntax must fail instead of being silently truncated.
+- Features that need meaning from an action must use conservative lexical
+  evidence or decline the optimization.

data/docs/decisions/0003-self-hosted-grammar-frontend.md

@@ -0,0 +1,32 @@
+# ADR 0003: Self-host the grammar parser behind an explicit bootstrap
+
+- Status: Accepted
+- Date: 2026-07-28
+
+## Context
+
+Keeping grammar syntax in a handwritten parser makes the generator unable to
+exercise its own parser pipeline. Direct self-hosting creates a cycle because
+the generated grammar parser is needed to regenerate itself.
+
+## Decision
+
+`lib/ibex/frontend/grammar.y` is the canonical grammar syntax. Its generated
+parser is committed and is the normal frontend implementation. A specialized
+lexer remains outside that grammar because opaque Ruby scanning and source
+locations are lexical responsibilities.
+
+An explicitly named bootstrap parser exists only to regenerate the committed
+parser when that parser is absent. The regeneration path loads the minimum
+frontend and generation components directly and does not load the normal
+generated frontend. Normal library loading does not use the bootstrap.
+
+No racc implementation or racc-generated source participates in bootstrap or
+normal execution.
+
+## Consequences
+
+- Ordinary grammar parsing continuously exercises Ibex-generated code.
+- Grammar syntax changes must keep the canonical grammar, bootstrap capability,
+  and generated parser deterministic and mutually consistent.
+- The bootstrap is recovery infrastructure, not a second supported frontend.

data/docs/decisions/0004-shared-semantic-and-lossless-source-model.md

@@ -0,0 +1,33 @@
+# ADR 0004: Derive semantic and lossless source views from one lexing pass
+
+- Status: Accepted
+- Date: 2026-07-28
+
+## Context
+
+Generation needs a semantic AST, while formatting, diagnostics, documentation,
+and editor features need comments, trivia, opaque bodies, and exact byte
+ranges. Re-lexing independently for each tool can disagree with the token
+stream that defined grammar meaning.
+
+## Decision
+
+One frontend lexing pass produces semantic tokens and immutable lossless
+segments over the same UTF-8 source. A source document correlates those views
+with half-open byte spans and reproduces the accepted input exactly. The
+self-hosted parser remains the authority for the semantic AST.
+
+Recovering diagnostics are bounded and may expose a clearly marked partial AST,
+but never attach that projection to the unchanged source as if it were a
+complete parse. Formatting changes trivia only, then reparses and rejects any
+semantic difference. Filesystem and unsaved-buffer access are supplied through
+an injected source loader; the parser itself performs no I/O.
+
+## Consequences
+
+- Formatter, documentation, resolver, and LSP features share one interpretation
+  of tokens, opaque Ruby, locations, and source bytes.
+- Exact byte coordinates remain distinct from editor-specific coordinate
+  encodings such as UTF-16.
+- Error recovery and overlays are tool boundaries around the strict parser,
+  not alternative grammar semantics.

data/docs/decisions/0005-contained-grammar-composition.md

@@ -0,0 +1,34 @@
+# ADR 0005: Resolve grammar composition in a contained filesystem boundary
+
+- Status: Accepted
+- Date: 2026-07-28
+
+## Context
+
+Composing grammar fragments introduces file identity, traversal order, cycles,
+diamonds, source provenance, and symlink escape. Textual concatenation loses
+those properties and makes programmatic source parsing perform implicit I/O.
+
+## Decision
+
+Root and fragment files have distinct syntax and ownership. Parsing records
+`import` nodes without reading their targets. A resolver is the sole filesystem
+boundary and returns one immutable resolution containing the merged AST,
+canonical dependency closure, and include provenance.
+
+Canonical real paths define identity. Imports are resolved in deterministic
+depth-first order, a completed canonical file is merged once, and cycles are
+reported by canonical path. Targets must remain below the canonical root
+directory after symlink resolution; absolute paths, parent traversal, and
+ambiguous path forms are rejected.
+
+Every CLI and build integration that accepts a grammar path uses this resolver.
+Programmatic source-string parsing must opt into it explicitly.
+
+## Consequences
+
+- All consumers observe the same merge order and dependency closure.
+- Diamonds are deterministic and symlink aliases cannot hide a cycle or escape
+  the root.
+- Composition is intentionally a flat merge; namespaces and re-export policy
+  require a separate design.

data/docs/decisions/0006-bounded-structural-grammar-lowering.md

@@ -0,0 +1,32 @@
+# ADR 0006: Lower grammar extensions structurally and under explicit bounds
+
+- Status: Accepted
+- Date: 2026-07-28
+
+## Context
+
+EBNF, parameterized rules, and inline rules can be represented as textual
+macros, frontend-only closures, or structural transformations. Textual
+expansion loses locations and can capture names; unbounded recursive expansion
+can exhaust the Ruby stack or memory.
+
+## Decision
+
+The frontend represents extensions as AST structure. Normalization lowers them
+into ordinary symbols, productions, and serializable action-composition plans
+before automaton construction. Synthetic names cannot collide with source
+identifiers, and generated productions retain source and expansion provenance.
+
+Parameterized specializations are memoized by structural arguments. Recursive
+work uses explicit worklists, rejects structurally growing cycles, and has a
+total specialization bound. Inline substitution rejects recursive dependency
+cycles and has a separate materialization bound for alternative products.
+Opaque action fragments remain ordered data in Grammar IR rather than
+generator-only closures.
+
+## Consequences
+
+- Every parser-construction algorithm consumes the same lowered Grammar IR.
+- Resumed IR preserves extension semantics and source mapping.
+- Some theoretically finite expansions may be rejected by conservative cycle
+  or resource bounds; callers can raise size bounds deliberately.

data/docs/decisions/0007-shared-parser-construction-pipeline.md

@@ -0,0 +1,33 @@
+# ADR 0007: Share one downstream pipeline across parser algorithms
+
+- Status: Accepted
+- Date: 2026-07-28
+
+## Context
+
+SLR, LALR, IELR, and canonical LR(1) differ in state construction and
+lookahead precision. Separate conflict resolution, table generation, or code
+generation paths would make algorithm selection change more than the automaton.
+
+## Decision
+
+All algorithms consume Grammar IR and produce the same Automaton IR contract.
+They share action candidate construction, conflict resolution, default-action
+selection, reporting, table generation, and code generation.
+
+LALR is the default and computes lookaheads directly over deterministic LR(0)
+item occurrences. SLR uses the same LR(0) collection with FOLLOW sets.
+Canonical LR(1) retains distinct contexts. IELR conservatively merges
+compatible canonical states and prefers extra states whenever equivalence is
+uncertain; it does not claim a minimum state count.
+
+Reference strategies may remain for equivalence testing, but they are not
+additional public algorithm identities when their output contract is the same.
+
+## Consequences
+
+- Algorithm choice changes automaton precision without changing downstream
+  semantics or generated APIs.
+- LALR avoids canonical state explosion in the default path.
+- IELR can avoid LALR merge inadequacies but may pay canonical construction
+  cost and retain more states than a lane-tracing implementation.