Source: schemas/library_catalog.json

{
  "title": "Turn Zero Cloud — the library catalog's shape",
  "description": "The shape of the catalog the platform serves (LC-01 in the library catalog contract), not a copy of its rows. Until 2026-08-22 UTC this file held the rows themselves — a one-entry selection with a channels column — and Q-216 retired both: publication is the whole awake library, latest only, with no channel and no selection, so the rows are derived from the library's source by the publisher and a committed copy of them would be the derived view KQ-21 retired. What stays committed is the contract's machine form, which is what CTX-01 serves an authoring AI: the members a row carries and what each means. A test in the platform's suite holds the publisher's output to this shape.",
  "derived_from": "system, by the publisher",
  "selection": {
    "rule": "Every awake entry with an authored L1 publishes, unless its L1 declares publication: withheld; the font families a sheet references and the library's own requirements entry, `library/prd`, publish with them, asked for no L1, that entry unless its own key withholds it; and nothing else.",
    "awake": "An entry whose owning document carries no Dormant marker. A dormant entry is never selected and is therefore never asked for a version or a summary — it goes live when it exists (Q-239).",
    "withheld": "An entry whose L1 front matter declares publication: withheld (FTR-L0-102). A withheld entry is awake and under development, and the publisher does not select it while the key stands; the next publish after the key is written drops the entry, and the next publish after the key is removed serves it again. Any other value of the key refuses the publish by name. The library's own requirements entry is withheld the same way, by the key in its platform document's front matter (FTR-L0-106).",
    "authored": "An entry whose L1 front matter carries a version: on FTR-L0-62's spelling and whose prd.md carries a Selection summary section (FTR-L0-57).",
    "refusal": "An awake package or vocabulary missing either fact is refused by name (LC-01; the library's retired decision LQ-01); a font family and the requirements entry are asked for neither. The generator does not omit it, because an omitted entry makes the inventory quietly incomplete, and does not derive the missing text, because a generated summary would stand where a customer reads to choose."
  },
  "catalog": {
    "source_commit": "The library commit the tree was read at, reachable from main and refused otherwise by the publisher's git gate. It is also the catalog's own address in the store: library/publishes/<source_commit>/catalog.json.",
    "published_at": "When this publish ran, ISO 8601. The publisher supplies it rather than the catalog builder reading a clock, so two runs over one tree agree exactly.",
    "entries": "The rows, one per selected entry, on the shape below."
  },
  "entry": {
    "name": "The entry's stable name: a package's folder name, `ui/<vocabulary>`, `fonts/<family>`, or `library/prd` for the library's own requirements entry. It is in the form a take line carries: one or two segments joined by a slash, each of lower-case letters, digits, `_` and `-`, opening with a letter or a digit. A publish whose catalog holds a name outside it is refused.",
    "kind": "package | vocabulary | font | document",
    "path": "Where the entry lives in the library's source, for a reader tracing a file back.",
    "version": "FTR-L0-62's front-matter version. Null on a font family, which carries no specification of its own and so no version of its own, and on the requirements entry, whose two documents declare none.",
    "summary": "FTR-L0-57's Selection summary, quoted from the entry's own prd.md and never re-authored here. Null on a font family and on the requirements entry, neither having such a section.",
    "supersedes": "The versions this entry's own front matter names as superseded (FTR-L0-49's key), quoted on the same terms as the summary: the package owns the words, the catalog quotes them, equality suite-held (LC-03). Empty on a font family, which carries no front matter, and on the requirements entry, whose documents name no superseded version. Absent on catalogs published before 2026-08-24 UTC; a reader treats absence as empty.",
    "closure_hash": "sha256 over the entry's served closure (LC-01: a package's folder less its tests/ folders and its TypeScript source files; a vocabulary's or a font family's folder whole; the requirements entry's two named documents), each line `path<TAB>sha256` and the lines sorted — so moving a file inside an entry changes the hash, which is what a consumer comparing two versions needs.",
    "files": "One row per file of the served closure: its path, its sha256, and its size. A package's compiled runtime modules under lib/ and its generated package.json are listed; its source and its tests are not (LC-01; Q-235). The bytes are fetched one file at a time by read_library_entry, never as a whole package.",
    "published_at": "When this version of this entry first appeared. Distinct from the catalog's own published_at: most entries do not change in most publishes, and API-L0-16's compatibility window counts from the entry rather than from the publish that carried it. An unchanged entry keeps this date across publishes.",
    "previous_versions": "Each superseded version with the times it was published and superseded, carried forward by each publish so a compatibility window has a date to count from. read_library_entry answers it and the inventory never does (LC-06). Empty on an entry's first publish. A font family and the requirements entry, which carry no version of their own, gain no row and keep the date they first appeared."
  },
  "served": {
    "inventory": "list_library answers each row's name, kind, version, closure hash, summary, and supersession list, anonymously and always (API-L0-15), and no version history. With an `installed` list it also answers a standing per entry: whether the caller's vendored copy (SPM-L0-49) is current, newer, or withdrawn — each held item naming the closure hash its manifest row records, compared with the served closure hash — and `not_held` for a served entry the list does not name, compared with nothing, unless the call carries `held_only`, which answers the named entries alone; the comparison made here rather than by each consumer (LC-06).",
    "content": "read_library_entry answers one entry's file list with its catalog row, its previous versions among them, or one named file, anonymously until an account capability is added (LC-02).",
    "latest_only": "A newer publish replaces what is served. Nothing promises that a removed version resolves; a consumer keeps its own copy of what it holds (LC-04)."
  }
}