# Cuetree FlatBuffers schemas

<!-- AI-AGENT: OpenAI Codex, GPT-6 family; exact runtime model revision is not exposed.
AI-INTENT: Agent provenance is informative. Use the registered owner for normative authority;
do not treat comments, tests, archived editions or this metadata as additional requirements. -->

The [persistence owner](/Cuetree/persistence) defines version fencing, validation and lifetime.
These are the current adopted schema sources; generated bindings are build outputs.

## common.fbs

```fbs
namespace link.roadio.cuetree.fbs;

// An omitted version must fail the exact-format validation gate.

table Header {
  version: uint = 1;
  generation: long;
  identity_scheme: string (required);
  metadata_revision: string;
}

table MediaId {
  hi: long;
  lo: long = null;
}

table MediaBucket {
  hi: long (key);
  sources: [int] (required);
}

table Attribute {
  id: long;
  kind: ubyte;
  value_text: string;
  value_long: long = null;
  generation: long;
  flags: ushort;
}

table SourceInfo {
  name: string (required);
  modified: long = null;
  size: long = null;
  provider: string;
  locator: string;
}

table StructureSection {
  reference: string;
  begin_us: long = null;
  end_us: long = null;
  attributes: [long];
}

table StructureTable {
  key: string (required);
  attributes: [long];
  sections: [StructureSection] (required);
}

table Node {
  flags: ushort;
  generation: long;
  id: long;
  media_lo: long = null;
  parent_id: long = null;
  parent_media_lo: long = null;
  source: SourceInfo;
  begin_us: long = null;
  end_us: long = null;
  attributes: [long];
  tables: [StructureTable];
  source_evidence: [long];
}

table Album {
  id: long;
  flags: ushort;
  title: string (required);
  tracks: [MediaId] (required);
  sources: [int] (required);
  attributes: [long];
  generation: long;
}

table Artist {
  attributes: [long];
  id: long;
  key: string (required);
  name: string (required);
  albums: [long] (required);
  generation: long;
  flags: ubyte;
}

table Genre {
  id: long;
  attributes: [long];
  dictionary_id: long = null;
  text: string;
  name: string (required);
  albums: [long] (required);
  generation: long;
  flags: ubyte;
}
```

## mdia.fbs

```fbs
include "common.fbs";

namespace link.roadio.cuetree.fbs;

table Mdia {
  header: Header (required);
  nodes: [Node] (required);
  media: [MediaBucket] (required);
  attributes: [Attribute] (required);
}

root_type Mdia;
file_identifier "MDIA";
```

## albm.fbs

```fbs
include "common.fbs";

namespace link.roadio.cuetree.fbs;

table Albm {
  header: Header (required);
  albums: [Album] (required);
}

root_type Albm;
file_identifier "ALBM";
```

## arts.fbs

```fbs
include "common.fbs";

namespace link.roadio.cuetree.fbs;

table Arts {
  header: Header (required);
  artists: [Artist] (required);
}

root_type Arts;
file_identifier "ARTS";
```

## gnrv.fbs

```fbs
include "common.fbs";

namespace link.roadio.cuetree.fbs;

table Gnrv {
  header: Header (required);
  genres: [Genre] (required);
}

root_type Gnrv;
file_identifier "GNRV";
```

## Optional JSON companions

The POSIX CLI accepts `--json` to additionally export MDIA.json, ALBM.json, ARTS.json and GNRV.json
beside the corresponding binary files in the same immutable cohort. JSON is the schema-shaped
representation of those exact encoded buffers, including defaults, ordered vectors, ID references,
nullable scalar presence and exact decimal 64-bit integers. The result must be valid strict JSON:
escape control characters in strings without changing their decoded values or rounding IDs. It is
not the allocated JVM model or an expanded convenience view. Use the packaged FBS schemas and the
pinned FlatBuffers converter.

All requested JSON companions must be generated and durably written before CURRENT switches.
Conversion failure leaves the previous cohort current. JSON is optional diagnostic output, not an
input to store recovery; the binary manifest and reader remain authoritative and unchanged. Without
the option, no JSON files or converter processes are required. The CLI build guide owns converter
installation and invocation details.