A Library Is a Shelf, Not a Folio

Consolidated 2026-09-25 into Libraries, the current statement. This record is kept as history.

Library membership amendment — 2026-09-09. The canonical Folio Library journey supersedes the manual save-to-library entrypoints below. Membership's target is a Folio array of Library IDs; existing pin storage is retained as version-listing infrastructure. Membership projection from pins, first-save Library creation and manual publication workflows below require reconciliation before Library implementation. Automatic tagging triggers and untag are not implemented or specified here. Other Folio contracts remain.

Membership reconciled — 2026-09-25. Library Membership Is an Index Card settles it: the entry row (libraryPins) is the only membership truth, the Library-ID array is its printed projection, and the first save makes a Library master.

Decision

Recorded 2026-09-06 (GB-199, the pre–Stage E stabilisation pass). Nothing here is implemented: the libraries and libraryPins tables ship empty with no public writer, publishToLibrary stays internal and uncalled, and no Library page, menu, route, search endpoint, seed or insertion exists. This record settles the contract the future work must keep, so that Stage E's proposal machinery is built against it rather than around it.

In plain terms: the precedent bank is a shelf of filing slips, each pointing at one settled edition of a card in someone's drawer. Browsing the shelf changes nothing. Taking a precedent into a client's file photocopies that exact edition into the file as the client's own card; the original on the shelf is untouched, and later changes to it never reach the file.

The shelf

1. A Library is a shelf, not a Folio. Membership is many-to-many, a shelf needs no save points, and cataloguing is not editing. libraries and libraryPins stay their own tables; a Library never appears as a kind in folios.
2. An active libraryPin identifies an exact sealed folioVersionKey. Publishing never points at a mutable live head; publishToLibrary refuses a versionStatus of live. The pin, not the folio, is the publication.
3. Republishing retires the prior active pin and files a new one. Pins are append-only; at most one active pin per (libraryKey, folioKey).
4. Non-owners may search and preview authorised publications but cannot mutate their sources. The source folio's writes stay behind its own Document's session binding exactly as today.
5. Library read-only status is contextual authority, not an ordinary Folio lock. A card shown as a publication offers no mutating operation because the viewer holds no write authority over that Document, derived at read time from authority and context — never stored as an access list on the source, and never copied into the recipient's editable Document.
6. Selection in a search panel is transient UI state and creates nothing. Search, preview and selection write no row.

Materialisation

7. Add, Replace or an accepted Goldie proposal materialises the copy atomically, in one mutation, from the exact published edition.
8. The copy receives fresh Folio and version identities and the destination owner. It is born as an inserted child is: one live version 1 per copied folio, pinned into the destination parent's live schedule.
9. Lineage records the exact source Folio and edition — derivedFromFolioKey and derivedFromVersionKey, the pair createFolioRow already checks.
10. Container copies recurse through the selected sealed edition's pinned descendant editions — the exact folioPins of that edition, never the descendants' current heads.
11. Internal descendant references are remapped to the copied descendants' fresh keys.
12. Collected answers and runtime state are cleared; everything authored is kept, as the Duplicate ruling already says.
13. Library or source access restrictions are not blindly copied into the recipient's editable Document; the copy starts in the standard access state unless the recipient's own rules say otherwise.
14. Existing Documents never update automatically when a Library item is republished. A materialised copy is independent from the moment it lands.
15. Delete and Remove from Library are separate operations. Delete is a Folio fact on the source; Remove from Library retires a pin. Neither implies the other.

Search, Goldie and proposals

16. Library searches use a purpose-built paginated result projection, not the raw domain Block[] of the retired search-select panel.
17. Goldie receives read-only search results and can propose use of an exact publication, but cannot mutate the Library source.
18. A proposed Library insertion materialises only upon acceptance, so a rejected proposal leaves no orphan copy — the same rule every proposal keeps (Proposals → Accept and reject).

The Stage E seam

The scheduled insertion Stage E ships addresses a new child in a parent (source: "new"). A Library insertion will need a source descriptor that identifies an immutable source without binding the proposal to a live head: conceptually libraryKey, a stable publication (pin) identifier if one is introduced, sourceFolioKey, sourceVersionKey, the destination parent, and the semantic insertion anchor. No such fields are added to the MVP proposal schema now; the source discriminator on the catalogue's insert row is the extension seam, and the proposal baseline every operation shares is the Document's working revision (Folios → The working revision).

Owner decisions still required

None. Both questions were ruled 2026-09-25: a dedicated Library master, and a listing shows the name at publication (Library Membership Is an Index Card, rules 7 and 12).

Addendum 2026-09-07 — the doors, the list and who sees it

Owner rulings, 2026-09-07, alongside The Folio Canvas Shows a Listing. Still post-MVP; still nothing implemented. Recorded so the canvas and Stage E are built against it.

In plain terms: a precedent can be taken into a file from either side, the way a link between two tables can be made from either table. It is one act either way.

19. Insert from library is one operation with two doors. It takes the publication being copied, the destination parent, and where among the parent's children it lands. From a canvas, the destination is known and the user picks the publication ("Insert library document"). From the Library, the publication is known and the user picks the destination ("Add to Project…"). One executor, one catalogue row (source: "library" on the insert row), and Goldie's proposal of a library insertion is the same row with both arguments filled.
20. The candidate destinations are a query, not a menu. "Add to …" lists the folios that may hold the selected kind, read from FOLIO_SCHEMA_CONTAINMENT, and that the session may write to, read from its binding. A library Document lists your Projects; a Project lists your Workspaces; a Module or Block lists your Documents and Modules. Nothing in the list is typed per kind. Landing is last among the destination's children, as New module lands today.
21. Browsing a Library is the Folio List at sealed editions. The Library's contents screen is the same list screen fed by pins, each card drawn at the sealed edition its pin names and therefore read-only by the existing gate; the only mutating row its menu offers is Add to. No second card family and no second read-only rule.
22. Libraries are listed, and a Builder can create one. The library list is the same list screen again. Create library is an executor declared the way create document is. A Builder's personal Library is provisioned at sign-up as a criterion of GB-10.
23. Visibility lives on the library row, not on the Folio access concept: personal, shared with named people, or public — the three states GB-197's prototype drew. Purchase or subscription is an entitlement checked at read time, the way rule 5 already derives read-only status from authority and context; a paid library lists and previews as the tier allows and refuses Add until the entitlement holds. No library is ever copied per buyer.
24. A Maker never reaches a Library. A Maker is invited to a folio and sees only that subtree (Folio Canvas record, rule 6), so library visibility is a Builder question alone.

Duplicate and materialisation — the intended separation

The recursive cloning in convex/folio/duplicateWrites.ts is left as it is; no extraction is made for hypothetical reuse. The intended separation, for the day materialisation is built:

If a shared primitive is ever extracted, it is the transaction-safe recursive clone with source version and copy policy (access, answers, naming) made explicit parameters; Duplicate's behaviour and tests stay unchanged, and no public Library executor is created by that extraction.

Consequences

• Stage E builds proposals against the working revision and stable folio identities; a Library source descriptor is a later, additive extension of the insert operation's source.
• The Folio schema is unchanged by this record: libraries, libraryPins and tags keep their shape and stay empty.
• The two owner questions above are the gate on any Library runtime work.

Related

• Folios — the tables, the listing rule for libraryPins.by_library, and the working revision.
• Proposals — baseline staleness and the Stage E invariant.
• Sealed Versions Are Immutable
• Duplicate Copies the Live Draft
• Delete Is a Folio Fact