ibex 0.2.0 → 0.3.0

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

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

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

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

data/docs/decisions/0010-committed-runtime-observation.md

@@ -0,0 +1,34 @@
+# ADR 0010: Observe only committed runtime transitions
+
+- Status: Accepted
+- Date: 2026-07-28
+
+## Context
+
+Hooks, tracing, coverage, and debugging need parser activity without depending
+on private mutable stacks. Emitting speculative events makes failed semantic
+actions and recovery attempts indistinguishable from committed parser state.
+Optional observation must also remain removable from the normal hot path.
+
+## Decision
+
+Runtime hooks and versioned events are emitted at documented committed
+boundaries for shifts, reductions, errors, recovery, discard, acceptance, and
+rejection. Payloads are immutable snapshots or bounded JSON-safe summaries;
+they never expose live parser stacks or retain arbitrary application objects.
+Observer failures are visible to the parser caller.
+
+Tracing and coverage consume this public boundary rather than adding parser
+drivers. When no observer or hook is active, the runtime does not construct
+event payloads.
+
+The generic runtime is the semantic reference. A fast path may run only after
+proving that every omitted observable capability is inactive, and must fall
+back before a newly enabled capability could miss its documented next event.
+
+## Consequences
+
+- Runtime tools compose without reading implementation state.
+- Coverage and traces describe completed transitions rather than intentions.
+- Performance work must preserve invalidation rules whenever a new observation
+  capability is added.

data/docs/decisions/0011-versioned-semantic-action-boundary.md

@@ -0,0 +1,37 @@
+# ADR 0011: Compile opaque actions once behind a versioned calling boundary
+
+- Status: Accepted
+- Date: 2026-07-28
+
+## Context
+
+Generated semantic actions need grammar-source backtraces, access to reduction
+values and locations, and efficient calls from the runtime. Re-evaluating
+source on every reduction is expensive, while changing generated method
+arguments can silently break older tables or application callables.
+
+## Decision
+
+The generator builds each opaque action method once and compiles it when the
+generated class loads, preserving the grammar filename and line. Direct
+generated-file mode emits the equivalent method body for inspection. Static
+action-shadow output uses the same method-source builder and is never executed
+by Ibex.
+
+Generated action call shapes are explicit production metadata covered by the
+parser-table format version. The runtime validates markers before input and
+grants generated-only ABIs only to generated action methods. Handwritten
+methods and callables keep their documented application ABI.
+
+Action dependency analysis is conservative. It may select a narrower values or
+positional ABI only when lexical evidence proves omitted stacks, locations, or
+containers are unused; unsupported or unparsable source uses the general ABI.
+Location references are rewritten only at Ruby code tokens, not inside literal
+or comment content.
+
+## Consequences
+
+- Actions compile once while retaining useful source-mapped failures.
+- Generated ABI optimization cannot silently change application callables.
+- Conservative fallback can miss an optimization but cannot omit an input the
+  action may observe.

data/docs/decisions/0012-bounded-nonexecuting-analysis.md

@@ -0,0 +1,37 @@
+# ADR 0012: Keep parser analysis bounded and free of semantic execution
+
+- Status: Accepted
+- Date: 2026-07-28
+
+## Context
+
+Conflict counterexamples, sample generation, table debugging, ambiguity
+checks, migration inspection, and automatic repair explore potentially
+unbounded parser or grammar configurations. Executing semantic actions on
+speculative paths would duplicate application side effects and make read-only
+tools unsafe.
+
+## Decision
+
+Static tools operate on validated Grammar IR, Automaton IR, or parser-table
+state only. They never load generated application code or invoke semantic
+actions. Every search has explicit token, configuration, stack, step, or
+expansion limits and terminates when a limit is reached.
+
+Results distinguish a proof from bounded evidence and from exhaustion. Failure
+to find an ambiguity is never reported as proof of unambiguity. Table
+simulation applies the same explicit-cell-before-default lookup rule as the
+runtime.
+
+Optional runtime repair also searches table configurations without actions.
+Only the selected repair is replayed through the ordinary runtime, where
+semantic actions and observers execute once on the committed path.
+
+## Consequences
+
+- Analysis is suitable for untrusted validated artifacts within caller-supplied
+  input-size limits.
+- Deep grammars may require explicitly larger budgets or produce an
+  inconclusive result.
+- Runtime and tooling share table semantics without sharing mutable parser
+  internals.

