ibex 0.1.0 → 0.3.0

data/docs/runtime-abi-evolution.md

@@ -0,0 +1,307 @@
+# Runtime ABI evolution
+
+This policy separates durable serialized input, generated parser tables, and
+the Ruby runtime API. The current format is the only supported Grammar and
+Automaton IR boundary; the numeric field is a wire discriminator, not a promise
+to read old files.
+
+<!-- ibex-runtime-abi-contract:start -->
+```yaml
+contract_version: 1
+ir:
+  grammar:
+    current_writer: 1
+    readable: [1]
+    migrations: []
+    preserve_loaded_version: false
+  automaton:
+    current_writer: 1
+    readable: [1]
+    migrations: []
+    preserve_loaded_version: false
+  lexer:
+    current_writer: 1
+    readable: [1]
+    migrations: []
+    standalone: true
+    embedded_in_grammar: true
+parser_tables:
+  current_writer: 6
+  readable: [6]
+  cst_readable: [6]
+  fail_before_input: true
+versions:
+  generator: "0.3.0"
+  runtime: "0.3.0"
+  runtime_dependency: "~> 0.3.0"
+runtime_paths:
+  - .github/pull_request_template.md
+  - .github/workflows/main.yml
+  - Rakefile
+  - docs/runtime-abi-evolution.md
+  - docs/test-interactions.md
+  - tool/quality/runtime_abi.rb
+  - tool/quality/runtime_abi/**/*
+  - test/quality/runtime_abi*_test.rb
+  - test/support/runtime_abi_test_project.rb
+  - test/fixtures/runtime_abi/**/*
+  - ibex.gemspec
+  - ibex-runtime.gemspec
+  - lib/ibex/version.rb
+  - lib/ibex/runtime.rb
+  - lib/ibex/runtime/**/*
+  - lib/ibex/runtime/version.rb
+  - lib/ibex/tables.rb
+  - lib/ibex/tables/**/*
+  - sig/ibex/tables.rbs
+  - sig/ibex/runtime.rbs
+  - sig/ibex/runtime/**/*
+  - sig/ibex/tables/**/*
+  - lib/ibex/codegen.rb
+  - lib/ibex/codegen/**/*
+  - sig/ibex/codegen.rbs
+  - sig/ibex/codegen/**/*
+  - lib/ibex/frontend/generated_parser.rb
+  - lib/ibex/ir.rb
+  - lib/ibex/ir/**/*
+  - sig/ibex/ir.rbs
+  - sig/ibex/ir/**/*
+  - schema/grammar-ir.schema.json
+  - schema/grammar-ir-foundation.schema.json
+  - schema/grammar-ir-extensions.schema.json
+  - schema/automaton-ir.schema.json
+  - schema/automaton-ir-definitions.schema.json
+  - schema/lexer-ir-v*.schema.json
+  - schema/cst-v*.json
+  - test/matrix.yml
+  - test/support/matrix_contract.rb
+  - test/support/matrix_runner.rb
+  - test/tooling/matrix_runner_test.rb
+  - tool/quality/golden.rb
+  - test/golden/**/*
+assessment:
+  states: [compatible, breaking, not_applicable]
+  surfaces: [parser_table, grammar_ir, automaton_ir, lexer_ir, runtime_api, embedded_runtime, generation_metadata, cst, test_matrix, policy, none]
+  abi_choices: [current_contract, new_table_format, new_ir_version, new_runtime_major, sidecar, none]
+  regeneration: [required, not_required, not_applicable]
+  required_fields: [state, surfaces, abi_choice, regeneration, rationale, affected_interactions, evidence, tests, verification]
+```
+<!-- ibex-runtime-abi-contract:end -->
+
+The fenced record above is validated against the constants, schemas, gemspecs,
+test declaration, and pull-request policy in this repository. Edit it only as
+part of the implementation change that moves the corresponding boundary.
+
+## IR read, write, migration, and freeze policy
+
+| Contract | Current writer | Current reader | Migration | Freeze |
+| --- | ---: | --- | --- | --- |
+| Grammar IR | current format | current format only | none | the current schema is closed; older documents are rejected |
+| Automaton IR | current format | current format only | none | the current schema is closed; older documents are rejected |
+| Lexer IR | schema 1 | schema 1 | none | the closed schema changes only through a new schema |
+
+The generator and runtime intentionally share one Grammar and Automaton IR
+format. Older documents are rejected before construction; there is no in-process
+IR migration command or compatibility reader. The current Grammar IR carries a
+required root `parser_contract` whose individual fields
+are either explicit with source locations or explicitly unspecified. Automaton
+IR embeds the current Grammar IR, includes that contract in `grammar_digest`,
+and records `entry_construction` as `shared` or `isolated`. Unknown versions and
+construction values are rejected.
+
+An extended root `parser ... end` declaration now writes explicit
+`parser.algorithm` and `parser.entries` members into the current contract. The
+declaration is generator input only: it selects existing construction paths and
+does not add a runtime lookup, generated parser method, action ABI field, or
+parser-table datum. Parser-table format v6 therefore remains the sole writer,
+and declaration-free grammar, generated Ruby, and table golden bytes remain
+unchanged.
+
+Resuming from the current Grammar IR resolves explicit contract values through the same
+typed configuration algebra as CLI values; a matching CLI value is accepted and
+a conflicting canonical-generation value fails at the recorded declaration
+location. Explicit analysis or grammar-test algorithm selection is reported as
+noncanonical and never reclassified as canonical generation. Resuming from a constructed Automaton IR rejects
+construction flags because they cannot rebuild the embedded tables. Its manifest
+keeps the grammar contract, embedded construction facts, and effective codegen
+configuration separate. These schema additions do not change parser-table
+format v6 or the runtime action ABI.
+
+Lexer IR schema 1 is independently versioned. It can be validated and serialized as
+a standalone `ibex_ir: lexer` document, and Grammar IR can carry the same
+versioned document in its optional `lexer` field. There is no Lexer IR
+migration today. Changing lexer rule meaning or its required shape therefore
+requires Lexer IR v2; changing only parser construction does not.
+
+The JSON schemas under `schema/` are the published closed shapes. An optional
+field may be added to a future version, but an existing closed schema is not
+made open to avoid assigning new meaning to an old version.
+
+## Parser-table formats
+
+The generator emits format v6, and the runtime recognizes only that current
+format. Older generated tables fail before input so the runtime does not carry
+historical action-ABI branches indefinitely:
+
+| Format | Non-CST runtime contract | CST contract | Current writer |
+| ---: | --- | --- | --- |
+| v6 | retains the preceding action contracts | structured CST metadata is accepted | yes |
+
+Plain and compact tables are encodings of the same lookup contract, not
+separate ABI versions. A change to compression is format-preserving only when
+every known and unknown token retains the same shift, reduce, accept, or error
+result. Required table shape, action calling convention, marker meaning, or
+runtime lookup meaning requires a new parser-table format.
+
+Every pull, `yyparse`, push, finish, and syntax entry starts a parser session by
+validating its table object. A missing or unsupported `format_version`, an
+invalid generated action marker combination, or a legacy/boolean CST shape is
+rejected before the runtime asks a pull lexer for a token or consumes a
+caller-supplied push token. Current generated action marker combinations are
+checked at that boundary. The error directs the application to regenerate.
+Validation cannot undo side effects the caller performed while constructing an
+argument before calling the runtime.
+
+Regeneration is required when:
+
+- a parser has no table-format version or uses a version the installed runtime
+  does not list;
+- any CST-aware parser predates structured format-v6 CST metadata;
+- generated action markers do not satisfy their current calling contract;
+- an embedded parser must receive runtime fixes or a newer runtime ABI; or
+- a release note for a new format explicitly retires an older reader.
+
+Non-CST v1-v5 tables are outside the pre-v1 runtime compatibility obligation
+and require regeneration. Applications that need to keep an old generated
+artifact can pin the matching pre-v1 runtime package instead of making the
+current reader retain every historical table branch.
+
+## Generator and runtime versions
+
+| Generated artifact | Runtime used | Status |
+| --- | --- | --- |
+| Ibex 0.3.0 non-embedded output (table v6) | `ibex-runtime` 0.3.0 | supported and covered by packaging/runtime tests |
+| Ibex 0.3.0 non-embedded output | a future version admitted by `~> 0.3.0` | dependency resolution permits it; compatibility is an obligation of that future release, not current execution evidence |
+| Ibex 0.3.0 embedded output | runtime sources copied by Ibex 0.3.0 | self-contained and covered by packaging/runtime tests |
+| Ibex 0.2.0 non-embedded output (table v6) | `ibex-runtime` 0.2.0 | supported and covered by packaging/runtime tests |
+| Ibex 0.2.0 non-embedded output | a future version admitted by `~> 0.2.0` | dependency resolution permits it; compatibility is an obligation of that future release, not current execution evidence |
+| Ibex 0.2.0 embedded output | runtime sources copied by Ibex 0.2.0 | self-contained and covered by packaging/runtime tests |
+| old non-CST or CST table v1-v5 | `ibex-runtime` 0.3.0 | rejected before input; regenerate or pin the matching pre-v1 runtime |
+| table v7 or later | `ibex-runtime` 0.3.0 | rejected before input; upgrade the runtime or regenerate to a supported format |
+
+`ibex` 0.3.0 declares `ibex-runtime ~> 0.3.0`; in RubyGems terms that admits
+runtime releases from 0.3.0 up to, but not including, 0.4.0. The previous
+0.2.0 line remains a historical compatibility boundary. The table format is
+still the executable compatibility check. A package requirement alone does not
+prove that an unpublished runtime can execute a generated parser.
+
+Normal generated output requires `ibex/runtime`. Embedded output concatenates
+the runtime files named by `Runtime::EmbeddedSource` in dependency order. Thus
+both modes use the same repository sources at generation time. Embedded output
+does not consult an installed runtime and does not acquire later security,
+correctness, or performance fixes: the application that chooses embedding owns
+regeneration and redeployment. Loading embedded and installed copies into one
+process is not a supported upgrade mechanism.
+
+### Syntax-session ABI classification
+
+Adding `SyntaxSession` and its syntax-only repair proposal keeps parser-table
+format v6 unchanged and adds methods and immutable result types to the current Ruby runtime API. Existing
+non-embedded generated source remains byte-identical and acquires the API from
+a compatible runtime-package upgrade. Embedded generated source copies runtime
+implementation bytes, so its bytes change and regeneration plus redeployment
+is required to acquire the API or later session correctness fixes. Existing
+embedded parsers that are not regenerated retain their previous parsing
+behavior but do not gain the new façade.
+
+The repository contract can represent that combined assessment without
+claiming a table-format bump. The conservative `regeneration: required` value
+applies to the affected embedded artifacts; the rationale records why the
+non-embedded path only needs a runtime upgrade:
+
+```yaml
+state: compatible
+surfaces: [runtime_api, embedded_runtime, cst]
+abi_choice: current_contract
+regeneration: required
+rationale: Table v6 is unchanged and the runtime API is additive; embedded output bytes change and must be regenerated to acquire SyntaxSession.
+affected_interactions: [incremental_cst, syntax_session, embedded_runtime]
+evidence: [lib/ibex/runtime/cst/incremental/relexer.rb, lib/ibex/runtime/cst/incremental/session.rb, lib/ibex/runtime/syntax_session.rb, lib/ibex/runtime/parser.rb, lib/ibex/runtime/embedded_source.rb, test/runtime/syntax_session_test.rb, test/packaging/runtime_gem_test.rb]
+tests: [test/runtime/cst_incremental_test.rb, test/runtime/syntax_session_test.rb, test/packaging/runtime_gem_test.rb]
+verification: [bundle exec rake quality:runtime_abi, bundle exec ruby -Itest test/runtime/cst_incremental_test.rb, bundle exec ruby -Itest test/runtime/syntax_session_test.rb, bundle exec ruby -Itest test/packaging/runtime_gem_test.rb]
+```
+
+## Sidecar, IR version, or table-format version
+
+Choose the boundary by its consumer:
+
+- Use a sidecar for optional generation, review, or editor metadata that the
+  parser does not need to accept input and whose absence preserves behavior.
+- Use a new Grammar, Automaton, or Lexer IR version when persisted generator
+  input changes shape or meaning, even if generated runtime tables do not.
+- Use a new parser-table format when runtime execution needs a required field,
+  new action convention, or changed table meaning before or during parsing.
+- Use both IR and table versions when the persisted construction contract and
+  the runtime execution contract both change.
+
+An optional table field is not automatically safe: if its absence selects new
+behavior or changes execution, it belongs behind a new format. Conversely,
+large diagnostics that never affect execution should not inflate every parser
+table merely to avoid a sidecar.
+
+## Pull-request ABI assessment
+
+The pull-request template contains a delimited YAML assessment. CI parses only
+that block and requires the exact declared fields when a changed path matches
+`runtime_paths` above. Free-form prose outside the block is not evidence.
+
+`compatible` means the change keeps a current contract or adds a sidecar.
+`breaking` selects a new table format, IR version, or runtime major version. A
+new table format requires regeneration. An IR-only or Ruby-runtime-API break
+must still make an explicit `required`/`not_required` regeneration decision;
+application migration can be required even when parser regeneration is not.
+`not_applicable` is accepted only when no declared runtime-facing path changed.
+Every changed runtime-facing path must appear in `evidence`; additional evidence
+must be a changed path or an existing regression test. `affected_interactions`
+uses ids from the test-interaction contract, and every listed interaction owns
+at least one path in `tests`. `verification` accepts only reviewed repository
+commands and must run the ABI gate plus the owned tests (or the full suite).
+The validator checks these relationships, while reviewers remain responsible
+for judging the rationale and whether all affected surfaces were identified.
+The deterministic rationale screen checks only structure: the value must be a
+non-empty string containing a Unicode letter, and it must not equal the exact
+repository-owned template sentinel after whitespace normalization. It does not
+classify general placeholders, identifiers, repetition, entropy, or semantic
+substance. Japanese, Arabic, and other writing systems are accepted. Reviewers
+must decide whether the rationale actually explains compatibility and whether
+TODO-like text is acceptable in context.
+
+The structured choice table is closed:
+
+| `abi_choice` | Required state | Required surface | Regeneration |
+| --- | --- | --- | --- |
+| `current_contract` | `compatible` | one or more concrete surfaces | `required` or `not_required` must be decided |
+| `sidecar` | `compatible` | exactly `generation_metadata` | `not_required` |
+| `new_table_format` | `breaking` | includes `parser_table` | `required` |
+| `new_ir_version` | `breaking` | includes `grammar_ir`, `automaton_ir`, or `lexer_ir` | `required` or `not_required` must be decided |
+| `new_runtime_major` | `breaking` | includes `runtime_api` or `embedded_runtime` | `required` or `not_required` must be decided |
+| `none` | only a non-runtime change | `none` | `not_applicable` |
+
+Runtime-facing changes cannot use `none` or `not_applicable`. A rationale must
+replace the exact template sentinel and contain a Unicode letter; required human
+review decides whether it is substantive. Verification commands are parsed as
+arguments, not executed by the validator; shell composition, arbitrary
+commands, unowned test files, and evidence-only README links are rejected.
+
+Run the contract-only `bundle exec rake quality:runtime_abi` locally.
+Pull-request CI uses a minimal dedicated job to invoke the separate
+`quality:runtime_abi_pr` entry with its event path and name explicitly. That PR
+gate derives the changed path list from
+the event's exact base and head SHAs without GitHub API writes or elevated
+permissions. It parses `runtime_paths` from the exact
+trusted base revision and unions those paths with the head policy, so a pull
+request cannot exempt its own changes merely by shrinking the head contract.
+Only the first explicit addition of this contract can use the fixed bootstrap
+path set. Repository rules must still require this check and review changes to
+the workflow and validator: code running solely from an untrusted head cannot
+defend against deletion or malicious replacement of the gate that launches it.

