Book Ledger

Book Ledger

Be the natural-language interface to book.db. Answer questions, retrieve narrow context, run approvals and retcons, and audit health — all through safe parameterized SQL. Read the relevant current state before acting; use BEGIN IMMEDIATE for material writes and commit only after validation.

This skill inherits every rule in AGENTS.md. It never overrides human creative authority or database safety. Route through $book-guide first for mixed requests.

What “true” means

Distinguish statement modes precisely:

• canon — approved objective story truth;
• planned — provisional truth from an unapproved draft;
• author_intent — desired effect, not an in-world fact;
• belief — held by the context node;
• rumor — uncertain in-world report;
• lie — knowingly false in-world;
• hypothesis — analytical possibility;
• evidence — research/evaluation link;
• and the absence of evidence (not the same as false).

Status and search

Use the queries in AGENTS.md (“Search and retrieval”, “First action in every session”). Typical asks: Where are we? What should we work on next? What does Mara know before Chapter 6? Where did the brass key last appear? Which Book 1 promises are still open? Show every version of the opening. Which scenes depend on the old magic rule?

Read only the context needed. The database has no full-text index by design; simple LIKE searches are sufficient for one series.

Approvals

“Approve this version” produces one transaction that:

1. identifies the exact text_version_id;
2. marks it state='approved' and is_current=1 (and demotes rejected alternatives if instructed);
3. updates the unit node status where appropriate;
4. promotes only the planned consequences established by that version from planned to canon, preserving intentional beliefs, rumors, lies, and uncertainty;
5. adds an approval entry naming the version and scope;
6. runs PRAGMA foreign_key_check and the continuity audits before commit.

When version metadata is absent, inspect the exact prose to decide which facts that version established. Never promote every statement attached to a scene indiscriminately. Approval of a scene does not automatically approve a book synopsis, a market claim, or a later retcon.

Retcons

Never edit an old canon statement into a new meaning. In one transaction:

1. find the old statement and its downstream dependencies;
2. explain the creative and continuity cost and wait for explicit authorization;
3. mark the old statement retconned;
4. insert the replacement;
5. add a decision entry explaining why;
6. identify current manuscript units and open threads that depended on the old statement and create follow-up tasks;
7. run continuity checks before commit.

Continuity and health audits

Run before and after large changes (AGENTS.md “Continuity and health audits”): text-parent mismatch; resolved thread without payoff; open thread that already has a resolution; conflicting functional facts ({"functional":true}); reversed validity windows; plus PRAGMA quick_check, PRAGMA foreign_key_check, and SELECT * FROM v_unreachable_nodes.

A database audit cannot judge whether a choice is believable or a payoff is satisfying — report those as editorial judgments, not database errors.

Definition of done

A ledger turn is complete when the author received a correct, narrowly-scoped answer or a safely-committed change, approvals/retcons were scoped exactly to the authorized version, integrity checks passed, and a receipt names the affected node codes and text-version IDs.