ibex 0.2.0 → 0.4.0

data/docs/decisions/0023-syntax-only-repair-results.md

@@ -0,0 +1,48 @@
+# ADR 0023: Keep editor repair proposals syntax-only
+
+## Status
+
+Accepted as an Experimental runtime API boundary.
+
+## Context
+
+The semantic repair path selects a `RepairPlan` whose buffered token positions
+and replay values are meaningful to a parser application, but an editor needs
+source edits and a fresh syntax result. Exposing replay values would couple the
+editor boundary to application semantic actions and could be mistaken for an
+intent or correctness guarantee.
+
+## Decision
+
+Add `SyntaxSession#repair` as a separate, additive operation. It runs a fresh
+private parser with production actions suppressed, captures token identity and
+absolute byte ranges, resolves source spelling only from caller-provided text
+or conservative punctuation literals, applies byte edits to an immutable
+`SourceText`, and validates the edited bytes with another fresh syntax session.
+The result contains bounded search status, immutable syntax edit metadata,
+diagnostics, exact updated source bytes, and the validation snapshot, but no
+semantic value. The originating session is never mutated and the application's
+repair callback is not invoked.
+
+## Alternatives rejected
+
+1. Reuse the semantic replay result: rejected because it would expose or
+   fabricate application values and would make editor output depend on action
+   execution.
+2. Add a second editor-specific search algorithm: rejected because it would
+   create two bounded-search semantics and a new proof surface.
+3. Infer arbitrary token spellings: rejected because a token name does not
+   define source bytes; missing named-token spelling therefore fails closed.
+
+The v1 boundary accepts one selected repair segment. Overlapping edits,
+multiple segments, exhaustion, cancellation, and hard service limits cannot
+be converted into successful results.
+
+## Consequences
+
+The runtime API and RBS surface grow additively while parser-table format v6,
+IR schemas, and grammar syntax remain unchanged. Embedded generated parsers
+must be regenerated to acquire the implementation. Accepted proposals prove
+only fresh syntactic acceptance; they do not prove semantic correctness or
+user intent. Error validation retains exact edited bytes separately because an
+error CST may contain only the consumed prefix.

data/docs/decisions/0024-direct-ielr-construction.md

@@ -0,0 +1,42 @@
+# ADR 0024: Keep direct IELR as an opt-in construction strategy
+
+- Status: Accepted for experimental implementation; default adoption remains held
+- Date: 2026-08-11
+
+## Context
+
+The existing IELR partition strategy constructs canonical LR(1) first and then
+merges compatible states. That path is conservative and is retained as the
+default. A direct implementation is useful when canonical state construction
+is the dominant cost, but it carries a larger proof and maintenance surface.
+
+## Decision
+
+Implement direct IELR as `Builder`'s explicit `ielr_strategy: :direct` and as
+the CLI option `--ielr-strategy=direct`. The direct pipeline is built from
+LR(0), goto-follow closures, lane annotations, split-stability checks, state
+splitting, and a second item-level lookahead propagation pass. It emits the
+same Automaton IR consumed by all other algorithms.
+
+Keep `:partition` as the default IELR strategy. Do not claim that direct IELR
+is globally state-minimal, do not change public state-number baselines, and do
+not enable unreachable-state compaction by default. The direct decision dossier
+remains a release and evidence gate; an opt-in implementation is not evidence
+that the gate has been satisfied.
+
+## Consequences
+
+- Direct construction can be exercised and profiled without changing existing
+  parser output or release defaults.
+- The implementation records phase metrics and offers bounded diagnostic
+  reports, which makes future independent review possible.
+- The direct path must retain adversarial fixtures, gallery regression tests,
+  RBS, and static-quality checks as part of its maintenance budget.
+- A future default change requires new real-workload measurements, an
+  independent adequacy review, and a separately updated decision record.
+
+## Provenance constraint
+
+The implementation is derived from the published IELR paper and local parser
+specifications only. GPL implementation sources are not inspected, translated,
+or used as design input.

data/docs/decisions/README.md

