Source: library_catalog.md

---
document: library_catalog
prefix: LC
---

# The Library Catalog — Contract

This file is the contract for the library catalog API-L0-14 names: the publication index of the system library Turn Zero Cloud serves. The machine form at `schemas/library_catalog.json` holds the contract's shape — the selection rule and the members a row carries — and holds no rows; the rows are generated from the library's source and served with each publish. This document states the catalog rules; it does not contain the published entry rows.

The awake library publishes together, latest only, less the packages whose contracts withhold publication (LC-01), and the MCP surface and the management API both answer from the same publish. The kit is a client of the served library rather than a channel of its own (Q-239).

Requirements are numbered LC-nn.

LC-01: The catalog is the library's publication index and is library-only: what one publish selected, at which versions, with which content hashes, from which commit. **The closure of a package is its folder less every `tests/` folder and every TypeScript source file**, a `.ts` name that is not a `.d.ts`, at any depth. The closure of a vocabulary or a font family is its folder whole (system:FTR-L0-47; Q-235). The closure of the library's own requirements entry, `library/prd`, the one entry of kind `document`, is the two documents the library's statement names, `feature_packages.md` and `platform.md` (system:FTR-L0-106).

A package's compiled runtime modules under `lib/` and its generated `package.json` are served, its source and its tests are not, and the content hash is computed over the served files alone. The publisher reads that set through one exported predicate, the family audit reads the same set through its own copy under system:FTR-L0-101, and the structure suite pins the two equal.

There is no channel and no per-channel selection. The awake library publishes together, the library's own requirements entry with it, less the packages whose contracts withhold publication and less that entry while its own key withholds it (API-L0-14; FTR-L0-102; system:FTR-L0-106). So the catalog records a derivation rather than a set of editorial choices, and no row is editable apart from the source it derives from. The derivation reads the tree and the publish's own date and nothing else: two runs over one tree agree row for row, and each file row carries the file's path, its hash, and its size.

An awake package or vocabulary that lacks its version or its Selection summary is refused by name and never omitted, because an omitted entry makes the inventory quietly incomplete, and the publisher derives neither fact. The requirements entry and a font family are asked for neither. A library source whose `prd` folder lacks one of the two documents the requirements entry names is refused by name, and a source that holds no such folder selects no requirements entry.

An entry's name is in the form a take line carries: one or two segments joined by a slash, each of lower-case letters, digits, `_`, and `-`, and each opening with a letter or a digit. A publish whose catalog holds a name outside that form is refused whole and writes nothing. The refusal names the first such entry by its place in the catalog, with its name where the name can be repeated (PLD-L0-95).