data/docs/stability.md

@@ -0,0 +1,234 @@
+---
+title: Stability policy
+description: Compatibility, promotion, deprecation, and feature-development rules for Ibex.
+---
+
+# Stability, compatibility, and deprecation
+
+Ibex separates support level from activation. Opt-in controls do not determine
+maturity: a documented opt-in API can be Stable, Preview, or Experimental.
+
+## Maturity ladder
+
+| Level | Activation | Guarantee |
+|---|---|---|
+| Stable | Default compatible mode or a documented stable API | Semantic versioning; compatible-mode behavior remains unchanged |
+| Preview | Feature-specific; compatible/default or explicit as recorded in the maturity audit | Before v1.0: changeable with a migration note; after v1.0: one-minor notice |
+| Experimental | Explicit policy/object or research entry point | May change without notice; budgets and failure modes are part of the experiment |
+
+After v1.0, promotion requires representative use in a shadow or gallery
+grammar, feature-specific invariant/property tests, two released versions
+without a specification change, dependent-tool support where applicable, and
+complete public documentation. For the initial v1.0 contract, accepted ADRs,
+versioned benchmark evidence, invariant/property coverage, dependent-tool
+support where applicable, and complete public documentation replace the
+impossible two-prior-release requirement. Only Stable features may be adopted
+by the production self-hosted grammar.
+
+Before v1.0, Preview is an evolving product boundary rather than a general
+backward-compatibility promise. A pre-v1 Preview change is allowed when the
+same change includes a release-note or migration note, updated black-box
+regressions, and a refreshed maturity record. Consumers of a Preview feature
+must therefore pin a pre-release or be prepared to migrate. After v1.0,
+Preview receives the one-minor notice described in the deprecation policy.
+
+Middle actions are accepted in compatible/default grammar productions and
+therefore remain under the Stable compatibility lock; their Preview row is
+retained only for traceability while its redundant classification is
+redesigned. Most other Preview surfaces require an extended declaration,
+command, or option. The [maturity audit](maturity.md) records activation and
+Stable overlap separately.
+
+## Execution trust is independent of maturity
+
+Stable, Preview, and Experimental describe compatibility and promotion, not
+sandbox strength. Static grammar and IR tools do not execute parser actions,
+generated lexer actions, or `header` / `inner` / `footer` sections. Generated
+lexer semantic parses execute parser and lexer actions. Handwritten pull and
+caller-fed semantic parses execute parser actions but do not invoke the
+generated lexer. Generated syntax-only parses suppress parser production
+actions but still execute generated lexer actions. All generated runtime paths
+may load user sections and are trusted application code, not sandboxes.
+
+A future nonexecuting syntax profile is a separate product contract. It must
+require a declarative built-in-only lexer and reject all user-code sections;
+neither the Stable batch CST API nor the Experimental incremental API currently
+makes that guarantee. See the [execution trust matrix](../README.md#execution-trust-matrix).
+
+## Feature development budget
+
+Feature development is not frozen. A `HOLD` release decision blocks publication
+of that release candidate, not investigation or feature development. The
+following limits keep new work reviewable:
+
+- at most three active new Preview development tracks;
+- at most one of those tracks may introduce grammar syntax; and
+- at most five Experimental product features.
+
+A development track starts when its first user-visible change is merged and
+ends when the feature becomes Stable or Experimental, or is removed. An
+investigation, an ADR, and an unmerged spike do not consume the budget. An
+existing Preview feature consumes a track only while its specification is being
+changed; promotion work that preserves its specification does not.
+
+There is currently one active Preview development track: root declarative
+parser construction. It consumes the one grammar-syntax slot while extending
+the existing Preview IELR and multiple-entry surfaces; it is not a Stable
+promotion. A pull request that starts or ends a track must update this
+statement and the inventory below.
+These limits do not relax the core IR contracts described under
+[Core IR freeze](#core-ir-freeze), but they do permit retiring an unpromoted
+Preview implementation when its maintenance cost exceeds its evidence.
+
+## v1 inventory
+
+Stable:
+
+- racc-compatible grammar input and generated `do_parse`/`yyparse` runtime;
+- default direct LALR construction, parser tables, recovery callbacks,
+  observation events, resource limits, migration checks, and bounded
+  counterexample/ambiguity analysis;
+- current core Grammar IR and Automaton IR, independently versioned Lexer IR, table formats, report
+  schemas, and their validators;
+- format-v6 Red/Green batch CST parsing, typed syntax views, persistent editing
+  and diffing, and the closed `ibex_cst` schema v1 serialization contract.
+
+Preview and Experimental:
+
+The machine-readable [maturity audit](maturity.md) re-evaluates every current
+feature. All eighteen Preview and both Experimental features remain at their
+current maturity. The canonical summary below is generated from that registry
+and checked against both public documents.
+
+<!-- maturity-summary:start -->
+Inventory: **18 Preview, 2 Experimental**. Active new Preview tracks: **1/3** (grammar syntax: **1/1**). Experimental product features: **2/5**.
+Release dependency state: R001 **hold_external**; R002 **pending_exact_revision**; no feature is promoted by this audit.
+
+| Stable ID | Feature | Current maturity | Decision | External use | Release gate |
+| --- | --- | --- | --- | --- | --- |
+| `ebnf-groups` | EBNF groups | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `parameterized-rules` | parameterized rules | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `inline-rules` | inline rules | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `middle-actions` | middle actions | Preview | Redesign Preview | not demonstrated | Blocked: R001, R002 |
+| `multiple-entries` | multiple entries | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `canonical-imports` | canonical imports | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `generated-lexers` | generated lexers | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `semantic-locations-types` | semantic locations/types | Preview | Redesign Preview | not demonstrated | Blocked: R001, R002 |
+| `ast-generation` | AST generation | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `grammar-tests` | grammar tests | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `documentation-tooling` | documentation tooling | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `ielr` | IELR | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `lsp` | LSP | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `watch` | watch | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `debug` | debug | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `coverage` | coverage | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `browser-playground` | browser playground | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `action-shadow` | action-shadow | Preview | Keep Preview | not demonstrated | Blocked: R001, R002 |
+| `bounded-repair` | bounded repair | Experimental | Keep Experimental | not demonstrated | Blocked: R001, R002 |
+| `incremental-cst` | incremental CST | Experimental | Keep Experimental | not demonstrated | Blocked: R001, R002 |
+<!-- maturity-summary:end -->
+
+The batch CST contract is selected for the initial v1 API under the
+initial-major evidence rule above. The remaining Preview features have not
+completed the normal two-release field period. Repair passed its usefulness
+spike but remains Experimental because two of ten baseline plans were not
+useful and inserted semantic values may be nil.
+
+## Research decisions
+
+- The Stage A matrix, golden, reproducibility, schema, adversarial, gallery,
+  fuzzing, dependency, and network gates now make feature-off and
+  algorithm-crossing regressions reviewable before promotion.
+- Independent verification detects all twenty committed structural table
+  faults across every gallery/algorithm/table combination.
+- Bounded grammar comparison distinguishes concrete shortest differences from
+  completed searches with no difference and never labels the latter a proof.
+- Conflict repair passed its first fixed twenty-case capability measurement at
+  20/20. The corpus is intentionally described as a regression baseline, not
+  a general repair-rate claim.
+- The analysis-only Bison adapter imports and builds five checksum-pinned
+  external grammars. Bison-era CRuby production counts match, its one-state
+  acceptance-convention delta is explained, and current Lrama-only `%rule`
+  structure is reported as incomplete instead of receiving unsafe repairs.
+- IELR passed its correctness/state-bound spike and remains preview while it
+  gains field experience. Direct LALR remains the default.
+- Bounded repair passed SP-4 with 8/10 useful plans and remains experimental.
+- GLR and `%dprec`/`%merge` did not enter the product: no delayed-action spike
+  met the ≤5% deterministic-overhead and ambiguity-policy gates.
+- Syntax-only incremental parsing entered as experimental after fixed-seed
+  structural edits matched fresh Green trees and the representative benchmark
+  measured 1.04–2.83x over Stage A and 1.66–4.48x over fresh syntax sessions.
+  It remains experimental until it completes the two-release field period.
+
+The supported alternatives are canonical LR(1) or IELR for LALR inadequacy,
+bounded ambiguity/counterexample analysis for ambiguous grammars, and
+`--watch` with full deterministic reparsing for editing workflows.
+
+## Core IR contract
+
+Grammar IR and Automaton IR each have one current closed format. Their required
+fields, meanings, identity rules, ordering, and validation semantics are
+reviewed as one contract. Older documents are rejected at the load boundary;
+there is no compatibility reader or migration command for either document.
+
+Before v1.0, an incompatible change to either current IR is a coordinated
+contract change: update the writer, reader, schemas, fixtures, and downstream
+consumers together. No legacy format is retained only to avoid a pre-release
+breaking change.
+
+Additive fields and meaning changes are deliberate schema changes with updated
+evidence. Current schemas remain closed and reject unknown fields.
+
+The `x-` namespace is reserved for future experimental data and is not frozen.
+Current closed schemas intentionally reject unknown fields and do not emit
+`x-` data. Introducing an experimental envelope therefore requires a new
+additive schema version; it cannot silently place fields into an existing
+closed document. Promotion moves reviewed data into a documented core field in
+a later schema version.
+
+## Compatibility policy
+
+<!-- stable:compatibility-policy:v1 -->
+
+Compatible mode is the permanent default. Opt-in extensions, exact lookahead
+defaults, repair, and research algorithms do not silently replace compatible
+behavior. Public migration evidence uses public commands and black-box
+behavior; implementation and generated-source layouts are not compatibility
+surfaces.
+
+An undeclared invalid token intentionally calls `on_error` before ordinary yacc
+recovery. This is the documented recommended behavior and is not changed by
+the freeze.
+
+Parser-table format v6 is the only runtime table contract and the only table
+writer. Older generated tables fail before token consumption with a
+regeneration instruction; they are not a pre-v1 compatibility obligation.
+The current Grammar IR adds generator-owned parser configuration without changing that
+runtime table contract. The closed `ibex_cst` schema v1 is a versioned
+interchange contract. Additive meaning requires a new schema version; readers
+do not accept unknown fields.
+
+## Evidence is not compatibility
+
+Exact source digests and clean-revision bindings establish what an evidence
+record measured. They are audit-integrity requirements, not promises that a
+consumer can execute an old generated artifact or reuse an old working-tree
+capture. Historical evidence remains immutable for auditability; current
+evidence must be regenerated and rebound after a relevant source or policy
+change. A stale-evidence failure therefore means “refresh the measurement,”
+not “preserve the old implementation forever.”
+
+## Deprecation policy
+
+After v1.0, a Stable API or syntax first emits a migration warning for at least
+two minor releases. The release notes and documentation must name the first
+warning release, replacement, migration command or procedure, and earliest
+removal release. Automated migration is supplied when practical; policy does
+not promise a command that the product does not provide. Preview features
+receive at least one minor release of notice only after v1.0; before v1.0 the
+release-note and maturity-evidence rule above applies. Experimental features
+may change without notice.
+
+The pre-v1 mixed semantic/syntax CST was a Preview contract and is removed
+while selecting the initial stable API. Its parser tables are rejected with a
+regeneration instruction. There are no Stable removals scheduled.

data/docs/status.md

@@ -0,0 +1,43 @@
+---
+title: Project status
+description: Human-readable release status, maturity boundaries, and evidence links for Ibex.
+---
+
+# Project status
+
+Ibex is pre-1.0. The default compatible mode is the conservative adoption
+baseline, while Preview and Experimental features require explicit activation
+and have feature-specific boundaries.
+
+## Release decision
+
+The v1.0 publication decision is currently on hold because the published error
+experience evidence still needs an independent review. This blocks publication
+of that release candidate; it does not freeze feature development. The current
+Grammar IR, Automaton IR, table, report, and runtime contracts remain closed
+and validated while Preview work continues under the stability policy.
+
+The complete rationale and evidence limitations are in the [release readiness
+report](release-readiness.md). The [error UX review status](error-ux-review-status-v1.json)
+is the machine-readable record; this page is the human entry point.
+
+## Maturity at a glance
+
+- **Stable baseline:** racc-compatible grammar input, default LALR construction,
+  current parser/runtime contracts, and format-v6 batch CST.
+- **Preview:** extended grammar syntax, generated lexers, IELR, LSP, watch,
+  diagnostics, and the browser playground. These require explicit activation
+  or are bounded tools.
+- **Experimental:** syntax-only incremental CST sessions and selected research
+  surfaces. They may change without the Stable compatibility promise.
+
+Consult [maturity.md](maturity.md) and [stability.md](stability.md) for the
+canonical feature registry, activation mechanism, and promotion requirements.
+
+## Evidence boundaries
+
+Repository tests and bounded benchmarks are evidence for the recorded revision,
+not universal performance claims. Comparative statements link to the relevant
+[comparison policy](comparison-policy.md), [workload registry](workloads.md),
+and release artifact. Ibex does not claim to be a sandbox: generated semantic
+parsers execute application Ruby.