@@ -0,0 +1,74 @@
+# Implementation architecture decisions
+
+This directory records only durable implementation choices whose rationale
+cannot be recovered safely from code or reference documentation alone.
+
+An ADR belongs here only when every answer below is yes:
+
+1. Were at least two credible implementation approaches available?
+2. Does the choice cross a component, execution, persistence, packaging, or
+   security boundary?
+3. Would reversing it require coordinated changes or invalidate stored or
+   generated artifacts?
+4. Does a future maintainer need the rejected alternatives and trade-offs to
+   avoid repeating the decision?
+
+Delete or merge an ADR when the answer stops being yes. Renumber the remaining
+files; this directory is a current architecture index, not an append-only
+project diary.
+
+The following are not ADRs:
+
+- feature and command specifications;
+- descriptions of code that has already been implemented;
+- compatibility fixes and migration edge cases;
+- individual performance optimizations or rejected experiments;
+- test plans, benchmarks, acceptance evidence, and release gates;
+- maturity or stability declarations; and
+- decisions superseded by the current implementation.
+
+Those facts belong in reference documentation, tests, benchmark artifacts, or
+version control. Evidence may support an ADR, but it is not the decision.
+
+The following subjects belong in their operational documents instead:
+
+- contributor workflow, CI jobs, test matrices, dependency automation, and
+  quality gates: [`docs/development.md`](../development.md);
+- benchmark protocols, artifact ingestion, and comparison rules:
+  [`benchmark/README.md`](../../benchmark/README.md);
+- documentation organization, generation, hosting, and publication:
+  the relevant documentation or workflow;
+- maturity, compatibility, and deprecation policy:
+  [`docs/stability.md`](../stability.md);
+- release decisions and release gates:
+  [`docs/release-readiness.md`](../release-readiness.md); and
+- error-experience evidence and human assessments:
+  [`docs/error-ux.md`](../error-ux.md).
+
+Use [`0000-template.md`](0000-template.md) for a new implementation decision.
+
+## Current decisions
+
+- [0001: Separate pipeline stages with current IR](0001-separate-ir-pipeline.md)
+- [0002: Keep grammar-embedded Ruby opaque until code generation](0002-opaque-user-code-boundary.md)
+- [0003: Self-host the grammar parser behind an explicit bootstrap](0003-self-hosted-grammar-frontend.md)
+- [0004: Derive semantic and lossless source views from one lexing pass](0004-shared-semantic-and-lossless-source-model.md)
+- [0005: Resolve grammar composition in a contained filesystem boundary](0005-contained-grammar-composition.md)
+- [0006: Lower grammar extensions structurally and under explicit bounds](0006-bounded-structural-grammar-lowering.md)
+- [0007: Share one downstream pipeline across parser algorithms](0007-shared-parser-construction-pipeline.md)
+- [0008: Separate the runtime behind a versioned parser-table ABI](0008-versioned-runtime-package-boundary.md)
+- [0009: Isolate mutable parser sessions from immutable parser data](0009-isolated-parser-sessions.md)
+- [0010: Observe only committed runtime transitions](0010-committed-runtime-observation.md)
+- [0011: Compile opaque actions once behind a versioned calling boundary](0011-versioned-semantic-action-boundary.md)
+- [0012: Keep parser analysis bounded and free of semantic execution](0012-bounded-nonexecuting-analysis.md)
+- [0013: Publish generated artifacts as a verified transaction](0013-transactional-generation-publication.md)
+- [0014: Model generated lexers as an independently versioned stage](0014-versioned-generated-lexer.md)
+- [0015: Isolate browser analysis in a replaceable worker](0015-worker-isolated-browser-analysis.md)
+- [0016: Represent concrete syntax with immutable Green data and lazy Red views](0016-red-green-concrete-syntax.md)
+- [0017: Persist and edit syntax through Green structure](0017-persistent-syntax-artifacts.md)
+- [0018: Reuse incremental syntax only with conservative proofs](0018-conservative-incremental-syntax-reuse.md)
+- [0019: Keep generated-language syntax sessions in the runtime](0019-runtime-syntax-session-boundary.md)
+- [0020: Persist parser contracts in Grammar IR](0020-grammar-ir-parser-contract.md)
+- [0021: Persist executable parser tables as a data-only sidecar](0021-data-only-parser-table-sidecar.md)
+- [0022: Bind scoped verification evidence through the generation manifest](0022-manifest-bound-verification-report.md)
+- [0023: Keep editor repair proposals syntax-only](0023-syntax-only-repair-results.md)