1. Background Context
Source: git-warp #395. Audited against main 94b40dac64034cd8caab9bb05efe14a0c22bd735. Template: feature; work type: type:feature.
Current scope and disposition: Expose measured strategy and cost evidence using #392’s vocabulary. Reuse current read providers and disclose incomplete/support posture; never infer bounded execution merely from an AsyncIterable result.
Discussion evidence, including corrections:
Additional source requirements/context:
Why It Is Cool:
It turns "are we secretly materializing the whole graph?" into visible
evidence instead of vibes.
2. Problem Description
Expose measured strategy and cost evidence using #392’s vocabulary. Reuse current read providers and disclose incomplete/support posture; never infer bounded execution merely from an AsyncIterable result.
Historical source report; the current disposition above supersedes obsolete claims:
Add a query explain-plan mode that shows which read strategy a query
used:
- full materialization
- sliced materialization
- cursor traversal
- cached hologram boundary
- stream-drain fallback
2b. Proposed Solution
Expose measured strategy and cost evidence using #392’s vocabulary. Reuse current read providers and disclose incomplete/support posture; never infer bounded execution merely from an AsyncIterable result.
Historical approach to reconcile:
Current architecture rules take precedence: parsing/encoding stays at adapters, domain concepts are runtime-backed, no trust casts are introduced, and tests run in Docker.
Add a query explain-plan mode that shows which read strategy a query
used:
- full materialization
- sliced materialization
- cursor traversal
- cached hologram boundary
- stream-drain fallback
2c. Alternatives considered and rejected
No additional alternatives are recorded as decided. Reject duplicate ownership, private-import escape hatches and a broken intermediate mainline; retain original alternatives below when present.
2d. Acceptance Criteria
2e. Test Plan
Golden: Run known-answer queries against the public provider/reading boundary.
Edges: Empty/disconnected graphs, duplicate neighbors, missing facts, cursor boundaries and basis changes.
Known failure modes: Refusal stays typed; cancellation and failing providers cannot return a falsely complete reading.
Fuzz and stress: Bounded adversarial generators with deadlines; verify termination and demand without collecting the whole source.
All tests and benchmarks execute in COPY-based Docker containers without host repository or Git-directory mounts. This planning audit does not claim those checks were run.
3. Prerequisites
Completion prerequisites; preparatory work may start earlier.
4. Scope
In: Expose measured strategy and cost evidence using #392’s vocabulary. Reuse current read providers and disclose incomplete/support posture; never infer bounded execution merely from an AsyncIterable result.
Source scope and exclusions:
- Keep this parked until query/read-model seams are more stable.
- Do not add runtime logging blobs or a generic explain manager.
- The output should report read strategy and cost evidence, not expose
internal RuntimeHost machinery.
- Pull this only as a design-first cycle with clear public/debug API
boundaries.
Safe intermediate state: the PR builds and passes relevant checks after its listed prerequisites; existing supported behavior remains usable. Any preparatory step must be independently mergeable.
5. Why now
Maintainer ordering: memory correctness first, supported attachments next, then land eligible PRs. Preserve this card’s existing priority unless a separately recorded scope decision changes it.
6. Risks
Main risk: implementing the historical description instead of the current runtime contract. Preserve compatibility, causal/ownership invariants and bounded behavior relevant to queries.
7. Definition of Done
The issue-specific acceptance checks pass, relevant validation evidence is attached, and the issue links the coherent PR and resulting mainline integration commit. No open item is hidden in a later repair PR.
8. Stakeholders
James Ross: maintainer, assignee and acceptance owner. git-warp contributors and consumers rely on this domain’s supported contract and reproducible evidence.
9. Related Issues
No additional downstream blocker is established. Shared domain membership alone is not a prerequisite.
Historical paths, counts, release names and shell examples in source material are evidence to reconcile, not authority to restore retired documentation or run host tests.
1. Background Context
Source: git-warp #395. Audited against main
94b40dac64034cd8caab9bb05efe14a0c22bd735. Template:feature; work type:type:feature.Current scope and disposition: Expose measured strategy and cost evidence using #392’s vocabulary. Reuse current read providers and disclose incomplete/support posture; never infer bounded execution merely from an AsyncIterable result.
Discussion evidence, including corrections:
Additional source requirements/context:
Why It Is Cool:
It turns "are we secretly materializing the whole graph?" into visible
evidence instead of vibes.
2. Problem Description
Expose measured strategy and cost evidence using #392’s vocabulary. Reuse current read providers and disclose incomplete/support posture; never infer bounded execution merely from an AsyncIterable result.
Historical source report; the current disposition above supersedes obsolete claims:
Add a query explain-plan mode that shows which read strategy a query
used:
2b. Proposed Solution
Expose measured strategy and cost evidence using #392’s vocabulary. Reuse current read providers and disclose incomplete/support posture; never infer bounded execution merely from an AsyncIterable result.
Historical approach to reconcile:
Current architecture rules take precedence: parsing/encoding stays at adapters, domain concepts are runtime-backed, no trust casts are introduced, and tests run in Docker.
Add a query explain-plan mode that shows which read strategy a query
used:
2c. Alternatives considered and rejected
No additional alternatives are recorded as decided. Reject duplicate ownership, private-import escape hatches and a broken intermediate mainline; retain original alternatives below when present.
2d. Acceptance Criteria
2e. Test Plan
Golden: Run known-answer queries against the public provider/reading boundary.
Edges: Empty/disconnected graphs, duplicate neighbors, missing facts, cursor boundaries and basis changes.
Known failure modes: Refusal stays typed; cancellation and failing providers cannot return a falsely complete reading.
Fuzz and stress: Bounded adversarial generators with deadlines; verify termination and demand without collecting the whole source.
All tests and benchmarks execute in COPY-based Docker containers without host repository or Git-directory mounts. This planning audit does not claim those checks were run.
3. Prerequisites
Completion prerequisites; preparatory work may start earlier.
4. Scope
In: Expose measured strategy and cost evidence using #392’s vocabulary. Reuse current read providers and disclose incomplete/support posture; never infer bounded execution merely from an AsyncIterable result.
Source scope and exclusions:
internal RuntimeHost machinery.
boundaries.
Safe intermediate state: the PR builds and passes relevant checks after its listed prerequisites; existing supported behavior remains usable. Any preparatory step must be independently mergeable.
5. Why now
Maintainer ordering: memory correctness first, supported attachments next, then land eligible PRs. Preserve this card’s existing priority unless a separately recorded scope decision changes it.
6. Risks
Main risk: implementing the historical description instead of the current runtime contract. Preserve compatibility, causal/ownership invariants and bounded behavior relevant to queries.
7. Definition of Done
The issue-specific acceptance checks pass, relevant validation evidence is attached, and the issue links the coherent PR and resulting mainline integration commit. No open item is hidden in a later repair PR.
8. Stakeholders
James Ross: maintainer, assignee and acceptance owner. git-warp contributors and consumers rely on this domain’s supported contract and reproducible evidence.
9. Related Issues
No additional downstream blocker is established. Shared domain membership alone is not a prerequisite.
Historical paths, counts, release names and shell examples in source material are evidence to reconcile, not authority to restore retired documentation or run host tests.