ibex 0.2.0 → 0.3.0

data/docs/release-readiness.md

@@ -1,21 +1,45 @@
+---
+title: Release readiness
+description: Outcome-based release evidence, limitations, and the current publication decision.
+---
+
 # v1.0 readiness report
 
 This is the outcome-based v1.0 decision required by the project design. It
-records measurements taken on 2026-07-27 with Ruby 4.0.0 on
-`arm64-darwin24`. Passing the implementation checklist is not sufficient for a
-stable release.
+records evidence current through 2026-08-08. Performance measurements used
+Ruby 4.0.0 on `arm64-darwin24`. Passing the implementation checklist is not
+sufficient for a stable release.
 
 ## Decision
 
 **HOLD v1.0.** Compatibility behavior, scale construction, semantic-value
-signatures, and the repository compatibility suite have evidence. The external
-generator/runtime performance target is not met, and the published ten-case
-error comparison has not received independent third-party review.
+signatures, and the repository compatibility suite have evidence. The exact
+formal public performance rerun is now recorded for the measured revision
+below. The published ten-case error comparison has not received independent
+third-party review. Its machine-readable
+[`R001` status](error-ux-review-status-v1.json) is
+`HOLD / awaiting_independent_review`; the linked status leads to the complete
+rubric, closed record schema, immutable evidence identity, and imported-record
+registry.
+
+<!-- r001-review-status:start -->
+R001: `HOLD` — [`awaiting_independent_review`](error-ux-review-status-v1.json).
+<!-- r001-review-status:end -->
+
+Feature development is not frozen. The open release gate blocks publication of
+v1.0, not feature development. New work remains subject to the feature budgets,
+maturity rules, compatibility checks, and exact-revision release gates
+documented by the project. The current Grammar IR and Automaton IR contracts
+remain closed and validated; before v1.0, incompatible changes are coordinated
+with their writers, readers, schemas, fixtures, and downstream consumers.
 
-The feature freeze remains in force while those two release gates are open.
 The format-v6 batch Red/Green CST has been selected as part of the initial
-Stable v1 API. Its syntax-only incremental layer remains Experimental. Other Preview and
-Experimental features may continue to ship in prereleases without promotion.
+Stable v1 API. Its syntax-only incremental layer remains Experimental. Other
+Preview and Experimental features may continue to ship in prereleases without
+promotion; before v1.0, those surfaces can change between prereleases when the
+release notes, migration note, regressions, and maturity evidence are updated.
+The release lock applies to Stable declarations and versioned persisted
+contracts, not to every Preview implementation detail or evidence capture.
 
 ## KPI result
 
@@ -24,9 +48,10 @@ Experimental features may continue to ship in prereleases without promotion.
 | Three public-gem migrations | Pass with documented adapters | Namae, BCDice, and Nokogiri behavior suites below |
 | Hundreds-of-productions scale | Pass | 501 productions, 503 states, 125.008 ms average complete build |
 | Ten-case error UX comparison | Partial | 10/10 snapshots and 8/10 useful repairs are public; independent review is missing |
-| Generator and parser performance at least racc | Fail | Reuse medians are at parity, but only Nokogiri's interval passes; all cold-generation and new-instance rows fail |
-| Semantic-value RBS and typed ratchet | Pass | Generated reduction signatures include declared RHS/LHS types; whole-library Steep is 89.6% typed |
+| Public generator/runtime performance baseline | Pass at measured revision | Direct formal ten-run result artifact is published below; the historical projection remains retained separately |
+| Semantic-value RBS and typed ratchet | Pass | Generated reduction signatures include declared RHS/LHS types; the 2026-08-08 evidence revision measured whole-library Steep at 88.4% typed |
 | Compatibility suite unbeaten | Pass at the measured revision | Current black-box, self-host, IR, property, and runtime suites are green |
+| Release basis | Pass without publication | Stable declaration diff is 0 across 48 locked files; both gems build byte-identically under two environments |
 
 ## Public-gem migration evidence
 
@@ -60,65 +85,72 @@ that omits `super` plus historical value-stack reads, and an unqualified
 
 ## Formal Pure Ruby performance comparison
 
