Problem and boundaries
The knowledge base is updated every day. Overwriting an index in place can expose partial results, so a new version must be built in an isolated directory, checked, and promoted only after it is healthy; failures must return to the previous version.
Design
Each index directory contains manifest.json, chunks.jsonl, and health-check results. current.json stores only the active version pointer. Promotion is one atomic file replacement.
Minimal implementation
import json
from pathlib import Path
def promote(root: Path, version: str) -> None:
manifest = json.loads((root / version / 'manifest.json').read_text())
if manifest.get('status') != 'healthy':
raise ValueError('index is not healthy')
tmp = root / 'current.json.tmp'
tmp.write_text(json.dumps({'version': version}))
tmp.replace(root / 'current.json')
Reproduction steps
- Write the input snapshot and build parameters into a new version directory.
- Check document count, chunk count, sampled retrieval, and permission filters.
- Mark the version healthy, then atomically replace current.json.
- Watch error rate and zero-result searches; on an anomaly, point current.json back to the old version.
Verification checklist
Verify that an interrupted build leaves current.json unchanged, a damaged manifest cannot be promoted, the old version remains readable after rollback, and cache keys include the index version.
Common questions
Why not use a database transaction? A production system can use a database pointer; this case uses a file pointer to make the atomic-switch idea explicit.
Does rollback delete the new index? No. Keep it until the rollback window ends and backups are complete.
Official references
OpenAI Production best practices; OpenAI Embeddings.
Last checked: 2026-11-16. Follow the linked sources for current interfaces and security boundaries; this case makes no performance or cost claim.
