Skip to content

docs: reorganize backend design guides - #739

Open
zzylol wants to merge 3 commits into
mainfrom
docs/concise-design-docs
Open

zzylol wants to merge 3 commits into
mainfrom
docs/concise-design-docs

Conversation

@zzylol

@zzylol zzylol commented Sep 18, 2026 •

Copy link
Copy Markdown
Contributor

The four backend design guides mixed dense protocol prose, repeated implementation phases, and acceptance requirements without a complete example near the start. This rewrite gives each document the same reader-first structure: an overview, one worked example, the reusable contract, and concise acceptance or limitation sections.

Changes:

  • Reorganize the ASAPQuery compatibility profile around one startup-to-query example, explicit profile boundaries, runtime contracts, and one executable evidence matrix; remove duplicated component/phase narratives.
  • Add a measured-evidence example and clarify artifact, ownership, comparison, and acceptance rules for offline o11y evaluation.
  • Add a shape-observation and ERP-match example, then separate matching, cost composition, fallback, payload migration, and population isolation.
  • Expand the previously dense completeness prose into explicit admission, publication, query-fence, drain, recovery, and limitation contracts with a partial-publication example.

The changes preserve the documented behavior and scope. They do not change runtime code or claim new capabilities.

Aligned with the updated PR #737 design and review replies: the guides distinguish the current runtime from the proposed plan-scoped state slot and instance inventory, carry Planner-selected producer deployment decisions with the complete query computation, and keep logical range, refresh cadence, retention, and readiness separate. The existing catalog-generation field remains described as current behavior pending an explicit migration to the proposed plan-version contract.

Expanded the ASAPQuery E2E acceptance matrix for issues #701 and #702: moving quantile windows, instant sum/count/avg, temporal min/max/avg, Top-K and composed ratios. The guide now identifies the current instant/range evidence, the remaining real-Prometheus and range gaps, and that the Docker demo alone does not satisfy the full matrix.

Validation:

  • git diff --check
  • local Markdown link and anchor validation, including inbound links from docs/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant