Observer Query Coordinate Language #392

1. Background Context

Source: git-warp #392. Audited against main 94b40dac64034cd8caab9bb05efe14a0c22bd735. Template: feature; work type: type:docs.

Current scope and disposition: Own one operational vocabulary for current observers, apertures, coordinates, frontiers, slices, cursors, streams and fallback/cost posture. Include #711 support-tier and neighborhood distinctions. #395 consumes these named result meanings.

Discussion evidence, including corrections:

• Comment ABIucqjA

Additional source requirements/context:

Why It Is Cool:
It prevents "query" from meaning "whatever RuntimeHost felt like doing
today."

2. Problem Description

Own one operational vocabulary for current observers, apertures, coordinates, frontiers, slices, cursors, streams and fallback/cost posture. Include #711 support-tier and neighborhood distinctions. #395 consumes these named result meanings.

Historical source report; the current disposition above supersedes obsolete claims:
Define a small vocabulary for query execution:

• observer
• aperture
• coordinate
• frontier
• slice
• hologram boundary
• cursor
• stream
• materialization fallback

2b. Proposed Solution

Own one operational vocabulary for current observers, apertures, coordinates, frontiers, slices, cursors, streams and fallback/cost posture. Include #711 support-tier and neighborhood distinctions. #395 consumes these named result meanings.

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.
Define a small vocabulary for query execution:

• observer
• aperture
• coordinate
• frontier
• slice
• hologram boundary
• cursor
• stream
• materialization 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

• Each vocabulary term maps to current code and observable behavior; support tier, legal counterfactual, obstruction and repair are distinguished without claiming native settlement from support material.
• The issue-specific positive and negative witnesses in Test Plan pass; relevant compatibility and failure behavior are recorded.

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

No unsatisfied open-issue prerequisite established by this review. This is not proof that an unresolved design or external readiness condition is satisfied.

4. Scope

In: Own one operational vocabulary for current observers, apertures, coordinates, frontiers, slices, cursors, streams and fallback/cost posture. Include #711 support-tier and neighborhood distinctions. #395 consumes these named result meanings.

Source scope and exclusions:

• Keep it short and operational.
• Tie every noun to code seams and user-facing behavior.
• Do not create abstract theory without implementation relevance.
• Use it to guide future query/read-model and observer cycles.

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

• Blocks completion of #395: Observer Query Coordinate Language #392 owns the operational read-strategy/coordinate vocabulary, including the Supported Outcome Settlement BTR and strand-neighborhood support #711 disclosure refinements; the explain-plan result in Query Hologram Explain Plan #395 uses that vocabulary with measured cost evidence.

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.