# packages/library Reads a writing repo by a mapping of folders to books, types, canon and playground. This is Case 2 row C2-01 (`docs/plans/2026-10-20_case2-rows.md`), built from design sections 1.1 to 1.3 and 7.4 in `agents/gosalyn/work/case2/DESIGN.md` on `gosalyn/case2-design`. It is pure code with no state. Business file loading (C2-04), sync (C2-03a), the index (C2-05a) and the guard (C2-06) build on it. ## Mapping `checkMapping(entry, where, { fail })` checks a `kind: "library"` project entry and returns a deep-frozen copy. `where` names the entry in messages. `fail(code, message)` defaults to throwing a `LibraryError`. C2-04 passes its own so a business file refusal carries the file name. ```json { "kind": "library", "remote": "https://git.example.invalid/her/books.git", "branch": "main", "user": "books-bot", "vaultPrefix": "books", "types": { "Characters": "character", "Places": "place", "Research": "research" }, "manuscript": ["Chapters"], "universes": { "harbor": { "name": "Harbor", "books": ["Book One"], "playground": ["Book One/Playground/"] } } } ``` - `remote` is https with no credentials, query or fragment. `branch` is a plain ref name. - `user` is the bot account name from design step 3, required for sync. It is optional in the mapping and checked with row 199's account name pattern, `[A-Za-z0-9_.-]`, 1 to 100 characters. - `vaultPrefix` is optional, one folder name. - `editor` is optional, exactly `{ "name", "email" }`: the ident her Console saves commit under (C2-01d). Each value is text that is non-empty after trim, with no control character (`U+0000`-`U+001F`, `U+007F`-`U+009F`), `<` or `>`. It comes back only when given. - `types` maps a folder name to `character`, `place`, `research`, `tracker` or `summary`. `manuscript` lists folder names and shares none with `types`. - A universe has `name`, `books` and `playground`. A hybrid adds `kind: "hybrid"`, two or more plain-universe `sources`, `constraints` (each one `{ "exclude": ... }` or `{ "pin": { "entity", "field", "value" } }`) and `notes`, and may have `books: []`. A draft universe has only `kind: "draft"`, `name` and one or more `playground` prefixes, and comes back as `{ kind: "draft", name, books: [], playground, supporting }`. `kind` is absent, `"hybrid"` or `"draft"`. - A playground prefix ends in `/` and has one of three levels (C2-01c). Book level lies inside one of its own entry's book folders. Universe level, in a plain universe or a hybrid, lies outside every book folder. A draft's prefixes all lie outside every book folder. No prefix holds another or is listed twice, across every entry. - Every universe kind may also have `supporting`, a list of prefixes where agents may write (C2-01d, M12). It comes back on every universe, `[]` when absent. A supporting prefix follows the playground's rules: it ends in `/`, has the same three levels, holds no other supporting prefix and is listed once, across every entry. - Between the two lists: a supporting prefix may equal a playground prefix of its own entry, and a playground prefix may hold one of its own entry's supporting prefixes. A supporting prefix may not hold a playground prefix, which scope would then never reach, and may not equal, hold or lie inside another entry's playground prefix. Refusals: | Code | When | |---|---| | `library-playground-other-universe` | a playground prefix lies inside, or holds, a book folder of another entry | | `library-supporting-other-universe` | a supporting prefix lies inside, or holds, a book folder of another entry | | `library-mapping-invalid` | any other shape fault: unknown key, bad remote or branch, an unknown `kind`, a book folder in two universes, a book folder that holds another, a playground or supporting prefix that holds another of its list or is listed twice, a prefix equal to a book folder or holding its own entry's book, a supporting prefix that holds a playground prefix or overlaps another entry's, a bad `editor`, a draft with `books` or with no prefix, a hybrid source that is unknown, a hybrid or a draft | ## Scope `classify(mapping, path)` decides scope from the path alone. Only paths ending in lowercase `.md` are mapped. It checks prefixes first, supporting before playground. A path under any entry's supporting prefix is `supporting`, and otherwise one under a playground prefix is `playground`. Either way that entry is `universe` and the book folder holding the prefix is `book`, or `null` at universe level and in a draft. Any other path under a book folder is `canon`. Everything else is `unmapped`. The type is the first folder after the prefix, or after the book: a `types` name, `manuscript`, or `null`. ## Agent write paths `supportingPath(mapping, universe, path, tree)` returns `path` when an agent may write it in that universe, else it refuses `library-write-story-path` (C2-01d, M12). `tree` is the array `listTree` returns for the commit the write lands on; anything else is a TypeError. It reads no git. The checks run in this order, so a path with two faults always names the same one: 1. a string of at most 1,024 UTF-8 bytes; 2. no control character (the `editor` class), and the message leaves the path out; 3. no backslash; 4. not absolute; 5. no empty, `.` or `..` segment, which also refuses `//` and a trailing `/`; 6. `classify` gives `supporting` in that same universe, which refuses unmapped, `.canvas`, `.base` and attachment paths, canon, a playground-only folder and another universe's prefix; 7. no folder on the way, and not the path itself, is a symlink (`120000`) or gitlink (`160000`) in `tree`; 8. no folder on the way, and not the path itself, matches a tree path or tree folder after `normalize('NFC').toLowerCase()` unless it is that exact name. APFS folds case and Unicode form, so her checkout would put the file somewhere else. A tree that already holds case twins refuses a write to either (R7). A delete's further rule, that the path exists at the tip as a `100644` blob, belongs to the C2-02 broker. ## Reader `readLibrary({ repo, commit, mapping })` reads one commit, never a working tree. `repo` may be a clone or a bare mirror. `commit` must be a full 40-hex id that names a commit, else `library-commit`. Git runs through `git()` and `gitBytes()` from `packages/project/src/git.mjs`, so the same safe config, environment and ceiling directory apply. A failed git call refuses `library-git`. It returns `{ commit, files, problems }`, deep-frozen and sorted. Each file has its path, scope, universe, book, type, numbered lines, `bodyLine`, parsed `frontmatter` or `null`, `frontmatterRaw` and `links`. Front matter `appears_in` and `relationships` wikilinks count as links. A link in a block list carries its list item's line. One in a scalar or flow value carries its key's line. Problems carry `{ code, path, line, message }`: | Rule | Meaning | File indexed | |---|---|---| | R1 | not a regular `100644` blob of at most 1 MiB, or not UTF-8, or holds a NUL | no | | R2 | path is unmapped | no | | R3 | front matter not fully parsed, `line` is where parsing stopped | yes, front matter kept raw | | R4 | link resolves to no file or to more than one | yes, link dropped | | R5 | canon file links into the playground | yes | | R6 | canon file links into another universe, a hybrid's sources excepted | yes | | R7 | two paths differ only in case | no, neither | The front matter parser takes scalars, quoted strings, flow lists, block lists and wikilinks. Nested maps, anchors, block scalars and duplicate keys stop it with R3. ## Links `resolver(paths, { vaultPrefix })` tries four steps in order, each with the target as written and then with `.md` added: 1. `root`: the path from the repo root. 2. `vault-prefix`: the same path with `vaultPrefix/` stripped. 3. `relative`: relative to the linking file, never above the repo root. 4. `shortest`: a target with no `/` that matches the base name of exactly one indexed file. It resolves only against indexed files. A link to a `.canvas` file or an attachment is R4. A link into another repo resolves to nothing. `extractLinks` skips fenced and inline code. A `![[...]]` embed resolves like any link. A body embed that resolves to nothing and whose target ends in an extension other than `.md`, in any case, embeds an attachment, and it is never R4. An extension is a dot and up to 8 letters and digits, at least one a letter. Any other unresolved embed is R4, and so is an unresolved front matter value written as an embed (C2-01b N3, sage-1900). ## renderItems `renderItems(body, { scopeOf, changed })` turns a reply body into the plain text both channels show. It is pure. Item kinds are `fact`, `finding`, `correction` (with `from` and `to`), `question` and `idea`. Each cite is a path with commit, line range and quote, or a url with a quote. ``` 1. Correction: Chapter 1 says grey. From: "green eyes" To: "grey eyes" [canon] Book One/Characters/Mara Vell.md:9 @bbbbbbb "green eyes" (changed since) ``` A body of `{ "items": [], "notice": ... }` gives `No cited answer`, `No answer` or `The turn failed`. Any other shape gives the fixed line `This reply could not be shown.` and none of the body's text. ## Survey ```sh mosaic library survey [--mapping ] ``` It reads the repo's HEAD commit and prints folder names, file counts by extension, front matter key sets, link-form counts and the count of body embeds whose target has an extension other than `.md`, which still count as embeds. That count goes by the name alone, so an embed of `Dr.Quinn.md` written `![[Dr.Quinn]]` counts there too. Folder names print as JSON strings, with DEL, C1 and bidi controls, U+061C among them, also as `\uXXXX`. It never prints file text, front matter values, file names or link targets. A key that is not a short identifier prints as `(other key)`, since it could be her words. With `--mapping` it adds scope counts, resolver step counts and problem counts by rule. Exit codes follow `packages/project`: 0 done, 2 the repo can't be read (`library-git`, `library-commit`), 3 a bad mapping, 4 usage. `scripts/mosaic` sends `library survey` here. Other library verbs will be bus verbs. ## Sync `sync(context, { slot, accept })` (C2-03a, design 7.2) fetches the entry's `branch` from its `remote` into `refs/remotes/library/` of the C2-04 mirror, then publishes under the library lock: | Fetched tip | `served` | State | |---|---|---| | a fast-forward, or the first sync | moves to the tip | `problems` rebuilt from the tip | | the served commit | stays | `lastFetch` set | | not a fast-forward | stays | `diverged` holds the tip, `library-diverged`, until `accept` | | fetch failed, slot missing | stays | `lastError` holds `library-fetch-failed` or `library-credential-missing` | `lastFetch` is the last fetch that succeeded. Once diverged, `served` stays put until a human runs `library.sync` with `accept` set to the fetched tip, even if a later tip is a fast-forward again. A tip back at the served commit clears it. A stale `accept` refuses `library-accept-stale`. `accept` also starts the state over, so it is how a changed `branch` gets a fresh record. An entry with no `user` refuses `library-remote-invalid` and runs no git. `syncCommand('fetch', url, { mirror, branch, user, slot })` gives the one argv and env. The argv is `SAFE` from `packages/project/src/git.mjs`, then `-c protocol.https.allow=always -c http.followRedirects=false -c credential.helper= -c core.createObject=rename`, then `-C ` and the fetch. `core.createObject=rename` is there because git's default files an object by link then unlink, and a reader's mirror check refuses a file with two links. The env is `gitEnv()` with `LC_ALL=C`, `GIT_ASKPASS` naming `bin/askpass`, and the host, user and slot path. The helper answers only `Username for 'https://': ` and `Password for 'https://@': `, the second from the slot's first line, and exits 1 on any other prompt. Sync checks that the slot is a private regular file and never opens it. The token is in no argv, env, URL, config or log. Sync never runs gc or prune. A file read takes `served` under the lock and reads its objects after it lets go, so an object must outlive the next move of `served`. The bus host runs `sync` for every entry with a `user`, once at start and then every 60 seconds; the slot is `/secrets//library-gitea`. `library.sync` is the human's bus verb for the same. The human transport (`packages/bus/src/human-cli.mjs`) waits 130 seconds for `library.sync`, past the server's 120-second hold, and 5 seconds for every other verb. A client that gives up before the answer gets `outcome-unknown`, but the sync keeps running: a second call meanwhile gets `library-sync-busy`, and `library.status` shows the result once it ends. A sync that outlasts the 120-second hold gets `request-timeout` from the server and still finishes the same way. The Console has no library route yet: `cli.mjs` passes `librarySync` to `startServer`, and `serve.mjs` doesn't read it. ## Tests ```sh node --test packages/library/tests/ ``` Fixtures are made-up repos built per test in a temp dir. A marker string stands in for her text, and the survey tests check that it never appears in output.