docs(design): rename Operator/Host/Sample/SketchFrame; trait composition; phase renumber - #216
Merged
zzylol merged 1 commit intoMay 2, 2026
Conversation
zzylol
force-pushed
the
docs/design-edge-framework-naming-and-design-revisions
branch
6 times, most recently
from
May 2, 2026 03:49
6532ed6 to
20bf4f6
Compare
…ion; phase renumber
In-place revisions to the edge precompute framework design doc per
naming and design audit:
NAMING — collisions resolved:
- Operator → Precompute (avoids k8s-operator / DataFusion-operator
confusion; matches existing `precompute_engine` naming on backend).
- asap-operator-{go,rs} → asap-precompute-{go,rs}.
- Host → Adapter; asap-host-* → asap-{otelcol,telegraf,vector,otap}
(drop host- prefix; "Host" is overloaded).
- Sample → Observation (avoids prometheus::Sample / pmetric collision;
matches observe() verb).
- SketchFrame → keep SketchEnvelope (existing proto name; "Frame" is
overloaded; "envelope" is the standard term for tagged-union wire
payloads).
- WindowMode { Batch, Window, Sliding } → AggregationMode { Tumbling,
Sliding, Batch } (drop Window variant inside Window-prefixed enum).
DESIGN — abstractions sharpened:
- Sketch trait split into Sketch + QuantileSketch + CardinalitySketch
+ FrequencySketch (each sketch only exposes queries it can answer;
matches asap_sketchlib current shape).
- Adapters emit raw Observations; runtime resolves agg_id via matchers
internally (single source of truth, simpler adapter contract).
- One Precompute instance per sketch type (matches today's per-processor
shape); generic over SketchT instead of dyn dispatch.
- Crash recovery (snapshot/restore) deferred to future
PersistentPrecompute trait; not in Phase 2 scope.
- New ControlChannel trait abstracts OpAMP / HTTP-poll / FileWatch
(§5.7 + §7).
- New backpressure config: max_series + OnOverflow (Drop | Block |
EvictOldest); needed once runtime is extracted from OTel pipeline.
PHASING — renumbered, ADR landing:
- Phase 0.5 (sketch-core retirement, already shipped) moved to
adr-0001-retire-sketch-core.md; design doc stays forward-looking.
- Phases 1-7 (no decimals): lock design → extract Go → extract Rust
→ Telegraf → OTAP → Vector → optional rename to asap-edge.
- R1 mitigation rewritten: cross-language *statistical-output*
comparison (P50/P90/cardinality within sketch error bound), not
byte-corpus (byte corpus is invalid because hash seeds and storage
growth strategies legitimately differ).
Length: 822 → 945 lines (+123). All cross-references updated.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
zzylol
force-pushed
the
docs/design-edge-framework-naming-and-design-revisions
branch
from
May 2, 2026 03:51
20bf4f6 to
e444ba2
Compare
This was referenced May 2, 2026
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
In-place revisions to `docs/design-asap-edge-framework.md` per naming + design audit.
Renames (collision resolutions)
Design changes
Phasing
R1 mitigation rewrite
Old: cross-language byte-corpus comparison.
New: cross-language statistical-output comparison (P50/P90/P99/count/sum/cardinality/top-K within each sketch's published error bound). Byte corpus is invalid because hash seeds and storage growth strategies legitimately differ across runtimes (we discovered this during the wire-format alignment audit). Harness to live in `sketchlib-bench`.
Stats
Out of scope