Beth’s Library System (and AI Multi-Agent Chat)

Minimum Implementation Spec, v1.1

Consolidated from design sessions of Sept 3-4, 2026. Two provenance classes are distinguished throughout: RULED (Beth decided it) and PROPOSED (engaged in conversation, not ratified; requires her decision before build). Open decisions are listed at the end and belong to Beth.

---

0. Constitution (one sentence)

Humans govern, agents propose, code writes, the record remembers.

Standing principles agreed throughout, enforced by construction, not policy:

• Models propose, code writes. No model ever holds a pen, copies bulk text, or supplies a timestamp.
• Annotation, never obstruction. Nothing gates the flow of work; watchers comment after.
• Append-only. Nothing is overwritten; corrections supersede; deletions tombstone.
• Anti-echo: every layer is checked by something that cannot share its failure mode.
• Untyped-but-true beats precisely-wrong (edges, notation, metadata alike).
• Ruler questions get ruler answers: anything checkable by code is checked by code, zero tokens.

---

1. The record (one git repository)

Species roots, separable along the privacy seam:

• transcript/ verbatim turns, byte exact, written by backend before any model runs. Private. Real encryption at rest; keys held by backend and owner; every decode is a logged event.
• store/ source library. PDF preservation masters plus markdown access copies (code-extracted, frontmatter: source hash, extraction tool and version, date, identifiers, species). Read-only at file-permission level; backend flips writable only during its own writes.
• map/ edge files (see section 2).
• artifacts/ drafts, review packets, exports. Reliance edges point from these to sources (blast-radius queries on supersession).
• Root governance files: legend, registry (node codes, aliases, Dewey numbers), roles, templates/, plus MIGRATION.md, README (cold-start), proposals/, findings.

Mechanics:

• Every turn and event: file write, then git add, git commit, machine-executed, before or immediately after the moment it records. Commit metadata: turn number, actor, timestamp.
• Actor field on every event and commit from day one. Git pushes from Beth’s account; the actor field records who or what actually spoke (human or role name).
• Reason field mandatory on every mutating commit, any actor, validator-enforced. (rev 2)
• IDs, never paths. A source’s identity is its content hash. manifest maps ID to current path, aliases (old filenames preserved forever), work-vs-copy structure (work, then expression by language/modality, then file), and tombstones (work existed, removed on date X, because Y). Edges resolve to tombstones rather than dangling.
• Relative paths only inside the record; machine-specific config lives outside the library.
• App independence covenant: everything readable with ls, cat, and any git client. The app is a patron of the library, not the building.

2. The map (v2 dialect)

Canonical form: the edge is the tuple (node, operator, node, mechanism, provenance pointer). The tuple’s normalized serialization has a structural hash; that hash is the edge’s identity. Every readable form is a registered rendering (render/v2-dialect is renderer number one). This is the forward-compatibility root.

Edge law: the mechanism (the “because”) is mandatory. No mechanism, no edge.

Filename grammar (ASCII-armored, all platforms): SEQ _._ TIMESTAMP _._ x--HEX .txt

• SEQ: digits, insertable segments (0014, 0014-50), unique forever, only field a rename may touch (repositioning). Joiner character: open decision (hyphen vs tilde for raw-ls sort order).
• TIMESTAMP: YYYYMMDDHHMMSS, machine-stamped from the turn’s receipt time. Models never supply timestamps; supplied ones are ignored, not merely checked.
• x–HEX: lowercase hex of the NFC-normalized UTF-8 dialect string. NFC normalization mandatory at write time. 240-character filename cap, refused with guidance (detail belongs in the body).
• Body: line 1 shebang ⟦map:v2:zh⟧; line 2 dialect string raw (what models read, native speed); line 3+ provenance pointers (session, turn, line range) into the verbatim record.

Dialect: hanzi plus tested math symbols plus ASCII. Legend carries three columns per operator: notation, filename/ASCII code, word fallback. Symbol set is chosen empirically per provider tokenizer (one-hour test); every symbol keeps an ASCII fallback. Mechanisms may be hanzi (density) or ASCII-hyphenated (precision). ⟦ ⟧ marks an in-string code shift in any other text.

Legend v1 draft (pending Beth’s final approval): ≅ isomorphic (symmetric, non-transitive; verify: map mechanism, find where it breaks) · ⊂ subset (transitive) · ∈ element (directed) · → causes (directed; demote to ~ if mechanism won’t trace) · ~ correlates (explicitly non-causal) · ⊥ orthogonal · ≠ contradicts (both ends open until supersede) · ∅ examined-and-non-contributory (record the exam) · ⇒ supersedes (target is a SEQ; append-only correction) · ◁ transposed-from (directed; name the key change) · RT related, the honest default. Pending additions Beth agreed to in principle: INVERSE_OF; a proposed-by/source-outside-the-loop provenance marker.