The rows are generated from the library's own source by the publisher and served with the publish; the committed `schemas/library_catalog.json` holds the contract's machine form — the selection rule and the members a row carries — and holds no rows. Turn Zero Cloud's own contracts and guides are the served-context index's and never rows here. This document states the rules and repeats none of them. The suite holds both directions: a row naming a library entry that does not exist is a defect, and an awake authored entry the catalog omits is a defect too, unless its contract withholds it (CTX-01's extension; Q-239).

LC-02: The access classes are one rule, never a column: both tiers — the inventory, meaning catalog rows and their selection summaries, and entry content — answer anonymously on the wire surface, and over MCP to any signed-in connection (API-L0-15; MCP-02). At launch there is no account to be the connected one, so gating content would close the library to every reader rather than to anonymous ones; when an account capability exists an amendment may gate content and may never gate the wire's inventory. No row carries an access member, because a constant column is dead data. The gate is derived from each action row's own access marking rather than from any list beside it (MAPI-11), and the suite holds the catalog, this rule, and the marking coherent (Q-239).

LC-03: Each entry's `summary` member quotes the entry's own Selection summary section — the package `prd.md` owns the words (FTR-L0-57), the catalog quotes them, equality suite-held, and the MCP listing descriptions derive from the same source (MCP-05). A summary is authored nowhere else, so it travels with the library through every served surface and cannot drift from its package. **An entry's supersession edge is quoted on the same terms**: where a package's own front matter names the versions it supersedes (FTR-L0-49's `supersedes:` key), the row quotes that list, the package owns the words, and equality is suite-held exactly as the summary's is. Which edges are live is the packages' front matter to say and the catalog's to derive; quoting an edge into the row is what makes it visible to anyone the catalog answers, the front matter alone reaching no connected client.

LC-04: A newer publish replaces what is served, and nothing promises that a superseded version still resolves. The catalog records what one publish selected from one commit, the `library/current` pointer names it, and the previous publish's catalog and blobs may be removed with no statement here obliging the store to keep them. A consumer does not depend on the server for what it already holds. A project that vendors an entry commits its own copy, recording the version, the content hash, and the commit published from, the compiled runtime modules inside that copy, and it decides for itself when to take a newer one (SPM-L0-49; Q-235).

**A content hash is a row member on every entry**, computed over the entry's closure as LC-01 defines it, and it is what a consumer compares to decide whether the folder it holds still matches what is served. Each file's path from the library's root is hashed with its content, so no two entries of one catalog share a closure hash, entries of identical content among them. A dormant entry is never published, because nothing is served that no forward pass maintains.

**A publish runs in three phases**, the publisher driving them in order: `begin`, which answers which of the catalog's blobs the store lacks; `put`, one blob per call under its own content hash (LC-05); and `commit`. The `commit` phase refuses by name where any blob the catalog names is absent and leaves the pointer unmoved. The pointer's swap is a publish's last write, so every reader sees the previous publish whole until it lands, and a partial publish never.

**A publish must not move the library backwards**: the publisher refuses before `begin` unless the served commit is absent, the same, or an ancestor of the publishing HEAD — backward, diverged, and locally unresolvable served commits each refuse by name. The check runs where the repository is, because the server holds no clone, so its commit phase answers no ancestry. It accepts a different commit only with `served_commit`, the publisher's evidence naming the served commit it was checked against, and refuses `publish_not_forward` where that evidence is absent or stale. Its `begin` refuses a differing catalog for the served commit by the same name. The publisher reaches these gates when invoked through a project-root symlink or junction, preserving its refusal outcome; importing its reusable definitions starts no publish.

**A publish serves no library source the estate's plane does not carry.** A platform release carries the library source at its build commit (LC-09), so before `begin` the publisher reads the source commit the health read of the estate it publishes to names (MAPI-13; PLD-L0-85). It refuses where the library source differs between that commit and the publishing HEAD, naming the served commit to publish from. It refuses by name where the read fails, names no commit, does not report a clean build, or names a commit the clone does not hold after its fetch, and where the comparison cannot be made. No flag admits a publish past these refusals.

**A version names one closure.** A publish that keeps an entry's version while its closure hash differs from the served entry's closure hash is refused by name, and the refusal states the entry, the version, and both hashes, each where it holds its shape. Two byte sets under one version name are what the content hash exists to make impossible. A font family carries no version, and neither does the library's own requirements entry, so the refusal reaches neither, and each one's closure hash is its whole identity. FTR-L0-101 is the repository-side rule that keeps a tree from reaching this refusal, and the record the audit under that rule reads is the publish record LC-08 states.

LC-05: A served entry's bytes verify against their hash by construction rather than by a check a route could skip. A file is stored at `library/blobs/<sha256>` and fetched by that name, so the name a read resolves through is the hash the catalog row records, and bytes that do not match the hash are not addressable. A fetch finding nothing at the name is a refusal naming the entry and the file, never bytes served with a warning. The consumer verifies again on its own side as it writes each file, so the promise is checkable from both ends rather than asserted from one.

A file may also be read in chunks under the served context's paging and text limits (CTX-07), each chunk's stamp the file's hash. The consumer verifies the joined bytes against that hash as it verifies a whole read, and the server refuses by name, `context_changed`, a stamp a publish has since moved. A blob absent under a name the current catalog cites is an integrity failure of the store rather than a bad request, is reported as one, and the entry stays unresolvable until a publisher re-publishes it.

On the MCP surface, the entry answer also carries the line that takes the entry with the turnzero-cloud command's `library take` (PLD-L0-100), in the two forms PLD-L0-94 states. Run at the project's root, the command checks every listed file against its hash and the entry's closure hash before it writes anything. An entry whose name the line cannot carry is answered with no line, saying so.

LC-06: Supersession is answered in the inventory and nowhere else. A superseded version is not served — the publish is latest only (LC-04) — so there is no read of it left to carry a notice. The inventory carries enough in its place, so that a consumer learns without asking a question it does not know to ask: each row quotes the entry's own supersession list (LC-03). No inventory row carries the version history: `read_library_entry` answers an entry's previously published versions with the times each was published and superseded.

The publisher sends no history. It sends each row dated to its own publish with an empty list of previous versions, and the platform merges the served catalog's history into the rows when the publish begins. An unchanged entry keeps the date it first appeared. A changed entry that carries a version gains a stored row for the version it replaced. A versionless entry gains none and keeps the date it first appeared, and a stored row naming no version is dropped at the next merge.

A `list_library` call naming what the caller holds is answered per entry as current, newer, withdrawn, or not held, the comparison made server-side rather than by every consumer separately. Each held item names the content hash its manifest row records, and that hash is compared with the served closure hash. A held item that names no hash is compared as not current and answered `newer`. A served entry the caller does not hold — no `installed` item of its name — is answered `not_held` without a comparison, so a consumer never mistakes an entry it never took for one whose publish moved (SPM-L0-49; Q-235; MAPI-02 records the enumeration's widening). Two calls answer fewer `not_held` rows: one carrying `held_only: true` answers none, and one carrying `contains` answers only those its text matches.

**A call carrying `held_only: true` answers the caller's own entries alone.** With `installed`, it answers only the entries the caller holds, current, newer, or withdrawn, each row whole with its supersession list. So a proof of a fetch or an update's compare reads its own entries and not the whole inventory. A `held_only: true` without `installed` names nothing to keep and is refused `invalid_request`.

**A call carrying `contains` answers the rows whose name or summary holds its text, ignoring case, and every row `installed` names.** The filter narrows only the rows the caller does not hold, so a held entry's `newer` or `withdrawn` standing is never hidden. An empty or absent `contains` narrows nothing.

What a client does with that answer is the client's: any tool holding the project's own record of what it holds can offer to take the newer version, and no statement here obliges one.

LC-07: A project's library folder carries `manifest.json` at its root, and that file is the record of what the project holds. One row per entry, each carrying the entry's name, the version held, the content hash of its whole closure, the commit it was published from, and when it was fetched. The folder records every entry the project holds, the packages whose compiled runtime modules ride inside their entries included, because the vendored copy is the one consumption mode (SPM-L0-49; Q-235).

**The hash is what makes the folder checkable rather than merely present**: `validate` rehashes each entry against its row and names any whose bytes have moved, which detects file changes against the locally recorded hash under SPM-L0-49's read-but-never-authored rule. The commit records which publish the bytes came from, so a holder can trace an entry back to the library source that produced it without the server's help. Only the turnzero-cloud command's `library take`, which the served installation and update skills run, writes the manifest, recording the files it installs (PLD-L0-100).

Local validation checks manifest form, listed-entry hashes, and unnamed entry folders; it does not authenticate the manifest’s version, source-commit, or fetch-time claims against a publication. Coordinated changes to entry files and their recorded hash can pass local validation. Compare installed entries with the published catalog through `list_library` under LC-06 when checking publication currency. Its machine form is `schemas/library_manifest.schema.json`, which holds the shape and no project's rows; this document states the rules and repeats none of them.

**A library source carries no manifest, and that is not a folder in breach of this rule.** This statement's subject is a folder a project holds — bytes fetched from a publish — and the manifest is the record of that fetch. The library's own source is what a publish reads rather than a copy of anything, so it has no fetch to record and carries none. The `validate` MCP tool with `kind: "library"` refuses it by name rather than reporting it as a vendored copy (SPM-L0-49) in breach, and the kit's conformance load treats it as unmeasured rather than untrusted.

**The check runs in both directions**: an entry folder the manifest does not name is reported beside an entry whose bytes have moved, because deleting a row must not silence the check for that entry. **And a manifest that does not read refuses rather than passing**: a row that is not an entry is reported as malformed rather than raising past the caller. A `manifest_version` this reader does not know is refused rather than read best-effort, on MAN-01's rule that a reader guessing at a format it does not know silently drops what it did not understand.

LC-08: **The publish record in the publishing clone.** After the server answers the commit phase, the publisher sets the git ref `refs/mark-one/library-published` in the repository it published from to the commit it published. The publisher then pushes the same ref to the origin remote. The repository so holds the last published commit without a tree write, and every linked worktree of the clone reads one value. FTR-L0-101 states the rule the family audit enforces from that ref.

A dry run and a refused publish set nothing. A push that fails leaves the local ref set, and the publisher reports the failure in its output and never as a refusal, because the publish itself has already succeeded. A local ref that cannot be set is reported the same way. The ref is a record and not a gate. The server's own refusals (LC-04) read nothing from it, and a clone without the ref publishes on the same terms as one with it.

LC-09: **The platform reads the library source and holds no vendored copy.** Turn Zero Cloud publishes the library (LC-01; Q-239) and operates the services its backend packages specify. Its processes compose those packages' reference modules from the library source in this repository as their own implementation. At this revision those modules are the account package's session token module, Node.js Runtime's boot module, and the logging package's client, each imported from the package's reference folder in the library source. A platform release carries the source at its build commit.

Turn Zero Cloud therefore holds no vendored copy and no instance file for a package whose service it operates (Q-239; kit:SPM-L0-49; system:FTR-L0-16), and each such package's statements bind the platform as the service's implementation, system:LGS-L0-16's in-process rule among them. Every consumer, the first-party applications included, consumes as kit:SPM-L0-49 states: a vendored copy of the entry, whose compiled runtime modules the consumer copies into `app/lib/` as a `file:` dependency and imports by name (Q-235).

A change to a reference module a consumer also runs reaches consumers by the next publish (LC-04; LC-08) and their takes, on the package's version grade (system:FTR-L0-100). So the platform may run source ahead of the served version between publishes, and the package contract's compatibility rules govern the served service against a consumer's held client.