docs: sid lifecycle design + distributed asapquery-backend extension sketch

[zzylol]

Summary

Adds docs/design-sid-lifecycle.md — a design doc capturing the registry-allocated sid model that landed in PR #190 + PR #192, plus a forward-looking extension to distributed asapquery-backend.

Contents

• Identity contract: sid = registry-allocated u64 for (metric, attrs_fingerprint, agg_kind_canonical). Uniqueness by construction (AtomicU64::fetch_add), not by hash probability.
• Component responsibilities across asapcollector (patched OTel-Go exporter dictionary) and asapquery-backend (SeriesIdResolver, SketchStore, ingest paths, query path).
• End-to-end architecture diagram showing the unified mint authority and the two ingest paths (sketch + precompute) converging on one resolver.
• Wire-case table for the 4 per-DP shapes (sid 0/!=0 × attrs present/absent).
• Failure-recovery sequence diagrams for cold start, stale sender sid, restart with WAL replay, restart without persistence.
• Durability semantics: fsync-per-mint, torn-write detection via short-read at replay, WAL v2 format.
• Distributed extension (forward-looking, not implemented):
  • Sharding axis = hash(tenant, metric); a single metric's series stay on one shard so warm-tier merges stay local.
  • ID-space partitioning: top 8 bits of u64 = shard_id, bottom 56 bits = local counter → no mint coordination, global uniqueness by construction, O(1) sid-to-shard routing.
  • Query fan-out via a coordinator that extracts shard_id from sids and routes per-shard reducer RPCs.
  • HA-within-shard options (S3-backed WAL with passive standby, EBS-snapshot pair, or Raft on the WAL).
  • Single → sharded migration path that needs no proto change and no collector update.
• Open questions (5 items): ResolveSeriesIDs RPC fate, WAL compaction, per-tenant sid subspace, collector-side routing colocation, cross-shard PromQL semantics.
• References to the relevant code paths and prior design docs.

What this doc does NOT do

• Doesn't propose changes — purely captures the model that's already shipped (PR feat(ingest): unified registry-allocated sid (PR-1+2+3, precompute follow-up in PR-4) #190/192) plus a sketch for scaling. Implementing the distributed section is a separate piece of work.
• Doesn't replace docs/design-controller-into-backend.md — that's still the canonical reference for the broader controller-into-backend refactor; this doc cross-references its §5.4.

Test plan

• Reviewer: skim the failure-recovery sequence diagrams (§4.1–4.4) against the live code paths in data_plane/src/drivers/ingest/otel.rs and confirm the wire cases match.
• Reviewer: validate the §5 distributed sketch is consistent with where you actually want the system to go. Specifically — is (tenant, metric) the right sharding key, or should it be something else (per-tenant, per-resource_attrs)?
• Reviewer: the ID-space split (8 bits shard / 56 bits counter) — is 256 shards × 72 quadrillion sids the right budget, or is a different split (16/48? 4/60?) more appropriate?

🤖 Generated with Claude Code