Skip to main content

VCAL Semantic Cache v0.6.0 — Background-Safe Snapshot Persistence

Release date: 2026-05-31

VCAL Semantic Cache v0.6.0 introduces a new snapshot persistence architecture designed to keep the server responsive while snapshots are saved.

Highlights​

  • Autosave and manual /v1/snapshot/save no longer enter drain mode.
  • Cache state is grouped behind one logical state lock.
  • Snapshot capture happens under a read lock, then files are written after the lock is released.
  • Graceful shutdown keeps the quiescent final snapshot path.
  • Startup restores vcal.index, answers.json, and tombstones.json when valid files are present.
  • Dependency resolution was updated to address the rustls-webpki RustSec advisory.

Snapshot Behavior​

Normal runtime snapshots​

Runtime autosave and manual snapshot saves now follow this model:

acquire cache-state read lock
serialize/copy snapshot bundle
release cache-state read lock
write files without entering drain mode

This applies to:

  • periodic autosave controlled by VCAL_AUTOSAVE_SECS,
  • manual admin saves through /v1/snapshot/save.

Shutdown save​

Shutdown keeps the strict quiescent path:

enter drain mode
stop accepting new work
wait for in-flight requests
save final paired snapshot
exit

This preserves final durability guarantees at process exit.

Paired Snapshot Files​

VCAL Semantic Cache v0.6.0 persists:

vcal.index
answers.json
tombstones.json

The tombstones.json file is important for delete persistence. A deleted vector may still exist inside the underlying index file, but tombstones prevent it from being returned after restart.

Verified Smoke Test Flow​

The v0.6.0 release was validated with:

healthz
readyz with auth
license status
insert
search
QA
manual snapshot save
delete
cleanup snapshot save
container restart
search/QA no-hit check after restart

Expected no-hit result after delete + cleanup snapshot + restart:

{"hits":[]}

and:

{
  "hit": false,
  "id": null,
  "distance": null,
  "similarity": null,
  "answer": null
}

Operational Notes​

  • /healthz remains public.
  • /readyz requires authentication when VCAL_AUTH_REQUIRED=1.
  • /metrics can be public when VCAL_ALLOW_METRICS_WITHOUT_AUTH=1.
  • Admin endpoints are under /v1/*, for example /v1/snapshot/save and /v1/license/status.
  • Old snapshots missing the Envelope v1 format field should be archived or migrated before startup.

Known Minor Observability Note​

Snapshot logs may show entries=1 even when active search results are empty. This can happen when the underlying index still contains a tombstoned/deleted vector. Use vcal_active_ids, search, or QA checks to verify active cache state.