ibex 0.2.0 → 0.3.0

data/docs/syntax-sessions.md

@@ -0,0 +1,183 @@
+# Generated-language syntax sessions
+
+The Experimental syntax-session API is a generated-language service boundary,
+not an LSP implementation. It reuses the existing incremental Red/Green CST
+engine and returns syntax only: parser production actions never run and no
+semantic value is available.
+
+## Trust must be acknowledged
+
+Current generated parser classes report exactly one execution profile:
+
+```ruby
+Calculator.syntax_execution_profile
+# => :trusted_application_code
+```
+
+Opening a session requires the caller to acknowledge that profile:
+
+```ruby
+session = Calculator.syntax_session(
+  "1 + 2",
+  execution_profile: :trusted_application_code
+)
+```
+
+Generated lexer actions execute while opening and editing a session because
+they define token emission, conversion, and lexer-state changes. Loading the
+generated Ruby class may already have executed `header`, `inner`, or `footer`
+sections. The explicit keyword records caller intent; it is not a sandbox flag.
+Omitting it raises `Ibex::Runtime::SyntaxSessionTrustError` before lexing.
+
+There is no `:declarative` switch. That profile will require a separately
+generated action-free parser artifact, a declarative built-in-only lexer, and
+no user-code sections. The current generator does not produce such an artifact,
+and overriding `syntax_execution_profile` cannot enable it.
+
+Parser callbacks and generated lexer hooks are application code too. The
+syntax-only guarantee is specifically that grammar production actions are
+suppressed. Use this API only with generated artifacts already trusted by the
+host process.
+
+## Opening, editing, and results
+
+Input is a `String` or `Ibex::Runtime::CST::SourceText`. Edits are
+`Ibex::Runtime::CST::TextEdit` values expressed as zero-based, half-open byte
+ranges against the current source:
+
+```ruby
+edit = Ibex::Runtime::CST::TextEdit.new(
+  start: 4,
+  delete_length: 1,
+  insert_text: "3"
+)
+result = session.apply_edits([edit])
+
+result.revision        # 1
+result.syntax_root     # immutable Red root
+result.diagnostics     # immutable diagnostics
+result.expected_tokens # expected terminals observed at parser failures
+result.status          # :ok or :syntax_error
+result.metrics         # immutable reuse/fallback evidence
+```
+
+`expected_tokens` reuses the generated parser's current ordinary or exact
+lookahead-correction policy. With several recoverable failures it is the
+first-seen union for that operation; it is not a completion ranking.
+
+The result and metrics snapshots are frozen. Metrics always describe the
+installed result of the completed operation. `token_count` is the number of
+entries in that result's final token memo, including parser-supporting tokens
+represented there. `reused_tokens` is the number of those entries whose Green
+token identity was reused from the preceding memo. It is zero for an initial
+open and for a full fresh-parse fallback. `reused_ratio` is the parser's
+completed structural-reuse ratio (or lexical ratio when the Blender is
+disabled), so it is not generally `reused_tokens / token_count`.
+
+`fallback?` and `fallback_reasons` distinguish a clean incremental operation
+from a successful fallback. A full lexical-error fallback reports no reuse.
+A decomposition or memo-budget fallback may still report independently
+validated lexical token reuse even though subtree reuse or memo retention was
+declined. Every fallback remains a valid syntax result.
+
+Fresh syntax sessions are the reference semantics. Incremental results must
+match fresh results in source bytes, Green structure and flags, and diagnostic
+content.
+
+## Syntax-only repair proposals
+
+`SyntaxSession#repair` is an additive Experimental operation for editor-style
+syntax proposals. It runs the bounded repair search on a fresh private parser,
+captures token identity and byte ranges, applies the resulting
+`CST::TextEdit` values to a new `CST::SourceText`, and validates the edited
+source with another fresh syntax session. The originating session and source
+are unchanged.
+
+```ruby
+proposal = session.repair(token_text: { "PLUS" => "+" })
+proposal.status          # :accepted, :progress, :rejected, or a bounded failure
+proposal.text_edits      # immutable byte edits
+proposal.updated_source  # exact edited bytes, when validation ran
+proposal.validation      # fresh syntax-only result, when validation ran
+```
+
+The result is deliberately syntax-only: it has no semantic `value`, never
+replays production actions, and never invokes the application's `on_repair`
+callback. `token_text` supplies source bytes only. Named inserted or replaced
+tokens fail closed when no spelling is supplied; punctuation literals may be
+derived conservatively. `:exhausted` and `:not_found` remain distinct bounded
+outcomes, while overlapping edits and multiple selected repair segments are
+reported as unavailable.
+
+An accepted result requires zero diagnostics and complete source consumption.
+For progress or rejection, `updated_source` retains the exact edited bytes and
+the validation CST may expose only its consumed prefix, as permitted by the
+existing error/early-accept CST contract. Cancellation and service limits raise
+their existing exceptions and are never returned as successful proposals.
+
+## Validation, cancellation, and limits
+
+A source passed directly as a String must have an ASCII-compatible Ruby
+encoding. `SourceText` and `TextEdit` are explicit byte containers and have
+already normalized their text to binary, so binary strings and invalid UTF-8
+bytes remain supported. A direct non-ASCII-compatible source such as UTF-16 is
+rejected instead of being silently reinterpreted. Edit shape, nonnegative
+offsets and lengths, overlap, and source bounds are validated by the existing
+`TextEdit` and `SourceText` contracts.
+
+`SyntaxSessionLimits` bounds source size, edit count, and inserted bytes. The
+existing `ResourceLimits` independently bounds parser stack/recovery work,
+incremental decomposition, and memo storage:
+
+```ruby
+limits = Ibex::Runtime::SyntaxSessionLimits.new(
+  max_source_bytes: 2 * 1024 * 1024,
+  max_edits_per_operation: 128,
+  max_inserted_bytes: 256 * 1024
+)
+parser_limits = Ibex::Runtime::ResourceLimits.new(
+  max_incremental_decomposed_nodes: 20_000,
+  max_session_memo_bytes: 8 * 1024 * 1024
+)
+```
+
+Exceeding a service or parser bound raises
+`SyntaxSessionResourceLimitError`. It is never returned as an `:ok` result.
+Incremental decomposition or memo exhaustion may instead use the existing
+sound fresh-path fallback and records that decision in metrics.
+
+Cancellation is cooperative:
+
+```ruby
+token = Ibex::Runtime::CancellationToken.new
+session = Calculator.syntax_session(
+  source,
+  execution_profile: :trusted_application_code,
+  cancellation: token
+)
+
+token.cancel!
+session.apply_edits(edits) # raises SyntaxSessionCancelled
+```
+
+Checks run before an operation and at synchronous parser runtime events. A
+cancellation requested after the final event belongs to the next operation;
+this keeps completion and publication one atomic session transition. A Ruby
+lexer action that does not return cannot be preempted; resource bounds and
+cancellation do not isolate its side effects. An edit cancelled at a checkpoint
+or stopped by a hard resource error leaves the last completed source and result
+installed, and is never confused with a successful parse. Calls to
+`apply_edits`, `source_text`, and `result` are serialized by the session.
+
+## Scope and packaging
+
+The prototype lives in `ibex-runtime`. A deployed generated parser needs only
+the runtime's parser tables, lexer, CST engine, and session façade; requiring
+the generator gem would unnecessarily add grammar construction concerns.
+A separate `ibex-workbench` package is deferred until there is evidence for a
+larger editor-service product boundary.
+
+This API does not define LSP transport, workspace or file-system semantics,
+cross-file indexing, query languages, formatting, or a declarative lexer. The
+existing grammar-authoring LSP remains a separate static tool and does not load
+generated application parsers.

