ibex 0.1.0 → 0.3.0

data/docs/cst-migration.md

@@ -0,0 +1,106 @@
+# 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, 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:
+
+```sh
+ibex grammar.y -o parser.rb
+```
+
+Upgrade the generator and runtime together, regenerate the parser, and update
+consumers to the current APIs below. The removed `CST::Trivia`, `CST::Token`,
+`CST::Missing`, `CST::Error`, and `CST::Node` constants are not defined.
+
+## Parsing
+
+Use `parse_with_syntax` when both the semantic result and syntax are needed:
+
+```ruby
+result = parser.parse_with_syntax(source, file: "input.txt")
+value = result.value
+root = result.syntax_root
+diagnostics = result.diagnostics
+```
+
+`parse`, `do_parse`, and `yyparse` keep returning the semantic result. After a
+CST parse, `syntax_root` exposes the most recently built Red root.
+
+## Changed tree shape
+
+The new root is always `source_file`:
+
+```text
+source_file
+├── selected start-symbol node
+└── $eof
+```
+
+The EOF token owns final trivia. Code that previously treated the returned CST
+as the start node should use `result.syntax_root.children.fetch(0)`.
+
+The legacy implementation exposed semantic values inside an actionless
+parent. For example, an action-bearing `term` could appear as a `CST::Token`
+whose symbol was `"term"` and whose value was the action result. Format v6
+always exposes the physical `term` syntax node in that position. Read the
+semantic result from `result.value`; syntax children never contain semantic
+values.
+
+These are the primary incompatible shapes found by the migration
+characterization suite. `deconstruct` continues to return syntax children and
+`deconstruct_keys` retains the compatibility keys. Typed field keys are added
+from `@node` slot metadata.
+
+## Removed public API mapping
+
+The inventory below records the removed values and their format-v6
+replacements.
+
+| Removed value and members | Previous use | Format-v6 replacement |
+| --- | --- | --- |
+| `CST::Trivia#text`, `#location`, `#to_h` | leading/trailing trivia assertions | `GreenTrivia#text` and `#kind`; obtain absolute location from the owning Red token |
+| `CST::Token#symbol`, `#value`, `#location`, `#leading_trivia` | terminal names, lexer action values, positions, skipped text | `SyntaxToken#kind_name`/`#symbol`, `#location`, and `#leading_trivia`; compatibility `#value` returns the same source bytes as `#text`, while semantic lexer values stay in the normal action/value path |
+| `CST::Token#kind`, `#children`, `#deconstruct`, `#deconstruct_keys`, `#to_h` | error classification and pattern matching | integer `#kind`, `#error?`/`#missing?`, empty `#children`/`#deconstruct`, and compatibility pattern/hash keys |
+| `CST::Missing` | bounded-repair insertion checks | `SyntaxToken#missing?`, `GreenToken#expected_kind`, and `CONTAINS_MISSING` |
+| `CST::Error#reason` | lexical, syntax, delete, and discard checks | `SyntaxToken#error?`, `SyntaxNode#error?`, diagnostics, and Green error/skipped flags |
+| `CST::Node#symbol`, `#production_id`, `#children`, `#location`, `#trailing_trivia` | root/reduction shape, source position, final trivia | `SyntaxNode#symbol`, `#children`, `#location`, and compatibility `#trailing_trivia`; `#production_id` is the `-1` sentinel because kinds/slot metadata replace occurrence-local production identity |
+| `CST::Node#each`, `#deconstruct`, `#deconstruct_keys`, `#to_h`, `#with_trailing_trivia` | enumeration, pattern matching, final-trivia attachment | Red `Enumerable`/pattern/hash methods; persistent trivia changes use the owning token's `with_leading`/`with_trailing` |
+
+Current pure-syntax shape and compatibility accessors are executable in
+`test/codegen/cst_characterization_test.rb`. Rejection of obsolete CST table
+shapes is covered by `test/runtime/table_format_test.rb` and
+`test/codegen/cst_runtime_integration_test.rb`. The semantic-value removal is
+the C1 change; the `source_file` root is C2.
+
+## Trivia
+
+`--cst-trivia=attach` remains accepted and means `leading`.
+
+- `leading`: skipped lexer text belongs to the next token.
+- `balanced`: text through the first newline belongs to the preceding token,
+  with the remainder leading the next token.
+- `drop`: trivia is omitted; source-coordinate and incremental APIs raise
+  because offsets no longer correspond to the original source.
+
+Use `to_source` for a binary-exact reconstruction. On early `yyaccept`,
+`incomplete_input?` is true and `to_source` is the consumed prefix.
+
+## Errors and repair
+
+Lexical failures, yacc recovery, panic discards, and bounded repair return a
+syntax result rather than changing the semantic action contract. Inspect
+`diagnostics`, `contains_error?`, `each_error`, missing tokens, and Green flags
+for skipped input. Unrecoverable input is retained under `synthetic_root`.
+
+## New capabilities
+
+Format v6 provides typed `Parser::Syntax` views, persistent
+path-copy editing, annotations, structural text diffing, `ibex_cst` v1
+serialization, and syntax-only incremental sessions. These APIs have no
+equivalent on the removed mixed semantic/syntax tree. Batch CST, views,
+editing, and serialization are Stable; incremental sessions remain
+Experimental. See the [CST guide](cst.md) for examples and the incremental
+action contract.

