Add schema versioning for expressions#54
Open
robertvansteen wants to merge 4 commits into
Open
Conversation
Persisted source trees now carry a SchemaVersion so future behavior changes (planned: strict typing in V2) won't silently change the meaning of existing schemas. - SchemaVersion enum (V1 only for now) - Schema envelope pairing a version with a Source tree - ResolverPreset builder owns version-sensitive resolver/overloader/matcher bindings; consumers can extend with custom source types and matchers but cannot override version-locked bindings (throws) - Expression::fromSchema() factory derives the resolver stack from the envelope's version via the preset; the legacy constructor still works but does not provide version guarantees V2 (StrictValueResolver, preflight typing) lands in a follow-up PR. https://claude.ai/code/session_01Mc5Bp2XTGyNTwNUXjxyuDR
Lead all Quick Start examples with Schema + Expression::fromSchema() instead of manual DelegatingResolver wiring. Add an "Extending the resolver preset" section showing the customize closure as the way to plug in custom resolvers, matchers, and overloaders. Add "Schema and SchemaVersion" and "Persisting and replaying schemas" subsections to Core Concepts, covering version semantics and codec patterns (PHP serialize for caches, tagged JSON for durable storage, tryFrom for forward-compatible decoders). Move the manual DelegatingResolver wiring example to "Manual resolver wiring (escape hatch)" under Advanced Usage with a note that it does not provide version guarantees. https://claude.ai/code/session_01Mc5Bp2XTGyNTwNUXjxyuDR
Make the schema-versioning narrative abstract and non-time-bound: describe the version contract in terms of the general guarantee (each enum case pins a coherent set of resolver semantics; new cases are added when behavior would otherwise drift) rather than naming a specific upcoming version or behavior change. https://claude.ai/code/session_01Mc5Bp2XTGyNTwNUXjxyuDR
ExpressionFromSchemaTest is risky on prefer-lowest because every fromSchema() call constructs an ExpressionMatcher via ResolverPreset::build() but the class isn't declared in #[UsesClass]. Add the attribute so PHPUnit's strict coverage metadata mode is satisfied. Also add a test that resolves a MatchExpression through the default V1 preset using both LiteralPattern and WildcardPattern arms. This exercises the default WildcardMatcher and LiteralMatcher wired by build(), killing three escaped mutations that removed or trimmed the defaultMatchers list. https://claude.ai/code/session_01Mc5Bp2XTGyNTwNUXjxyuDR
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Persisted source trees now carry a SchemaVersion so future behavior changes (planned: strict typing in V2) won't silently change the meaning of existing schemas.
bindings; consumers can extend with custom source types and matchers
but cannot override version-locked bindings (throws)
envelope's version via the preset; the legacy constructor still works
but does not provide version guarantees
V2 (StrictValueResolver, preflight typing) lands in a follow-up PR.
https://claude.ai/code/session_01Mc5Bp2XTGyNTwNUXjxyuDR