Problem
.synix/ is a stateful directory containing all build artifacts, snapshots, releases, and fold checkpoints. Wiping it destroys hours of expensive LLM-generated content with no recovery path. The release directory (.synix/releases/) contains materialized search indexes and flat files.
This happened multiple times during the knowledge server deployment — corrupted objects from a format migration caused build failures, and the response was to wipe .synix/ repeatedly, destroying completed builds each time.
Needed
1. synix repair command
- Scan object store for corrupt/invalid objects and remove them
- Rebuild refs from checkpoints if HEAD is broken
- Validate snapshot integrity
- Report what was removed/fixed
2. Documentation
- CLAUDE.md / README: "NEVER delete .synix/ — use synix repair instead"
- Document what .synix/ contains and why each subdirectory matters
3. Object store resilience
_recover_orphaned_artifacts already handles json.JSONDecodeError but crashed on valid JSON that parses to a string (fixed in 7dca901)
- Should also handle: missing content OIDs gracefully, corrupt checkpoint files, broken refs
Context
The _recover_orphaned_artifacts crash was caused by old agent-mesh objects stored as JSON-encoded strings (valid JSON, but not dicts). Fixed by adding isinstance(obj, dict) check. But the real fix is a repair command that handles all corruption gracefully.
Problem
.synix/is a stateful directory containing all build artifacts, snapshots, releases, and fold checkpoints. Wiping it destroys hours of expensive LLM-generated content with no recovery path. The release directory (.synix/releases/) contains materialized search indexes and flat files.This happened multiple times during the knowledge server deployment — corrupted objects from a format migration caused build failures, and the response was to wipe
.synix/repeatedly, destroying completed builds each time.Needed
1.
synix repaircommand2. Documentation
3. Object store resilience
_recover_orphaned_artifactsalready handlesjson.JSONDecodeErrorbut crashed on valid JSON that parses to a string (fixed in 7dca901)Context
The
_recover_orphaned_artifactscrash was caused by old agent-mesh objects stored as JSON-encoded strings (valid JSON, but not dicts). Fixed by addingisinstance(obj, dict)check. But the real fix is a repair command that handles all corruption gracefully.