data/docs/table-artifact.md

@@ -0,0 +1,125 @@
+# Data-only parser table artifact
+
+The table artifact is an Experimental, separately versioned JSON sidecar for
+inspecting and recognizing parser token streams without parsing or loading
+generated Ruby. Version 1 is a prototype persistence and execution boundary;
+it is not accepted directly by the current parser runtime and is not part of
+the Stable generated-parser ABI.
+
+Load the prototype explicitly:
+
+```ruby
+require "ibex/table_artifact"
+
+document = Ibex::TableArtifact.build(automaton, representation: :compact)
+loaded = Ibex::TableArtifact.load(document.dump)
+result = Ibex::TableArtifact::Executor.new(loaded).recognize([number_token_id])
+result.accepted?
+```
+
+`recognize` consumes internal terminal IDs. It does not lex source text,
+convert external token values, run semantic actions, build semantic values, or
+perform recovery search. Callers may select a named entry and must treat
+`max_steps` as the execution bound for hostile or cyclic input.
+
+## Authority and representation
+
+The artifact is executable table authority for its limited recognition
+profile. The executor reads its actions, defaults, GOTOs, productions, and
+entry states directly; it does not reconstruct an automaton or call the parser
+builder. This is the execution benefit over retaining only Automaton IR.
+
+The canonical payload contains:
+
+- all symbol and terminal names, display names, and internal IDs;
+- entry names and initial states;
+- signed action codes, GOTOs, and default actions in either closed sparse rows
+  or row-displacement arrays;
+- production left sides, right sides, stack lengths, and opaque action slots;
+- static CST kind/field metadata and recovery declaration IDs;
+- Grammar IR, Automaton IR, whole-payload, CST-metadata, and recovery-metadata
+  SHA-256 identities; and
+- static byte, occupied-cell, lookup, and recognition-cost descriptions.
+
+Signed action codes use `0` for accept, `-1` for error, `1 + state` for shift,
+and `-2 - production` for reduce. Artifact schema version 1 pins those meanings
+to parser-table format version 6. This is a semantic identity, not a claim that
+the JSON object has the Ruby hash/object shape accepted by the v6 runtime.
+
+Objects are serialized with recursively sorted string keys. Array order is
+part of the format and is either semantic or validated as canonical. The
+authoritative closed contract is
+[`schema/table-artifact-v1.schema.json`](../schema/table-artifact-v1.schema.json),
+and the Ruby loader additionally checks referential and canonical invariants
+that JSON Schema cannot express.
+
+`canonical_payload_bytes` is the exact byte count of compact canonical JSON for
+the payload only. Compact lookup is an O(1) row-displacement probe; plain sparse
+rows use O(log row width) binary search. These complexity strings and the
+occupied-cell counts are static descriptions. `measurement: not-measured`
+means none of them is a
+wall-clock, allocation, RSS, or end-to-end parser benchmark.
+
+## Validation and trust boundary
+
+The loader applies a 16 MiB default byte bound, parses JSON, rejects unknown
+fields, checks table encodings and references, recomputes payload/CST/recovery
+digests and static cost fields, then deeply freezes the document. It never
+loads generated classes or evaluates action strings. Semantic action slots are
+production-ID bindings with `verified: false`; action bodies are deliberately
+absent.
+
+Compact tables must use the unique minimal row-displacement layout produced by
+the v1 packer; unused padding is not canonical. Accept is valid only on `$eof`,
+`$eof` cannot be shifted, and default actions are limited to errors and
+reductions. The executor also converts any attempt to run beyond the bounded
+input into a rejected result rather than leaking an indexing exception.
+
+The grammar and automaton digests are provenance linkage claims copied from
+the builder input. An artifact alone cannot recompute either source object or
+establish its authenticity. A caller that has the source IR must recompute and
+compare those digests, and a publication system must separately authenticate
+the artifact. Digests detect inconsistency; they are not signatures.
+
+Ordinary V002 construction hashes the supplied IR, including its diagnostic
+source locations. The explicit verifiable-generation-bundle API instead
+passes a `source-logical-v1` Automaton copy to this unchanged builder. Its
+table identities are therefore path-neutral and exactly match the companion
+report without changing the meaning of standalone `TableArtifact.build`.
+
+The validator checks structural and internal table consistency. It does not
+prove that the table implements a claimed grammar, that CST or recovery
+metadata was derived correctly, or that the parser runtime and semantic
+actions are correct. The separately recomputed CST and recovery digests make
+those metadata regions explicit identities for later bundle binding, but do
+not make them independently true.
+
+This does not extend the claims of [`ibex verify`](verifier-trust-boundary.md).
+Default and strict verification still rebuild tables from Automaton IR; strict
+still adds collection-completeness checks only. Neither mode consumes this
+sidecar. The separate [scoped generation verification
+report](verification-report.md) binds a verifier outcome to this table's
+identity and lets the generation manifest bind both to a wrapper without
+changing that distinction.
+
+## Compatibility and stop-condition result
+
+The prototype is intentionally absent from the default `ibex` require path,
+the generator CLI, `Codegen::Ruby`, generated constants, and `ibex-runtime`.
+The explicitly required bundle API can publish it as a companion artifact.
+Existing generation therefore emits byte-for-byte the same output when the
+feature is not explicitly used, and runtime packaging has no new dependency.
+
+The V002 stop conditions do not apply to this scoped adoption:
+
+- wrapper/table separation does not change the Stable ABI because the sidecar
+  is separate Experimental data;
+- direct bounded recognition supplies execution value beyond duplicating
+  Automaton IR; and
+- action bodies remain opaque wrapper authority, so loading or parsing them is
+  not required.
+
+Promoting the sidecar into default generated output, accepting it in
+`ibex-runtime`, binding action calling conventions, or promising compatibility
+beyond schema version 1 requires a separate compatibility decision and
+migration plan.