data/docs/decisions/0013-transactional-generation-publication.md

@@ -0,0 +1,37 @@
+# ADR 0013: Publish generated artifacts as a verified transaction
+
+- Status: Accepted
+- Date: 2026-07-28
+
+## Context
+
+One generation can produce Ruby, RBS, static action source, reports, and
+metadata. Writing outputs as renderers finish can expose a mixed generation,
+and filesystem aliases or a source change during generation can invalidate the
+candidate being published.
+
+## Decision
+
+Generation renders every requested artifact in memory before changing output
+paths. It records the exact input closure and revalidates it before
+publication. Targets are resolved and checked for input aliases and
+cross-output collisions.
+
+Stages and recovery backups are created exclusively beside their targets.
+Publication uses ordered locks, flushed and synchronized stages, atomic
+renames, directory synchronization, and reverse-order restoration on failure.
+Because a portable filesystem cannot atomically replace several paths, an
+optional final manifest is the coherence marker: readers that need one
+generation verify artifact digests against a stable manifest read.
+
+Watch mode runs this same transaction only after a stable source closure is
+observed; it never publishes a candidate built from changing inputs.
+
+## Consequences
+
+- Rendering, source races, and recoverable write failures do not intentionally
+  publish a partial candidate as complete.
+- Multi-file coherence requires the manifest protocol rather than an
+  unsupported cross-file atomicity claim.
+- Transaction and watch code pay filesystem synchronization and hashing costs
+  in exchange for a recoverable publication boundary.

data/docs/decisions/0014-versioned-generated-lexer.md

@@ -0,0 +1,35 @@
+# ADR 0014: Model generated lexers as an independently versioned stage
+
+- Status: Accepted
+- Date: 2026-07-28
+
+## Context
+
+Handwritten token sources keep the parser runtime general, but a generated
+lexer needs durable matching, state, streaming, and location semantics.
+Embedding those details directly in Grammar or Automaton IR would tie lexer
+evolution to parser construction.
+
+## Decision
+
+Generated lexer declarations normalize into immutable Lexer IR with its own
+schema version. Grammar IR may embed that document, while Lexer IR can also be
+validated and consumed independently.
+
+Rules are ordered and state-scoped. At one input position the lexer chooses the
+longest match, then the lowest rule id; empty matches are invalid. Lexical state
+is explicit per parser instance. Streaming input retries a match when the
+current chunk may be a strict prefix, so tokenization does not depend on chunk
+boundaries.
+
+Lexer actions execute only in the generated runtime boundary. Static tools may
+inspect their opaque source but do not run it.
+
+## Consequences
+
+- Lexer format can evolve without changing Automaton IR or handwritten token
+  sources.
+- Matching is deterministic but intentionally uses a simple ordered rule model
+  rather than a hidden engine-specific DFA contract.
+- Regular-expression safety remains an application responsibility; static
+  warnings are not a proof against pathological expressions.

data/docs/decisions/0015-worker-isolated-browser-analysis.md

@@ -0,0 +1,32 @@
+# ADR 0015: Isolate browser analysis in a replaceable worker
+
+- Status: Accepted
+- Date: 2026-07-28
+
+## Context
+
+Ruby running through WebAssembly can consume substantial CPU and memory.
+Running grammar analysis on the main browser thread would let a pathological
+input freeze the interface, and interpolating grammar text into Ruby source
+would create an unnecessary execution boundary.
+
+## Decision
+
+The Ruby VM and grammar-analysis pipeline run in a dedicated module worker.
+The main thread owns the timeout and replaces the worker on expiry. Input,
+diagnostic, conflict, and search sizes are bounded. Grammar bytes cross the
+JavaScript/Ruby boundary as data and semantic action bodies are never
+evaluated.
+
+The worker returns serialized analysis results only. Browser assets are
+self-hosted under a restrictive Content Security Policy, and no submitted
+grammar is sent to or stored by an application server.
+
+## Consequences
+
+- Pathological analysis cannot retain Ruby state after worker replacement and
+  cannot block the main thread indefinitely.
+- Worker termination is the isolation boundary, not a claim that WebAssembly
+  is a security sandbox.
+- Browser support depends on Web Workers, WebAssembly, module scripts, and the
+  shipped Ruby VM asset.