Registry: short letter codes for nodes (e.g. cw), aliases, hanzi forms, Dewey number per subject. Collision-unique, human-gated. Dewey numbers are never model-recalled; models propose the subject, the registry supplies the digits. Filenames hyphenate DDC dots (133-324); registry and frontmatter keep true dotted form.

Shelving vs catalog: coarse Dewey bins as physical folders (one home per file); everything fine-grained and multi-subject lives in edges pointing at manifest IDs. Reclassification is a map event, not a file move.

Map authorship: humans never hand-author map files (validator: an edge whose provenance pointer does not resolve fails at the gate). Humans influence the map by speaking in-session; humans govern it via legend, registry, and approvals. RULED.

MAP ORGANIZATION: SUSPENDED, UNDECIDED. What is ruled above covers the edge unit, the grammar, the dialect, and map/ existing as its own isolated top-level folder (Beth’s requirement). How the map is organized internally was never decided and must be, before build:

• Internal layout of map/ as it grows vast: one flat folder, or sharded (by seq range, by session, by Dewey region, or otherwise).
• Seq scope: one global sequence forever, or per-session/per-project sequences. (Raised once, never ruled; SUPERSEDES targeting and the insertable-adjacency property both depend on this.)
• Relation of sessions to the map: one map for everything, or per-project maps with a shared registry.
• Whether and how the spatial-adjacency property (post-its near what they relate to) is expressed in organization rather than only in seq insertion.

Opacity layers: hex armor on the judgment/personal map layer is an intent gate (decode is one deliberate command; the act of decoding is the consent event). Real cryptography is reserved for transcript/ and designated private roots. Opacity is asymmetric by ownership: the owner renders any slice to English on demand, and each render is logged.

Subject-notify rule: models are data-agnostic clerks; fidelity outranks fondness. A discrepancy in a known person’s data grants exactly one power: notify that person. Only the subject corrects their record, or leaves it, with reason. Agents never unilaterally edit a human’s entry.

3. Roles, bindings, templates, sessions

Role = contract, defined as data in the roles file: function, context assembly rule, output contract, permissions. Validator refuses events from undefined roles. Roles are model-agnostic.

Binding = role to provider + model string + prompt variant. Provider adapters normalize call shapes (Anthropic first; OpenAI-class second). A ported persona (e.g. Astra) is a re-instantiation from records: system prompt plus exported memory; stated honestly as a new expression of the same work.

Default roster (template v1 defaults, all rebindable):

• Performer (default Opus): drafts, converses, decides when to call consult_research.
• Librarian, closed-book (default Fable): answers only from retrieved passages, cites source IDs; “the retrieved material does not address this” is a valid return.
• Verifier (default Fable): scores each performer reply against the store; rubric anchored in its system prompt; percentage rendered under the message; comment only when low. Verification mode and review-packet-preparation mode never share a prompt.
• Scribe (default Sonnet): proposes map edges (nodes, operator, mechanism) per turn. Proposes only; backend assembles filenames, stamps time, writes.
• Auditor (default Sonnet, different prompt): staggered N turns behind; checks map accuracy (does every edge correspond to real text) and recall (what did the scribe miss); recall is weighted.
• Commentator class (the gallery): read-only on the rendered conversation, annotate-only output, own visual lane, multiple seats, deliberately cross-provider for diversity. Zero write path.

Templates: named, versioned config files in templates/: seated roles, default bindings, cadences (scribe every turn; auditor stagger), thresholds (verifier comment floor, badge spike interrupt), context policies. Session start instantiates a template; binding overrides recorded in the opening commit; mid-session rebinding is a reasoned config commit. Sessions outside any template and new templates are both permitted. Template concept encodes one-cognitive-mode-per-session (fact-pass, edit-pass, collection-leg, brainstorm variants anticipated).

Permissions: two tiers. Standard (propose-text, propose-edges, propose-verdicts, annotate) available to any role. Privileged (write, execute) exists in the schema but is inert without a live grant: grants are owner-issued events with scope, duration, and reason; revocable; expiring by default; never template-inherited (template requests pause for the human); never transitive. Governance capabilities (approving roles, legend, registry, templates; issuing grants; deletions) exist only on human administrator accounts and are inexpressible for agents. Ruled: approval is never delegable. Optional enterprise dial, listed only: two-person rule on governance commits.

