Skip to content

Release layout: snapshot-addressed releases with named symlinks #97

@marklubin

Description

@marklubin

Problem

Releases are currently stored under .synix/releases/<name>/ where <name> comes from --to local. Releasing twice to the same name overwrites the previous release — history is only preserved in a history/ subdirectory of receipt JSONs, but the actual materialized artifacts (search.db, context.md) are lost.

Additionally, pipeline.build_dir is a misnomer — nothing is written to it during synix build. It's only used as an anchor to locate .synix/ via synix_dir_for_build_dir(). The FlatFile adapter's default output_path="./build/context.md" further confuses this by writing outside .synix/.

Proposed Layout

.synix/releases/
├── <snapshot-oid>/        # immutable, snapshot-addressed
│   ├── search.db
│   ├── context.md
│   └── receipt.json
├── HEAD -> <latest-oid>/  # symlink to most recent release
└── local -> <oid>/        # named alias (from --to local)

Every release is immutable by snapshot ID. Named targets (local, prod) become symlinks. Re-releasing to the same name just repoints the symlink. Old releases are preserved and addressable.

What Changes

  • release_engine.py — write to releases/<snapshot_oid>/, create/update symlink for named target
  • search/adapter.py, flat_file_adapter.py — no change needed (they write to target_path which is passed in)
  • synix search --release <name> — resolve symlink, same behavior
  • synix releases list — show both snapshot-addressed releases and named aliases
  • synix revert <ref> --to <name> — repoint symlink to existing snapshot release (instant if already materialized)
  • SDK Release class — resolve symlinks transparently
  • pipeline.build_dir — consider renaming to project_dir or removing entirely (separate from this, but related naming confusion)

Context

Surfaced during review of #96 (Chunk transform PR). Both the OpenAI and Claude automated reviewers flagged the build_dir naming confusion. The snapshot-addressed layout would also make synix revert instant when the target snapshot was previously released.

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