-The formal artifact was collected from clean revision `3fda78c` with ten
+<!-- comparative-evidence:racc-public-performance-2026-07-31:start -->
+At clean Ibex revision 984d4ae7a1c96db4c71e3077669842b7bbc3b4ea, the readiness
+projection for three pinned workloads on Ruby 4.0.0, arm64-darwin24, with YJIT disabled
+records slower cold generation and new-instance runtime than Racc 1.8.1's Ruby backend;
+the direct formal result artifact is absent, so this is evidence-pending and non-publishable
+as a comparative claim.
+
+Evidence record ID: `racc-public-performance-2026-07-31`. Its complete scope,
+evidence paths, missing artifact, and limitations are registered in
+[`claims.yml`](claims.yml) under the [comparison policy](comparison-policy.md).
+CPU model, kernel release, and processor count were not retained in this
+readiness projection. Host CPU and host OS were also not recorded as separate
+fields. The measurements below do not describe the current checkout.
+
+The historical readiness projection says the measurement was collected on
+2026-07-31 from clean revision
+`984d4ae7a1c96db4c71e3077669842b7bbc3b4ea` with ten
 alternating isolated runs per implementation, 50 warm-up workloads, 250
 measured workloads, and 10,000 bootstrap samples. Each workload parses the
 five fixed public inputs. Ruby 4.0.0 ran with YJIT disabled; Racc 1.8.1 was
 forced to its Ruby backend and every worker verified the selected runtime.
-Ratios below are Ibex divided by Racc. Bold values meet the gate, whose timing
-and allocation metrics require the bootstrap interval's upper bound to be no
-greater than 1.0.
+Ratios below are Ibex divided by Racc; time cells include the bootstrap 95%
+interval. The harness's `target_met` field marks absolute parity when the
+interval's upper bound is no greater than 1.0. That field is diagnostic:
+v1.0 requires publication of measurements and their conditions, while a
+future performance gate may reject only a relative regression measured under
+an identical environment and configuration.
 
 | Project | Cold generation time | Reuse time | Reuse allocations | New-instance time | New-instance allocations | Generated bytes |
 |---|---:|---:|---:|---:|---:|---:|
-| Namae | 1.194x | 0.994x | **0.849x** | 1.185x | 1.208x | **0.862x** |
-| BCDice command | 1.204x | 0.995x | **0.666x** | 1.258x | 1.129x | **0.981x** |
-| Nokogiri CSS | 1.187x | **0.953x** | **0.662x** | 1.167x | 1.075x | **0.937x** |
+| Namae | 1.238x [1.184, 1.272] | 0.985x [0.966, 1.032] | 0.849x | 1.194x [1.157, 1.248] | 1.190x | 0.862x |
+| BCDice command | 1.329x [1.278, 1.420] | 1.052x [1.008, 1.075] | 0.666x | 1.373x [1.326, 1.415] | 1.103x | 0.981x |
+| Nokogiri CSS | 1.309x [1.277, 1.343] | 0.985x [0.963, 1.029] | 0.662x | 1.186x [1.149, 1.255] | 1.051x | 0.937x |
 
 Result values and ordered result sequences are equivalent in every runtime
 row. The measured parser-time medians in milliseconds per parse were