Proposal machinery (operators, nodes, roles, and future capabilities): proposal file in proposals/ with the contract/definition, motivating evidence (SEQ numbers), and why existing items don’t fit; duplicate-proposal check against pending and rejected; separate action-required counter next to the audit badge; owner approves (item lands, interim CONNECTS edges get superseding retypes) or rejects (file stays, marked, with reason; rejected list prevents resurfacing).

4. Turn lifecycle: PROPOSED ASSEMBLY, NOT RATIFIED

What a turn actually is has not been decided. The five-step sequence below is a proposed assembly of individually discussed parts and requires Beth’s ratification or redesign before build.

Component rulings that ARE Beth’s, wherever the final turn shape lands:

• No gatekeeping: the reply is never held for review; watchers annotate after. RULED.
• Truthfulness percentage rendered under each performer reply; comment only when low. RULED (her design).
• The verbatim record is code-written before any model runs; no model records. RULED.
• The performer runs the show; the librarian passes research silently; the verifier interjects only when correction is needed. RULED (her stated shape).
• A scribe layer builds the map as the conversation proceeds; an auditor checks it. RULED.
• Badge counters for findings (reset on log open, timestamps kept, spike interrupt) and for proposals. RULED.

Proposed and awaiting her decision:

• The five-step sequence itself (commit, performer call, mid-draft research, render, async watchers) as THE definition of a turn.
• What counts as a turn: one user message plus one performer reply, or something else; whether she can address any role directly and what that does to the cycle.
• Commit boundaries: per message, per exchange, or otherwise.
• Collapsed-expandable rendering of tool calls; placement and form of scores, badges, and gallery lanes; everything about what she sees. (All UI is hers.)
• Cadences as defaults: scribe every turn, auditor staggered N.

Per-call context manifest (rev 2): every model call logs its recipe: turn ranges, map files, retrievals, prompt version, plus codec name and version once the codec slot exists. No copied text, pointers only. RULED.

Badges and logs: audit findings increment a counter; opening the log resets it; entry timestamps are kept so rate is always reconstructable; configurable spike threshold converts the badge into an interrupt (may start disabled). Salvage log: retrievals returned but unused by the draft are logged. Override log: proceeding past a low verifier score is logged. All append-only.

Anti-lazy law: no model is ever asked to reproduce bulk text anywhere in the system; excerpt and packet assembly is by manifest, code-copied, byte-checked against the record.

5. Intake and services (code only)

Drop zone, not Downloads (ingestion is an intentional act; consent by placement). One path: drop zone to local repo store; hash, manifest, commit before any second copy exists; the mirror carries it outward afterward.

Intake ladder, cheapest rung wins, delete never an output:

1. Byte hash: exact duplicate detected, logged, skipped.
2. Filename-as-identifier: arXiv IDs, DOI suffixes, ISBNs, SSRN/ACM/publisher patterns resolved without opening the file.
3. Embedded and first-pages text: DOI/identifier regex; frontmatter agreement check for captured sources.
4. Book rung: calibre command-line metadata fetch (title, author, ISBN) for the book corpus.
5. Model proposal: a Sonnet reads a sample and proposes title, authors, year, venue, species, subject edges; code performs the rename and filing; new-node proposals go through the approval gate.
6. Quarantine: needs-review folder plus badge. Never a guessed name.

Also at intake: two-level dedup (byte identity and work identity via DOI); species detection (paper, preprint, book, standard, regulation, report) feeding naming and frontmatter; content verification (flag paywall/landing pages saved as papers; empty text layers route to OCR with the fact recorded, or to review); genre and topic checks flag, never block (topic = grep against registry and aliases; zero-match files ingest wearing a “new territory or stray” flag). Check-before-acquire: collection legs query holdings (DOI, title, hash) before fetching; duplicates return “already held, batch, date.”

Old-name preservation: every prior filename becomes a manifest alias.

Night crawler, scheduled, zero tokens: existence, placement, and hash of everything against the manifest. Moved: heals the manifest path, logged. Untracked: routed to intake. Altered: alarm with git context attached. Missing: dated finding with evidence. Findings dispositions: fixed (crawler verifies and closes), investigate (stays open), expected (permanent silence with one-line reason, keyed by ID plus issue type; a silenced issue never re-alerts; a different issue on the same ID still does). Deletion as workflow: delete, crawler notices, owner acknowledges with reason, manifest entry becomes a tombstone, git retains the bytes.