data/docs/cst.md

@@ -0,0 +1,237 @@
+---
+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,
+editing, diffing, and `ibex_cst` serialization are Stable for v1; syntax-only
+incremental sessions are Experimental.
+
+```text
+class Calculator
+pragma cst
+token NUM PLUS
+lexer
+  skip /[[:space:]]+/
+  NUM /[0-9]+/ { lexeme.to_i }
+  PLUS '+'
+end
+rule
+start: expression
+expression: NUM PLUS NUM @node Addition(left, operator, right)
+end
+```
+
+## Parsing and tree shape
+
+`parse_with_syntax` runs semantic actions normally and returns both results:
+
+```ruby
+result = Calculator.new.parse_with_syntax("1 + 2", file: "input.txt")
+value = result.value
+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:
+
+```text
+source_file
+├── selected start-symbol node
+└── $eof
+```
+
+The immutable Green layer stores kind ids, source bytes, trivia, flags, widths,
+and children without parents or absolute positions. It is Ractor-shareable.
+The Red `SyntaxNode`/`SyntaxToken` layer adds lazy parent, child-index, offset,
+span, and location navigation for one occurrence. Equal Green values can
+therefore appear at several positions without sharing Red coordinates.
+
+`root.to_source` reconstructs the consumed bytes exactly. Early `yyaccept`
+marks `root.incomplete_input?` and reconstructs the consumed prefix.
+
+## Trivia and coordinates
+
+Select trivia ownership while generating:
+
+- `leading` owns skipped text on the following token;
+- `balanced` owns text through the first newline on the preceding token and
+  the remainder on the following token;
+- `drop` omits trivia.
+
+Pass the policy explicitly when needed:
+
+```sh
+ibex --cst-trivia=leading grammar.y
+ibex --cst-trivia=balanced grammar.y
+ibex --cst-trivia=drop grammar.y
+```
+
+`attach` is accepted as an alias for `leading`. EOF owns final leading trivia.
+`drop` trees deliberately reject span, location, and incremental APIs because
+their offsets cannot describe the original source.
+
+Spans are zero-based, half-open byte ranges. `SourceText#position` and
+`#location` convert them to one-based Unicode-scalar lines and columns while
+preserving byte offsets.
+
+## Typed syntax views
+
+An `@node` annotation generates a view in `Parser::Syntax` without changing the
+physical tree:
+
+```ruby
+addition = Calculator::Syntax::Addition.cast(
+  result.syntax_root.children.fetch(0).children.fetch(0)
+)
+addition.left
+addition.operator
+addition.right
+```
+
+Accessors use normalized physical RHS slots. Lowered repetitions add element
+enumerators; separated lists also expose separators. These views are distinct
+from generated `Parser::AST` Data values: syntax views retain punctuation and
+trivia, while AST values are semantic-action results.
+
+## Errors and repair
+
+Lexical failure, yacc recovery, panic discard, and bounded repair all produce a
+tree. Inspect `diagnostics`, `contains_error?`, error nodes, missing tokens, and
+Green flags. Inserted tokens are zero-width `missing_token` values. Discarded
+input remains under error nodes or `skipped_tokens` trivia. An unrecoverable
+parse uses `synthetic_root`.
+
+## Persistent editing and diffing
+
+Editing returns a new Red root and path-copies only changed ancestors:
+
+```ruby
+old_root = result.syntax_root
+first = old_root.first_token
+new_root = first.with_text("10")
+edits = Ibex::Runtime::CST::Diff.text_edits(old_root, new_root)
+new_source = old_root.source_text.apply(edits)
+```
+
+Nodes support `replace_with`, `with_child`, `insert_child`, and `remove_child`.
+Tokens support `replace_with`, `with_text`, `with_leading`, and
+`with_trailing`. `SyntaxRewriter` performs bottom-up kind dispatch;
+`SyntaxEditor` applies several occurrence-addressed replacements in one pass.
+`SyntaxAnnotation` marks one occurrence and excludes annotated Green values
+from interning.
+
+## Incremental syntax sessions
+
+Incremental parsing is Experimental and deliberately syntax-only:
+
+```ruby
+source = Ibex::Runtime::CST::SourceText.new("1 + 2", file: "input.txt")
+session = Calculator.incremental_session(source)
+result = session.edit([
+  Ibex::Runtime::CST::TextEdit.new(
+    start: 4,
+    delete_length: 1,
+    insert_text: "3"
+  )
+])
+```
+
+The initial parse and every edit suppress parser production actions.
+`SyntaxResult` therefore has `syntax_root`, `diagnostics`, and `reused_ratio`,
+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
+syntax-only contract forbids executing them.
+
+The default Stage B path relexes soundly from the beginning, validates old
+token boundaries/states, and directly reuses only subtrees whose LR state,
+follow token, flags, width, and damage range are safe. Pass `blender: false` to
+retain the Stage A full LR drive. `ResourceLimits` bounds decomposition and
+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:
+
+```ruby
+tables = Calculator.parser_tables
+json = Ibex::Runtime::CST::Serialize.dump(
+  session.result.syntax_root,
+  grammar_digest: tables.fetch(:grammar_digest),
+  table_format: tables.fetch(:format_version),
+  state_count: tables.fetch(:state_count),
+  production_count: tables.fetch(:production_count),
+  memo: session.parse_memo
+)
+loaded = Ibex::Runtime::CST::Serialize.load(
+  json,
+  grammar_digest: tables.fetch(:grammar_digest),
+  state_count: tables.fetch(:state_count),
+  production_count: tables.fetch(:production_count)
+)
+```
+
+Valid UTF-8 bytes use JSON strings; other bytes use canonical Base64 objects.
+Loading rebuilds widths, aggregate flags, and descendant counts. A grammar
+digest mismatch raises `ValidationError`. State or production count mismatch
+silently discards only the optional parse memo. Annotations are session-local
+and cannot be serialized.
+
+## Invariants and test coverage
+
+The Red/Green contract is continuously exercised by the following repository
+tests:
+
+| Invariant | Automated evidence |
+| --- | --- |
+| I1 consumed-input fidelity | `test/runtime/cst_fidelity_property_test.rb` is PT1 over random grammars and valid, lexical-error, recovery, repair, and early-accept inputs; `test/fixtures/cst/runtime-paths-v1.json` fixes every error/trivia path, including long unmatched remainders and repair deletion. |
+| I2 Green purity | `test/runtime/cst_green_test.rb` checks derived-only immutable state and Ractor shareability; `test/codegen/cst_characterization_test.rb` keeps semantic values outside syntax children. |
+| I3 lazy Red navigation | `test/runtime/cst_red_test.rb` checks occurrence-local memoization, offsets, parents, cursors, and deterministic traversal. |
+| I4 determinism | PT3 in `test/runtime/cst_green_test.rb` compares cache-on/off structure, source, and dump; PT6 in `test/runtime/cst_serialize_test.rb` checks byte-stable dump/load/dump; generated Ruby and RBS have golden tests. |
+| I5 unchanged action contract | `test/codegen/cst_contract_test.rb` compares CST/no-CST `parse`, `do_parse`, `yyparse`, hooks, observer order, and non-CST table shape; characterization and obsolete-CST-table rejection regressions remain active. |
+| I6 sharing boundary | PT5 in `test/runtime/cst_green_test.rb` checks Green shareability and concurrent Ractor reads; editing and parser-table tests keep Red/session state occurrence-owned. |
+| I7 versioned contracts | `test/runtime/cst_serialize_test.rb`, `test/runtime/table_format_test.rb`, and `test/packaging/schema_files_test.rb` cover schema validation, memo compatibility, old table readers, and schema packaging. |
+| I8 type soundness | CI regenerates the `sig/` tree, runs Steep and RBS validation, and rejects a type-statistics regression. |
+
+`test/runtime/cst_incremental_property_test.rb` is the large PT2 authority. Its
+fixed seed generates four grammar shapes and executes 20,000 random edits
+through Stage A plus 20,000 through Stage B, comparing fresh syntax sessions in
+Green structure, bytes, flags, diagnostics, and memo cardinality after every
+edit. `test/runtime/cst_incremental_test.rb` adds focused stateful-lexer,
+fallback, sharing, minimal-diff, action-suppression, no-value, and unsupported
+configuration cases.
+
+See [the migration guide](cst-migration.md) for removed tree-shape changes and
+[the stability policy](stability.md) for support levels.

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.

