Canonical runtime and removal inventory

The runtime separates source access, recognition, concrete trees and named ASTs. The removal inventory records the breaking API cleanup. All authoring styles use byte-coordinate, immutable snapshot, cached semantic and explicit-commit contracts.

typed objects / Ruleset factories / RFC imports
                    |
           Source + ParseSession
                    |
       ParseResult + diagnostics + CST
                    |
         AST / typed value / collections
                    |
           validation + explicit commit

Closed removal inventory

Removed surface Supported replacement Verification
Parser\Terminal\Integer Automatically loaded Numbers extension and Extensions\Numbers\Parser\IntegerNumber Integer parser tests, extension discovery tests and canonical API gate
Extensions\Integers and its parser namespace Extensions\Numbers\Numbers and Extensions\Numbers\Parser Numbers tests and canonical API gate
Extensions\Numbers\Parser\Integer Extensions\Numbers\Parser\IntegerNumber Numeric parser tests and canonical API gate
String/context runtime and protected parse(&$input, ...) Typed recognize(Source, int, ParseSession) and one checked delegation path Terminal/combinator fixtures, Unicode and custom extension tests
match(), matchSource(), parseSource(), unresolved/ASCII matching bridges and Parser invocation matchPrefix() and parseAll() returning ParseResult Consumption tests and canonical API gate
supportsSource() allowlist/opt-in, ASCII fallback, compatibility mode flags Every subclass implements the same source contract Custom parser and Source-interface tests
CoordinatePolicy, Coordinates, CoordinateToken, LegacyParserAdapter Canonical byte spans; explicit source code-point conversions Source and diagnostics tests
LegacySpacing and independent-context spacing dispatch Scoped intervening trivia in the owning session, explicit boundary trivia and lexeme suppression Trivia, effect order, case-policy and scope-restoration tests
Automatic callbacks and four-argument string callback signatures onCommit(callable(ParseResult)), semantic validation and idempotent commit Lifecycle tests, discarded attempts and retained errors
TokenProjection, Core Token and parser/match token callbacks Direct immutable CST/AST array, JSON and XML schemas TreeSerializationTest, AST and concrete-node tests
Token transparency, token child indexes and compatibility-only serialization layouts Complete CST children, named AST projection and semantic-leaf markers Punctuation, unnamed input, trivia and empty-span tests
ArgumentsTrait and string/int/array/class-name rule coercion Typed facade/Parser factory results; low-level constructors retain explicit Parser arguments, while facade composition accepts literal strings as Text Constructor rejection, facade literal and factory-contract tests
Magic instance/static Ruleset dispatch and shared rule registry define(), facade-returning rule(), Parser-returning ref(), defined(), undefine() on each instance; facade definitions detach on registration Rule isolation, forward references and missing-name tests
Magic Stub/Implementation properties and Definition invocation Low-level Stub::setParser()/getParser(), facade-returning Definition::build() Recursive examples and canonical API gate
Definition's speculative validation and parent-dependent processors ParseResult semantic validators and cached processors over local collections Selected validation, caching and abandoned-definition tests
Compatibility-only fixtures and obsolete documentation Canonical behavior fixtures, updated contracts and runnable examples Full suite, PHP syntax/API gate and example execution
Free Library functions (s, c, star, plus, opt, repeat and terminal factories) Immutable Comprehend factories/composition, accepted directly by Ruleset; parser() exports for Parser-only boundaries Grammar factory/RFC tests and canonical API gate

Internal Match\AbstractMatch, Success and Failure are execution records, not additional public result shapes. Success allocates mutable ExecutionState only where needed. After tree construction and guards, plain child records can be released; records with deferred state remain on the selected collection/effect and concrete validation paths. They retain lazy operations and observed recognition progress; consumers use ParseResult and immutable source trees.

Breaking changes

Low-level Parser entry points require an explicit new Utf8Source($text) or new ByteSource($bytes). Comprehend and FrozenGrammar also accept strings as validated UTF-8. Use facade parse() or parseAll() for complete input and matchPrefix() when remaining input is allowed. Success is ->success; consumption is ->consumedByteLength, zero on failure; observed failure position is ->farthestFailure with structured diagnostics. Use results()/result() for collections, value() for typed output and node/ast() for syntax. No coordinate adapter or old output wrapper remains.

Construct new Sequence(new Text('a'), new Text('b')), not string/array shorthand. Call rule('name', ...$arguments) explicitly; supply Comprehend, Parser, Definition or a factory to define(). Strings are not rule aliases or class-name factories. Use chr() explicitly for octets passed to Char/Range. Replace token() naming with name(); serializers operate on CST/AST, with the schema in serialization. Replace callback() with onCommit() and take ParseResult as its only argument. Definition validators likewise receive ParseResult; processors receive local collection arrays, without parent output.

spacing(null) disables intervening trivia; omission inherits the scoped policy. Boolean spacing toggles are removed. Intervening policy applies between grammar items, including zero-width items. Automatic trivia shares session case/choice policy and disables recursive automatic spacing within the trivia grammar. Leading/trailing material must be explicit. Nothing silently consumes boundary trivia. Accepted trivia stays in the CST and participates in validation/commit, but automatic trivia does not add named collections or AST nodes.

Current implementation and verification

Graph-wide reference resolution, frozen snapshots, named grammar authoring, immutable fluent composition and graph safety analysis are implemented. See Grammar authoring for the current contracts. They use the same typed parser graph and recognition runtime.

Seekable file snapshots and cooperative depth/work limits are also implemented; see File input and Performance measurements for their costs and limits. See Contributing for verification commands. CI targets PHP 8.2–8.5, with an experimental PHP 8.6 job.