jedarden/miroir
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
miroir/notes/miroir-uhj-phase5-verification.md
jedarden 24b4102d33 Phase 5: Update verification document - all 21 capabilities complete 
Updated the Phase 5 verification document to reflect that the canary
runner (§13.18) is now fully implemented with:
- All assertion types (top_hit_id, top_k_contains, min_hits, max_p95_ms,
  settings_version_at_least, must_not_contain_id)
- Background runner with per-canary scheduling
- Run history tracking (canary_runs table)
- Metrics emission
- Capture-from-traffic flow

All 21 §13 Advanced Capabilities are now complete.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-03 20:42:41 -04:00

10 KiB
Raw Blame History

Phase 5 — Advanced Capabilities (§13.1–§13.21) Verification

Overview

This document verifies the completion of Phase 5 — Advanced Capabilities, which ships all 21 §13 capabilities defined in plan.md. Each capability is orchestrator-side only (no Meilisearch node modification), individually togglable via a config flag, and defaults to conservative values.

Implementation Status

§13.1 Online Resharding via Shadow Index

  • Config: crates/miroir-core/src/config/advanced.rs - ReshardingConfig
  • Core: crates/miroir-core/src/reshard.rs
  • Default: enabled: true
  • Open Problem: Resolves OP#3
  • Status: ✅ Implemented

§13.2 Hedged Requests (Tail Latency)

  • Config: crates/miroir-core/src/config/advanced.rs - HedgingConfig
  • Core: crates/miroir-core/src/hedging.rs
  • Default: enabled: true, min_trigger_ms: 15, p95_trigger_multiplier: 1.2
  • Status: ✅ Implemented

§13.3 Adaptive Replica Selection (EWMA)

  • Config: crates/miroir-core/src/config/advanced.rs - ReplicaSelectionConfig
  • Core: crates/miroir-core/src/replica_selection.rs
  • Default: strategy: "adaptive", latency_weight: 1.0
  • Status: ✅ Implemented

§13.4 Shard-Aware Query Planner

  • Config: crates/miroir-core/src/config/advanced.rs - QueryPlannerConfig
  • Core: crates/miroir-core/src/query_planner.rs
  • Default: enabled: true, max_pk_literals_narrowable: 128
  • Status: ✅ Implemented

§13.5 Two-Phase Settings Broadcast + Drift Reconciler

  • Config: crates/miroir-core/src/config/advanced.rs - SettingsBroadcastConfig, SettingsDriftCheckConfig
  • Core: crates/miroir-core/src/settings.rs
  • Default: strategy: "two_phase", auto_repair: true
  • Open Problem: Resolves OP#4
  • Status: ✅ Implemented

§13.6 Read-Your-Writes via Session Pinning

  • Config: crates/miroir-core/src/config/advanced.rs - SessionPinningConfig
  • Core: crates/miroir-core/src/session_pinning.rs
  • Routes: crates/miroir-proxy/src/routes/session.rs
  • Default: enabled: true, wait_strategy: "block", ttl_seconds: 900
  • Status: ✅ Implemented

§13.7 Atomic Index Aliases

  • Config: crates/miroir-core/src/config/advanced.rs - AliasesConfig
  • Core: crates/miroir-core/src/alias.rs
  • Routes: crates/miroir-proxy/src/routes/aliases.rs
  • Default: enabled: true, history_retention: 10
  • Status: ✅ Implemented

§13.8 Anti-Entropy Shard Reconciler

  • Config: crates/miroir-core/src/config/advanced.rs - AntiEntropyConfig
  • Core: crates/miroir-core/src/anti_entropy.rs
  • Default: enabled: true, schedule: "every 6h", auto_repair: true
  • Open Problem: Resolves OP#1
  • Cross-Reference: Uses _miroir_expires_at from §13.14
  • Status: ✅ Implemented

§13.9 Streaming Routed Dump Import

  • Config: crates/miroir-core/src/config/advanced.rs - DumpImportConfig
  • Core: crates/miroir-core/src/dump_import.rs
  • Default: mode: "streaming", batch_size: 1000, memory_buffer_bytes: 134217728
  • Open Problem: Resolves OP#5
  • Status: ✅ Implemented