data/docs/decisions/0016-red-green-concrete-syntax.md

@@ -0,0 +1,34 @@
+# ADR 0016: Represent concrete syntax with immutable Green data and lazy Red views
+
+- Status: Accepted
+- Date: 2026-07-28
+
+## Context
+
+A lossless syntax tree must support sharing, navigation, recovery, and editing.
+Nodes containing absolute offsets, parents, or semantic action results cannot
+be safely interned or reused at multiple source occurrences.
+
+## Decision
+
+Green nodes, tokens, and trivia are immutable, position-independent values.
+They contain integer kinds, source bytes, child structure, flags, and derived
+widths, but no parent, absolute location, parser instance, or semantic value.
+Tokens own trivia deterministically, including final trivia on EOF.
+
+Red values are lazy occurrence views over Green values. They provide parents,
+child indexes, and absolute offsets without changing Green identity.
+
+CST-aware parsers maintain a Green stack parallel to the semantic stack.
+Every physical reduction builds syntax independently of whether a semantic
+action exists. Recovery and repair produce flagged syntax, and the public
+syntax root is a synthetic `source_file` containing the selected start node
+and EOF. Structured CST metadata in the parser-table ABI selects this path.
+
+## Consequences
+
+- Equal Green subtrees can be interned, shared across Ractors, and reused at
+  multiple Red occurrences.
+- Syntax shape does not depend on semantic action return values.
+- Absolute navigation allocates Red wrappers lazily, while Green construction
+  must preserve exact source width and trivia ownership.

data/docs/decisions/0017-persistent-syntax-artifacts.md

@@ -0,0 +1,35 @@
+# ADR 0017: Persist and edit syntax through Green structure
+
+- Status: Accepted
+- Date: 2026-07-28
+
+## Context
+
+Mutable syntax nodes make snapshots and sharing difficult. Serializing Red
+parents and offsets would duplicate derived occurrence state and tie the file
+format to one navigation implementation.
+
+## Decision
+
+Syntax edits replace one Green occurrence and path-copy only its ancestor
+chain. Batch rewriting resolves replacements by Red occurrence; unchanged
+subtrees retain Green identity. Annotations are occurrence-scoped identities,
+exclude annotated Green values from interning, and are not serialized.
+
+Concrete syntax uses an independently versioned closed schema. It records
+grammar and parser compatibility metadata, kind metadata, trivia policy, and
+one Green root. Source bytes use a canonical UTF-8-or-Base64 representation.
+Loading validates the closed shape and compatibility, then recomputes widths,
+descendant counts, and aggregate flags through Green constructors. Red parents,
+offsets, cached wrappers, and annotations are deliberately absent.
+
+Text diffs descend past identical Green values and emit byte-oriented edits
+whose application must reconstruct the new source exactly.
+
+## Consequences
+
+- Small edits allocate in proportion to the changed occurrence path.
+- Serialized trees are independent of Red navigation caches and preserve
+  arbitrary source bytes.
+- Structural editing may produce grammar-invalid trees; parsing validation is
+  a separate operation.

data/docs/decisions/0018-conservative-incremental-syntax-reuse.md

