wanderbooks

swaits/wanderbooks

0 Fork 0

Commit Graph

Author	SHA1	Message	Date
swaitsandClaude Opus 5.5	535874e0f3	fix(cash flow): a payment to a government is other operating, by its payee The P3 cutover review's open point 2: a state's LLC filing fee, booked to an organization-costs account (tax category organization_startup), read as "Cash paid to suppliers and employees". B-14 rule 5 sent a payment to class (g) only when every operating line's account was taxes_licenses, so the account, not the payee, decided. ASC 230-10-45-17, read in EY's guide that reproduces it (Statement of cash flows, July 2026, p. 43; the PDF re-fetched and its SHA-256 recorded in docs/spec/sources/fasb-asc.md), lists apart "(b) Cash payments to other suppliers and employees for other goods or services" and "(c) Cash payments to governments for taxes, duties, fines, and other fees or penalties". 45-25's classes name only income taxes (f) among the latter, so the rest are (g), other operating cash payments. A formation filing fee is rightly an organization cost (its account and tax line), and still a payment to a government: the payee is what 45-17(c) is about. So rule 5 now sends a payment's government part to (g): of an operating payment the structure classes (d), what went to a party with the government_agency or tax_agency role (the chain root's parties, so a reversal keeps its original's class) is (g), on any account; and, as before, a payment whose every operating line is on a taxes_licenses account is (g). Every party a government: the whole payment. A government and a supplier named together: the payment is split by their resolved shares (B-35), the government's part (g), the rest (d), since ASC 230-10-45-22 has "each separately identifiable source or each separately identifiable use" classed "on the basis of the nature of the underlying cash flows" (EY p. 44; quoted in fasb-asc.md; it names the three activities, read for 45-25's classes too as a CONVENTION). The government's part is the payment x its share / the whole, rounded half to even to the base currency's places, the rest exact, so the line still sums to the payment and a reversal mirrors it. Shares that don't resolve leave the whole payment (d). One naming no party is decided by its accounts. Receipts are untouched (a refund from a government stays (c)). No total changes, only which operating row a payment is in. Two limits, from the review of this change: a government selling goods or services (postage) is 45-17(b)'s supplier "for other goods or services", so the rule says, and the handbook tells the agent, to add such a payee as a vendor, never with the government_agency role (the books can't tell what a payment bought; the role says it). And payroll keeps its structure (CONVENTION): an entry with a line on the salary expense or a payroll payable control account, or on a pay tax category (salaries_wages, officer_compensation, employee_benefits, pension_profit_sharing), stays (d) whoever it names: withheld taxes remitted are the employees' pay, and the payables mix them with the employer's taxes, which a remittance can't tell apart. So a remittance to the IRS is (d) as it was before this change; the employer's payroll tax paid on its own expense account is a tax, (g). The first company's books have this case: their state filing fee moves from "Cash paid to suppliers and employees" to "Other operating cash payments" at every date once its entry names the state's agency with the government_agency role and its own entry is the one whose cash the statement lists (paid from the bank, or on a card that is a lender's credit, D-42, or by a member through the members' account while it is a financing account, B-14 rule 11, the way that fee was paid); charged to an operating-payable card, its cash leaves in the card payment, whose payee is the bank, and it stays with suppliers. STATUS says how to check both, and that the cutover goldens' cash-flow snapshots will differ on the two class lines only (totals the same), so the next cutover diff isn't read as a regression. Docs: rules.md B-14 rule 5 (the rule, its source quoted, the date and what it was before); fasb-asc.md (45-17(b) and (c) quoted exactly, with the guide's SHA-256); the handbook's entries section (name the agency as the party on a tax, fee, fine or penalty paid to a government; a shared payment named with both amounts; a government selling services added as a vendor; payroll remittances stay with pay; a fee on a card follows the card payment); fasb-asc.md also quotes 45-22 and 45-22A; bookspec example cash-flow.government-fees.toml (a filing fee and a lawyer on one organization-costs account, a license on taxes and licenses with no party, a penalty to a tax agency on the wrong account, paper from a supplier, an annual report paid through a registered agent, 37.00 the state's and 100.00 the agent's; every figure by hand) with a new `class.<a..g>` key in the cash_flow query (bookspec README; the runner checks every class the statement has is given); testing.md; STATUS. Tests: ledger-core tests/spec_cash_flow.rs `a_payment_to_a_government_is_other_operating` (the filing fee and a penalty to a tax agency (g); the same account paid to a lawyer, or with no payee, (d); its reversal next month keeps (g); a refund (c)), `a_government_payee_moves_a_fee_on_any_account` (a taxes_licenses license with no party (g); a payment shared half and half between a government and a printer split 50.00 (g) and 50.00 (d), the government alone all (g)), `a_shared_government_payment_splits_to_the_cent` (a third by percent of 100.01: 33.34 (g), 66.67 (d); amounts split as given; the reversal mirrors to the cent), `a_payroll_remittance_to_a_tax_agency_stays_pay` (withheld taxes remitted from a payable holding its payroll role, and pay on a salaries_wages account, stay (d) with the IRS named; the employer's tax on its own expense account is (g)), `a_government_selling_services_is_a_supplier` (postage to a vendor (d); given government_agency, (g): the limit the handbook guards); src cashflow.rs `tests` `a_government_part_rounds_half_to_even` and the proptest `a_government_part_sums_and_mirrors`; the bookspec example; from the P4 review, `a_reversal_takes_its_originals_payee` (a fee and its reversal next month land in one class, the chain's payee deciding: the books keep a chain's parties one, so reading the reversal's own parties is an equivalent mutant) and `a_shared_government_payment_a_member_paid_splits_both_ways` (a shared payment a member paid: each part with its own on_behalf; fails with the on-behalf part unsplit). docs/mcp-interface.md: books.cash_flow and the Roles paragraph say a government or tax agency payee makes a payment other operating, and a shared one two operating lines. Broken to confirm: without the payee check the five spec tests and the example fail; without the split for mixed payees the two shared-payment tests and the example (class.d -549.50) fail; without the payroll exclusion the payroll test fails; rounding toward zero fails both unit tests; without the tax-category route `operating_classes_follow_asc_230_10_45_25`, the second test and the example fail. The viewer's cash flow page, rendered on made-up books before and after: the fee moved from "Cash paid to suppliers and employees" to "Other operating cash payments", every total the same; and on made-up books with an annual report shared between the state and an agent: each part on its own class line, every total the same. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T3gXMVt7XJPi6ens1or9Dj	2026-10-22 19:31:18 -06:00
swaitsandClaude Opus 5.5	eb4329bb2a	P3: the cash flow statement by ASC 230 (defect 1, D-35, D-42) check / check (push) Canceled after 0s Details Direct method with the operating reconciliation and noncash schedules; it foots by construction (Lean and Kani). Every non-cash account belongs to one section; reversals net; a member or lender paying for the company is cash borrowed and spent (D-42, constructive receipt and disbursement); property a member contributes stays noncash. The bookspec seed: one loader checks every example. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T3gXMVt7XJPi6ens1or9Dj	2026-10-21 09:35:32 -06:00
swaitsandClaude Opus 5.5	8693d5a3f5	MCP: short connect text, a handbook, tool annotations, safe local imports - The 13K-character instructions (clients cut them short) become a connect text of at most 1,400 characters whose first 512 stand alone, plus books.handbook and books://handbook/{section}: the old guidance by section, with no helper commands, home paths, pull requests or file-reading suggestions (tool_text_lint). - Every tool has a title and read-only/destructive hints; no requiresUserInteraction anywhere (owner decision 2026-10-16). - books.import_local_file reads only regular files inside the import roots (the downloads folder by default, or --import-root), never the data dir, books dir, vault or the key's folder, no symlink escapes or hard links, and the file opened must be the file checked. - The store lock is a tokio mutex taken off the runtime threads. - get_info refreshes settings first; a bare books://digest reads. Review fixes (P0 review, 2026-10-16): - Fail closed: a tokio mutex never poisons and spawn_blocking caught the panic, so after a panic mid-mutation the server kept serving a Store behind its journal. A panic (the task, or while holding the store) now stops the shared store; every later request on every session is refused with a plain message; a restart re-verifies the journal. The join error goes through redact_refusal and never carries the panic's text. - books.set_w9 w9_file_path read any path (a link named w9.pdf to the vault key was stored and get_w9 wrote it out): it now goes through the import roots' lockdown, its type judged on the canonical path. - Sealed even inside a root: the key file in force, where a linked one leads, both folders, and the default key folder whatever the settings say. Refusals check the roots first, so outside them every path gets one message (no probing what exists); inside, other books-dir files say to copy them out first. - The open is O_NOFOLLOW \| O_NONBLOCK (a pipe swapped in after the check can't hang a thread) and must match the checked file's device and inode. New dependency: libc (unix only), for those two open flags, which std doesn't name. - Default import roots are the downloads folder only (the plan); files with full TINs (get_w9, vendor_1099 include_tins, the CPA package with TINs) are never written into an import root, and the server refuses to import any file it wrote with TINs (by SHA-256). - set_tin and set_w9 overwrite vault records: destructive_hint = true; annotations_complete pins the key tools' hints. The read-only hint is checked in behaviour on every spec_mcp call (journal and data-dir files unchanged). - Text: the connect text names the settings file as the one local file to edit, says every entry balances on real accounts and names its party, says invoice/bill/payment/payroll tools post unchecked, rewords the exemptions, and shows the company name as one plain line; the handbook takes section "all", lists its ids in the schema and says to read contract first; books.settings drops the config.json path and no error names the data dir or the key file. tool_text_lint covers the whole tool JSON and resources and bans git/commit/FL-0001; tool descriptions over 700 characters are pinned to today's eight (P5). - digest: an empty since= is bare; the default date is pinned on every day of a month. Round-2 review fixes (2026-10-16): - TIN files (B-26): the in-memory, per-session set of TIN-file hashes became one registry beside the vault (vault/tin-files.sha256, hashes only), shared by every session and every later server. It holds the W-9 set_w9 reads (recorded as read), get_w9 copies, 1099 worksheets with TINs, CPA packages with TINs and each file in one that holds a TIN; a file is recorded before it is written, and a failure refuses. import_local_file, attach_receipt and file_document (base64 was never checked) refuse a recorded file, and a text file (by type, name, or UTF-8/UTF-16 decoding) holding a full TIN. Not caught: an altered binary copy; the docs say so (P2/P7 remove the path tools). - The text check is narrow (owner/engineer decision, 2026-10-16: bank exports are filed for reconciliation, and has_full_tin's "nine digits however separated" refused their routing numbers, long references and dates run into amounts). Text is refused when it holds (a) a TIN the vault holds for a party, anywhere, as nine digits, 3-2-4 joined by hyphens, spaces or dots, or 2-7 joined by a hyphen or space, compared on the server against the decrypted vault and never returned or logged (a vault that can't be opened leaves (b)); or (b) a stand-alone printed SSN (123-45-6789) or EIN (12-3456789) shape: no digit, and no hyphen or dot followed by a digit, beside it. Full-width digits and Unicode hyphens and spaces read as ASCII. has_full_tin still guards refusals and results (redact_refusal). Known limit, for P7: a refusal under (a) tells the agent a text it chose holds a vault TIN. New dependency: zeroize in ledger-mcp (already in the workspace through ledger-vault, same major version), so the vault's TINs decoded for the scan are wiped from memory on drop as the vault's own are. - Mutation testing of the final P0 diff (docs/testing.md): tests for each law a survivor broke (handbook titles, a dropped default root, a .jpg W-9, the waker, the walk's folder flags against a link and a pipe, the 40-link limit, save paths refused as such, the package marking only its TIN files, a registry that can't be read, text types, the short receipt rule's counts and a 12-character code). Simpler code where only a race could tell: inspect places an existing path by canonicalize itself (no second comparison), read_checked's read limit is its one size check, openat fails on -1 as specified. The 25 MiB upload test removes its 50 MB of books however it ends. - The GUI's stale-rule prompt no longer says to open a pull request: it asks the agent to find the figure from the rule's official authority, confirm it with the human, pass it explicitly, and tell the human so it can be reported upstream (as the handbook says); a lib test pins it and bans files, git, GitHub and pull requests from every attention prompt. - Import roots (local_files.rs INVARIANT 0): XDG_DOWNLOAD_DIR="$HOME/" made $HOME (or /) the root. No root may be /, the home folder or hold it, or hold the books, data dir, vault or a key: a named one stops the server at startup, a default one is dropped; the default falls back to ~/Downloads only if that is a real folder other than $HOME; with no root, an import says so. - The read is a component walk from / with openat(O_NOFOLLOW \| O_DIRECTORY) per folder and O_NOFOLLOW \| O_NONBLOCK for the file, so a folder swapped for a link after the check fails; no step may land on a protected inode (one renamed into a root); dev/ino and nlink stay. No /proc. Portable to macOS. (libc's openat, two small unsafe blocks.) - One refusal for missing, dangling and outside paths: resolved() follows every link, dangling ones too, so a link's target existing or not no longer changes the answer. - Sealing: the key files (in force, default) and their targets always; their folders only when not $HOME, not a root, not holding a root; and ~/.config/wanderbooks whatever XDG_CONFIG_HOME says. - Agent text (I-12): RuleNotKnown names the authority (IRS, with its address) and says to tell the human, never a repo path, PR or GitHub; the digest's stale_rules drop the repo catalog and path for it; vault, outside-books, STOPPED and local-file refusals name no git, path or flag. tool_text_lint bans docs/, .md, /home, data dir, --data-dir, --import-root, vault.key, .jsonl, sqlite, .gitignore, github, pull request, and also lints every error template (scanned from source), built error texts, and the server's refusal constants. - The receipt rule told (ReceiptPolicy::rule) is the one enforced: the exact threshold in the base currency (no "$", no rounding), required and exempt accounts, reversals exempt; the connect text fits 1,400 characters by dropping reasons, then codes, never the rule. - The connect text follows the parties setting; "offer books.digest" everywhere. shown_name drops Unicode format characters (bidi, zero width). - read_only_tools_change_nothing compares file contents, the database by every row, the vault and the settings file (raw database bytes did not change either; rows are the stable comparison). - import_local_file takes the name and type from the canonical path; the digest's journal repair says when the tail was set aside, not the journal's file name; "version-history messages" back in the TIN rule; openWorldHint false on every tool, pinned in annotations_complete. - Outside the MCP crate, for the same texts: ledger-core's DatedRule gains `authority` (the statute or publication with its address) and RuleNotKnown carries it; ledger-store's "sqlite error" reads "database error"; ledger-config's ReceiptPolicy::rule takes the base currency. New dev-dependency: rusqlite in ledger-mcp (already in the workspace, same version and features as ledger-store), to read the database's rows in read_only_tools_change_nothing. - The filing scan is no TIN oracle (tin_files.rs INVARIANT 4): text holding more than two TIN-shaped numbers (any rendering rule (a) reads) that end in a known TIN's last four (the books' TIN and W-9 facts, via known_tin_last4, before the vault is opened; then the vault's own) is refused with TIN_PROBE, the same words whether or not one is the vault's TIN; only one or two candidates are compared against the vault. Tests: unit text_probing_for_a_tin_is_refused_alike_whether_or_not_it_holds_it, one_or_two_candidates_are_compared_against_the_vault; over HTTP text_probing_for_a_tin_is_refused_alike_by_every_filing_tool. Plan: plan/served.md P0, section 6 "Immediate hole (P0)", 4.1, 4.3, 4.9. Review round 3. S1: a panic stops the server for every session, so no input may reach one. Dates are four-digit years (new ledger_core:: calendar, 0001-01-01..9999-12-31): the MCP's parse_date is strict YYYY-MM-DD, periods are bounded, last_day_of_month returns a refusal (server and store); schedules, assets, recurring entries, periods, documents, disposals and entries refuse dates outside the calendar, and replay refuses such journal dates. Every amount a command takes is at most a line's (draft lines by size, document lines, payouts, payroll, statements, shares, tax basis, proceeds, recurring templates), on replay too, so sums are exact; the 1099 vendor part and the K-1 property share use checked products (TooLargeToCompute); a recurring run makes at most 1,000 drafts. tests/hostile_args.rs drives every tool with schema-derived hostile arguments and every resource with generated URIs, asserting the server never stops; the audit's panics are pinned. S2: a `.` or `..` path name is refused as NO_SUCH_FILE up front. S3: NUL-interleaved UTF-16 without a byte-order mark is scanned both ways. S4: resource-read refusals are TIN-redacted. S5: set_w9 records its W-9 only once the call passes every check, just before the vault write. S8: idempotentHint only on verify, run_depreciation, run_schedules, run_recurring, set_party_roles (a repeat leaves journal and vault alone; spec_vault checks every candidate twice); every tool's hints pinned in one table. C1: books.settings lists receipt_required_accounts and receipt_exempt_accounts uncut. C2: the default company name reads "a new company". C3: the parties rule names no-party reasons. C4/C5: the handbook names the settings file only as books.settings' books_toml, and restores "check books.digest and offer it". C6: an import root inside the books, data dir or vault is refused at startup. The lint catches `just` however it ends and where the books are; digest_resource_bare_reads reads the server's month. Review round 4 (2026-10-17): round 3's bounds ran in replay too, so journals main wrote and reopened (an entry dated 0000-06-01 or +10000-01-01, a draft line of 2e15, an asset ending past 9999, a basis or share past the line limit, sub-cent document and payroll lines) no longer opened. Posted is forever: the bounds are the commands' only. - Replay applies main's rule exactly: parse_date takes any date chrono reads; replay_add_line(_fx) has no size bound (add_line/add_line_fx do); replay_register_asset/correct_asset (chrono overflow only), replay_set_asset_tax_basis (check_journaled), replay_set_entry_parties (check_shares_journaled), replay_register_recurring (validate_recurring_journaled), replay_register_schedule (months 1 to 600), replay_create_period (order only), replay_dispose_asset, and no line, date, payment or payroll range checks in replay_invoice/bill, their payments and replay_payroll_run. - Derived figures over such books refuse (TooLargeToCompute, DateOutOfRange), never panic: amortization plans, depreciation into chrono's last month (and the true-up for lives past 9999), intervals, document totals and aging, net pay and payroll plans, money flows and share resolution, the asset register, receipt-policy debits; the MCP tools and the viewer show what can't be computed. - tests/fixtures/old-books: the review's 13 journals, its control and 15 more edges, written by main's Store API with main's figures (expected.json); every one opens in the writer and the viewer to those figures, every derived figure computes or refuses, every MCP tool and GUI page answers; hostile_args restarts the server after each property; each bound has a command/replay test pair. Final review: a schedule's plan refuses a total of 10^26 or more (TooLargeToCompute) instead of letting Decimal round its cents silently, and a null `remaining` in the schedule output is always explained by plan_error. Replay is unaffected: no journaled schedule month can belong to a total that large (the line limit bounds every posted month). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T3gXMVt7XJPi6ens1or9Dj	2026-10-17 09:25:00 -06:00

Author

SHA1

Message

Date

swaitsandClaude Opus 5.5

535874e0f3

fix(cash flow): a payment to a government is other operating, by its payee

The P3 cutover review's open point 2: a state's LLC filing fee, booked
to an organization-costs account (tax category organization_startup),
read as "Cash paid to suppliers and employees". B-14 rule 5 sent a
payment to class (g) only when every operating line's account was
taxes_licenses, so the account, not the payee, decided.

ASC 230-10-45-17, read in EY's guide that reproduces it (Statement of
cash flows, July 2026, p. 43; the PDF re-fetched and its SHA-256
recorded in docs/spec/sources/fasb-asc.md), lists apart "(b) Cash
payments to other suppliers and employees for other goods or services"
and "(c) Cash payments to governments for taxes, duties, fines, and
other fees or penalties". 45-25's classes name only income taxes (f)
among the latter, so the rest are (g), other operating cash payments.
A formation filing fee is rightly an organization cost (its account and
tax line), and still a payment to a government: the payee is what
45-17(c) is about.