Backfill jobs (one-time, then steady state): manual triage of existing Downloads into the drop zone; the book library backfill (the WeLib corpus) through the book rung, in its own root with its own mirror-scope decision.

6. Copies, portability, forward compatibility

Three copies, three jobs: working repo on the PC (live); private git remote (full history, disaster recovery, the collaborator door); Drive mirror, one-way on a schedule (rclone-style), shareable species only, transcript never mirrored, repo never placed inside a sync client’s folder. Chat-side agents read the mirror, never the original.

Restore drill: run the crawler against a fresh clone; a move or restore is done when the crawl passes, and the drill is rehearsed annually.

Large binaries: git-lfs vs hash-verified external store is an explicitly flagged build decision.

Forward compatibility (the QWERTY vaccine): canonical tuples with structural hashes beneath every rendering; renderer registry with the current stack as render/v2; conformance suite in tests/golden/, stated as tuples-in, behavior-out (any future implementation in any language proves itself by reproducing the golden pairs byte-exactly); codec slot in the context-assembly layer with codec+version recorded in the manifest; a fidelity harness of adjacency-dependent canonical queries as the acceptance gate for any future compression protocol.

MIGRATION.md, drafted now, executed whenever a successor substrate arrives: (1) copy, full clone, original untouched; (2) verify the copy, crawler fixity pass; (3) translate, new renderer walks the tuples; (4) confirm, three independent instruments: structural-hash round-trip, conformance suite, behavioral parity diff; (5) sweep for the missed, reconciliation diff of full inventories, discrepancies as dated findings, fixed forward; (6) parallel run, both systems receiving every new deposit, sweeps recurring, exit defined numerically (N consecutive zero-finding sweeps, N set by the administrator), expected duration years; (7) archive the old as a system-scale tombstone: sealed, hash-manifested, superseded-by recorded, retained forever as the parallel text that lets any future mind re-verify the translation. Migration is a governance act, human-administered end to end; the trigger clause: the moment a candidate format passes the conformance suite, an evaluation is owed.

7. Existing artifacts (already built and tested this session)

• mapname.py: standalone tool, no dependencies. new (NFC-normalizes, hex-armors, machine-stamps, refuses duplicates and over-length), read (the decoder ring; numeric seq ordering), check (grammar, decode, NFC, shebang, body-matches-name, seq-unique; findings not fixes; real exit code). Tamper test passed.
• legend.txt: draft treaty file (shebang, grammar, operator table with notation, ASCII codes, properties, verification instructions, consent-and-fidelity clauses).
• beths_library_system_map.html: the catalog card, rev 2.1, house typography (Atkinson Hyperlegible Next body, Roboto Serif headings, mono reserved for literal paths, the stamp, and rev tags).
• Design considerations audit (Reddit replies): both upgrades incorporated as rev 2 items above.

8. Decisions register

Settled by ruling this session:

• No gatekeeping; verification after render.
• Approval never delegable; governance is human-administrator-only.
• Timestamp granularity: seconds; name carries the turn’s receipt time; git carries the mapping time.
• Never overwrite; corrections supersede; deletion via tombstone.
• Verbatim record is code-written; second Sonnet audits annotations, not bytes.
• Hex is identity/transit armor, never the meaning layer; meaning rides pre-installed vocabularies.
• Python for tooling, dull on purpose; the system is the design, not the language.

Open, Beth decides (explicitly reserved):

• Map organization, in full: internal layout of map/, seq scope (global vs per-session), session-to-map relation, spatial-adjacency expression. SUSPENDED pending decision.
• The turn, in full: ratify or redesign the proposed lifecycle; what counts as a turn; direct address of roles; commit boundaries; all rendering and UI.
• Interface stack (local web app vs other).
• Runtime: raw Messages API vs Agent SDK backend (control vs included programmatic credit).
• Seq joiner character (hyphen vs tilde for raw-ls ordering).
• Auditor stagger N; verifier comment floor; badge spike threshold and whether it starts enabled.
• git-lfs vs external binary store.
• Migration exit metric N.
• Legend v1 final approval; INVERSE_OF and the outside-the-loop provenance marker, formally.
• Book library root and mirror scope (which shelves face the street).
• Template roster v1 contents (which templates exist at launch).
• The two rev-2-adjacent choices already flagged: none remaining; both incorporated.

9. Inputs to hand the build session

This spec; mapname.py; legend.txt; the catalog card HTML; context_window_memory_design_summary.md (from the Sept 3 session outputs); the source-library-capture skill (already installed) as the MD-sibling format; Beth’s decisions on the open register above, as they land.