-0.038783/0.039015 (Ibex/Racc) for Namae reuse,
-0.019542/0.019646 for BCDice reuse, and
-0.024074/0.025269 for Nokogiri reuse. The corresponding new-instance medians
-were 0.047493/0.040076, 0.025937/0.020618, and 0.031041/0.026609.
-
-The remaining runtime gap is isolated to parser-instance construction and the
-per-instance mutation tracker; the reused hot loop's point estimates are at
-practical parity, although Namae and BCDice still need narrower passing
-intervals. Cold generation remains 18.7–20.4% slower and is dominated by
-process/load, frontend, and code-generation setup. These are evidence for the
-release decision, not portable scores.
-
-## Superseded native-backend diagnostic
-
-The previous artifact was collected from clean revision `53aa4ab` with ten
-alternating isolated runs per implementation, 50 warm-up workloads, 250
-measured workloads, and 10,000 bootstrap samples. Each workload parses the
-five fixed public inputs. Ruby 4.0.0 ran with YJIT disabled; racc 1.8.1 was
-verified to use its native backend. The formal release contract now compares
-the two Pure Ruby runtimes, so these stricter native-backend measurements are
-retained only as diagnostic context and do not decide the KPI. Ratios below
-are Ibex divided by racc.
-
-| Project | Cold generation time | Reuse time | Reuse allocations | New-instance time | New-instance allocations | Generated bytes |
+0.039443/0.040048 (Ibex/Racc) for Namae reuse,
+0.020925/0.019897 for BCDice reuse, and
+0.024892/0.025280 for Nokogiri reuse. The corresponding new-instance medians
+were 0.048234/0.040413, 0.027523/0.020044, and 0.030420/0.025642.
+
+The results deliberately retain the unfavorable rows: cold generation is
+23.8–32.9% slower, and new-instance parsing is 18.6–37.3% slower. Reuse point
+estimates range from 1.5% faster to 5.2% slower. Ibex allocates fewer objects
+for every reuse workload, while new-instance allocation ratios remain
+1.051–1.190x. Generated output is smaller for all three grammars. These values
+are a release baseline, not portable scores or an assertion of parity.
+<!-- comparative-evidence:racc-public-performance-2026-07-31:end -->
+
+## Exact-revision formal rerun
+
+<!-- comparative-claim:racc-public-performance-2026-08-08:start -->
+At clean Ibex revision 26e94ce631bf5c075ecbca0205a34a8c231c31d9, on Ruby 4.0.0,
+arm64-darwin24, with YJIT disabled, the direct formal comparison of the pinned
+Namae, BCDice command, and Nokogiri CSS workloads against Racc 1.8.1 produced
+equivalent result sequences; Ibex recorded slower cold generation and new-instance
+parsing, fewer reuse allocations, and smaller generated output in every workload.
+
+| Project | Cold generation ratio | Reuse time ratio | Reuse allocations ratio | New-instance time ratio | New-instance allocations ratio | Generated bytes ratio |
 |---|---:|---:|---:|---:|---:|---:|
-| Namae | 1.210x | 1.177x | **0.970x** | 1.408x | 1.376x | **0.862x** |
-| BCDice command | 1.211x | 1.943x | **0.852x** | 2.445x | 1.430x | **0.981x** |
-| Nokogiri CSS | 1.236x | 1.562x | **0.881x** | 1.993x | 1.418x | **0.937x** |
+| Namae | 1.317830 | 0.996320 | 0.854462 | 1.209687 | 1.207559 | 0.861519 |
+| BCDice command | 1.309690 | 1.010467 | 0.675012 | 1.331780 | 1.129299 | 0.981449 |
+| Nokogiri CSS | 1.288118 | 0.994802 | 0.670484 | 1.193522 | 1.074838 | 0.936806 |
 
-Result values and ordered result sequences are equivalent in every runtime
-row. The measured parser-time medians in milliseconds per parse were
-0.038938/0.033094 (Ibex/racc) for Namae reuse,
-0.020118/0.010354 for BCDice reuse, and
-0.024413/0.015626 for Nokogiri reuse. The corresponding new-instance medians
-were 0.046953/0.033340, 0.026933/0.011016, and 0.030744/0.015426.
-
-Profiles attribute the remaining reuse gap to the Pure Ruby direct LR loop
-after lexer and semantic-action costs. New-instance rows additionally include
-the per-instance tracker that preserves runtime hook mutation semantics.
-Cold-generation profiles are dominated by process/load cost plus frontend and
-code-generation work. These are diagnostic optimization evidence, not
-portable scores or formal release evidence.
+The complete formal result is [`2026-08-08-8c9cef999d09-ruby-4.0.0-arm64-darwin24.json`](../benchmark/results/public/2026-08-08-8c9cef999d09-ruby-4.0.0-arm64-darwin24.json). It records ten alternating isolated runs per implementation and scenario, 50 warm-up workloads, 250 measured workloads, five behavior probes, 10,000 bootstrap samples, exact public checkout revisions, and equivalent result and result-sequence digests.
+<!-- comparative-claim:racc-public-performance-2026-08-08:end -->
 
 ## Scale evidence
 
@@ -145,19 +177,45 @@ presented as a substitute for an application-specific benchmark.
 malformed JSON inputs against the public racc callback. Eight selected repairs
 were assessed useful. A maintainer assessment is not independent review; at
 least one external reviewer must record a review of the cases and usefulness
