Skip to content

Add synix repair command and protect .synix/ from accidental deletion #113

@marklubin

Description

@marklubin

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions