docs(adr): close Phase 1 — three ADRs + Phase 2 execution plan - #218
Merged
Merged
Conversation
Phase 1 of the edge-framework migration is "lock the design + ADRs"
per docs/design-asap-edge-framework.md §9. Adds:
- adr-0001-retire-sketch-core.md (Accepted, retrospective). Records
what shipped in asap_sketchlib#36 + ASAPQuery-backend#73 +
ASAPQuery#309: sketch-core retired, ImplMode dispatch removed,
dsrs/clap/ctor/asap-cli deps dropped, well-known-name renames
(HllDelta → HllSketchDelta, HeapItem → CmsHeapItem, CountMinDelta
→ CountMinSketchDelta).
- adr-0002-extract-precompute-runtime.md (Proposed, gates Phases
2 / 3). Pins the asap-precompute-{go,rs} crate layout, the
Precompute / Sketch / PrecomputeConfig trait surface, the
behavior-preservation contract (b3-delta produces same value),
and the performance contract (p99 within 10%).
- adr-0003-adapter-trait-and-control-channel.md (Proposed, gates
Phases 4 / 5 / 6). Pins the Adapter trait, the ControlChannel
trait, the hard rule that ControlChannel runs in an internal
goroutine/task on every adapter (precedent: tailsamplingprocessor),
and the Strategy A/B encoding choice with the project-standard
well-known field names.
- phase-2-execution-plan.md (companion to ADR-0002). File-by-file
function-level extraction map for all 5 OTel processors
(~3850 LoC → ~1500 LoC shared module + 5 × ~50 LoC shims).
Identifies two structural patterns (DDSketch/KLL/HLL nested
windows vs CountSketch/CMS flat partitioned windows) and
unifies them under the generic Precompute trait. 11-step work
breakdown with phase-exit criterion.
Once these ADRs land, Phase 1 is done and Phase 2 (Go runtime
extract) can start.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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.
Summary
Closes Phase 1 of the edge-framework migration (see `docs/design-asap-edge-framework.md` §9). Phase 1's exit criterion is "doc reviewed + ADRs opened"; the design doc has been through three iterations already (#213, #216, #217) so this PR adds the three ADRs and the Phase 2 execution plan.
What's in the PR
`docs/adr/adr-0001-retire-sketch-core.md` (Accepted, retrospective)
Records what shipped in asap_sketchlib#36 + ASAPQuery-backend#73 + ASAPQuery#309: sketch-core retired into `asap_sketchlib`'s existing `src/sketches/` layout; ImplMode dispatch removed; dsrs / clap / ctor / asap-cli deps dropped; renames (`HllDelta` → `HllSketchDelta`, `HeapItem` → `CmsHeapItem`, `CountMinDelta` → `CountMinSketchDelta`).
`docs/adr/adr-0002-extract-precompute-runtime.md` (Proposed, gates Phases 2 / 3)
Pins the `asap-precompute-{go,rs}` crate layout, the `Precompute` / `Sketch` / `PrecomputeConfig` API surface, the behavior-preservation contract (b3-delta produces same value at offset −90s), and the performance contract (per-observation p99 within 10%).
`docs/adr/adr-0003-adapter-trait-and-control-channel.md` (Proposed, gates Phases 4 / 5 / 6)
Pins the `Adapter` trait, the `ControlChannel` trait, the hard rule that `ControlChannel` runs in an internal goroutine/task on every adapter (precedent: OTel's `tailsamplingprocessor`), and the Strategy A/B encoding choice with the project-standard well-known field names.
`docs/phase-2-execution-plan.md` (companion to ADR-0002)
File-by-file extraction map for all 5 OTel processors (~3850 LoC across `{ddsketch,kll,hll,countsketch,countminsketch}processor/processor.go` → ~1500 LoC shared `asap-precompute-go` module + 5 × ~50 LoC shims). Identifies two structural patterns:
Unifies both under the generic `Precompute[SketchT]` trait. 11-step work breakdown with explicit phase-exit gate (b3-delta value, p99 latency, P8 accuracy reducer, controlchannel smoke).
Stats
```
docs/adr/adr-0001-retire-sketch-core.md 137
docs/adr/adr-0002-extract-precompute-runtime.md 195
docs/adr/adr-0003-adapter-trait-and-control-channel.md 179
docs/phase-2-execution-plan.md 280
---
791 lines
```
Next
Once these land, Phase 1 is done and Phase 2 (Go runtime extract) can start using the execution plan as the work-breakdown spec.