data/docs/decisions/0008-versioned-runtime-package-boundary.md

@@ -0,0 +1,36 @@
+# ADR 0008: Separate the runtime behind a versioned parser-table ABI
+
+- Status: Accepted
+- Date: 2026-07-28
+
+## Context
+
+Applications executing a generated parser do not need the grammar frontend or
+generator. Independently installed generated code and runtime code still need a
+precise compatibility boundary; otherwise a table-shape change can fail or be
+misinterpreted during a parse.
+
+## Decision
+
+The dependency-free parser runtime ships as `ibex-runtime`; the generator
+depends on it but runtime deployments do not depend on generator code. Normal
+generated parsers require the runtime package, while embedded output carries
+the same runtime implementation.
+
+Every generated table declares a parser-table format version. The runtime
+validates the version and marker combinations before consuming input. Changes
+to required shape, action calling convention, or table meaning increment that
+version.
+
+Plain and compact tables are two encodings of the same lookup contract.
+Compression may change representation only when every declared and unknown
+token retains the same shift, reduce, accept, or error result. In particular,
+explicit error cells must mask default reductions.
+
+## Consequences
+
+- Generator and runtime packaging can evolve independently within the declared
+  dependency and table-format contracts.
+- Unsupported generated parsers fail before lexer or semantic side effects.
+- Compact representation remains replaceable and optimizable without becoming
+  a second parser semantics.