data/docs/test-interactions.md

@@ -0,0 +1,219 @@
+# Runtime test interactions
+
+The suite uses a bounded product for the common generated-parser pipeline and
+focused tests for runtime features that do not fit that product. Matrix size is
+not a proxy for coverage: every runtime-facing feature still needs an explicit
+interaction assessment.
+
+<!-- ibex-test-interaction-contract:start -->
+```yaml
+contract_version: 1
+matrix:
+  axes:
+    algorithm: [slr, lalr, ielr, lr1]
+    table: [plain, compact]
+    cst: ["off", "on"]
+    locations: ["off", "on"]
+    entries: [single, multi, isolated]
+  expected_cases: 96
+  representative_cases: 12
+  roles:
+    normal: representative
+    scheduled: full
+    promotion: full_review
+scheduled_long_gates: ["test:matrix:full", "test:adversarial", "fuzz:long"]
+golden:
+  task: "test:zero_cost"
+  policy: feature_off_byte_identity
+  digest_path: test/golden/digests.yml
+  sources:
+    - test/fixtures/compat/calculator.y
+    - benchmark/grammars/representative.y
+    - gallery/json/grammar.y
+  update_command: "bundle exec rake golden:update"
+interactions:
+  - id: parser_semantics
+    axes: [algorithm, table, cst, locations, entries]
+    coverage: matrix
+    tests: [test/tooling/matrix_runner_test.rb]
+  - id: generated_lexer
+    axes: [algorithm, table, cst, locations, entries]
+    coverage: matrix_and_focused
+    tests: [test/codegen/lexer_test.rb, test/frontend/lexer_test.rb]
+  - id: semantic_actions
+    axes: [table, locations, cst]
+    coverage: matrix_and_focused
+    tests: [test/runtime/action_contract_test.rb, test/analysis_no_exec_test.rb]
+  - id: table_encoding
+    axes: [algorithm, table, cst, entries]
+    coverage: matrix_and_focused
+    tests: [test/tables_test.rb, test/runtime/table_format_test.rb]
+  - id: locations
+    axes: [locations, table, cst, entries]
+    coverage: matrix_and_focused
+    tests: [test/location_test.rb, test/runtime/action_contract_test.rb]
+  - id: cst
+    axes: [cst, algorithm, table, locations, entries]
+    coverage: matrix_and_focused
+    tests: [test/codegen/cst_runtime_integration_test.rb, test/runtime/cst_serialize_test.rb]
+  - id: entry_modes
+    axes: [entries, algorithm, table, cst]
+    coverage: matrix_and_focused
+    tests: [test/codegen/multiple_start_test.rb]
+  - id: parser_drivers
+    axes: [table, cst, locations]
+    coverage: focused_regression
+    tests: [test/runtime/parser_test.rb, test/runtime/push_parser_test.rb, test/runtime/parser_table_session_test.rb]
+  - id: generated_ast
+    axes: [algorithm, table, locations]
+    coverage: focused_regression
+    tests: [test/codegen/ast_test.rb, test/tooling/matrix_runner_test.rb]
+  - id: recovery
+    axes: [algorithm, table, cst, entries]
+    coverage: focused_regression
+    tests: [test/runtime/repair_test.rb, test/runtime/sync_recovery_test.rb]
+  - id: resource_limits
+    axes: [algorithm, table, cst, entries]
+    coverage: matrix_and_focused
+    tests: [test/runtime/resource_limits_test.rb]
+  - id: observation
+    axes: [table, cst, locations]
+    coverage: focused_regression
+    tests: [test/runtime/observation_test.rb, test/codegen/embedded_tracer_test.rb]
+  - id: incremental_cst
+    axes: [cst, table, locations]
+    coverage: focused_regression
+    tests: [test/runtime/cst_incremental_test.rb]
+  - id: syntax_session
+    axes: [algorithm, table, cst, locations, entries]
+    coverage: focused_regression
+    tests: [test/runtime/syntax_session_test.rb, test/packaging/runtime_gem_test.rb]
+  - id: embedded_runtime
+    axes: [table, cst]
+    coverage: focused_regression
+    tests: [test/packaging/runtime_gem_test.rb, test/codegen/ractor_shareability_test.rb]
+```
+<!-- ibex-test-interaction-contract:end -->
+
+The quality validator compares this record with `test/matrix.yml`, the CI
+workflow, the golden generator, and the files named by every interaction.
+
+## The 96-case product
+
+The full matrix is exactly:
+
+```text
+4 algorithms × 2 table encodings × 2 CST states × 2 location states × 3 entry modes = 96
+```
+
+The algorithm axis is SLR, LALR, IELR, and canonical LR(1). The table axis is
+plain and compact. CST and semantic locations are independently off or on. The
+entry axis is a single start, shared multi-start automaton, or isolated
+multi-start construction.
+
+Each case normalizes and round-trips Grammar IR, builds and round-trips
+Automaton IR, proves deterministic generated bytes, executes valid and invalid
+input, compares algorithm/table behavior within the same CST/location/entry
+shape, and enforces a stack resource limit. The runner separately checks
+generated AST node equivalence for every algorithm/table pair.
+
+The normal pull-request gate chooses twelve deterministic representatives from
+the ordered product. Twelve is a fast regression net, not a claim of pairwise
+coverage and not a substitute for feature-focused tests. Scheduled CI runs all
+96 cases plus bounded hostile-input tests and the 100,000-sentence fuzz run.
+Promotion of a Preview or Experimental runtime feature requires a reviewed
+full-96 result on the candidate revision even if scheduled CI was recently
+green.
+
+## Interaction map and covering rules
+
+The machine-readable map names the current runtime-facing families and their
+owned tests. `matrix` means the 96-product is the primary coverage.
+`matrix_and_focused` combines product coverage with semantic edge cases.
+`focused_regression` means the feature is not an independent matrix axis and
+the named suite owns its current protocol and edge cases. It does not claim
+that every listed axis pair is already covered; a change to that row must apply
+the covering rules below and record the chosen combinations in its tests.
+
+For a new runtime-facing feature:
+
+1. List every existing axis and feature family whose state or observable result
+   it can affect.
+2. Add it as a matrix axis only when all values are cheap, orthogonal, and
+   meaningful for the common pipeline. Update the declared product count in
+   the same change.
+3. Otherwise select a deterministic covering set containing every new value,
+   every affected existing value, and each pair the implementation says can
+   interact. Record the selection rule and own it in a focused test.
+4. Use feature-specific exhaustive tests for small finite state spaces,
+   protocol transitions, version readers, and failure-before-input behavior.
+5. Add scheduled long fuzz/property cases only when shorter deterministic tests
+   cannot provide the same signal. Seeds, counts, and budgets stay fixed.
+
+Pairwise coverage is the minimum for declared interactions, not permission to
+ignore a known three-way dependency. A bug involving three or more settings is
+promoted to a permanent focused regression and its interaction is added to the
+map. Unsupported combinations must be rejected explicitly and tested; omitting
+them from a generator is not coverage.
+
+Current non-product boundaries include embedded versus installed runtime,
+pull/`yyparse`/push driver transitions, action marker versions, recovery and
+repair state, observation hooks, incremental reuse, serialization, Ractor
+shareability, and packaging. Their focused suites remain mandatory even though
+they do not multiply the 96 common cases.
+
+Syntax sessions require CST and a generated lexer, so a disabled-CST value is
+rejected by the service boundary rather than multiplied into the common
+product. `test/runtime/syntax_session_test.rb` exhaustively crosses all four
+algorithms, both table encodings, and shared versus isolated multi-entry
+construction (16 cases). A separate four-case cross covers both table encodings
+with grammar actions that omit or reference semantic locations. Production
+actions, including their semantic-location references, never execute in a
+syntax session, so that location-action choice is independent of algorithm and
+entry construction; CST source locations remain mandatory internally. The
+remaining tests own trust acknowledgement, fresh-result equivalence, fallback
+metrics, cancellation, resource bounds, and malformed edit sequences.
+`test/packaging/runtime_gem_test.rb` owns the embedded-runtime acquisition path.
+
+## Normal, scheduled, and promotion gates
+
+Normal pushes and pull requests run the twelve representative cases and the
+feature-off golden check as part of the bounded safety net. The weekly schedule
+runs `test:matrix:full`, long adversarial settings, and `fuzz:long`. Manual
+workflow dispatch does not currently run the full matrix or long fuzz merely by
+being manual; use the explicit local tasks when preparing a promotion.
+
+A promotion review records the exact candidate revision and includes:
+
+- all 96 matrix cases;
+- every focused suite named by the promoted feature's interaction row;
+- version-reader, invalid-version, and regeneration diagnostics when an ABI is
+  involved;
+- the feature-off golden diff; and
+- any scheduled long property or fuzz evidence assigned to the feature.
+
+Scheduled success is supporting evidence only. It is not a silent maturity
+promotion and does not replace review of the exact candidate change.
+
+## Golden zero-cost policy
+
+`test:zero_cost` regenerates three committed parsers and requires both exact
+bytes and their SHA-256 index to match. When a new feature is disabled, its
+implementation must not change these reviewed generated bytes. This is a
+source-size and emitted-code zero-cost contract for the fixed corpus, not a
+runtime performance or allocation claim.
+
+If a cross-cutting correction intentionally changes feature-off output, run
+`bundle exec rake golden:update` and review the generated source diff and
+digest index in the same pull request. Never update the digest merely to make a
+failure green. Add a new representative source when the existing three cannot
+exercise a stable feature-off boundary.
+
+## Merge rule
+
+A change under the runtime-facing paths in
+[the ABI policy](runtime-abi-evolution.md#pull-request-abi-assessment) cannot
+merge without a valid structured ABI assessment. The automated check verifies
+the declared versions, matrix arithmetic, scheduled commands, golden inputs,
+and assessment structure. Human review still decides whether the chosen ABI
+boundary and interaction set match the behavior of the change.

data/docs/verification-report.md

@@ -0,0 +1,137 @@
+---
+title: Verification report
+description: Validate parser-table artifacts and understand the independent verifier trust boundary.
+---
+
+# Scoped generation verification report
+
+Ibex can explicitly render a verifiable generation bundle containing a
+data-only parser table, generated Ruby wrapper, scoped verification report,
+and generation manifest. This Experimental API is opt-in and is not part of
+default CLI generation:
+
+```ruby
+require "ibex/verifiable_generation_bundle"
+
+bundle = Ibex::VerifiableGenerationBundle.new(
+  automaton,
+  wrapper_path: "build/parser.rb",
+  wrapper_source: generated_ruby,
+  table_path: "build/parser.tables.ibex.json",
+  report_path: "build/parser.verification.ibex.json",
+  manifest_path: "build/parser.ibex.json",
+  source_records: generation_inputs,
+  manifest_options: { "table" => "compact" },
+  strict: true
+)
+bundle.publish
+
+Ibex::VerifiableGenerationBundle.validate_file("build/parser.ibex.json")
+```
+
+`render` returns the four in-memory artifacts without publishing them.
+`publish` passes the complete artifact set and exact input records to the
+existing generation transaction. The transaction installs the table and
+report, then the parser wrapper, and installs the manifest last as the
+coherence marker. Rendering or verification failure changes no target.
+
+## Claims and outcomes
+
+The version 1 report is a closed JSON document described by
+[`schema/verification-report-v1.schema.json`](../schema/verification-report-v1.schema.json).
+It records:
+
+- logical input identities, content digests, and byte sizes;
+- canonical Grammar IR and Automaton IR digests and the construction
+  algorithm;
+- the data-only table artifact and payload digests, schema version, and
+  representation;
+- the Ibex checker version, default or strict profile, requested checks,
+  completed checks, and state/item bounds; and
+- a distinct `pass`, `violations`, or `exhausted` outcome.
+
+A completed default report names V1, V3, V4, V6, V7, and V8. A completed
+strict report additionally names V2, V5, and V9. V9 executes only for IELR
+and records a bounded canonical acceptance witness. An exhausted report conservatively
+records no completed checks, includes the requested profile and bounds, and
+is not a pass. The meanings and limitations of V1-V9 remain those in
+[`verifier-trust-boundary.md`](verifier-trust-boundary.md).
+
+The report's `evidence_digest` covers the complete report except that digest
+field itself. Input identities use `input/NNNN/BASENAME`, and the table uses
+`table/BASENAME`. These logical identities preserve ordering and artifact
+roles without embedding an absolute checkout path. Both forms are closed:
+`NNNN` is exactly four decimal digits, a report contains at most 10,000 input
+records, and `BASENAME` is one non-empty component other than `.` or `..`
+without slash, backslash, or control characters.
+
+The `ir.identity_scope` value `source-logical-v1` defines the versioned digest
+scope. Before building the bundle table, Ibex rebuilds an immutable Automaton
+IR copy in which every source-location `file` is the corresponding indexed
+input identity and every non-null source-provenance `root` is `input`. The
+Grammar IR digest, embedded Automaton IR grammar digest, Automaton IR digest,
+table source identities, report IR claims, and evidence digest all derive
+from that same copy. Every IR source file must map uniquely to
+`source_records`; an absent or ambiguous mapping is rejected.
+
+This normalization is limited to the explicit bundle/report boundary. It does
+not mutate the supplied Automaton, change diagnostic locations, or alter the
+ordinary V002 `TableArtifact.build(automaton)` identity. Lower-level callers
+that render a report directly can obtain the required copy with
+`VerificationReport.canonical_automaton`; pairing a raw-path table with the
+canonical report is rejected as an IR/table mismatch.
+
+## Non-cyclic manifest binding
+
+The report binds input, Grammar IR, Automaton IR, table artifact, and table
+payload identities. It deliberately contains neither a manifest path nor a
+manifest digest. After the report is rendered, the generation manifest lists
+and hashes the table, wrapper, and report. This gives one direction of
+dependency:
+
+```text
+input + IR -> table -> verification report -> generation manifest
+                    wrapper ---------------> generation manifest
+```
+
+Adding the manifest digest to the report would require the report hash before
+the manifest can be completed and the manifest hash before the report can be
+completed. Version 1 rejects that circular format.
+
+`validate_bundle` checks supplied manifest, report, and table bytes without
+loading generated Ruby. `validate_bundle_file` additionally resolves all
+artifacts from the manifest and verifies every manifest byte count and digest.
+Both reject a missing or duplicate report/table/wrapper entry, stale report or
+table bytes, mismatched logical table identity, input mismatch, IR/table
+identity mismatch, payload mismatch, and an invalid report evidence digest.
+Digests detect inconsistency; they are not signatures or authenticity claims.
+
+## Excluded trust surface
+
+This artifact is a **verification report**, not a proof-carrying parser. The
+closed `excluded_trust` field always identifies the following boundaries:
+
+- source parsing and normalization into IR;
+- semantic derivation or language equivalence from Automaton IR to the
+  persisted table (the sidecar receives closed structural validation and
+  digest binding only);
+- generated wrapper structure and behavior;
+- semantic action meaning, safety, termination, and side effects;
+- generated or handwritten lexer actions and tokenization;
+- the Ruby and Ibex runtime implementations;
+- application hooks; and
+- grammar unambiguity.
+
+The manifest binds the wrapper's bytes to the same publication, but neither
+the report builder nor validator parses, loads, or executes those bytes.
+Likewise, the table sidecar exposes opaque production action slots with
+`verified: false`. V1-V9 rebuild internal table views but do not consume the
+persisted sidecar or prove the builder's Automaton-IR-to-sidecar projection.
+A `pass` applies only to the named V1-V9 checks over the supplied Automaton IR
+plus the reported structural validation and digest relationships.
+
+The checker, IR validator and serializer, reference collection, set analysis,
+table construction/validation, JSON and digest implementations, host runtime,
+and publication filesystem remain trusted as documented. Hostile input also
+requires outer byte, time, memory, and process limits beyond the two reference
+collection bounds.