@@ -0,0 +1,38 @@
+# ADR 0018: Reuse incremental syntax only with conservative proofs
+
+- Status: Accepted
+- Date: 2026-07-28
+
+## Context
+
+Parser production actions may depend on arbitrary mutable state. Replaying or
+skipping them during incremental parsing can duplicate side effects or return a
+stale semantic value. Reusing a syntax subtree is also unsafe unless lexer and
+LR state match at its boundaries.
+
+## Decision
+
+Incremental sessions are syntax-only: parser production actions are suppressed
+and no semantic value is returned. Generated lexer actions still run because
+they define token emission and lexical state. A fresh syntax parse remains the
+reference result.
+
+Relexing may reuse an old token suffix only after exact source-boundary, lexer
+state, kind, text, flags, and trivia agreement. Green interning may preserve
+equal token and node identity independently of parser reuse.
+
+Subtree blending additionally requires the recorded left LR state to match the
+live state, an unchanged following lookahead, a positive-width complete
+nonterminal, and no error, missing, or skipped flags. Parse memo identity is by
+occurrence position, not Green object identity. Every cache, decomposition, and
+memo has a resource bound; uncertainty or exhaustion falls back to the already
+available fresh path.
+
+Incremental sessions and their caches are single-owner mutable objects.
+
+## Consequences
+
+- Incremental parsing cannot silently reuse semantic side effects or values.
+- Valid reuse is intentionally missed whenever proof metadata is insufficient.
+- Correctness is defined by equality with a fresh syntax parse; performance is
+  evidence for optimization, not part of this decision.

data/docs/decisions/0019-runtime-syntax-session-boundary.md

@@ -0,0 +1,51 @@
+# ADR 0019: Keep generated-language syntax sessions in the runtime
+
+- Status: Accepted
+- Date: 2026-08-05
+
+## Context
+
+The Red/Green CST and incremental parser already provide syntax-only parsing,
+but application integrations otherwise have to assemble trust checks, edits,
+failure expectations, fallback evidence, cancellation, and resource bounds.
+This boundary is for one loaded generated language. It is not the existing
+grammar-authoring LSP and has no workspace or protocol semantics.
+
+Generated lexer actions and generated-file user sections are arbitrary Ruby.
+A session-time flag cannot make an already loaded parser class safe.
+
+## Decision
+
+Add an Experimental `SyntaxSession` façade to `ibex-runtime`, backed solely by
+the existing `IncrementalParseSession`. Current parser classes expose
+`:trusted_application_code` and require that exact profile as an explicit
+caller acknowledgement. No `:declarative` mode is exposed until the generator
+can produce a separate action-free syntax artifact with a declarative lexer and
+without user-code sections.
+
+Return immutable result and metric snapshots. Treat syntax errors as results,
+but represent cancellation and hard resource exhaustion with distinct
+exceptions. Preserve the previous completed session state when an edit aborts.
+
+Keep the boundary in `ibex-runtime`: deployed generated languages need the
+runtime but not grammar construction. Do not create `ibex-workbench` until a
+larger editor-service boundary has independent demand. Do not add LSP,
+workspace, indexing, query, or formatting behavior here.
+
+## Consequences
+
+- Parser production actions remain suppressed; lexer actions and runtime hooks
+  remain explicit trusted application execution.
+- Fresh syntax parsing remains the correctness oracle and the existing CST
+  implementation remains the only parser/tree engine.
+- Parser-table format v6 and normal semantic parse behavior do not change. The
+  installed-runtime API is additive, and feature-off non-embedded generated
+  bytes remain unchanged.
+- Embedded generated bytes do change because they copy the runtime sources.
+  Existing embedded artifacts continue to parse but must be regenerated and
+  redeployed to acquire `SyntaxSession` and its fixes. A non-embedded generated
+  parser acquires the additive API by upgrading its compatible runtime package.
+- Cancellation is cooperative and cannot preempt a nonreturning Ruby lexer
+  action.
+- The façade remains part of the existing Experimental incremental-CST product
+  surface rather than claiming a new Stable editor platform.

data/docs/decisions/0020-grammar-ir-parser-contract.md