data/docs/decisions/0009-isolated-parser-sessions.md

@@ -0,0 +1,34 @@
+# ADR 0009: Isolate mutable parser sessions from immutable parser data
+
+- Status: Accepted
+- Date: 2026-07-28
+
+## Context
+
+Generated tables are immutable program data, while LR stacks, lexer state,
+lookahead, recovery state, observers, and incremental caches are per parse.
+Supporting pull, yielding, and push input through separate engines would make
+their recovery and callback behavior drift.
+
+## Decision
+
+Generated parser classes own recursively frozen tables. Each parser instance
+owns one mutable session and permits only one active driver. Pull, yielding, and
+push APIs feed the same LR transition and recovery machinery; nested or mixed
+drivers fail before mutating state.
+
+State, semantic value, optional location, and optional Green stacks remain
+index-aligned. Capabilities allocate their parallel state only when the
+generated grammar or runtime tooling requires it.
+
+Per-instance resource limits bound stack growth, recovery attempts, and other
+session-owned search or memo structures. Exceeding a bound produces a
+structured failure rather than unbounded work. Sharing a parser instance or
+its application callbacks across concurrent parses is outside the contract.
+
+## Consequences
+
+- Parser classes and eligible table graphs can be shared while sessions remain
+  independently mutable.
+- All input lifecycles preserve one action, recovery, and callback ordering.
+- Applications choose stricter or larger limits without regenerating tables.