base_dir/
├── _metadata/                         # Manifest metadata directory
│   └── manifest-{version}.avro       # Manifest files (e.g., manifest-1.avro)
├── _data/                             # Column group data files
│   └── {group_id}_{uuid}.{format}    # Data files (Parquet, Vortex, etc.)
├── _delta/                            # Delta log files
│   └── {delta_log_files}             # Delete operation logs
├── _stats/                            # Statistics files
│   └── {stats_files}                 # Bloom filters, BM25, etc.
└── _index/                            # Index files
    └── {index_files}                  # HNSW, IVF, bitmap, etc.

+-------------------+-------------------+
| MAGIC (int32)     | VERSION (int32)   |
| 0x4D494C56        | 1 or 2            |
+-------------------+-------------------+
| COLUMN_GROUPS     | DELTA_LOGS        |
| (avro array)      | (avro array)      |
+-------------------+-------------------+
| STATS             | INDEXES           |
| (avro map)        | (avro array,      |
|                   |  version 2+ only) |
+-------------------+-------------------+

struct ColumnGroupFile {
  std::string path;               // File path (relative within _data/)
  int64_t start_index;            // Start row index in the file (inclusive)
  int64_t end_index;              // End row index in the file (exclusive)
  std::vector<uint8_t> metadata;  // Optional metadata (e.g., external table info)
};

struct ColumnGroup {
  std::vector<std::string> columns;    // Column names in this group
  std::string format;                  // Storage format
  std::vector<ColumnGroupFile> files;  // Physical file references
};

struct DeltaLog {
  std::string path;     // File path (relative within _delta/)
  DeltaLogType type;    // Delete type (encoded as int32)
  int64_t num_entries;  // Number of delete entries
};

std::map<std::string, std::vector<std::string>> stats;

struct Index {
  std::string column_name;                         // Column this index is on
  std::string index_type;                          // Index algorithm
  std::string path;                                // File path (relative within _index/)
  std::map<std::string, std::string> properties;   // Index-specific parameters
};

Serialization:   /data/base/_data/0_abc.parquet  →  0_abc.parquet
Deserialization:  0_abc.parquet  →  /data/base/_data/0_abc.parquet

Open(fs, base_path, version)
        |
        v
  Read manifest at version
  (or empty manifest if version=0)
        |
        v
  Record updates via fluent API:
    .AddColumnGroup(cg)
    .AppendFiles(cgs)
    .AddDeltaLog(delta)
    .UpdateStat(key, files)
    .AddIndex(idx)
    .DropIndex(col, type)
        |
        v
  Commit()
    1. Read latest manifest (seen_manifest)
    2. Invoke resolver(read, read_ver, seen, seen_ver, updates)
    3. Write resolved manifest as manifest-{seen_ver+1}.avro
    4. On conflict, retry up to retry_limit times
        |
        v
  Return committed version

Transaction: AppendFiles to column group containing "embedding"
  → Any index with column_name="embedding" is silently removed

class Manifest final {
  // Construction
  explicit Manifest(ColumnGroups column_groups = {},
                    const std::vector<DeltaLog>& delta_logs = {},
                    const std::map<std::string, std::vector<std::string>>& stats = {},
                    const std::vector<Index>& indexes = {},
                    uint32_t version = MANIFEST_VERSION);

  // Serialization
  arrow::Status serialize(std::ostream& output,
                          const std::optional<std::string>& base_path = std::nullopt) const;
  arrow::Status deserialize(std::istream& input,
                            const std::optional<std::string>& base_path = std::nullopt);

  // Accessors
  ColumnGroups& columnGroups();
  std::shared_ptr<ColumnGroup> getColumnGroup(const std::string& column_name) const;
  std::vector<DeltaLog>& deltaLogs();
  std::map<std::string, std::vector<std::string>>& stats();
  std::vector<Index>& indexes();
  const Index* getIndex(const std::string& column_name,
                        const std::string& index_type) const;
  int32_t version() const;
};

class Transaction {
  static arrow::Result<std::unique_ptr<Transaction>> Open(
      const ArrowFileSystemPtr& fs,
      const std::string& base_path,
      int64_t version = LATEST,
      const Resolver& resolver = FailResolver,
      uint32_t retry_limit = 1);

  arrow::Result<int64_t> Commit();
  arrow::Result<std::shared_ptr<Manifest>> GetManifest();
  int64_t GetReadVersion() const;

  // Fluent builder
  Transaction& AddColumnGroup(const std::shared_ptr<ColumnGroup>& cg);
  Transaction& AppendFiles(const std::vector<std::shared_ptr<ColumnGroup>>& cgs);
  Transaction& AddDeltaLog(const DeltaLog& delta_log);
  Transaction& UpdateStat(const std::string& key,
                           const std::vector<std::string>& files);
  Transaction& AddIndex(const Index& index);
  Transaction& DropIndex(const std::string& column_name,
                          const std::string& index_type);
};

manifest-3.avro
├── Magic: 0x4D494C56
├── Version: 2
├── ColumnGroups:
│   ├── [0] columns=["id", "text"], format="parquet"
│   │   └── files:
│   │       ├── path="0_a1b2c3.parquet", start=0, end=50000
│   │       └── path="0_d4e5f6.parquet", start=0, end=30000
│   └── [1] columns=["embedding"], format="parquet"
│       └── files:
│           ├── path="1_g7h8i9.parquet", start=0, end=50000
│           └── path="1_j0k1l2.parquet", start=0, end=30000
├── DeltaLogs:
│   └── path="delete_001.del", type=PRIMARY_KEY, num_entries=128
├── Stats:
│   └── "bloomfilter" → ["bf_001.bin"]
└── Indexes:
    └── column_name="embedding", index_type="hnsw",
        path="embedding_hnsw.idx",
        properties={"M": "16", "efConstruction": "128", "metric_type": "L2"}