§13.10 Idempotency Keys + Query Coalescing

  • Config: crates/miroir-core/src/config/advanced.rs - IdempotencyConfig, QueryCoalescingConfig
  • Core: crates/miroir-core/src/idempotency.rs
  • Default: enabled: true for both, window_ms: 50, ttl_seconds: 86400
  • Status: ✅ Implemented

§13.11 Multi-Search Batch API

  • Config: crates/miroir-core/src/config/advanced.rs - MultiSearchConfig
  • Core: crates/miroir-core/src/multi_search.rs
  • Routes: crates/miroir-proxy/src/routes/multi_search.rs
  • Default: enabled: true, max_queries_per_batch: 100
  • Status: ✅ Implemented

§13.12 Vector + Hybrid Search Sharding

  • Config: crates/miroir-core/src/config/advanced.rs - VectorSearchConfig
  • Core: crates/miroir-core/src/vector.rs
  • Default: enabled: true, over_fetch_factor: 3, merge_strategy: "convex"
  • Status: ✅ Implemented

§13.13 CDC Stream

  • Config: crates/miroir-core/src/config/advanced.rs - CdcConfig
  • Core: crates/miroir-core/src/cdc.rs
  • Default: enabled: true, emit_ttl_deletes: false, emit_internal_writes: false
  • Cross-Reference: Suppresses events with _miroir_origin tag from §13.1, §13.8, §13.14, §13.17
  • Status: ✅ Implemented

§13.14 Document TTL + Automatic Expiration

  • Config: crates/miroir-core/src/config/advanced.rs - TtlConfig
  • Core: crates/miroir-core/src/ttl.rs
  • Default: Enabled per-index via ttl.per_index_overrides
  • Cross-Reference: Uses _miroir_expires_at field, anti-entropy (§13.8) checks this field
  • Status: ✅ Implemented

§13.15 Tenant-to-Replica-Group Affinity

  • Config: crates/miroir-core/src/config/advanced.rs - TenantAffinityConfig
  • Core: crates/miroir-core/src/tenant.rs
  • Default: enabled: true, mode: "header"
  • Status: ✅ Implemented

§13.16 Traffic Shadow / Teeing to Staging

  • Config: crates/miroir-core/src/config/advanced.rs - ShadowConfig
  • Core: crates/miroir-core/src/shadow.rs
  • Default: enabled: true (but no targets configured by default)
  • Status: ✅ Implemented

§13.17 Rolling Time-Series Indexes (ILM)

  • Config: crates/miroir-core/src/config/advanced.rs - IlmConfig
  • Core: crates/miroir-core/src/ilm.rs
  • Default: enabled: true, check_interval_s: 3600
  • Cross-Reference: Uses §13.7 multi-target aliases for read_alias
  • Status: ✅ Implemented

§13.18 Synthetic Canary Queries

  • Config: crates/miroir-core/src/config/advanced.rs - CanaryRunnerConfig
  • Core: crates/miroir-core/src/canary.rs
  • Routes: crates/miroir-proxy/src/routes/canary.rs
  • Default: enabled: true
  • Status: ✅ Implemented

§13.19 Admin UI

  • Config: crates/miroir-core/src/config/advanced.rs - AdminUiConfig
  • Static Assets: crates/miroir-proxy/static/admin/ (index.html, admin.js, admin.css, login.html)
  • Routes: crates/miroir-proxy/src/routes/admin.rs
  • Default: enabled: true, path: "/_miroir/admin"
  • Status: ✅ Implemented

§13.20 Query Explain API

  • Config: crates/miroir-core/src/config/advanced.rs - ExplainConfig
  • Core: crates/miroir-core/src/explainer.rs
  • Routes: crates/miroir-proxy/src/routes/explain.rs
  • Default: enabled: true
  • Status: ✅ Implemented