-labels before this KPI passes.
-
-The current whole-library `steep stats` result is 18,115 typed calls and 2,097
-untyped calls out of 20,212, or 89.6% typed. Generated parser RBS refines
+labels before this KPI passes. Reviewers use the versioned
+[`independent rubric`](error-ux-review-rubric-v1.md), generate a draft with the
+exact checkout and environment identity, set all structured consent fields, and
+publish the final permalink-free payload at a full-SHA blob URL. Maintainers
+import the exact bytes and register publication provenance separately, without
+rewriting. Ordinary CI validates the offline kit; the release gate performs
+fail-closed blob checks and requires the source owner, GitHub API author,
+publisher, and reviewer logins to agree. This establishes only GitHub namespace
+control and account metadata, not cryptographic identity or a signature. The
+gate remains intentionally failing while the public status is HOLD.
+
+The 2026-07-31 evidence snapshot recorded 23,517 typed calls and 2,946
+untyped calls out of 26,463, or 88.9% typed. Generated parser RBS refines
 declared terminal, nonterminal, RHS tuple, and reduction result types. Untyped
 values remain explicit at undeclared grammar symbols, decoded JSON, dynamic
-table cells, and opaque application Ruby boundaries.
+table cells, and opaque application Ruby boundaries. The current repository
+result is maintained in the generated type-statistics block in `README.md`.
+
+## Release-basis evidence
+
+`bundle exec rake release:reproducible` compares 47 normalized Stable RBS
+declaration files with the v0.2.0 baseline. The current result has zero
+differences; the installed-Gem embedded-source helper is an internal packaging
+implementation and is outside that public lock. The task also builds both
+gems twice under distinct locale, timezone, and frozen-string settings and
+requires byte-identical artifacts. SHA-256 digests are emitted for the exact
+candidate revision rather than recorded as if the current HOLD revision were
+a release.
+
+No release signing credential is stored in this repository. A signature or
+provenance attestation must be supplied by a protected external release
+environment after the outcome gates pass; an unsigned local test key would not
+establish publisher identity.
 
 ## Actions required to release v1.0
 
-1. Optimize cold generation and parser-instance construction, then repeat the
-   formal Pure Ruby measurements until no row is slower than Racc.
-2. Obtain and link an independent review of the ten error cases and usefulness
-   judgments; revise the versioned assessment if the review disagrees.
-3. Re-run every compatibility, IR, type, benchmark, and site gate on the exact
+1. Obtain and publish an independent review of the ten error cases using the
+   R001 rubric, then import the record byte-for-byte with its immutable
+   permalink and consent. Preserve disagreements separately from the normative
+   maintainer assessment.
+2. Re-run every compatibility, IR, type, benchmark, and site gate on the exact
    release revision.

data/docs/repair-semantics.md

