Design parser provider facade layer#748
Draft
mariusvniekerk wants to merge 1 commit into
Draft
Conversation
roborev: Combined Review (
|
mariusvniekerk
force-pushed
the
locate-parser-interface
branch
from
f8a39c8 to
204a879
Compare
roborev: Combined Review (
|
This was referenced Jun 20, 2026
roborev: Combined Review (
|
Collaborator
Author
This was referenced Jun 21, 2026
This was referenced Jun 21, 2026
mariusvniekerk
force-pushed
the
locate-parser-interface
branch
from
3632277 to
3d2b79d
Compare
roborev: Combined Review (
|
Parser integration has grown across registry callbacks, sync-engine switches, and provider-specific source handling. This design captures a shared provider facade so future parser work has one contract for discovery, fingerprinting, parsing, capabilities, and source lookup while preserving current normalized output types and sync semantics. It also records the decision to keep source shape provider-owned, provide reusable JSONL source helpers, migrate every existing provider, and use enumer-generated capability support values for readable JSON reporting. docs(parser): clarify provider embedding pattern The provider facade design was intended to use embedded defaults, but the written spec did not show that pattern concretely enough. Add explicit provider examples so new provider implementations start from ProviderBase and embed or delegate source helper types instead of treating the facade as a loose collection of functions. docs(parser): harden provider facade contract The provider facade spec needed sharper boundaries before implementation: providers must be root-bound instances, source lookup cannot assume persisted paths are real files, and parse outcomes need to preserve retry eligibility without corrupting data-version state. This keeps ProviderBase as the single embedded no-op surface while making reusable source discovery plain composition with explicit forwarding, so new provider work has a predictable contract without a hidden hook layer. Validation: rg stale contract terms; git diff --check. docs(parser): clarify provider facade edge cases The provider facade contract still had ambiguity around mixed multi-session outcomes, fresh source lookup, changed-path filtering, and migration staging. Those gaps would let different provider migrations handle retries, diagnostics, and lookup callers differently. This follow-up makes data-version state per parsed result, defines fresh-source resolution without assuming filesystem paths, gives fingerprint performance criteria, and splits caller migration into reviewable stages. Validation: rg stale contract terms; git diff --check. Go tests not run because this is docs-only. docs(parser): require provider config snapshots Provider instances are meant to be root-bound and immutable after construction. The examples now show ProviderConfig cloning so helper roots and ProviderBase.Config cannot share a mutable caller slice. Validation: rg stale contract terms; git diff --check. Go tests not run because this is docs-only. docs(parser): define partial source failure semantics Multi-session providers need an unambiguous rule for retryable session failures. The spec now requires SourceError.SessionID for per-session errors, routes unknown-scope failures to whole-source errors, and preserves absent rows during partial parses unless the provider explicitly excludes or cleanly replaces them. Validation: rg stale contract terms; git diff --check. Go tests not run because this is docs-only. docs(parser): tighten provider retry cache semantics Provider results now have per-session retry state, but skip-cache persistence remains source-scoped. The spec now makes that aggregate rule explicit and also requires independent root-slice ownership between ProviderBase config and source helpers. Validation: rg stale contract terms; git diff --check. Go tests not run because this is docs-only. docs(parser): require complete results for clean source skips Per-result retry state does not make skip-cache entries per-result. The spec now requires providers to declare a complete result set before the engine can persist a clean source/fingerprint skip, and keeps failures as diagnostic or failure-cache state instead of clean source state. Validation: rg stale contract terms; git diff --check. Go tests not run because this is docs-only. docs(parser): define provider contract edge cases Provider migration depends on source references being fingerprintable, outcome IDs being comparable to persisted rows, and incremental parsing having unambiguous fallback semantics. Without those rules, a new provider could satisfy the facade shape while diverging in skip-cache, retry, or caller migration behavior. This also records provider concurrency and SourceRef lifetime requirements so helpers can stay plain data holders while engine callers can safely share one provider instance. docs(parser): require dual-run provider migration Provider branches need to prove migration, not just add parallel provider implementations. Documenting the root dual-run harness, manifest opt-in, and stack-tip-only legacy removal gives each PR an obvious review surface while preserving legacy sync as the writer during the stack. Validation: git diff --check; spec self-review for placeholders and stale defaulting language; mdformat hook formatting.
mariusvniekerk
force-pushed
the
locate-parser-interface
branch
from
3d2b79d to
833ccf4
Compare
roborev: Combined Review (
|
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
1 participant
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.
Designs a parser provider facade so discovery, watch routing, lookup, fingerprinting, parsing, incremental parsing, and capability reporting move behind config-bound providers instead of sync-engine switches.
The design keeps normalized ParseResult output and database writes outside providers, preserves provider-owned source shape, keeps ProviderBase as the embedded zero-value optional-method surface, and defines reusable source-set helpers for common JSONL, composite, virtual-path, and database-backed layouts.
Migration work is tracked in kata under parent task terh.