swaitsandClaude Opus 5.5
d7fa16e974
check / check (push) Canceled after 0s
refuse hand entries (P4b S1, part A) Plan P4b (D-45), slice S1, the engine half: rules.md B-38. - ledger-core: every receivables or payables line carries its document (Ledger.line_docs: DocRef, Movement, DocTag), written by the document commands in the step that posts it, derived on replay from the existing document events (the role's account as it stood then; payments by the ordinal rule), copied onto a reversal's mirror. Ledger::stands_on; doc_state / invoice_state / bill_state (total, paid, outstanding, status Open/Partial/Paid/WrittenOff/Void, overdue days) as of any day; ar_aging / ap_aging read them, so reversed payments and voids are right. The control guard (add_line, add_line_fx, post_entry, register_recurring) refuses untagged lines on receivables/payables, exempting a reversal's mirror of a legacy line; replay never refuses. Bounds (kernel::running_bounds, bounds_kept) on payments and reversals; a document reversal never dated before its entry; deposit/payer accounts must be cash-like and hold no role. New API: receive_payment_with / pay_bill_with (PaymentDetails: instrument, reference), void_document / check_void_document, control_check, payments_recorded, standing_payments, replay_reverse_entry. Invoice.amount_paid/status remain only as derived caches for the MCP layer until part B. cashflow bill_splits reads payments from the tags. - ledger-store: journal feature document_standing (D-39 gated) for a payment accepted only because an earlier one was reversed; receive_payment_with / pay_bill_with (instrument journaled as entry.instrument_set, reference in the description), void_document; replay uses replay_reverse_entry; schema 15 drops the projection's amount_paid/status. Fixture p4-arap-before + golden figures written by the version before S1, adjudicated in arap_standing.rs. - ledger-gui: party card, cash "coming up" and company owed totals read doc_state as of today (late from the derived state). - Lean Documents.lean (control_agrees and friends); Kani bounds_check_matches_definition, bounds_kept_is_the_definition_on_books_in_bounds; rules B-38, B-18/B-23 amended; bookspec `older = true` for legacy hand lines; tests that hand-post to 1200/2000 post as replay or renumbered. Review fixes (both reviews of part A): - control_role_of guards only an account the role is assigned to or one holding its documents' lines (a chart's own 1200 Equipment or card at 2000 is free until a document posts there); payment accounts check other roles by holds_role (type-checked). The MCP tests that failed on the guard (oracle_mcp, spec_projects) pass unchanged. - standing_payments leaves out reversals (sorted, deduped); replayed tags match the movement's side; payments_recorded counts every payment event (tagged or not, Ledger.payment_events) and refuses overflow. - The record caches settled (paid + discounted + written off) and owed (Invoice/Bill.owed, never serialized): a void never reads as paid. - assign_role: receivables/payables refuse moving onto an account with untagged lines (RoleAccountHasHandLines) and, on their control account holding a balance, say DocumentRoleHoldsBalance (no hand entry named); B-23 reworded. The reversal-mirror exemption only takes a hand line off (even chain depth); putting it back is refused. - DocStatus Overpaid and Unattached; aging leaves out credit balances; ControlCheck.attention lists out-of-bounds and unattached documents. - stands_on counts a chain in order; indexes (doc_index, doc_accounts, order_pos, reversed_by) keep the derived figures linear. - Viewer reads a post-dated document as of its own date; one state per row. bounds_kept's side-crossing documented as intended. - Tests: ten new spec_documents scenarios, stronger proptests, store proptest arap_props (live = replay = snapshot at every date, closed months), fuzz ops void/payments with details, a GUI post-dated test; Lean Step.assign / Step.release with unattached_zero kept; model limits stated in docs/testing.md and B-38. Review fixes (CPA and engineering lenses): only an assigned role's account or one holding document lines is a control account (a chart's own 1200 asset stays free); a role can't move onto untagged lines or off document lines (Lean Step.assign); a void's cache never reads as paid; no Decimal sum panics; per-document indexes keep figures linear; a replayed tag matches its side; the feature gate counts payment events; a payment's reversal is never listed as standing; an overpaid document has its own status; the viewer keeps post-dated documents. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T3gXMVt7XJPi6ens1or9Dj
85 lines
6.4 KiB
Markdown
85 lines
6.4 KiB
Markdown
# Specification sources
|
|
|
|
wanderbooks' rules come from documents, not from anyone's memory. This
|
|
directory holds the authorities the engine's specs cite (`docs/spec/rules.md`
|
|
is the rule catalog), and every spec block in the code carries a `SOURCE:`
|
|
line pointing into it.
|
|
|
|
## The authority stack
|
|
|
|
There is no single "bible" of US bookkeeping. Authority is layered, and the
|
|
layers differ in what they cover and in whether we may copy them:
|
|
|
|
| Layer | What it governs | Copyright | Here |
|
|
|---|---|---|---|
|
|
| **Pacioli (1494), Geijsbeek translation (1914)** | The mechanics of double entry: debits equal credits, the trial balance, one money, writing only forward, correcting by opposite entry, closing into capital. No modern standard restates these; they predate every regulator. | Public domain | Vendored verbatim: `sources/pacioli-1494.md` |
|
|
| **IRS: Internal Revenue Code, Treasury Regulations, publications, form instructions** | Records and supporting documents, retention, accounting periods and methods, information returns (1099), capitalization (de minimis, 12-month rule), partners' capital, tax basis of purchased and contributed property (`sources/irs-partnership-basis.md`), payroll taxes, rounding on returns, return line items for tax categories (`sources/irs-tax-lines.md`) | Public domain (17 U.S.C. §105; IRS.gov's content policy) | Vendored verbatim: `sources/irs-*.md`, `sources/us-public-domain-status.md` |
|
|
| **File formats: Intuit (QuickBooks Online bank CSV, QuickBooks Desktop IIF), ECMA-376 Office Open XML, Microsoft Excel limits, Avery label sheets** | What `ledger-import` reads and writes: bank/card CSV layouts and signs, IIF journal entries, how XLSX stores numbers and Excel's 15-digit precision, asset-label sheet geometry (Avery 5160) | © Intuit Inc.; © Ecma International; © Microsoft; © Avery Products Corporation | Cited with short quotes, URLs, and hashes: `sources/intuit-bank-csv.md`, `sources/intuit-iif.md`, `sources/xlsx-numbers.md`, `sources/avery-5160.md` |
|
|
| **FASB Accounting Standards Codification (ASC)** | Authoritative US GAAP: cash flows (ASC 230), revenue and principal vs agent (ASC 606), foreign currency (ASC 830), credit losses and aging (ASC 326), property and depreciation (ASC 360) | © Financial Accounting Foundation | Cited by paragraph with short quotes only (in `rules.md`; the paragraphs read, with where and when, in `sources/fasb-asc.md` and below) |
|
|
| **FASB Concepts Statement No. 8, Chapter 4 (2021)** | Definitions of the five elements (it replaced Concepts Statement 6) | © Financial Accounting Foundation; non-authoritative | Cited with short quotes only |
|
|
| **Textbooks (OpenStax *Principles of Accounting, Vol. 1*)** | Conventions no standard states: normal balances, closing-entry mechanics, straight-line depreciation arithmetic | CC BY-NC-SA 4.0 (incompatible with this repo's license) | Cited with short quotes and attribution only |
|
|
| **Convention or decision** | Where no authority speaks: aging bucket edges, cent rounding among members, closed-period locks | — | Stated as CONVENTION or DECISION, with who decided and when |
|
|
|
|
## How to read a SOURCE line
|
|
|
|
```text
|
|
SOURCE: Pacioli ch. 36 (sources/pacioli-1494.md); IRS Pub. 583 (sources/irs-records.md)
|
|
SOURCE: ASC 830-20-30-1 (cited, rules.md B-3)
|
|
SOURCE: DECISION (the owner, 2026-10-13)
|
|
SOURCE: CONVENTION (QuickBooks aging); nearest authority ASC 326-20-55-38 (illustrative)
|
|
```
|
|
|
|
A rule whose only source is CONVENTION or DECISION is a candidate for a
|
|
human to confirm or overturn; nothing else is.
|
|
|
|
## Rules added later never lock out older books
|
|
|
|
When a rule is tightened (a check added to a command), books written
|
|
before it must still open. Journal replay and the SQLite cross-check read
|
|
history through the engine's `replay_*` commands, which skip checks added
|
|
later; new commands go through the checked ones. Pinned by
|
|
`books_written_under_older_rules_still_open` (ledger-store).
|
|
|
|
## Vendoring rules
|
|
|
|
- Public-domain texts are copied **verbatim** (whitespace normalized), each
|
|
with its URL, retrieval date, and the SHA-256 of the retrieved file, so
|
|
anyone can check the excerpt against the original.
|
|
- Copyrighted sources are cited by paragraph, quoted briefly, never copied.
|
|
- When an authority changes (the IRS revises a publication; a statute is
|
|
amended), add the new text beside the old with its effective date. Rules
|
|
that depend on dates (1099 thresholds) must say which text applies when.
|
|
- Rules that change with the law are registered in
|
|
`crates/ledger-core/src/rules.rs` with the years they are known for and
|
|
a review date. Past what it knows, the engine refuses rather than
|
|
guesses; from the review date, the MCP digest and the viewer flag the
|
|
rule. Whoever updates one (human or agent) vendors the new official
|
|
text here, extends the rule, and sends the change upstream: a pull
|
|
request at https://github.com/swaits/wanderbooks (best), or an issue.
|
|
|
|
## Open: sources we could not verify
|
|
|
|
Read on 2026-10-13 through Deloitte's free DART roadmaps, which reproduce
|
|
ASC text: ASC 230-10-45-16 and -28, 326-20-55-37/38, 606-10-25-23, 45-2,
|
|
55-37/38, 830-20-30-1. Read directly in the ASC basic view on 2026-10-14
|
|
(`sources/fasb-asc.md`): 360-10-35-4, 340-10-05-2/4/5, 210-10-45-1/2/5,
|
|
230-10-45-7/10/12/13/14/15, 606-10-55-36 through 55-38. Read on
|
|
2026-10-20 where public sources reproduce the Codification (EY's FRD on
|
|
the statement of cash flows, July 2026; FASB ASUs 2016-15 and 2016-18;
|
|
Deloitte's public DART Roadmap): ASC 230-10-10-1, 45-1, 45-4, 45-5,
|
|
45-8, 45-9, 45-12(c), 45-13(c), 45-14(a), 45-15(a)/(c), 45-16(a)/(b),
|
|
45-17, 45-24 to 45-26, 45-28 to 45-31, 50-3 to 50-8, and 830-230-45-1;
|
|
each checked again against the same sources in the P3 review (numbers,
|
|
pages and wording hold). Open: 105-10-05-1 to 05-3, read only in their
|
|
2009 text (ASU 2009-01, and as Wiley GAAP 2020 quotes them); their
|
|
current wording is unconfirmed. Also open (P3 surface review, 2026-10-21): ASC 230-10-45-15(f) (debt
|
|
issue costs, cited by B-14 rule 11) is in neither list above; ASC
|
|
606-10-25-31, 25-32 and 55-20 (B-16's over-time method) are not yet read;
|
|
B-15 rule 6 cites ASC 250 with no paragraph; B-17's 606-10-55-39 is in
|
|
neither list. Each is to be read in the ASC basic view and listed in
|
|
`sources/fasb-asc.md` before it is relied on further. Also open (plan
|
|
P4b, 2026-10-23): B-38 cites ASC 310-10, 405-20-40-1 and 606-10-45-4,
|
|
none yet read in the ASC basic view; B-38 keeps the CONVENTION label
|
|
until they are vendored with a SHA-256, as P4b.16 lists with the sources
|
|
B-39 to B-41 will need.
|