@@ -0,0 +1,65 @@
+# ADR 0020: Persist parser contracts in Grammar IR
+
+- Status: Accepted
+- Date: 2026-08-05
+
+> The pre-release compatibility readers and in-process IR migration path were
+> retired before v1.0. Racc-compatible grammar input remains supported.
+
+## Context
+
+Parser construction algorithm, multiple-entry construction, and CST trivia
+ownership are durable grammar-owned contracts. They must survive normalization,
+IR-only generation, Automaton IR embedding, and static inspection before a
+source declaration can be released. The current Grammar IR stores these
+contracts at the root so a resumed pipeline sees the same explicit and
+unspecified states as the source pipeline.
+
+Three persistence boundaries were credible:
+
+1. add one root `parser_contract` to Grammar IR;
+2. publish a separately versioned Parser Contract IR; or
+3. wrap grammar and contract documents in a grammar-bundle envelope.
+
+The choice crosses persisted schemas, grammar digests, resumed generation, and
+the Automaton IR boundary. Reversing it requires coordinated changes to the
+writer, reader, schemas, fixtures, and downstream consumers.
+
+## Decision
+
+The current Grammar IR owns one closed, root-level `parser_contract`. Its admitted
+fields are parser algorithm, entry construction, and CST trivia ownership.
+Each field records an explicit value and source location, or an explicit
+unspecified state. Unspecified contract state contains no built-in default;
+defaults and invocation requests remain inputs to the typed configuration
+resolver.
+
+Automaton IR embeds the exact current Grammar IR document. Its grammar digest
+therefore binds the parser contract. It also records whether entry construction
+was shared or isolated; the existing algorithm field remains the selected
+automaton fact.
+
+There is one reader and one writer for the current format. `Grammar.new` and
+`Automaton.new` both construct the current format directly.
+
+A separate Parser Contract IR is rejected because it would create two
+authorities that must be joined atomically and included independently in every
+digest. A bundle envelope is rejected because Grammar IR already contains the
+normalized root and resolved fragment result; an additional container would
+add identity rules without an independently lifecycled artifact.
+
+The contract remains generator-side data. It does not change parser-table
+format, generated runtime constants, or the `ibex-runtime` ABI. Static readers
+validate it without evaluating grammar actions or application code.
+
+## Consequences
+
+- Source and IR-only pipelines share one normalized contract and one grammar
+  digest.
+- Unspecified source contract remains distinct from a newly selected built-in
+  default.
+- Fragments cannot acquire parser-wide authority; only the normalized root has
+  a parser contract.
+- Grammar and Automaton IR each have one closed current schema.
+- Revisit the rejected sidecar only if parser contracts gain an independent
+  lifecycle or a non-grammar authority with multiple real consumers.

data/docs/decisions/0021-data-only-parser-table-sidecar.md

@@ -0,0 +1,50 @@
+# ADR 0021: Persist executable parser tables as a data-only sidecar
+
+- Status: Accepted
+- Date: 2026-08-05
+
+## Context
+
+Automaton IR is suitable for construction analysis, but a consumer must still
+build runtime tables from it. Generated Ruby already contains executable
+tables, but inspecting that file safely would require parsing Ruby and loading
+it may execute application code. Keeping only Automaton IR provides no
+separate object that a publication report can identify as the executed table.
+
+The alternatives were to keep rebuilding tables from Automaton IR, treat
+generated Ruby as the table container, or persist the table projection as a
+closed data format. The last option crosses persistence, execution, packaging,
+and trust boundaries and therefore needs a durable decision.
+
+## Decision
+
+Adopt an Experimental, separately versioned JSON sidecar as the data-only
+authority for parser recognition tables. It records canonical internal token
+IDs, actions, GOTOs, defaults, production stack effects, entries, static CST
+and recovery metadata, and explicit source/table/metadata identities.
+
+Semantic action bodies, generated wrappers, lexers, external token conversion,
+and application hooks remain outside the artifact. Productions identify only
+opaque wrapper action slots. The prototype executor recognizes internal token
+ID sequences and never reconstructs Automaton IR or evaluates an action.
+
+Artifact schema versioning is independent of the generated parser Stable ABI.
+Version 1 names parser-table format v6 only to pin action and production
+semantics; the current runtime does not accept the JSON representation. The
+sidecar remains outside default generation and runtime packaging until another
+decision defines compatibility and publication binding.
+
+## Consequences
+
+- Consumers can validate and exercise table data without loading generated
+  application code, and later reports have a non-Ruby table identity to bind.
+- The sidecar has real execution value beyond Automaton IR, while retaining the
+  wrapper as authority for semantic actions and tokenization.
+- Source digests in a standalone artifact are linkage claims, not proofs or
+  signatures; verification against source IR requires that IR as another
+  input.
+- The prototype duplicates some Automaton IR projection data and introduces a
+  schema/loader compatibility obligation.
+- Runtime consumption, semantic action ABI binding, default emission, or a
+  stability promotion must revisit this decision and define migration without
+  silently changing existing generated bytes.