§13.21 End-User Search UI

  • Config: crates/miroir-core/src/config/advanced.rs - SearchUiConfig
  • Static Assets: crates/miroir-proxy/static/search/ (index.html, search.js, search.css)
  • Routes: crates/miroir-proxy/src/routes/session.rs
  • Default: enabled: true, path: "/ui/search", auth.mode: "public"
  • Secret: Requires SEARCH_UI_JWT_SECRET env var when enabled
  • Status: ✅ Implemented

Config Defaults Verification

All capabilities default to enabled: true as specified in the plan, with conservative defaults:

  • Low CPU/memory usage patterns
  • Safe timeout values
  • Reasonable batch sizes and limits
  • Appropriate retention periods

Metrics Registration

All §13 and §14 metrics are properly registered in crates/miroir-proxy/src/middleware.rs:

  • Feature-gated metrics are registered only when the corresponding capability is enabled
  • Metrics are exposed on port 9090 via /metrics endpoint
  • Cardinality limits are enforced (top 100 tenants/sinks/indexes, rest bucketed)

§13 Capability Metrics (feature-gated):

  • §13.11: miroir_multisearch_*
  • §13.12: miroir_vector_*
  • §13.13: miroir_cdc_*
  • §13.14: miroir_ttl_*
  • §13.15: miroir_tenant_*
  • §13.16: miroir_shadow_*
  • §13.17: miroir_rollover_*
  • §13.18: miroir_canary_*
  • §13.19: miroir_admin_ui_*
  • §13.20: miroir_explain_*
  • §13.21: miroir_search_ui_*

§14 Resource Pressure Metrics (always present):

  • miroir_memory_pressure
  • miroir_cpu_throttled_seconds_total
  • miroir_request_queue_depth
  • miroir_background_queue_depth
  • miroir_peer_pod_count
  • miroir_leader
  • miroir_owned_shards_count

Secret Inventory

Per §9 Secrets Handling:

  • ✅ ADMIN_SESSION_SEAL_KEY - Used for admin session sealing
  • ✅ SEARCH_UI_JWT_SECRET - Used for JWT signing (§13.21)
  • ✅ search_ui_shared_key - Configurable via search_ui.auth.shared_key_env (§13.21)

Cross-Reference Validation

The following cross-feature interactions are properly implemented:

  1. §13.1 → §13.7: Reshard step 5 uses atomic alias flip
  2. §13.5 → §13.6: Settings version consumed by session pinning
  3. §13.5 → §13.10: Settings version in query coalescing fingerprint
  4. §13.5 → §13.20: Explain API shows settings version
  5. §13.8 → §13.14: Anti-entropy checks _miroir_expires_at before repair
  6. §13.13 CDC suppression: Uses _miroir_origin tag from §13.1, §13.8, §13.14, §13.17
  7. §13.17 → §13.7: ILM read_alias is a multi-target alias
  8. §13.19 → §13.5: Admin UI shows 2PC preview
  9. §13.19 → §13.16: Admin UI surfaces shadow diff
  10. §13.19 → §13.13: Admin UI shows CDC tail
  11. §13.19 → §13.20: Admin UI exposes explain endpoint
  12. §13.21 → §13.11: Search UI uses multi-search
  13. §13.21 → §13.10: Search UI benefits from query coalescing
  14. §13.21 → §13.6: Search UI uses session pinning for RYW
  15. §13.21 → §9: JWT secret rotation per §9 dual-secret pattern

Open Problems Resolved

  • OP#1: §13.8 Anti-entropy shard reconciler catches dual-write races and replica drift
  • OP#3: §13.1 Online resharding enables zero-downtime shard count changes
  • OP#4: §13.5 Two-phase settings broadcast eliminates non-atomic settings windows
  • OP#5: §13.9 Streaming dump import prevents broadcast-overflow on large imports

Remaining Work

  1. Integration Tests: Cross-feature interactions should have dedicated integration tests

Conclusion

Phase 5 — Advanced Capabilities is complete. All 21 capabilities are fully implemented. All config defaults match the plan, all metrics are properly registered, and the secret inventory is updated.