@@ -0,0 +1,123 @@
+# Existing bounded repair semantics
+
+Ibex bounded repair is an opt-in Experimental runtime facility. Assign an
+immutable `Ibex::Runtime::RepairPolicy` before starting a parser session. With
+no policy, parsing does not search or prefetch for repairs and existing error
+recovery is unchanged.
+
+## Search state and bounds
+
+`RepairSearch` runs Dijkstra search over configurations containing:
+
+- a copied LR state stack;
+- the buffered-input index;
+- consecutive successful shifts;
+- accumulated edit cost and ordered edits;
+- whether that configuration has reached the proof goal.
+
+Insertion, deletion, and replacement are the only edits. The default costs are
+1, 1, and 2, with maximum cost 3. Search also has independent defaults of 5,000
+simulated configurations, 8 lookahead tokens, 3 proof shifts, and stack depth
+256. Every policy number is positive and proof shifts cannot exceed lookahead.
+
+The queue orders configurations lexicographically by:
+
+1. total cost;
+2. semantic-value risk;
+3. ordered edit keys `(input position, delete|insert|replace rank, token id)`;
+4. goal before non-goal;
+5. more successful shifts;
+6. earlier buffered-input index;
+7. LR state stack.
+
+Word-like token names add semantic-value risk; punctuation does not. This is a
+deterministic tie-break, not a claim that punctuation edits are correct.
+Candidate inserted/replacement token IDs are ordered and exclude EOF and the
+reserved `error` token. A plan succeeds after the configured consecutive
+shifts or accept.
+
+Search simulates table actions and reductions on integer state stacks only. It
+does not call semantic actions, `on_error`, `on_repair`, lexer actions, or
+runtime observers. Reduction-stack cycles, excess stack depth, excess cost,
+and excess configuration count stop a path. Pull parsing may read ahead to the
+lookahead bound. An incomplete push prefix yields the internal `NEED_INPUT`
+sentinel and waits for more input.
+
+The compatibility `RepairSearch#search` projection still returns the legacy
+`RepairPlan | NEED_INPUT | nil` shape. The additive `search_result` method
+retains a frozen typed outcome (`:selected`, `:need_input`, `:exhausted`, or
+`:not_found`) for syntax tooling, so bounded exhaustion is not confused with a
+complete search that found no plan.
+
+## Selection, hooks, and replay
+
+On a reported syntax error, the runtime captures the error context and CST
+error, publishes the runtime `error` event, and calls `on_error`. If search
+selected a plan, `on_repair(plan)` is called next. If either hook raises, its
+exception propagates before edited tokens are applied.
+
+After both hooks return, the runtime rebuilds the buffered token prefix:
+
+| Edit | Replay token value | Replay location | CST effect |
+| --- | --- | --- | --- |
+| insert | `nil` | location at the insertion point | missing token |
+| delete | absent from replay | original source retained separately | skipped/error trivia |
+| replace | original token value | original token location | error-marked replacement |
+
+The rebuilt prefix then passes through ordinary shift/reduce/accept handling.
+Committed semantic actions and observers therefore run normally; speculative
+search never runs them. Replay emits normal parser events and does not invent a
+`recover` event for the selected repair. The original syntax error remains a
+diagnostic even if replay accepts.
+
+Inserted `nil` and a replacement's retained value are compatibility mechanics,
+not evidence of user intent. A syntactically accepted repair can still be
+semantically unsafe.
+
+## Syntax-only editor proposals
+
+`SyntaxSession#repair` is a separate Experimental boundary for callers that
+need byte edits rather than semantic replay. It runs the same bounded search
+on a fresh private parser, captures absolute source ranges, resolves source
+spelling only from caller-provided text or conservative punctuation literals,
+and validates the applied bytes with a fresh syntax session. Production actions
+and the application's `on_repair` callback do not run, and the result has no
+semantic `value`. The originating session remains unchanged.
+
+`SyntaxRepairResult` distinguishes `:accepted`, `:progress`, and `:rejected`
+from bounded `:exhausted` and `:not_found` outcomes and selected-but-unavailable
+cases such as missing token spelling or multiple repair segments. Accepted
+results require a diagnostic-free fresh parse consuming all edited bytes. For
+error results, `updated_source` keeps the exact bytes while the CST may expose
+only the consumed prefix under the existing error CST contract. See [E002
+syntax-only repair](investigations/E002-syntax-only-repair-result.md) and
+[ADR 0023](decisions/0023-syntax-only-repair-results.md).
+
+## CST and source ownership
+
+CST parsing retains the original source bytes. Insertions are represented by
+missing nodes, replacements carry an error flag, and deleted token bytes are
+preserved as skipped-token trivia rather than silently disappearing. These
+representations are part of the existing CST error-path contract, not a text
+edit API. `RepairPlan#position` is a buffered token index, not a source-byte
+offset.
+
+## Executable coverage
+
+<!-- repair-semantics:coverage:start -->
+| Concept | Executable evidence |
+| --- | --- |
+| policy-and-default-off | `test/runtime/repair_test.rb` |
+| dijkstra-priority-and-outcomes | `test/runtime/repair_characterization_test.rb` |
+| typed-search-outcomes | `test/runtime/repair_characterization_test.rb` |
+| values-locations-and-replay | `test/runtime/repair_test.rb` |
+| hooks-actions-and-observers | `test/runtime/repair_test.rb` |
+| pull-and-push-bounds | `test/runtime/repair_test.rb` |
+| cst-representation | `test/codegen/cst_test.rb` |
+| cst-source-fidelity | `test/runtime/cst_fidelity_property_test.rb` |
+| syntax-only-repair-projection | `test/runtime/syntax_repair_test.rb` |
+<!-- repair-semantics:coverage:end -->
+
+The H003 [round-two evidence](error-ux-round2.md) records exact selected plans
+and fresh reparses but keeps external usefulness judgments on HOLD. Neither
+that evidence nor this characterization promotes bounded repair to Stable.