Repository navigation
atlas-search service: query-embedding + snapshot result caching, --no-cache/--wait/--expand/--raw flags #5668
Description
Implementation of §3 of the Scaler-era data architecture revision (design doc PR #5667, doc/2026-11-04T21-27-34Z_design_atlas_scaler_revision/). Builds on the search service from epic #5350 (esp. #5354 serve mode).
Scope:
- Query-embedding cache: key
sha256(model_id || model_rev || normalized_text), no TTL; service-memory LRU (~10k entries) + shared Turso cache DB in the internal tier; cache writes async/best-effort, never in the request path. - Result cache: key
sha256(query || snapshot_id || ceiling || flags); reused while the snapshot id (publish manifest hash) is current; 24 h TTL as GC bound only; in-service memory per the Atlas step 4: serve mode — job protocol, worker pool, in-memory temp store #5354 privacy rule (no cross-client result sharing by default). - Flags end-to-end (CLI + service protocol):
--no-cache(bypass reads, refresh writes),--wait(block for full fused result vs job handle + first page),--expand N(hydrate top N to full chunk/file text from the content store),--raw/--raw=branches(ungrouped rows, pre-fusion option). All flags are part of the cache key. - Snapshot id plumbing: aggregator promotion batches bump the snapshot id; the service must observe bumps without restart.
Acceptance: golden-311 parity unchanged with caches cold and warm (eval runs use --no-cache); a repeated identical query against an unchanged snapshot is served from cache with no Turso round-trip for the ranking; a snapshot bump invalidates all result entries at once; PBT over cache-key construction (flag sensitivity, ceiling sensitivity) + MBT for the snapshot-rotation invalidation, per the testing doctrine (every test names its oracle).
Design: #5667 §3. Parent context: hatch-personal#21.
Acceptance criteria
- Query-embedding cache: key
sha256(model_id || model_rev || normalized_text), no TTL, service-memory LRU (~10k) plus shared Turso cache DB; writes async/best-effort, never in the request path. - Result cache: key
sha256(query || snapshot_id || ceiling || flags); hits only while the snapshot id is current; 24h TTL as GC bound only; per-service memory per the Atlas step 4: serve mode — job protocol, worker pool, in-memory temp store #5354 privacy rule (no cross-client result sharing by default). - Flags work end-to-end (CLI + service protocol) and are part of the cache key:
--no-cache,--wait,--expand N,--raw/--raw=branches. - Snapshot id from aggregator promotion batches (issue atlas staging tier: versioned schema, registry, aggregator with merge-on-close promotion into three-level core #5669) invalidates stale result-cache entries.
- Behaviour matches design PR docs: Scaler-era Atlas/Turso data architecture revision #5667 section 3; deviations are recorded on this issue.
Metadata
Metadata
Assignees
Labels
Large: multi-day or open-ended; expect staged check-insIntake review done: acceptance criteria, links, and normalized labels addedOrdinary priority (the default)Queue or user escalation stateFiled directly by a humanQueue or user escalation stateQueue packet kind: verify, reproduce, and route this itemQueue worker lifecycle state
Activity
dezren39 commentedon Nov 4, 2026
Intake review
Intake by fleet monitor (repo-fleet-monitor), 2026-11-04 run.
dezren39 commentedon Nov 4, 2026
Drew approval recorded (2026-11-04 ~17:10 CST): the shared INTERNAL-tier embedding-cache DB (revision §3.1) is CONFIRMED — "yes, all of these things."
First instance already created under the TursoDB pilot approval:
pilot-tursodb-embedcache(Turso-type DB, groupgreat-star-lord, empty, labeled pilot). The cache/flags work in this issue can target it for the embedding-cache store; the query/result cache design (§3) is unchanged.dezren39 commentedon Nov 5, 2026
🤖 Agent note · handed off
opencodeper task 10102 lane assignment; the laptop opencode claimant launches the bound session that drives this task. This lane did not work it directly, verified only that issue atlas-search service: query-embedding + snapshot result caching, --no-cache/--wait/--expand/--raw flags #5668 is OPEN with no hard-stop labels, and created no worktree or competing PR.dezren39 commentedon Nov 5, 2026
🤖 Agent note · picked up
dezren39 commentedon Nov 5, 2026
Triage findings — task 10102
Verified against laptop
mainat6a06a926a0a0e1f3a1aac661fa65c5bab2b4aacb(fast-forwarded; no tracked local changes). Issue #5668 remains open. Design PR #5667 is merged; #5669, which supplies the snapshot id used by result caching, remains open. No open implementation PR for #5668 or #5669 was found.Packet/design defect requiring a decision: the existing Rust CLI
--expand Nmeans “include N neighboring chunks” (pkgs/atlas-search/crates/atlas-search/src/main.rs:197-199;pkgs/atlas-search/crates/atlas-core/src/search.rs:70-71). The merged design §3.3 and this issue instead define--expand Nas hydrating the top N results to full chunk/file content. Neither says whether the existing neighbor behavior is preserved under another flag or intentionally removed. Please choose and record the compatibility/migration contract before implementation; this lane will not guess.Ordering once clarified: query-embedding caching can proceed independently; result caching must use the current snapshot id from #5669 and retain the #5354 per-service privacy boundary (no cross-client result sharing by default).
🤖 Agent note · blocked
--expandbehavior;repo-queue blockreason classpacket_defect.