data/docs/decisions/0022-manifest-bound-verification-report.md

@@ -0,0 +1,77 @@
+# ADR 0022: Bind scoped verification evidence through the generation manifest
+
+- Status: Accepted
+- Date: 2026-08-05
+
+## Context
+
+The independent Automaton IR verifier and the data-only parser table sidecar
+have useful but separate identities. A published parser also includes a Ruby
+wrapper containing opaque actions. Consumers need to detect a table, report,
+wrapper, or input taken from another generation without loading the wrapper or
+overstating what the verifier checks.
+
+A report could contain every artifact digest including its manifest, be
+embedded in generated Ruby, use physical paths as artifact identities, or be
+published as a separate manifest-bound artifact. Including the manifest
+digest creates a hash cycle because the manifest must hash the report.
+Embedding evidence in Ruby makes nonexecuting inspection depend on a source
+container that also carries opaque code. Physical paths make equivalent
+evidence differ between checkouts.
+
+## Decision
+
+Adopt an Experimental, separately versioned scoped verification report and an
+explicit verifiable-generation-bundle API. The report records logical input
+identities, Grammar and Automaton IR digests, the data-only table artifact and
+payload digests, checker version, verification profile, completed checks,
+bounds, outcome, and a closed excluded-trust list. That machine-readable
+exclusion includes semantic derivation or language equivalence from Automaton
+IR to persisted table data; version 1 validates table structure and digest
+linkage but does not independently prove that projection.
+
+The report never contains the manifest digest or path. Generation renders the
+table, wrapper, and report in memory, then renders a generation manifest that
+lists and hashes all three. The existing transaction publishes non-marker
+artifacts and the wrapper before installing that manifest as the final
+coherence marker.
+
+Canonical report evidence uses ordered logical identities rather than
+absolute paths: indexed input basenames and a role-qualified table basename.
+Version 1 closes both forms to one basename, exactly four input-index digits,
+and at most 10,000 inputs.
+
+IR claims use the explicitly named `source-logical-v1` identity scope. Bundle
+construction rebuilds an immutable Automaton IR copy from the supplied IR and
+`source_records`: every location file becomes its ordered logical input
+identity and each non-null source root becomes `input`. The table and verifier
+consume that same copy, so its Grammar IR digest, embedded Automaton IR
+grammar digest, Automaton IR digest, table identity, report claims, and report
+evidence digest cannot disagree. An unmapped or ambiguous source location is
+an error. The original Automaton, its diagnostic provenance, and ordinary
+V002 table construction remain unchanged.
+
+The bundle validator checks report self-identity, manifest artifact bytes,
+input identity, table identity and payload, and IR/table linkage without
+parsing or loading generated Ruby.
+
+The API stays outside the default `ibex` require path and generator CLI. An
+application must explicitly require and invoke it. This preserves existing
+generation bytes and leaves CLI/stability promotion to a later compatibility
+decision.
+
+## Consequences
+
+- A manifest is the single non-cyclic publication marker for table, wrapper,
+  and report coherence.
+- Equivalent source records produce identical table and report evidence
+  across checkout roots when their ordered logical basenames and bytes match.
+- Missing, stale, duplicated, or cross-generation table/report/manifest
+  combinations are rejected before generated Ruby is loaded.
+- A passing report remains bounded evidence for named V1-V8 checks, not proof
+  of table semantic derivation, wrapper, action, lexer, runtime, application,
+  source-to-IR, authenticity, or grammar-unambiguity correctness.
+- The new schema and validator are persistence and trusted-computing-base
+  obligations. Future schema versions may extend evidence only without
+  silently widening version 1 claims.
+- Default CLI generation and the Stable generated-parser ABI do not change.