So rule 5 now sends a payment's government part to (g): of an
operating payment the structure classes (d), what went to a party with
the government_agency or tax_agency role (the chain root's parties, so
a reversal keeps its original's class) is (g), on any account; and, as
before, a payment whose every operating line is on a taxes_licenses
account is (g). Every party a government: the whole payment. A
government and a supplier named together: the payment is split by their
resolved shares (B-35), the government's part (g), the rest (d), since
ASC 230-10-45-22 has "each separately identifiable source or each
separately identifiable use" classed "on the basis of the nature of the
underlying cash flows" (EY p. 44; quoted in fasb-asc.md; it names the
three activities, read for 45-25's classes too as a CONVENTION). The
government's part is the payment x its share / the whole, rounded half
to even to the base currency's places, the rest exact, so the line still
sums to the payment and a reversal mirrors it. Shares that don't
resolve leave the whole payment (d). One naming no party is decided by
its accounts. Receipts are untouched (a refund from a government stays
(c)). No total changes, only which operating row a payment is in.

Two limits, from the review of this change: a government selling goods
or services (postage) is 45-17(b)'s supplier "for other goods or
services", so the rule says, and the handbook tells the agent, to add
such a payee as a vendor, never with the government_agency role (the
books can't tell what a payment bought; the role says it). And payroll
keeps its structure (CONVENTION): an entry with a line on the salary
expense or a payroll payable control account, or on a pay tax category
(salaries_wages, officer_compensation, employee_benefits,
pension_profit_sharing), stays (d) whoever it names: withheld taxes
remitted are the employees' pay, and the payables mix them with the
employer's taxes, which a remittance can't tell apart. So a remittance
to the IRS is (d) as it was before this change; the employer's payroll
tax paid on its own expense account is a tax, (g).

The first company's books have this case: their state filing fee moves
from "Cash paid to suppliers and employees" to "Other operating cash
payments" at every date once its entry names the state's agency with the
government_agency role and its own entry is the one whose cash the
statement lists (paid from the bank, or on a card that is a lender's
credit, D-42, or by a member through the members' account while it is
a financing account, B-14 rule 11, the way that fee was paid);
charged to an operating-payable card, its cash leaves in the card
payment, whose payee is the bank, and it stays with suppliers.
STATUS says how to check both, and that the cutover goldens' cash-flow
snapshots will differ on the two class lines only (totals the same),
so the next cutover diff isn't read as a regression.

Docs: rules.md B-14 rule 5 (the rule, its source quoted, the date and
what it was before); fasb-asc.md (45-17(b) and (c) quoted exactly, with
the guide's SHA-256); the handbook's entries section (name the agency as
the party on a tax, fee, fine or penalty paid to a government; a shared
payment named with both amounts; a government selling services added as
a vendor; payroll remittances stay with pay; a fee on a card follows the
card payment); fasb-asc.md also quotes 45-22 and 45-22A; bookspec
example cash-flow.government-fees.toml (a filing fee and a lawyer on
one organization-costs account, a license on taxes and licenses with no
party, a penalty to a tax agency on the wrong account, paper from a
supplier, an annual report paid through a registered agent, 37.00 the
state's and 100.00 the agent's; every figure by hand) with a new `class.<a..g>`
key in the
cash_flow query (bookspec README; the runner checks every class the
statement has is given); testing.md; STATUS.

Tests: ledger-core tests/spec_cash_flow.rs
`a_payment_to_a_government_is_other_operating` (the filing fee and a
penalty to a tax agency (g); the same account paid to a lawyer, or with
no payee, (d); its reversal next month keeps (g); a refund (c)),
`a_government_payee_moves_a_fee_on_any_account` (a taxes_licenses
license with no party (g); a payment shared half and half between a
government and a printer split 50.00 (g) and 50.00 (d), the government
alone all (g)), `a_shared_government_payment_splits_to_the_cent` (a
third by percent of 100.01: 33.34 (g), 66.67 (d); amounts split as
given; the reversal mirrors to the cent),
`a_payroll_remittance_to_a_tax_agency_stays_pay` (withheld taxes
remitted from a payable holding its payroll role, and pay on a
salaries_wages account, stay (d) with the IRS named; the employer's tax
on its own expense account is (g)),
`a_government_selling_services_is_a_supplier` (postage to a vendor (d);
given government_agency, (g): the limit the handbook guards); src
cashflow.rs `tests` `a_government_part_rounds_half_to_even` and the
proptest `a_government_part_sums_and_mirrors`; the bookspec example;
from the P4 review, `a_reversal_takes_its_originals_payee` (a fee and
its reversal next month land in one class, the chain's payee deciding:
the books keep a chain's parties one, so reading the reversal's own
parties is an equivalent mutant) and
`a_shared_government_payment_a_member_paid_splits_both_ways` (a shared
payment a member paid: each part with its own on_behalf; fails with
the on-behalf part unsplit). docs/mcp-interface.md: books.cash_flow
and the Roles paragraph say a government or tax agency payee makes a
payment other operating, and a shared one two operating lines.
Broken to confirm: without the payee check the five spec tests and the
example fail; without the split for mixed payees the two shared-payment
tests and the example (class.d -549.50) fail; without the payroll
exclusion the payroll test fails; rounding toward zero fails both unit
tests; without the tax-category route
`operating_classes_follow_asc_230_10_45_25`, the second test and the
example fail. The viewer's cash flow page,
rendered on made-up books before and after: the fee moved from "Cash
paid to suppliers and employees" to "Other operating cash payments",
every total the same; and on made-up books with an annual report
shared between the state and an agent: each part on its own class
line, every total the same.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T3gXMVt7XJPi6ens1or9Dj

2026-10-22 19:31:18 -06:00

swaitsandClaude Opus 5.5

eb4329bb2a

P3: the cash flow statement by ASC 230 (defect 1, D-35, D-42)

check / check (push) Canceled after 0s

Details

Direct method with the operating reconciliation and noncash schedules; it
foots by construction (Lean and Kani). Every non-cash account belongs to
one section; reversals net; a member or lender paying for the company is
cash borrowed and spent (D-42, constructive receipt and disbursement);
property a member contributes stays noncash. The bookspec seed: one loader
checks every example.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T3gXMVt7XJPi6ens1or9Dj

2026-10-21 09:35:32 -06:00

swaitsandClaude Opus 5.5

8693d5a3f5

MCP: short connect text, a handbook, tool annotations, safe local imports

- The 13K-character instructions (clients cut them short) become a
  connect text of at most 1,400 characters whose first 512 stand alone,
  plus books.handbook and books://handbook/{section}: the old guidance by
  section, with no helper commands, home paths, pull requests or
  file-reading suggestions (tool_text_lint).
- Every tool has a title and read-only/destructive hints; no
  requiresUserInteraction anywhere (owner decision 2026-10-16).
- books.import_local_file reads only regular files inside the import
  roots (the downloads folder by default, or --import-root), never the
  data dir, books dir, vault or the key's folder, no symlink escapes or
  hard links, and the file opened must be the file checked.
- The store lock is a tokio mutex taken off the runtime threads.
- get_info refreshes settings first; a bare books://digest reads.

Review fixes (P0 review, 2026-10-16):
- Fail closed: a tokio mutex never poisons and spawn_blocking caught the
  panic, so after a panic mid-mutation the server kept serving a Store
  behind its journal. A panic (the task, or while holding the store)
  now stops the shared store; every later request on every session is
  refused with a plain message; a restart re-verifies the journal. The
  join error goes through redact_refusal and never carries the panic's
  text.
- books.set_w9 w9_file_path read any path (a link named w9.pdf to the
  vault key was stored and get_w9 wrote it out): it now goes through the
  import roots' lockdown, its type judged on the canonical path.
- Sealed even inside a root: the key file in force, where a linked one
  leads, both folders, and the default key folder whatever the settings
  say. Refusals check the roots first, so outside them every path gets
  one message (no probing what exists); inside, other books-dir files say
  to copy them out first.
- The open is O_NOFOLLOW | O_NONBLOCK (a pipe swapped in after the check
  can't hang a thread) and must match the checked file's device and
  inode. New dependency: libc (unix only), for those two open flags,
  which std doesn't name.
- Default import roots are the downloads folder only (the plan); files
  with full TINs (get_w9, vendor_1099 include_tins, the CPA package with
  TINs) are never written into an import root, and the server refuses to
  import any file it wrote with TINs (by SHA-256).
- set_tin and set_w9 overwrite vault records: destructive_hint = true;
  annotations_complete pins the key tools' hints. The read-only hint is
  checked in behaviour on every spec_mcp call (journal and data-dir files
  unchanged).
- Text: the connect text names the settings file as the one local file
  to edit, says every entry balances on real accounts and names its
  party, says invoice/bill/payment/payroll tools post unchecked, rewords
  the exemptions, and shows the company name as one plain line; the
  handbook takes section "all", lists its ids in the schema and says to
  read contract first; books.settings drops the config.json path and no
  error names the data dir or the key file. tool_text_lint covers the
  whole tool JSON and resources and bans git/commit/FL-0001; tool
  descriptions over 700 characters are pinned to today's eight (P5).
- digest: an empty since= is bare; the default date is pinned on every
  day of a month.

Round-2 review fixes (2026-10-16):
- TIN files (B-26): the in-memory, per-session set of TIN-file hashes
  became one registry beside the vault (vault/tin-files.sha256, hashes
  only), shared by every session and every later server. It holds the
  W-9 set_w9 reads (recorded as read), get_w9 copies, 1099 worksheets
  with TINs, CPA packages with TINs and each file in one that holds a
  TIN; a file is recorded before it is written, and a failure refuses.
  import_local_file, attach_receipt and file_document (base64 was never
  checked) refuse a recorded file, and a text file (by type, name, or
  UTF-8/UTF-16 decoding) holding a full TIN. Not caught: an altered
  binary copy; the docs say so (P2/P7 remove the path tools).
- The text check is narrow (owner/engineer decision, 2026-10-16: bank
  exports are filed for reconciliation, and has_full_tin's "nine digits
  however separated" refused their routing numbers, long references and
  dates run into amounts). Text is refused when it holds (a) a TIN the
  vault holds for a party, anywhere, as nine digits, 3-2-4 joined by
  hyphens, spaces or dots, or 2-7 joined by a hyphen or space, compared
  on the server against the decrypted vault and never returned or
  logged (a vault that can't be opened leaves (b)); or (b) a stand-alone
  printed SSN (123-45-6789) or EIN (12-3456789) shape: no digit, and no
  hyphen or dot followed by a digit, beside it. Full-width digits and
  Unicode hyphens and spaces read as ASCII. has_full_tin still guards
  refusals and results (redact_refusal). Known limit, for P7: a refusal
  under (a) tells the agent a text it chose holds a vault TIN.
  New dependency: zeroize in ledger-mcp (already in the workspace
  through ledger-vault, same major version), so the vault's TINs decoded
  for the scan are wiped from memory on drop as the vault's own are.
- Mutation testing of the final P0 diff (docs/testing.md): tests for
  each law a survivor broke (handbook titles, a dropped default root, a
  .jpg W-9, the waker, the walk's folder flags against a link and a
  pipe, the 40-link limit, save paths refused as such, the package
  marking only its TIN files, a registry that can't be read, text types,
  the short receipt rule's counts and a 12-character code). Simpler
  code where only a race could tell: inspect places an existing path by
  canonicalize itself (no second comparison), read_checked's read limit
  is its one size check, openat fails on -1 as specified. The 25 MiB
  upload test removes its 50 MB of books however it ends.
- The GUI's stale-rule prompt no longer says to open a pull request: it
  asks the agent to find the figure from the rule's official authority,
  confirm it with the human, pass it explicitly, and tell the human so it
  can be reported upstream (as the handbook says); a lib test pins it and
  bans files, git, GitHub and pull requests from every attention prompt.
- Import roots (local_files.rs INVARIANT 0): XDG_DOWNLOAD_DIR="$HOME/"
  made $HOME (or /) the root. No root may be /, the home folder or hold
  it, or hold the books, data dir, vault or a key: a named one stops the
  server at startup, a default one is dropped; the default falls back to
  ~/Downloads only if that is a real folder other than $HOME; with no
  root, an import says so.
- The read is a component walk from / with openat(O_NOFOLLOW |
  O_DIRECTORY) per folder and O_NOFOLLOW | O_NONBLOCK for the file, so a
  folder swapped for a link after the check fails; no step may land on a
  protected inode (one renamed into a root); dev/ino and nlink stay. No
  /proc. Portable to macOS. (libc's openat, two small unsafe blocks.)
- One refusal for missing, dangling and outside paths: resolved()
  follows every link, dangling ones too, so a link's target existing or
  not no longer changes the answer.
- Sealing: the key files (in force, default) and their targets always;
  their folders only when not $HOME, not a root, not holding a root; and
  ~/.config/wanderbooks whatever XDG_CONFIG_HOME says.
- Agent text (I-12): RuleNotKnown names the authority (IRS, with its
  address) and says to tell the human, never a repo path, PR or GitHub;
  the digest's stale_rules drop the repo catalog and path for it; vault,
  outside-books, STOPPED and local-file refusals name no git, path or
  flag. tool_text_lint bans docs/, .md, /home, data dir, --data-dir,
  --import-root, vault.key, .jsonl, sqlite, .gitignore, github, pull
  request, and also lints every error template (scanned from source),
  built error texts, and the server's refusal constants.
- The receipt rule told (ReceiptPolicy::rule) is the one enforced: the
  exact threshold in the base currency (no "$", no rounding), required
  and exempt accounts, reversals exempt; the connect text fits 1,400
  characters by dropping reasons, then codes, never the rule.
- The connect text follows the parties setting; "offer books.digest"
  everywhere. shown_name drops Unicode format characters (bidi, zero
  width).
- read_only_tools_change_nothing compares file contents, the database
  by every row, the vault and the settings file (raw database bytes did
  not change either; rows are the stable comparison).
- import_local_file takes the name and type from the canonical path;
  the digest's journal repair says when the tail was set aside, not the
  journal's file name; "version-history messages" back in the TIN rule;
  openWorldHint false on every tool, pinned in annotations_complete.
- Outside the MCP crate, for the same texts: ledger-core's DatedRule
  gains `authority` (the statute or publication with its address) and
  RuleNotKnown carries it; ledger-store's "sqlite error" reads "database
  error"; ledger-config's ReceiptPolicy::rule takes the base currency.
  New dev-dependency: rusqlite in ledger-mcp (already in the workspace,
  same version and features as ledger-store), to read the database's
  rows in read_only_tools_change_nothing.
- The filing scan is no TIN oracle (tin_files.rs INVARIANT 4): text
  holding more than two TIN-shaped numbers (any rendering rule (a)
  reads) that end in a known TIN's last four (the books' TIN and W-9
  facts, via known_tin_last4, before the vault is opened; then the
  vault's own) is refused with TIN_PROBE, the same words whether or not
  one is the vault's TIN; only one or two candidates are compared
  against the vault. Tests: unit
  text_probing_for_a_tin_is_refused_alike_whether_or_not_it_holds_it,
  one_or_two_candidates_are_compared_against_the_vault; over HTTP
  text_probing_for_a_tin_is_refused_alike_by_every_filing_tool.

Plan: plan/served.md P0, section 6 "Immediate hole (P0)", 4.1, 4.3, 4.9.

Review round 3. S1: a panic stops the server for every session, so no
input may reach one. Dates are four-digit years (new ledger_core::
calendar, 0001-01-01..9999-12-31): the MCP's parse_date is strict
YYYY-MM-DD, periods are bounded, last_day_of_month returns a refusal
(server and store); schedules, assets, recurring entries, periods,
documents, disposals and entries refuse dates outside the calendar, and
replay refuses such journal dates. Every amount a command takes is at
most a line's (draft lines by size, document lines, payouts, payroll,
statements, shares, tax basis, proceeds, recurring templates), on
replay too, so sums are exact; the 1099 vendor part and the K-1
property share use checked products (TooLargeToCompute); a recurring
run makes at most 1,000 drafts. tests/hostile_args.rs drives every tool
with schema-derived hostile arguments and every resource with generated
URIs, asserting the server never stops; the audit's panics are pinned.
S2: a `.` or `..` path name is refused as NO_SUCH_FILE up front. S3:
NUL-interleaved UTF-16 without a byte-order mark is scanned both ways.
S4: resource-read refusals are TIN-redacted. S5: set_w9 records its W-9
only once the call passes every check, just before the vault write.
S8: idempotentHint only on verify, run_depreciation, run_schedules,
run_recurring, set_party_roles (a repeat leaves journal and vault
alone; spec_vault checks every candidate twice); every tool's hints
pinned in one table. C1: books.settings lists receipt_required_accounts
and receipt_exempt_accounts uncut. C2: the default company name reads
"a new company". C3: the parties rule names no-party reasons. C4/C5:
the handbook names the settings file only as books.settings' books_toml,
and restores "check books.digest and offer it". C6: an import root
inside the books, data dir or vault is refused at startup. The lint
catches `just` however it ends and where the books are;
digest_resource_bare_reads reads the server's month.

Review round 4 (2026-10-17): round 3's bounds ran in replay too, so
journals main wrote and reopened (an entry dated 0000-06-01 or
+10000-01-01, a draft line of 2e15, an asset ending past 9999, a basis
or share past the line limit, sub-cent document and payroll lines) no
longer opened. Posted is forever: the bounds are the commands' only.
- Replay applies main's rule exactly: parse_date takes any date chrono
  reads; replay_add_line(_fx) has no size bound (add_line/add_line_fx
  do); replay_register_asset/correct_asset (chrono overflow only),
  replay_set_asset_tax_basis (check_journaled), replay_set_entry_parties
  (check_shares_journaled), replay_register_recurring
  (validate_recurring_journaled), replay_register_schedule (months 1 to
  600), replay_create_period (order only), replay_dispose_asset, and no
  line, date, payment or payroll range checks in replay_invoice/bill,
  their payments and replay_payroll_run.
- Derived figures over such books refuse (TooLargeToCompute,
  DateOutOfRange), never panic: amortization plans, depreciation into
  chrono's last month (and the true-up for lives past 9999), intervals,
  document totals and aging, net pay and payroll plans, money flows and
  share resolution, the asset register, receipt-policy debits; the MCP
  tools and the viewer show what can't be computed.
- tests/fixtures/old-books: the review's 13 journals, its control and 15
  more edges, written by main's Store API with main's figures
  (expected.json); every one opens in the writer and the viewer to those
  figures, every derived figure computes or refuses, every MCP tool and
  GUI page answers; hostile_args restarts the server after each
  property; each bound has a command/replay test pair.

Final review: a schedule's plan refuses a total of 10^26 or more
(TooLargeToCompute) instead of letting Decimal round its cents silently,
and a null `remaining` in the schedule output is always explained by
plan_error. Replay is unaffected: no journaled schedule month can belong
to a total that large (the line limit bounds every posted month).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T3gXMVt7XJPi6ens1or9Dj

2026-10-17 09:25:00 -06:00