docs(ops): operational serving split (ADR 0011) + ops-surfaces spec (D1) - #143
Merged
Conversation
…ces spec (D1)
The operational layer (domain.md §4: Order 360 timeline, stuck-orders
worklist, exception inbox) needed a committed home for three very
different read shapes before D2-D4 implement it.
ADR 0011 records the split: every ops surface composes exactly the two
existing ports - QueryEngine/ServingBackend for analytical reads (entity
point-reads, the pipeline_events journal, open-order scans) and
ControlPlaneStore for transactional triage state - with no third data
path. Rejected with reasons: everything-on-ClickHouse,
everything-on-PostgreSQL, direct vault reads for the customer block,
precomputed ops marts. The exception-triage overlay becomes the seventh
control-plane state class (extends ADR 0010's inventory).
docs/ops-surfaces-spec.md is the D2-D4 implementation contract: SLA
stage model with budgets as catalog data (stages: block in the order
entity contract), orders.status stage-entry journal rows as the stage
clock with an honest created_at fallback, the journal entity_id axis
made real on live writes (today only the demo seed populates it),
endpoint contracts for /v1/entity/order/{id}/timeline,
/v1/ops/stuck-orders and /v1/ops/exceptions (+stats), reconciliation
checks R1/R2, the manual-resolutions counter, a pinned demo story
(ORD-20260404-1004 as the sole SLA breach) and twelve machine-checkable
invariants as the test contract.
architecture.md and domain.md gain pointers; CHANGELOG entry added.
Docs-only - no runtime behavior changes.
DORA Metrics
|
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.
What
Design step D1 of the endgame plan: the architectural decision + implementation contract for the operational layer (
domain.md§4 — Order 360 timeline, stuck-orders worklist, exception inbox), ahead of implementation slices D2–D4.ADR 0011 — operational serving split
QueryEngine/ServingBackendfor analytical reads (entity point-reads,pipeline_eventsjournal, open-order scans),ControlPlaneStorefor transactional triage state. No third data path (noquery_engine._conn, no vault DSN) — pinned as a structural-ratchet invariant.users_enrichedis the PII-free MDM projection), precomputed ops marts (freshness is the point).docs/ops-surfaces-spec.md — the D2–D4 contract
stages:block incontracts/entities/order.yaml), single ladder v1 (pending 30m / confirmed 24h / shipped 5d).orders.statusjournal rows with an honestcreated_atfallback (clock: "fallback"); the journal'sentity_idaxis becomes real on live writes (today only the demo seed populates it — verified inlocal_pipeline.py/clickhouse_sink.py).GET /v1/entity/order/{id}/timeline,GET /v1/ops/stuck-orders,GET /v1/ops/exceptions(+stats, +acknowledge/resolve).error_ratedenominator moves with seeded stage rows — re-pin by arithmetic).Also
architecture.md+domain.mdgain pointers; CHANGELOG[Unreleased]entry.🤖 Generated with Claude Code