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/WL-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
This commit is contained in:
161 files changed
+18938
-1110
No files matched your search
File diff suppressed because it is too large.
Load diff
@@ -27,11 +27,20 @@ impl Mcp {
|
||||
}
|
||||
|
||||
fn spawn_with(data_dir: &std::path::Path, extra: &[&std::ffi::OsStr]) -> Self {
|
||||
Self::spawn_env(data_dir, extra, &[])
|
||||
}
|
||||
|
||||
fn spawn_env(
|
||||
data_dir: &std::path::Path,
|
||||
extra: &[&std::ffi::OsStr],
|
||||
env: &[(&str, &std::path::Path)],
|
||||
) -> Self {
|
||||
let bin = env!("CARGO_BIN_EXE_ledger-mcp");
|
||||
let mut child = Command::new(bin)
|
||||
.arg("--data-dir")
|
||||
.arg(data_dir)
|
||||
.args(extra)
|
||||
.envs(env.iter().map(|(k, v)| (*k, v.as_os_str())))
|
||||
.stdin(Stdio::piped())
|
||||
.stdout(Stdio::piped())
|
||||
.stderr(Stdio::null())
|
||||
@@ -147,7 +156,7 @@ fn mcp_end_to_end_over_stdio() {
|
||||
// Tool listing: the narrow tools; chart is read-only.
|
||||
let list = mcp.request("tools/list", json!({}));
|
||||
let tools = list["result"]["tools"].as_array().unwrap();
|
||||
assert_eq!(tools.len(), 93, "expected 93 tools, got {}", tools.len());
|
||||
assert_eq!(tools.len(), 94, "expected 94 tools, got {}", tools.len());
|
||||
let chart = tools.iter().find(|t| t["name"] == "books.chart").unwrap();
|
||||
assert_eq!(chart["annotations"]["readOnlyHint"], true);
|
||||
assert!(
|
||||
@@ -745,6 +754,541 @@ fn mcp_resources_over_stdio() {
|
||||
assert!(resp.get("error").is_some());
|
||||
}
|
||||
|
||||
/// `--import-root` replaces the default import root (the downloads
|
||||
/// folder): a file in the named folder is filed; one beside it is not.
|
||||
#[test]
|
||||
fn import_root_flag_replaces_the_defaults() {
|
||||
let dir = test_dir("import-root");
|
||||
let inbox = dir.with_extension("inbox");
|
||||
std::fs::create_dir_all(&inbox).unwrap();
|
||||
let inside = inbox.join("receipt.txt");
|
||||
let temp = dir.with_extension("elsewhere.txt");
|
||||
for p in [&inside, &temp] {
|
||||
std::fs::write(p, b"a receipt").unwrap();
|
||||
}
|
||||
let mut mcp = Mcp::spawn_with(
|
||||
&dir.join("books-data"),
|
||||
&[std::ffi::OsStr::new("--import-root"), inbox.as_os_str()],
|
||||
);
|
||||
mcp.request(
|
||||
"initialize",
|
||||
json!({
|
||||
"protocolVersion": "2025-06-18",
|
||||
"capabilities": {},
|
||||
"clientInfo": {"name": "smoke-test", "version": "0.1.0"},
|
||||
}),
|
||||
);
|
||||
mcp.notify("notifications/initialized");
|
||||
let ok = mcp.call(
|
||||
"books.import_local_file",
|
||||
json!({"path": inside.to_str().unwrap(), "category": "receipt"}),
|
||||
);
|
||||
assert_eq!(ok["file_name"], "receipt.txt");
|
||||
let why = mcp.call_err(
|
||||
"books.import_local_file",
|
||||
json!({"path": temp.to_str().unwrap(), "category": "receipt"}),
|
||||
);
|
||||
assert!(
|
||||
why.contains("no such file in the server's import folders"),
|
||||
"{why}"
|
||||
);
|
||||
}
|
||||
|
||||
/// Start a session: initialize, then initialized.
|
||||
fn init(mcp: &mut Mcp) -> Value {
|
||||
let init = mcp.request(
|
||||
"initialize",
|
||||
json!({
|
||||
"protocolVersion": "2025-06-18",
|
||||
"capabilities": {},
|
||||
"clientInfo": {"name": "smoke-test", "version": "0.1.0"},
|
||||
}),
|
||||
);
|
||||
mcp.notify("notifications/initialized");
|
||||
init
|
||||
}
|
||||
|
||||
/// Through the real tools, inside a root (local_files.rs INVARIANTS 1-3,
|
||||
/// Protected::of; S1 and S5 of the P0 review, I of round 2): the key
|
||||
/// file in force, moved into the root after the server started (a root
|
||||
/// holding the books or a key is refused at startup: startup.rs), is
|
||||
/// sealed with what its link leads to and their folders, but never the
|
||||
/// root itself; links in the root to the journal or a vault record lead
|
||||
/// outside it, and get the one refusal a missing file gets (INVARIANT 2).
|
||||
/// books.import_local_file and books.set_w9's w9_file_path agree.
|
||||
#[test]
|
||||
fn import_local_file_and_set_w9_refuse_the_key_vault_and_journal_inside_a_root() {
|
||||
use std::os::unix::fs::symlink;
|
||||
let dir = test_dir("sealed-in-root");
|
||||
let root = dir.join("root");
|
||||
let books = dir.join("books");
|
||||
let data = books.join("books-data");
|
||||
let tray = root.join("drop");
|
||||
let config = dir.join("config");
|
||||
for d in [
|
||||
&data,
|
||||
&tray,
|
||||
&root.join("alias"),
|
||||
&root.join("hidden"),
|
||||
&config.join("wanderbooks"),
|
||||
] {
|
||||
std::fs::create_dir_all(d).unwrap();
|
||||
}
|
||||
std::fs::write(root.join("hidden/real.key"), "ab".repeat(32)).unwrap();
|
||||
std::fs::write(root.join("hidden/notes.pdf"), b"%PDF beside the key").unwrap();
|
||||
std::fs::write(root.join("loose.key"), "ef".repeat(32)).unwrap();
|
||||
symlink(root.join("hidden/real.key"), root.join("alias/vault.key")).unwrap();
|
||||
std::fs::write(config.join("wanderbooks/vault.key"), "cd".repeat(32)).unwrap();
|
||||
let settings = |key: &std::path::Path| {
|
||||
std::fs::write(
|
||||
books.join("wanderbooks.toml"),
|
||||
format!(
|
||||
"[company]\nname = \"Sealed Co\"\n[vault]\nkey_file = \"{}\"\n",
|
||||
key.display()
|
||||
),
|
||||
)
|
||||
.unwrap();
|
||||
};
|
||||
// Started with the default key (outside the root), so it starts.
|
||||
settings(&config.join("wanderbooks/vault.key"));
|
||||
std::fs::write(tray.join("receipt.pdf"), b"%PDF a receipt").unwrap();
|
||||
std::fs::write(tray.join("w9.pdf"), b"%PDF\xff W-9 scan").unwrap();
|
||||
let root_arg = [std::ffi::OsStr::new("--import-root"), root.as_os_str()];
|
||||
let mut mcp = Mcp::spawn_env(&data, &root_arg, &[("XDG_CONFIG_HOME", &config)]);
|
||||
init(&mut mcp);
|
||||
mcp.call(
|
||||
"books.add_party",
|
||||
json!({"name": "Acme", "roles": ["contractor"]}),
|
||||
);
|
||||
mcp.call(
|
||||
"books.set_tin",
|
||||
json!({"party": "Acme", "tin": "571-93-2846", "tin_type": "ssn"}),
|
||||
);
|
||||
let journal = data.join(ledger_store::JOURNAL_FILE);
|
||||
let vault_record = books
|
||||
.join("vault")
|
||||
.read_dir()
|
||||
.unwrap()
|
||||
.map(|e| e.unwrap().path())
|
||||
.find(|p| p.extension().is_some_and(|e| e == "bin"))
|
||||
.unwrap();
|
||||
for (name, to) in [
|
||||
("journal-link.pdf", journal.clone()),
|
||||
("record-link.pdf", vault_record.clone()),
|
||||
("default-key-link.pdf", config.join("wanderbooks/vault.key")),
|
||||
("dangling-link.pdf", config.join("wanderbooks/missing.key")),
|
||||
] {
|
||||
symlink(&to, tray.join(name)).unwrap();
|
||||
}
|
||||
// The key in force moves into the root (a link, alias/vault.key ->
|
||||
// hidden/real.key); the settings reload.
|
||||
settings(&root.join("alias/vault.key"));
|
||||
let refuse = |mcp: &mut Mcp, path: &std::path::Path, why: &str| {
|
||||
let path = path.to_str().unwrap();
|
||||
let err = mcp.call_err(
|
||||
"books.import_local_file",
|
||||
json!({"path": path, "category": "document"}),
|
||||
);
|
||||
assert!(err.contains(why), "{path}: {err}");
|
||||
assert!(!err.contains(dir.to_str().unwrap()), "names a path: {err}");
|
||||
let err = mcp.call_err(
|
||||
"books.set_w9",
|
||||
json!({"party": "Acme", "received_on": "2026-01-03", "entity_type": "Individual",
|
||||
"tin": "571-93-2846", "tin_type": "ssn", "w9_file_path": path}),
|
||||
);
|
||||
assert!(err.contains(why), "{path}: {err}");
|
||||
};
|
||||
for p in [
|
||||
root.join("hidden/real.key"),
|
||||
root.join("hidden/notes.pdf"),
|
||||
root.join("alias/vault.key"),
|
||||
] {
|
||||
refuse(&mut mcp, &p, "belongs to the books or the TIN vault");
|
||||
}
|
||||
for p in [
|
||||
journal.clone(),
|
||||
vault_record,
|
||||
config.join("wanderbooks/vault.key"),
|
||||
tray.join("journal-link.pdf"),
|
||||
tray.join("record-link.pdf"),
|
||||
tray.join("default-key-link.pdf"),
|
||||
tray.join("dangling-link.pdf"),
|
||||
tray.join("missing.pdf"),
|
||||
] {
|
||||
refuse(
|
||||
&mut mcp,
|
||||
&p,
|
||||
"no such file in the server's import folders (by default your downloads folder)",
|
||||
);
|
||||
}
|
||||
// A key kept loose in the root itself seals the key, not the root.
|
||||
settings(&root.join("loose.key"));
|
||||
refuse(
|
||||
&mut mcp,
|
||||
&root.join("loose.key"),
|
||||
"belongs to the books or the TIN vault",
|
||||
);
|
||||
// Ordinary files in the root are filed (with the key the vault was
|
||||
// made with back in force).
|
||||
mcp.call(
|
||||
"books.import_local_file",
|
||||
json!({"path": tray.join("receipt.pdf").to_str().unwrap(), "category": "receipt"}),
|
||||
);
|
||||
// A link is filed under the name and type of the file it leads to.
|
||||
std::fs::write(tray.join("photo.png"), b"\x89PNG a photo").unwrap();
|
||||
symlink(tray.join("photo.png"), tray.join("named-like.pdf")).unwrap();
|
||||
let filed = mcp.call(
|
||||
"books.import_local_file",
|
||||
json!({"path": tray.join("named-like.pdf").to_str().unwrap(), "category": "receipt"}),
|
||||
);
|
||||
assert_eq!(filed["file_name"], "photo.png");
|
||||
let back = mcp.call(
|
||||
"books.get_receipt",
|
||||
json!({"attachment_id": filed["attachment_id"]}),
|
||||
);
|
||||
assert_eq!(back["mime_type"], "image/png", "{back}");
|
||||
settings(&config.join("wanderbooks/vault.key"));
|
||||
mcp.call(
|
||||
"books.set_w9",
|
||||
json!({"party": "Acme", "received_on": "2026-01-03", "entity_type": "Individual",
|
||||
"tin": "571-93-2846", "tin_type": "ssn",
|
||||
"w9_file_path": tray.join("w9.pdf").to_str().unwrap()}),
|
||||
);
|
||||
}
|
||||
|
||||
/// Outputs that carry full TINs (books.get_w9, books.vendor_1099 with
|
||||
/// include_tins, books.export_cpa_package with TINs) are never written
|
||||
/// into an import root, and a copy of one moved into a root is refused by
|
||||
/// its bytes: a TIN-bearing file can't be filed back in as a receipt and
|
||||
/// read out through books.get_receipt (S7 of the P0 review, 2026-10-16).
|
||||
#[test]
|
||||
fn tin_bearing_files_never_land_where_they_could_be_filed_back_in() {
|
||||
let dir = test_dir("tin-files");
|
||||
let root = dir.join("inbox");
|
||||
let out = dir.join("out");
|
||||
let config = dir.join("config");
|
||||
for d in [&root, &out, &config] {
|
||||
std::fs::create_dir_all(d).unwrap();
|
||||
}
|
||||
std::fs::write(root.join("w9.pdf"), b"%PDF W-9 TIN 571-93-2846").unwrap();
|
||||
let root_arg = [std::ffi::OsStr::new("--import-root"), root.as_os_str()];
|
||||
let mut mcp = Mcp::spawn_env(
|
||||
&dir.join("books").join("books-data"),
|
||||
&root_arg,
|
||||
&[("XDG_CONFIG_HOME", &config)],
|
||||
);
|
||||
init(&mut mcp);
|
||||
mcp.call(
|
||||
"books.add_account",
|
||||
json!({"code": "1000", "name": "Cash", "account_type": "asset"}),
|
||||
);
|
||||
mcp.call(
|
||||
"books.add_party",
|
||||
json!({"name": "Acme", "roles": ["contractor"]}),
|
||||
);
|
||||
mcp.call(
|
||||
"books.set_w9",
|
||||
json!({"party": "Acme", "received_on": "2026-01-03", "entity_type": "Individual",
|
||||
"tin": "571-93-2846", "tin_type": "ssn",
|
||||
"w9_file_path": root.join("w9.pdf").to_str().unwrap()}),
|
||||
);
|
||||
let in_root = |name: &str| root.join(name).to_str().unwrap().to_string();
|
||||
for (tool, args) in [
|
||||
(
|
||||
"books.get_w9",
|
||||
json!({"party": "Acme", "save_to": in_root("copy.pdf")}),
|
||||
),
|
||||
(
|
||||
"books.vendor_1099",
|
||||
json!({"year": 2026, "include_tins": true, "save_csv_to": in_root("1099.csv")}),
|
||||
),
|
||||
(
|
||||
"books.export_cpa_package",
|
||||
json!({"cash_accounts": ["1000"], "save_to": in_root("cpa.zip")}),
|
||||
),
|
||||
(
|
||||
"books.export_cpa_package",
|
||||
json!({"cash_accounts": ["1000"], "save_to": root.to_str().unwrap()}),
|
||||
),
|
||||
] {
|
||||
let why = mcp.call_err(tool, args);
|
||||
assert!(
|
||||
why.contains("never saved in the server's import folders"),
|
||||
"{tool}: {why}"
|
||||
);
|
||||
}
|
||||
assert_eq!(
|
||||
std::fs::read_dir(&root).unwrap().count(),
|
||||
1,
|
||||
"wrote into the root"
|
||||
);
|
||||
// Saved elsewhere, then moved into the root: refused by its bytes.
|
||||
let w9 = out.join("copy.pdf");
|
||||
mcp.call(
|
||||
"books.get_w9",
|
||||
json!({"party": "Acme", "save_to": w9.to_str().unwrap()}),
|
||||
);
|
||||
let csv = out.join("1099.csv");
|
||||
mcp.call(
|
||||
"books.vendor_1099",
|
||||
json!({"year": 2026, "include_tins": true, "save_csv_to": csv.to_str().unwrap()}),
|
||||
);
|
||||
for (from, name) in [(&w9, "receipt.pdf"), (&csv, "statement.csv")] {
|
||||
std::fs::copy(from, root.join(name)).unwrap();
|
||||
let why = mcp.call_err(
|
||||
"books.import_local_file",
|
||||
json!({"path": in_root(name), "category": "receipt"}),
|
||||
);
|
||||
assert!(why.contains("wrote with full TINs"), "{why}");
|
||||
}
|
||||
// Without TINs, the 1099 worksheet may go anywhere a file may.
|
||||
mcp.call(
|
||||
"books.vendor_1099",
|
||||
json!({"year": 2026, "save_csv_to": in_root("plain.csv")}),
|
||||
);
|
||||
}
|
||||
|
||||
/// The connect text and the receipt rule show a few account codes of each
|
||||
/// kind, shortened, and say books.settings lists them: it does, every one,
|
||||
/// uncut, so no account the rule names is out of the agent's reach.
|
||||
#[test]
|
||||
fn every_receipt_account_left_out_of_the_connect_text_is_in_books_settings() {
|
||||
let dir = test_dir("receipt-accounts");
|
||||
let long = "6000-A-CODE-LONGER-THAN-ANY-RULE-SHOWS-IT";
|
||||
let required: Vec<String> = std::iter::once(long.to_string())
|
||||
.chain((1..20).map(|i| format!("{}", 6000 + i)))
|
||||
.collect();
|
||||
let exempt: Vec<String> = (0..12).map(|i| format!("{}", 1100 + i)).collect();
|
||||
std::fs::write(
|
||||
dir.join("config.json"),
|
||||
json!({"receipt_policy": {"require_receipts_above": "0.00",
|
||||
"receipt_required_accounts": required, "receipt_exempt_accounts": exempt}})
|
||||
.to_string(),
|
||||
)
|
||||
.unwrap();
|
||||
let mut mcp = Mcp::spawn(&dir);
|
||||
let init = mcp.request(
|
||||
"initialize",
|
||||
json!({
|
||||
"protocolVersion": "2025-06-18",
|
||||
"capabilities": {},
|
||||
"clientInfo": {"name": "smoke-test", "version": "0.1.0"},
|
||||
}),
|
||||
);
|
||||
mcp.notify("notifications/initialized");
|
||||
let connect = init["result"]["instructions"].as_str().unwrap().to_string();
|
||||
assert!(connect.contains("books.settings lists"), "{connect}");
|
||||
let settings = mcp.call("books.settings", json!({}));
|
||||
let rule = settings["receipt_rule"].as_str().unwrap();
|
||||
assert!(rule.contains("books.settings lists them"), "{rule}");
|
||||
let listed = |key: &str| -> Vec<String> {
|
||||
settings[key]
|
||||
.as_array()
|
||||
.unwrap_or_else(|| panic!("books.settings has no {key}: {settings}"))
|
||||
.iter()
|
||||
.map(|c| c.as_str().unwrap().to_string())
|
||||
.collect()
|
||||
};
|
||||
assert_eq!(listed("receipt_required_accounts"), required);
|
||||
assert_eq!(listed("receipt_exempt_accounts"), exempt);
|
||||
// Some codes really are left out of the connect text and the rule,
|
||||
// and the long one is shown cut there, whole here.
|
||||
let left_out: Vec<&String> = required
|
||||
.iter()
|
||||
.chain(&exempt)
|
||||
.filter(|c| !connect.contains(c.as_str()))
|
||||
.collect();
|
||||
assert!(left_out.len() > 20, "{connect}");
|
||||
assert!(!rule.contains(long), "{rule}");
|
||||
for code in left_out {
|
||||
assert!(
|
||||
listed("receipt_required_accounts").contains(code)
|
||||
|| listed("receipt_exempt_accounts").contains(code),
|
||||
"{code} is in neither the connect text nor books.settings"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/// A bare `books://digest` (no `since`) reads this month so far: an entry
|
||||
/// dated this month is in it, one dated last month is not (plan P0).
|
||||
/// "This month" is the server's: read from its own bare digest, never this
|
||||
/// process's clock, and the run starts over on fresh books if the month
|
||||
/// turns while it runs (midnight on the 1st).
|
||||
#[test]
|
||||
fn digest_resource_bare_reads() {
|
||||
for attempt in 0..3 {
|
||||
if digest_bare_reads_once(attempt) {
|
||||
return;
|
||||
}
|
||||
}
|
||||
panic!("the month kept turning while the test ran");
|
||||
}
|
||||
|
||||
/// One run of `digest_resource_bare_reads`: false if the server's month
|
||||
/// turned during it (nothing is checked then).
|
||||
fn digest_bare_reads_once(attempt: u32) -> bool {
|
||||
let dir = test_dir(&format!("digest-bare-{attempt}"));
|
||||
let mut mcp = Mcp::spawn(&dir.join("books-data"));
|
||||
mcp.request(
|
||||
"initialize",
|
||||
json!({
|
||||
"protocolVersion": "2025-06-18",
|
||||
"capabilities": {},
|
||||
"clientInfo": {"name": "smoke-test", "version": "0.1.0"},
|
||||
}),
|
||||
);
|
||||
mcp.notify("notifications/initialized");
|
||||
let since = |mcp: &mut Mcp, uri: &str| -> Value {
|
||||
let read = mcp.request("resources/read", json!({"uri": uri}));
|
||||
let text = read["result"]["contents"][0]["text"].as_str().unwrap();
|
||||
serde_json::from_str(text).unwrap()
|
||||
};
|
||||
// The server's first day of this month.
|
||||
let first: chrono::NaiveDate = since(&mut mcp, "books://digest")["since"]
|
||||
.as_str()
|
||||
.unwrap()
|
||||
.parse()
|
||||
.unwrap();
|
||||
assert_eq!(chrono::Datelike::day(&first), 1, "{first}");
|
||||
let before = first.pred_opt().unwrap();
|
||||
for (code, name, typ) in [("1000", "Cash", "asset"), ("6000", "Fees", "expense")] {
|
||||
mcp.call(
|
||||
"books.add_account",
|
||||
json!({"code": code, "name": name, "account_type": typ}),
|
||||
);
|
||||
}
|
||||
for (date, what) in [(first, "this month"), (before, "last month")] {
|
||||
let id = mcp.call(
|
||||
"books.draft_entry",
|
||||
json!({"date": date.to_string(), "description": what}),
|
||||
)["entry_id"]
|
||||
.as_u64()
|
||||
.unwrap();
|
||||
for (side, code) in [("debit", "6000"), ("credit", "1000")] {
|
||||
mcp.call(
|
||||
"books.add_line",
|
||||
json!({"entry_id": id, "account": code, "side": side, "amount": "5.00"}),
|
||||
);
|
||||
}
|
||||
mcp.call(
|
||||
"books.post_entry",
|
||||
json!({"entry_id": id, "confirmed": true}),
|
||||
);
|
||||
}
|
||||
// Bare, and with an empty since=, alike (the default date itself is
|
||||
// pinned on every day of a month in server.rs's unit test).
|
||||
for uri in ["books://digest", "books://digest?since="] {
|
||||
let digest = since(&mut mcp, uri);
|
||||
if digest["since"] != first.to_string() {
|
||||
return false;
|
||||
}
|
||||
let seen: Vec<&str> = digest["entries"]
|
||||
.as_array()
|
||||
.unwrap()
|
||||
.iter()
|
||||
.map(|e| e["description"].as_str().unwrap())
|
||||
.collect();
|
||||
assert_eq!(seen, ["this month"], "{uri}");
|
||||
}
|
||||
true
|
||||
}
|
||||
|
||||
/// The handbook is one tool and one resource per section, with the
|
||||
/// receipt rule in force rendered in; the connect text points to it.
|
||||
#[test]
|
||||
fn handbook_tool_and_resources_over_stdio() {
|
||||
let dir = test_dir("handbook");
|
||||
let mut mcp = Mcp::spawn(&dir.join("books-data"));
|
||||
let init = mcp.request(
|
||||
"initialize",
|
||||
json!({
|
||||
"protocolVersion": "2025-06-18",
|
||||
"capabilities": {},
|
||||
"clientInfo": {"name": "smoke-test", "version": "0.1.0"},
|
||||
}),
|
||||
);
|
||||
let instructions = init["result"]["instructions"].as_str().unwrap();
|
||||
assert!(instructions.chars().count() <= 1400);
|
||||
// The first 512 characters (not bytes: a name may be multibyte).
|
||||
let lead: String = instructions.chars().take(512).collect();
|
||||
assert!(lead.contains("books.handbook"));
|
||||
mcp.notify("notifications/initialized");
|
||||
let index = mcp.call("books.handbook", json!({}));
|
||||
let sections = index["sections"].as_array().unwrap();
|
||||
assert_eq!(sections[0]["id"], "contract");
|
||||
assert!(index["read_first"].as_str().unwrap().contains("contract"));
|
||||
assert_eq!(index["section"], Value::Null);
|
||||
// The schema names every section, and "all".
|
||||
let list = mcp.request("tools/list", json!({}));
|
||||
let tool = list["result"]["tools"]
|
||||
.as_array()
|
||||
.unwrap()
|
||||
.iter()
|
||||
.find(|t| t["name"] == "books.handbook")
|
||||
.unwrap()
|
||||
.clone();
|
||||
let said = tool["inputSchema"]["properties"]["section"]["description"]
|
||||
.as_str()
|
||||
.unwrap()
|
||||
.to_string();
|
||||
for s in sections {
|
||||
let id = s["id"].as_str().unwrap();
|
||||
assert!(said.contains(id), "the schema doesn't name {id}: {said}");
|
||||
}
|
||||
assert!(said.contains("\"all\""), "{said}");
|
||||
// Section "all": every section's text, in order, under its own title.
|
||||
let all = mcp.call("books.handbook", json!({"section": "all"}));
|
||||
assert_eq!(all["section"]["title"], "The whole handbook");
|
||||
let text = all["section"]["text"].as_str().unwrap();
|
||||
let mut at = 0;
|
||||
for s in sections {
|
||||
let one = mcp.call("books.handbook", json!({"section": s["id"]}));
|
||||
// A section is titled by its heading, as the index lists it.
|
||||
assert_eq!(one["section"]["title"], s["title"]);
|
||||
let part = one["section"]["text"].as_str().unwrap();
|
||||
assert_eq!(
|
||||
part.lines().next().unwrap(),
|
||||
format!("# {}", s["title"].as_str().unwrap())
|
||||
);
|
||||
at += text[at..].find(part).expect("a section missing from all") + part.len();
|
||||
}
|
||||
let one = mcp.call(
|
||||
"books.handbook",
|
||||
json!({"section": "evidence-and-receipts"}),
|
||||
);
|
||||
let text = one["section"]["text"].as_str().unwrap();
|
||||
assert!(text.contains("needs at least one receipt"), "{text}");
|
||||
assert!(!text.contains("{evidence_rule}"));
|
||||
let why = mcp.call_err("books.handbook", json!({"section": "nope"}));
|
||||
assert!(why.contains("contract"), "{why}");
|
||||
|
||||
let list = mcp.request("resources/list", json!({}));
|
||||
let uris: Vec<&str> = list["result"]["resources"]
|
||||
.as_array()
|
||||
.unwrap()
|
||||
.iter()
|
||||
.map(|r| r["uri"].as_str().unwrap())
|
||||
.collect();
|
||||
assert!(uris.contains(&"books://handbook"));
|
||||
for s in sections {
|
||||
let uri = s["uri"].as_str().unwrap();
|
||||
assert!(uris.contains(&uri), "{uri} not listed");
|
||||
let read = mcp.request("resources/read", json!({"uri": uri}));
|
||||
let c = &read["result"]["contents"][0];
|
||||
assert_eq!(c["mimeType"], "text/markdown");
|
||||
assert_eq!(
|
||||
c["text"].as_str().unwrap().chars().count() as u64,
|
||||
s["chars"].as_u64().unwrap()
|
||||
);
|
||||
}
|
||||
let read = mcp.request("resources/read", json!({"uri": "books://handbook"}));
|
||||
let idx: Value =
|
||||
serde_json::from_str(read["result"]["contents"][0]["text"].as_str().unwrap()).unwrap();
|
||||
assert_eq!(idx["sections"].as_array().unwrap().len(), sections.len());
|
||||
let resp = mcp.request_raw("resources/read", json!({"uri": "books://handbook/nope"}));
|
||||
assert!(resp.get("error").is_some());
|
||||
}
|
||||
|
||||
fn base64_like(bytes: &[u8]) -> String {
|
||||
const ALPHABET: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
|
||||
let mut out = String::new();
|
||||
@@ -1603,7 +2147,8 @@ fn mcp_vendor_1099_over_stdio() {
|
||||
for needle in [
|
||||
"only through 2026",
|
||||
"official source",
|
||||
"github.com/swaits/wanderbooks",
|
||||
"irs.gov",
|
||||
"tell the human",
|
||||
] {
|
||||
assert!(why.contains(needle), "missing {needle:?} in: {why}");
|
||||
}
|
||||
|
||||
@@ -85,6 +85,14 @@ fn books_toml(dir: &Path, threshold: &str) -> PathBuf {
|
||||
path
|
||||
}
|
||||
|
||||
/// The server's import root, beside the books (never the books dir): files
|
||||
/// given to books.import_local_file.
|
||||
fn inbox(dir: &Path) -> PathBuf {
|
||||
let inbox = dir.with_extension("inbox");
|
||||
std::fs::create_dir_all(&inbox).unwrap();
|
||||
inbox
|
||||
}
|
||||
|
||||
fn data_dir(dir: &Path) -> PathBuf {
|
||||
dir.join("books-data")
|
||||
}
|
||||
@@ -99,6 +107,8 @@ impl Mcp {
|
||||
.arg(data_dir(dir))
|
||||
.arg("--books-toml")
|
||||
.arg(&toml)
|
||||
.arg("--import-root")
|
||||
.arg(inbox(dir))
|
||||
.env("XDG_RUNTIME_DIR", &run)
|
||||
.stdin(Stdio::piped())
|
||||
.stdout(Stdio::piped())
|
||||
@@ -1868,6 +1878,14 @@ fn digest_reports_journal_repairs_since_the_date() {
|
||||
assert_eq!(repairs.len(), 1, "the digest reports it: {out}");
|
||||
assert_eq!(repairs[0]["at"], want[0].0.as_str());
|
||||
assert_eq!(repairs[0]["bytes"], json!(want[0].1));
|
||||
// Only the stamp the bytes were set aside under: never the journal's
|
||||
// file name (plan I-12).
|
||||
let stamp = want[0].2.rsplit_once(".torn.").unwrap().1;
|
||||
assert_eq!(repairs[0]["set_aside"], stamp);
|
||||
assert!(
|
||||
!out.to_string().contains(ledger_store::JOURNAL_FILE),
|
||||
"{out}"
|
||||
);
|
||||
let mut m = Mcp::start(&dir, "1000000.00");
|
||||
let later = m.ok("books.digest", json!({"since": "2999-01-01"}));
|
||||
assert_eq!(later["journal_repairs"], json!([]), "none since 2999");
|
||||
@@ -2115,7 +2133,10 @@ fn receipts_and_documents_round_trip() {
|
||||
json!({"category": "legal", "file_name": "oa.png", "mime_type": "image/png",
|
||||
"content_base64": b64e(second), "description": "Operating agreement"}),
|
||||
);
|
||||
let local_doc = dir.join("ein-letter.pdf");
|
||||
// Local files come from outside the books, in the server's import
|
||||
// folder (local_files.rs).
|
||||
let inbox = inbox(&dir);
|
||||
let local_doc = inbox.join("ein-letter.pdf");
|
||||
std::fs::write(&local_doc, b"EIN letter bytes").unwrap();
|
||||
let c = m.ok(
|
||||
"books.import_local_file",
|
||||
@@ -2123,7 +2144,7 @@ fn receipts_and_documents_round_trip() {
|
||||
"document_category": "tax", "description": "IRS CP 575"}),
|
||||
);
|
||||
assert_eq!(c["file_name"], "ein-letter.pdf");
|
||||
let local_receipt = dir.join("scan.png");
|
||||
let local_receipt = inbox.join("scan.png");
|
||||
std::fs::write(&local_receipt, b"a scanned receipt").unwrap();
|
||||
let r = m.ok(
|
||||
"books.import_local_file",
|
||||
@@ -2135,6 +2156,18 @@ fn receipts_and_documents_round_trip() {
|
||||
"books.import_local_file",
|
||||
json!({"path": local_receipt.to_str().unwrap(), "category": "photo"}),
|
||||
);
|
||||
// Nothing of the books is ever read back in through a path: outside
|
||||
// the import folders, it gets the one refusal any path there gets.
|
||||
let journal = data_dir(&dir).join(ledger_store::JOURNAL_FILE);
|
||||
for p in [journal, dir.join("wanderbooks-1000000.00.toml")] {
|
||||
assert!(p.exists());
|
||||
let why = m.refuse(
|
||||
"books.import_local_file",
|
||||
json!({"path": p.to_str().unwrap(), "category": "document"}),
|
||||
);
|
||||
assert!(why.contains("import folders"), "{why}");
|
||||
assert!(!why.contains(dir.to_str().unwrap()), "names a path: {why}");
|
||||
}
|
||||
|
||||
// (result, bytes, file name, MIME type, entry, description)
|
||||
type Case<'a> = (&'a Value, &'a [u8], &'a str, &'a str, Option<u64>, &'a str);
|
||||
@@ -2217,6 +2250,18 @@ fn receipts_and_documents_round_trip() {
|
||||
fn uploads_up_to_25_mib_are_accepted_and_no_more() {
|
||||
const LIMIT: usize = 25 * 1024 * 1024;
|
||||
let dir = test_dir("limits");
|
||||
// Over 50 MB of books: removed however the test ends (the system temp
|
||||
// dir is often RAM, and a mutation run starts this test hundreds of
|
||||
// times).
|
||||
struct Cleanup(Vec<PathBuf>);
|
||||
impl Drop for Cleanup {
|
||||
fn drop(&mut self) {
|
||||
for d in &self.0 {
|
||||
let _ = std::fs::remove_dir_all(d);
|
||||
}
|
||||
}
|
||||
}
|
||||
let _cleanup = Cleanup(vec![dir.clone(), inbox(&dir)]);
|
||||
let s = new_store(&dir);
|
||||
drop(s);
|
||||
let mut m = Mcp::start(&dir, "1000000.00");
|
||||
@@ -2247,7 +2292,7 @@ fn uploads_up_to_25_mib_are_accepted_and_no_more() {
|
||||
}
|
||||
|
||||
for (n, accepted) in [(2 * 1024 * 1024, true), (LIMIT, true), (LIMIT + 1, false)] {
|
||||
let path = dir.join(format!("local-{n}.bin"));
|
||||
let path = inbox(&dir).join(format!("local-{n}.bin"));
|
||||
std::fs::write(&path, vec![b'c' ^ (n % 7) as u8; n]).unwrap();
|
||||
let args = json!({"path": path.to_str().unwrap(), "category": "receipt"});
|
||||
if accepted {
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
//! binary.
|
||||
//!
|
||||
//! Expected behavior comes only from the GOAL/SOURCE/INVARIANTS blocks of
|
||||
//! `src/server.rs` and `src/policy.rs`, the server's `INSTRUCTIONS`,
|
||||
//! `src/server.rs` and `src/policy.rs`, the server's connect text and handbook,
|
||||
//! `docs/mcp-interface.md`, `docs/spec/sources/{mcp-tools,jsonrpc-2.0,
|
||||
//! irs-records}.md`, and the server's own `tools/list` (the declared
|
||||
//! interface: names, input and output schemas). Where those are silent the
|
||||
@@ -13,12 +13,15 @@
|
||||
//! 2.0 §5); a refused call (isError or a JSON-RPC error) leaves
|
||||
//! `journal.jsonl` byte-identical (server invariant 2); a success has
|
||||
//! `structuredContent` that validates against the tool's `outputSchema`
|
||||
//! and the same JSON in a text block (invariant 1); and no money key holds
|
||||
//! a JSON number or a string outside `^-?\d+\.\d{2,}$` (invariant 3).
|
||||
//! and the same JSON in a text block (invariant 1); no money key holds
|
||||
//! a JSON number or a string outside `^-?\d+\.\d{2,}$` (invariant 3);
|
||||
//! and a tool annotated readOnlyHint leaves the journal and the set of
|
||||
//! files under the data dir as they were, success or refusal (plan 4.9,
|
||||
//! "Annotations (P0)": the hint is true in behaviour).
|
||||
|
||||
use proptest::prelude::*;
|
||||
use serde_json::{Value, json};
|
||||
use std::collections::{BTreeSet, HashMap};
|
||||
use std::collections::{BTreeMap, BTreeSet, HashMap};
|
||||
use std::io::{BufRead, BufReader, Write};
|
||||
use std::path::{Path, PathBuf};
|
||||
use std::process::{Child, ChildStdin, Command, Stdio};
|
||||
@@ -152,6 +155,8 @@ struct Mcp {
|
||||
validators: HashMap<String, jsonschema::Validator>,
|
||||
/// Tools that returned a success at least once.
|
||||
exercised: BTreeSet<String>,
|
||||
/// readOnlyHint tools that succeeded and were seen to change nothing.
|
||||
read_only_checked: BTreeSet<String>,
|
||||
/// Invariant 3 (amounts out) violations: `tool: path = value`.
|
||||
money_violations: Vec<String>,
|
||||
}
|
||||
@@ -177,6 +182,14 @@ fn test_dir(name: &str) -> PathBuf {
|
||||
|
||||
/// A directory beside the books dir `dir`, outside it (vault keys, files
|
||||
/// with TINs).
|
||||
/// The import root beside the books dir `dir`: files the tests hand the
|
||||
/// server by path (books.import_local_file, books.set_w9 w9_file_path).
|
||||
fn inbox(dir: &Path) -> PathBuf {
|
||||
let d = dir.with_extension("inbox");
|
||||
std::fs::create_dir_all(&d).unwrap();
|
||||
d
|
||||
}
|
||||
|
||||
fn outside(dir: &Path) -> PathBuf {
|
||||
let d = PathBuf::from(format!("{}-outside", dir.display()));
|
||||
std::fs::create_dir_all(&d).unwrap();
|
||||
@@ -206,6 +219,10 @@ fn spawn_child(dir: &Path, toml: &Path) -> Child {
|
||||
.arg(dir.join("books-data"))
|
||||
.arg("--books-toml")
|
||||
.arg(toml)
|
||||
// Local files come only from here (the default is the downloads
|
||||
// folder): never the books, never where the server writes.
|
||||
.arg("--import-root")
|
||||
.arg(inbox(dir))
|
||||
// books.show writes a viewer request here; keep it out of the
|
||||
// user's real runtime dir.
|
||||
.env("XDG_RUNTIME_DIR", &run)
|
||||
@@ -243,6 +260,7 @@ impl Mcp {
|
||||
schemas: HashMap::new(),
|
||||
validators: HashMap::new(),
|
||||
exercised: BTreeSet::new(),
|
||||
read_only_checked: BTreeSet::new(),
|
||||
money_violations: Vec::new(),
|
||||
};
|
||||
let init = mcp.rpc(
|
||||
@@ -274,6 +292,48 @@ impl Mcp {
|
||||
std::fs::read(self.data.join("journal.jsonl")).unwrap_or_default()
|
||||
}
|
||||
|
||||
/// What a read-only tool must leave as it was: every file under the
|
||||
/// data dir, the books dir's vault/ and its settings file, by path,
|
||||
/// each with the SHA-256 of its contents. The database is compared by
|
||||
/// what it holds (every row of every table, in order: SQLite moves
|
||||
/// pages between the file and its write-ahead log on its own, and a
|
||||
/// reader writes its read marks into the shared-memory file), so the
|
||||
/// -wal and -shm files are left out.
|
||||
fn data_files(&self) -> BTreeMap<PathBuf, String> {
|
||||
fn walk(dir: &Path, out: &mut BTreeMap<PathBuf, String>) {
|
||||
for e in std::fs::read_dir(dir).into_iter().flatten().flatten() {
|
||||
let p = e.path();
|
||||
let name = p.file_name().unwrap().to_string_lossy().into_owned();
|
||||
if p.is_dir() {
|
||||
walk(&p, out);
|
||||
} else if name.ends_with("-wal") || name.ends_with("-shm") {
|
||||
continue;
|
||||
} else if name == ledger_store::DB_FILE {
|
||||
out.insert(p.clone(), db_digest(&p));
|
||||
} else {
|
||||
let bytes = std::fs::read(&p).unwrap_or_default();
|
||||
out.insert(p, ledger_store::journal::sha256_hex(&bytes));
|
||||
}
|
||||
}
|
||||
}
|
||||
let mut out = BTreeMap::new();
|
||||
walk(&self.data, &mut out);
|
||||
let books = self.data.parent().unwrap();
|
||||
walk(&books.join("vault"), &mut out);
|
||||
let toml = books.join("wanderbooks.toml");
|
||||
out.insert(
|
||||
toml.clone(),
|
||||
ledger_store::journal::sha256_hex(&std::fs::read(&toml).unwrap_or_default()),
|
||||
);
|
||||
out
|
||||
}
|
||||
|
||||
fn read_only(&self, name: &str) -> bool {
|
||||
self.schemas
|
||||
.get(name)
|
||||
.is_some_and(|t| t["annotations"]["readOnlyHint"] == json!(true))
|
||||
}
|
||||
|
||||
fn send_line(&mut self, line: &str) {
|
||||
writeln!(self.stdin, "{line}").unwrap();
|
||||
self.stdin.flush().unwrap();
|
||||
@@ -315,6 +375,7 @@ impl Mcp {
|
||||
/// Call a tool and check invariants 1, 2, 3 and 7 on the outcome.
|
||||
fn tool(&mut self, name: &str, args: Value) -> Out {
|
||||
let before = self.journal();
|
||||
let files = self.read_only(name).then(|| self.data_files());
|
||||
let resp = self.rpc("tools/call", json!({"name": name, "arguments": args}));
|
||||
let out = if let Some(err) = resp.get("error") {
|
||||
Out::RpcErr(err.clone())
|
||||
@@ -337,6 +398,20 @@ impl Mcp {
|
||||
"invariant 2: refused {name} {args} changed the journal ({out:?})"
|
||||
);
|
||||
}
|
||||
if let Some(files) = files {
|
||||
assert!(
|
||||
self.journal() == before,
|
||||
"readOnlyHint: {name} {args} changed the journal"
|
||||
);
|
||||
assert_eq!(
|
||||
self.data_files(),
|
||||
files,
|
||||
"readOnlyHint: {name} {args} changed the files of the books"
|
||||
);
|
||||
if !out.refused() {
|
||||
self.read_only_checked.insert(name.to_string());
|
||||
}
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
@@ -694,7 +769,7 @@ fn happy_path(name: &str) -> Mcp {
|
||||
json!({"party": "Landlord", "received_on": "2026-01-03", "entity_type": "LLC (partnership)",
|
||||
"tin_last4": "4321", "kept_at": "CPA portal"}),
|
||||
);
|
||||
let w9_pdf = outside(&dir).join("landlord-w9.pdf");
|
||||
let w9_pdf = inbox(&dir).join("landlord-w9.pdf");
|
||||
std::fs::write(&w9_pdf, b"%PDF-1.4 W-9 EIN 12-3454321").unwrap();
|
||||
m.ok(
|
||||
"books.set_w9",
|
||||
@@ -798,7 +873,8 @@ fn happy_path(name: &str) -> Mcp {
|
||||
"books.unlink_attachment",
|
||||
json!({"attachment_id": filed, "subject": {"kind": "company"}, "reason": "a lease, not a formation document"}),
|
||||
);
|
||||
let local = dir.join("local-receipt.txt");
|
||||
// From outside the books, in the server's import folder.
|
||||
let local = inbox(&dir).join("local-receipt.txt");
|
||||
std::fs::write(&local, b"a local receipt").unwrap();
|
||||
m.ok(
|
||||
"books.import_local_file",
|
||||
@@ -1017,6 +1093,10 @@ fn happy_path(name: &str) -> Mcp {
|
||||
json!({"period_id": p, "confirmed": true}),
|
||||
);
|
||||
|
||||
// The handbook: its index, and a section.
|
||||
m.ok("books.handbook", json!({}));
|
||||
m.ok("books.handbook", json!({"section": "contract"}));
|
||||
|
||||
// Reports over the populated books.
|
||||
m.ok("books.chart", json!({}));
|
||||
m.ok("books.trial_balance", json!({"as_of": "2026-12-31"}));
|
||||
@@ -1102,6 +1182,26 @@ fn inv1_every_tool_result_matches_its_output_schema() {
|
||||
assert!(missing.is_empty(), "tools never exercised: {missing:?}");
|
||||
}
|
||||
|
||||
/// The read-only hint is true in behaviour: every tool annotated
|
||||
/// readOnlyHint succeeded on the fixture company and left the journal,
|
||||
/// every file under the data dir (its contents, the database by every row
|
||||
/// it holds), the vault and the settings file exactly as they were
|
||||
/// (checked in [`Mcp::tool`] on every call).
|
||||
#[test]
|
||||
fn read_only_tools_change_nothing() {
|
||||
let m = happy_path("read-only");
|
||||
let read_only: Vec<&String> = m.schemas.keys().filter(|t| m.read_only(t)).collect();
|
||||
assert!(read_only.len() > 30, "only {read_only:?}");
|
||||
let unchecked: Vec<&&String> = read_only
|
||||
.iter()
|
||||
.filter(|t| !m.read_only_checked.contains(**t))
|
||||
.collect();
|
||||
assert!(
|
||||
unchecked.is_empty(),
|
||||
"read-only tools never checked: {unchecked:?}"
|
||||
);
|
||||
}
|
||||
|
||||
/// Invariant 3, amounts out, weak form: no money key ever holds a JSON
|
||||
/// number, over every tool's results.
|
||||
#[test]
|
||||
@@ -2364,3 +2464,36 @@ fn assigned_roles_steer_invoices() {
|
||||
assert!(tb.contains("1110") && tb.contains("4100"), "{tb}");
|
||||
assert!(!tb.contains("\"1200\"") && !tb.contains("\"4000\""), "{tb}");
|
||||
}
|
||||
|
||||
/// The database at `path` by what it holds: every row of every table, in
|
||||
/// rowid order, as text, hashed. Read through a read-only connection
|
||||
/// beside the server's (WAL mode lets a reader in while it writes).
|
||||
fn db_digest(path: &Path) -> String {
|
||||
let conn =
|
||||
rusqlite::Connection::open_with_flags(path, rusqlite::OpenFlags::SQLITE_OPEN_READ_ONLY)
|
||||
.unwrap();
|
||||
let mut tables: Vec<String> = conn
|
||||
.prepare("SELECT name FROM sqlite_master WHERE type = 'table' ORDER BY name")
|
||||
.unwrap()
|
||||
.query_map([], |r| r.get(0))
|
||||
.unwrap()
|
||||
.map(Result::unwrap)
|
||||
.collect();
|
||||
tables.sort();
|
||||
let mut dump = String::new();
|
||||
for t in &tables {
|
||||
dump.push_str(&format!("table {t}\n"));
|
||||
let mut stmt = conn
|
||||
.prepare(&format!("SELECT * FROM \"{t}\" ORDER BY rowid"))
|
||||
.unwrap();
|
||||
let cols = stmt.column_count();
|
||||
let mut rows = stmt.query([]).unwrap();
|
||||
while let Some(row) = rows.next().unwrap() {
|
||||
for i in 0..cols {
|
||||
dump.push_str(&format!("{:?}\t", row.get_ref(i).unwrap()));
|
||||
}
|
||||
dump.push('\n');
|
||||
}
|
||||
}
|
||||
ledger_store::journal::sha256_hex(dump.as_bytes())
|
||||
}
|
||||
@@ -88,6 +88,14 @@ fn outside(dir: &Path) -> PathBuf {
|
||||
d
|
||||
}
|
||||
|
||||
/// The server's import root, beside the books dir `dir`: W-9 files handed
|
||||
/// to books.set_w9 by path. Never where the server writes TINs.
|
||||
fn inbox(dir: &Path) -> PathBuf {
|
||||
let d = PathBuf::from(format!("{}-inbox", dir.display()));
|
||||
std::fs::create_dir_all(&d).unwrap();
|
||||
d
|
||||
}
|
||||
|
||||
/// `wanderbooks.toml` with a company name, the receipt threshold, and
|
||||
/// extra `[books]` TOML; the vault key file is outside the books dir.
|
||||
fn books_toml(dir: &Path, threshold: &str, books_extra: &str) -> PathBuf {
|
||||
@@ -114,6 +122,9 @@ impl Mcp {
|
||||
.arg(dir.join("books-data"))
|
||||
.arg("--books-toml")
|
||||
.arg(toml)
|
||||
// Files handed over by path come only from here.
|
||||
.arg("--import-root")
|
||||
.arg(inbox(dir))
|
||||
.env("XDG_RUNTIME_DIR", &run)
|
||||
// Never the user's real vault key (the default key file is
|
||||
// under XDG_CONFIG_HOME); the tests name theirs anyway.
|
||||
@@ -461,7 +472,7 @@ impl Mcp {
|
||||
}
|
||||
/// A W-9 file outside the books; it shows the TIN, like the real one.
|
||||
fn w9_file(&self, name: &str, tin: &str) -> PathBuf {
|
||||
let p = self.outside().join(name);
|
||||
let p = inbox(&self.books_dir()).join(name);
|
||||
std::fs::write(&p, format!("%PDF-1.4 Form W-9 TIN {tin}")).unwrap();
|
||||
p
|
||||
}
|
||||
@@ -566,8 +577,8 @@ fn set_w9_refusals_write_nothing_anywhere() {
|
||||
let mut m = books("refusals");
|
||||
let acme = m.party_id("Acme Design");
|
||||
m.add_party("IRS", &["tax_agency"]);
|
||||
let missing = m.outside().join("no-such-w9.pdf");
|
||||
let txt = m.outside().join("w9.txt");
|
||||
let missing = inbox(&m.books_dir()).join("no-such-w9.pdf");
|
||||
let txt = inbox(&m.books_dir()).join("w9.txt");
|
||||
std::fs::write(&txt, "W-9").unwrap();
|
||||
for (party, extra) in [
|
||||
("Acme Design", json!({"tin": "57193284", "tin_type": "ssn"})), // eight digits
|
||||
@@ -722,6 +733,20 @@ fn the_w9_file_goes_to_the_vault_never_the_documents() {
|
||||
json!({"party": "Acme Design", "save_to": save_to.to_str().unwrap()}),
|
||||
);
|
||||
}
|
||||
// Each refused as such, never as a failed write.
|
||||
for (save_to, said) in [
|
||||
(to.clone(), "a file is there already"),
|
||||
(
|
||||
m.outside().join("no/such/dir/w9.pdf"),
|
||||
"the folder for that path doesn't exist",
|
||||
),
|
||||
] {
|
||||
let why = m.refuse(
|
||||
"books.get_w9",
|
||||
json!({"party": "Acme Design", "save_to": save_to.to_str().unwrap()}),
|
||||
);
|
||||
assert!(why.contains(said), "{why}");
|
||||
}
|
||||
// A party with no W-9 file in the vault.
|
||||
m.w9("Rent Co", json!({"tin": EIN, "tin_type": "ein"}));
|
||||
m.refuse(
|
||||
@@ -741,6 +766,36 @@ fn the_w9_file_goes_to_the_vault_never_the_documents() {
|
||||
assert_eq!(p["w9"]["kept_at"], "wanderbooks vault");
|
||||
}
|
||||
|
||||
/// A W-9 file is a PDF, PNG or JPEG, by its extension in any case
|
||||
/// (.pdf, .png, .jpg, .jpeg): each is taken into the vault and comes back
|
||||
/// byte for byte, under its own name.
|
||||
#[test]
|
||||
fn every_w9_file_type_is_taken() {
|
||||
let mut m = books("w9-types");
|
||||
for (n, name) in ["w9.pdf", "w9.png", "w9.jpg", "w9.jpeg", "W9.JPG"]
|
||||
.iter()
|
||||
.enumerate()
|
||||
{
|
||||
let party = format!("Payee {n}");
|
||||
m.add_party(&party, &["contractor"]);
|
||||
let src = m.w9_file(name, "000");
|
||||
let Out::Ok(p) = m.w9(
|
||||
&party,
|
||||
json!({"tin_last4": "0000", "w9_file_path": src.to_str().unwrap()}),
|
||||
) else {
|
||||
panic!("{name} refused")
|
||||
};
|
||||
assert_eq!(p["w9"]["in_vault"], true, "{name}");
|
||||
let to = m.outside().join(format!("copy-{n}"));
|
||||
let out = m.ok(
|
||||
"books.get_w9",
|
||||
json!({"party": party, "save_to": to.to_str().unwrap()}),
|
||||
);
|
||||
assert_eq!(out["file_name"], *name);
|
||||
assert_eq!(std::fs::read(&to).unwrap(), std::fs::read(&src).unwrap());
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_locked_vault_says_so_and_never_guesses() {
|
||||
let mut m = books("locked");
|
||||
@@ -811,7 +866,7 @@ fn a_key_file_inside_the_books_is_refused() {
|
||||
let why = m
|
||||
.w9("Acme Design", json!({"tin": SSN, "tin_type": "ssn"}))
|
||||
.err_text();
|
||||
assert!(why.contains("inside the books dir"), "{why}");
|
||||
assert!(why.contains("inside the books' folder"), "{why}");
|
||||
assert!(!dir.join("vault.key").exists());
|
||||
assert!(!dir.join("vault").exists());
|
||||
}
|
||||
@@ -1184,7 +1239,7 @@ fn books_in_git_must_ignore_the_vault() {
|
||||
.w9("Acme Design", json!({"tin": SSN, "tin_type": "ssn"}))
|
||||
.err_text();
|
||||
assert!(
|
||||
why.contains(".gitignore") && why.contains("vault/"),
|
||||
why.contains("version history") && why.contains("Ask the human"),
|
||||
"{why}"
|
||||
);
|
||||
assert!(!m.vault().exists() && !m.key().exists());
|
||||
@@ -1697,6 +1752,48 @@ fn a_package_with_tins_goes_only_outside_the_books() {
|
||||
assert!(!books.join("cpa.zip").exists());
|
||||
}
|
||||
|
||||
/// A package goes to a new file in a folder that exists, with or without
|
||||
/// TINs: a missing folder and a taken file are each refused as such (not
|
||||
/// as a failed write); without TINs, a new .zip path or an existing folder
|
||||
/// takes it.
|
||||
#[test]
|
||||
fn a_package_goes_only_to_a_new_file_in_a_folder_that_exists() {
|
||||
let mut m = k1_books("k1-dest");
|
||||
let missing = m.outside().join("no/such/dir/cpa.zip");
|
||||
let taken = m.outside().join("taken.zip");
|
||||
std::fs::write(&taken, b"x").unwrap();
|
||||
for tins in [true, false] {
|
||||
for (to, said) in [
|
||||
(&missing, "the folder for that path doesn't exist"),
|
||||
(&taken, "a file is there already"),
|
||||
] {
|
||||
let why = m.refuse(
|
||||
"books.export_cpa_package",
|
||||
json!({"as_of": "2026-12-31", "cash_accounts": ["1000"],
|
||||
"include_tins": tins, "save_to": to.to_str().unwrap()}),
|
||||
);
|
||||
assert!(why.contains(said), "include_tins {tins}: {why}");
|
||||
}
|
||||
}
|
||||
assert_eq!(std::fs::read(&taken).unwrap(), b"x");
|
||||
let to = m.outside().join("plain.zip");
|
||||
m.read_only(
|
||||
"books.export_cpa_package",
|
||||
json!({"as_of": "2026-12-31", "cash_accounts": ["1000"],
|
||||
"include_tins": false, "save_to": to.to_str().unwrap()}),
|
||||
);
|
||||
assert!(unzip(&to).contains_key("README.txt"));
|
||||
let folder = m.outside().join("packages");
|
||||
std::fs::create_dir_all(&folder).unwrap();
|
||||
m.read_only(
|
||||
"books.export_cpa_package",
|
||||
json!({"as_of": "2026-12-31", "cash_accounts": ["1000"],
|
||||
"include_tins": false, "save_to": folder.to_str().unwrap()}),
|
||||
);
|
||||
let saved: Vec<_> = std::fs::read_dir(&folder).unwrap().collect();
|
||||
assert_eq!(saved.len(), 1, "one package in the folder");
|
||||
}
|
||||
|
||||
/// A locked vault never fails the package: every TIN row says why, and
|
||||
/// tin_gaps lists each member and payee.
|
||||
#[test]
|
||||
@@ -1775,6 +1872,35 @@ fn refusals_never_echo_a_tin() {
|
||||
}
|
||||
}
|
||||
|
||||
/// B-26 for resource reads: a refused `resources/read` quotes the URI it
|
||||
/// was given, in its message and its data, and never repeats a TIN in it,
|
||||
/// however the URI carries one (a receipt id, a handbook section, an
|
||||
/// unknown path, a digest's `since`).
|
||||
#[test]
|
||||
fn resource_refusals_never_echo_a_tin() {
|
||||
let mut m = books("resource-echo");
|
||||
for uri in [
|
||||
format!("books://receipts/{MEMBER_SSN_DIGITS}"),
|
||||
format!("books://receipts/{MEMBER_SSN}"),
|
||||
format!("books://handbook/{MEMBER_SSN}"),
|
||||
format!("books://handbook/{MEMBER_SSN_DIGITS}"),
|
||||
format!("books://{MEMBER_SSN_DIGITS}"),
|
||||
format!("books://reports/{MEMBER_SSN}"),
|
||||
format!("books://digest?since={MEMBER_SSN}"),
|
||||
format!("books://digest?since={MEMBER_SSN_DIGITS}"),
|
||||
] {
|
||||
let resp = m.rpc("resources/read", json!({"uri": uri}));
|
||||
let err = resp
|
||||
.get("error")
|
||||
.unwrap_or_else(|| panic!("{uri} should be refused: {resp}"));
|
||||
assert!(
|
||||
!holds_tin(err.to_string().as_bytes(), MEMBER_SSN_DIGITS),
|
||||
"{uri} echoed the TIN: {err}"
|
||||
);
|
||||
assert!(!err["message"].as_str().unwrap().is_empty(), "{err}");
|
||||
}
|
||||
}
|
||||
|
||||
/// k1::member_party: a vendor whose display name is a member's name, with
|
||||
/// a W-9 EIN in the vault, never puts its TIN on the member's K-1 row:
|
||||
/// the member's TIN is a gap.
|
||||
@@ -1833,3 +1959,173 @@ fn joint_filers_are_noted_in_the_package() {
|
||||
let note = "Stephen Example and Kat Example file a joint individual return: each receives their own Schedule K-1; both are reported on the one Form 1040 (Schedule E, Part II).";
|
||||
assert_eq!(readme.matches(note).count(), 1, "once per pair: {readme}");
|
||||
}
|
||||
|
||||
/// The vault's files and their bytes, by path.
|
||||
fn vault_bytes(m: &Mcp) -> std::collections::BTreeMap<PathBuf, Vec<u8>> {
|
||||
files_under(&m.vault())
|
||||
.into_iter()
|
||||
.map(|p| {
|
||||
let bytes = std::fs::read(&p).unwrap();
|
||||
(p, bytes)
|
||||
})
|
||||
.collect()
|
||||
}
|
||||
|
||||
/// MCP's idempotentHint ("calling it again with the same arguments has no
|
||||
/// further effect"; plan/served.md 4.9): a tool says so only when it is
|
||||
/// true of the books. Each tool here is called twice with the same
|
||||
/// arguments on a fixture where the first call does something; the hint is
|
||||
/// set exactly when the second call leaves the journal and the TIN vault
|
||||
/// byte for byte as the first left them. Every tool marked idempotent is in
|
||||
/// the table, so a new one is checked too.
|
||||
#[test]
|
||||
fn idempotent_tools_change_nothing_when_repeated() {
|
||||
let mut m = books("idempotent");
|
||||
m.accounts(&[
|
||||
("1200", "Receivables", "asset"),
|
||||
("1300", "Prepaid", "asset"),
|
||||
("1500", "Equipment", "asset"),
|
||||
("1501", "Accumulated Depreciation", "asset"),
|
||||
("6100", "Depreciation", "expense"),
|
||||
("6300", "Insurance", "expense"),
|
||||
]);
|
||||
m.add_party("Dana Employee", &["employee"]);
|
||||
let entry = m.post(
|
||||
"2026-02-01",
|
||||
json!({}),
|
||||
&[("6000", "debit", "100.00"), ("1000", "credit", "100.00")],
|
||||
);
|
||||
let asset = m.ok(
|
||||
"books.register_asset",
|
||||
json!({"description": "Laptop", "purchase_date": "2026-01-15", "cost": "2400.00",
|
||||
"useful_life_months": 24, "cost_account": "1500",
|
||||
"accum_depr_account": "1501", "expense_account": "6100"}),
|
||||
)["asset_id"]
|
||||
.as_u64()
|
||||
.unwrap();
|
||||
m.ok(
|
||||
"books.create_schedule",
|
||||
json!({"kind": "prepaid_expense", "description": "Insurance", "total": "300.00",
|
||||
"start": "2026-01-01", "months": 3, "balance_account": "1300",
|
||||
"pl_account": "6300"}),
|
||||
);
|
||||
m.ok(
|
||||
"books.create_recurring",
|
||||
json!({"description": "Rent", "frequency": "monthly", "start": "2026-01-01",
|
||||
"lines": [{"account": "6999", "side": "debit", "amount": "50.00"},
|
||||
{"account": "1000", "side": "credit", "amount": "50.00"}]}),
|
||||
);
|
||||
let category = m.read_only("books.tax_categories", json!({}))["categories"][0]["key"]
|
||||
.as_str()
|
||||
.unwrap()
|
||||
.to_string();
|
||||
let calls: Vec<(&str, Value)> = vec![
|
||||
("books.verify", json!({"blobs": true})),
|
||||
(
|
||||
"books.run_schedules",
|
||||
json!({"through": "2026-03-31", "confirmed": true}),
|
||||
),
|
||||
("books.run_recurring", json!({"through": "2026-03-15"})),
|
||||
(
|
||||
"books.set_vendor_1099",
|
||||
json!({"vendor": "Acme Design", "form_1099": "misc"}),
|
||||
),
|
||||
(
|
||||
"books.set_entry_vendor",
|
||||
json!({"entry_id": entry, "vendor": "Acme Design"}),
|
||||
),
|
||||
(
|
||||
"books.label_asset",
|
||||
json!({"asset": asset.to_string(), "serial": "SN-1"}),
|
||||
),
|
||||
(
|
||||
"books.set_asset_tax_basis",
|
||||
json!({"asset": asset.to_string(), "rule": "cost"}),
|
||||
),
|
||||
(
|
||||
"books.assign_role",
|
||||
json!({"role": "receivables", "account": "1200"}),
|
||||
),
|
||||
(
|
||||
"books.set_tax_category",
|
||||
json!({"account": "6000", "category": category}),
|
||||
),
|
||||
(
|
||||
"books.run_depreciation",
|
||||
json!({"period": "2026-03", "asset_id": asset}),
|
||||
),
|
||||
(
|
||||
"books.mark_cleared",
|
||||
json!({"entry_id": entry, "line_index": 1, "cleared": true}),
|
||||
),
|
||||
(
|
||||
"books.update_party",
|
||||
json!({"party": "Rent Co", "notes": "pays on the 1st"}),
|
||||
),
|
||||
(
|
||||
"books.set_party_roles",
|
||||
json!({"party": "Rent Co", "add": ["financial_institution"]}),
|
||||
),
|
||||
(
|
||||
"books.set_w9",
|
||||
json!({"party": "Acme Design", "received_on": "2026-01-05",
|
||||
"entity_type": "individual/sole proprietor", "tin": SSN, "tin_type": "ssn"}),
|
||||
),
|
||||
(
|
||||
"books.set_w9",
|
||||
json!({"party": "Rent Co", "received_on": "2026-01-05", "entity_type": "llc",
|
||||
"tin_last4": "9105", "kept_at": "the office safe"}),
|
||||
),
|
||||
(
|
||||
"books.set_tin",
|
||||
json!({"party": "Dana Employee", "tin": MEMBER_SSN, "tin_type": "ssn"}),
|
||||
),
|
||||
(
|
||||
"books.set_w4",
|
||||
json!({"party": "Dana Employee", "received_on": "2026-01-05", "state": "UT",
|
||||
"kept_at": "the office safe"}),
|
||||
),
|
||||
(
|
||||
"books.set_entry_party",
|
||||
json!({"entry_id": entry, "party": "Acme Design"}),
|
||||
),
|
||||
(
|
||||
"books.set_fx_rate",
|
||||
json!({"currency": "EUR", "date": "2026-01-02", "rate": "1.10"}),
|
||||
),
|
||||
];
|
||||
let list = m.rpc("tools/list", json!({}));
|
||||
let marked: std::collections::BTreeSet<String> = list["result"]["tools"]
|
||||
.as_array()
|
||||
.unwrap()
|
||||
.iter()
|
||||
.filter(|t| t["annotations"]["idempotentHint"] == json!(true))
|
||||
.map(|t| t["name"].as_str().unwrap().to_string())
|
||||
.collect();
|
||||
for name in &marked {
|
||||
assert!(
|
||||
calls.iter().any(|(n, _)| n == name),
|
||||
"{name} is marked idempotent: add it to this table"
|
||||
);
|
||||
}
|
||||
let mut repeats_change: std::collections::BTreeMap<&str, bool> = Default::default();
|
||||
for (name, args) in &calls {
|
||||
m.ok(name, args.clone());
|
||||
let (journal, vault) = (m.journal(), vault_bytes(&m));
|
||||
m.ok(name, args.clone());
|
||||
let changed = m.journal() != journal || vault_bytes(&m) != vault;
|
||||
*repeats_change.entry(name).or_default() |= changed;
|
||||
}
|
||||
let wrong: Vec<String> = repeats_change
|
||||
.into_iter()
|
||||
.filter(|(name, changed)| marked.contains(*name) == *changed)
|
||||
.map(|(name, changed)| {
|
||||
format!(
|
||||
"{name}: marked idempotent {}, but a repeat {} the books",
|
||||
marked.contains(name),
|
||||
if changed { "changes" } else { "leaves alone" },
|
||||
)
|
||||
})
|
||||
.collect();
|
||||
assert!(wrong.is_empty(), "{wrong:#?}");
|
||||
}
|
||||
@@ -211,3 +211,185 @@ fn newer_books_are_refused_as_newer_not_corrupt() {
|
||||
journal
|
||||
);
|
||||
}
|
||||
|
||||
/// Start the server and report whether it refused to start (it never got
|
||||
/// as far as serving), with its standard error.
|
||||
fn refuses_to_start(cmd: &mut Command) -> Option<String> {
|
||||
let mut child = cmd
|
||||
.stdin(Stdio::piped())
|
||||
.stdout(Stdio::piped())
|
||||
.stderr(Stdio::piped())
|
||||
.spawn()
|
||||
.unwrap();
|
||||
// A server that starts waits on stdin; closing it ends the server.
|
||||
drop(child.stdin.take());
|
||||
let out = child.wait_with_output().unwrap();
|
||||
let err = String::from_utf8_lossy(&out.stderr).into_owned();
|
||||
(!err.contains("serving over stdio")).then_some(err)
|
||||
}
|
||||
|
||||
/// local_files.rs INVARIANT 0: a named import root that is `/`, the home
|
||||
/// folder, a folder holding it, a folder holding the books, the data dir
|
||||
/// (a symlinked --data-dir placed where it really is), the vault or a key
|
||||
/// file, or a folder inside the books, the data dir or the vault, stops
|
||||
/// the server at startup, saying why; a folder holding none of them is
|
||||
/// used.
|
||||
#[test]
|
||||
fn an_import_root_holding_the_books_or_the_home_folder_is_refused() {
|
||||
let dir = temp("bad-roots").canonicalize().unwrap();
|
||||
let home = dir.join("home");
|
||||
let books = home.join("work/books");
|
||||
let data = books.join("books-data");
|
||||
let keys = dir.join("keys");
|
||||
for d in [&home.join("Downloads"), &books, &keys, &dir.join("config")] {
|
||||
std::fs::create_dir_all(d).unwrap();
|
||||
}
|
||||
std::fs::write(
|
||||
books.join("wanderbooks.toml"),
|
||||
format!(
|
||||
"[vault]\nkey_file = \"{}\"\n",
|
||||
keys.join("vault.key").display()
|
||||
),
|
||||
)
|
||||
.unwrap();
|
||||
let link = dir.join("data-link");
|
||||
std::os::unix::fs::symlink(&data, &link).unwrap();
|
||||
let start = |data: &std::path::Path, root: &std::path::Path| {
|
||||
let mut cmd = Command::new(BIN);
|
||||
cmd.arg("--data-dir")
|
||||
.arg(data)
|
||||
.arg("--import-root")
|
||||
.arg(root)
|
||||
.env("HOME", &home)
|
||||
.env("XDG_CONFIG_HOME", dir.join("config"))
|
||||
.env("XDG_RUNTIME_DIR", dir.join("config"));
|
||||
refuses_to_start(&mut cmd)
|
||||
};
|
||||
for (root, why) in [
|
||||
(std::path::PathBuf::from("/"), "whole filesystem"),
|
||||
(home.clone(), "home folder"),
|
||||
(dir.clone(), "home folder"),
|
||||
(home.join("work"), "holds the books"),
|
||||
(books.clone(), "holds the books"),
|
||||
(data.clone(), "holds the books"),
|
||||
(
|
||||
keys.clone(),
|
||||
"holds the books, the TIN vault, or a vault key",
|
||||
),
|
||||
(
|
||||
dir.join("config"),
|
||||
"holds the books, the TIN vault, or a vault key",
|
||||
),
|
||||
] {
|
||||
let err = start(&data, &root).unwrap_or_else(|| panic!("{} was used", root.display()));
|
||||
assert!(
|
||||
err.contains("can't be used") && err.contains(why),
|
||||
"{}: {err}",
|
||||
root.display()
|
||||
);
|
||||
}
|
||||
// A folder inside the books, the data dir or the vault: every file in
|
||||
// it would be refused, so the root is.
|
||||
for root in [
|
||||
books.join("company"),
|
||||
data.join("blobs"),
|
||||
books.join("vault/inner"),
|
||||
] {
|
||||
std::fs::create_dir_all(&root).unwrap();
|
||||
let err = start(&data, &root).unwrap_or_else(|| panic!("{} was used", root.display()));
|
||||
assert!(
|
||||
err.contains("can't be used") && err.contains("inside the books"),
|
||||
"{}: {err}",
|
||||
root.display()
|
||||
);
|
||||
}
|
||||
// Through a symlinked data dir, the books are where they really are.
|
||||
let err = start(&link, &home.join("work")).expect("a root holding the real books");
|
||||
assert!(err.contains("holds the books"), "{err}");
|
||||
// A folder holding none of them is used.
|
||||
assert_eq!(start(&data, &home.join("Downloads")), None);
|
||||
}
|
||||
|
||||
/// local_files.rs INVARIANT 0, the default: an XDG_DOWNLOAD_DIR of
|
||||
/// "$HOME/" (or "/") never makes the home folder an import root. With no
|
||||
/// real ~/Downloads there is no root, and an import says so; with one, it
|
||||
/// is the root, and the rest of the home folder stays out of reach.
|
||||
#[test]
|
||||
fn a_download_dir_of_home_never_opens_the_home_folder() {
|
||||
let dir = temp("xdg-home").canonicalize().unwrap();
|
||||
let home = dir.join("home");
|
||||
std::fs::create_dir_all(home.join(".ssh")).unwrap();
|
||||
std::fs::write(home.join(".ssh/id_ed25519"), "PRIVATE KEY").unwrap();
|
||||
let key = home.join(".ssh/id_ed25519");
|
||||
let import = |xdg: &str, path: &std::path::Path| {
|
||||
one_call(
|
||||
Command::new(BIN)
|
||||
.arg("--data-dir")
|
||||
.arg(dir.join("books/books-data"))
|
||||
.env("HOME", &home)
|
||||
.env("XDG_DOWNLOAD_DIR", xdg)
|
||||
.env("XDG_CONFIG_HOME", dir.join("config"))
|
||||
.env("XDG_RUNTIME_DIR", dir.join("config")),
|
||||
"books.import_local_file",
|
||||
serde_json::json!({"path": path.to_str().unwrap(), "category": "document"}),
|
||||
)
|
||||
};
|
||||
for xdg in ["$HOME/", "$HOME", "/"] {
|
||||
let reply = import(xdg, &key);
|
||||
assert!(reply.contains("has no import folder"), "{xdg}: {reply}");
|
||||
}
|
||||
std::fs::create_dir_all(home.join("Downloads")).unwrap();
|
||||
std::fs::write(home.join("Downloads/receipt.pdf"), "%PDF a receipt").unwrap();
|
||||
for xdg in ["$HOME/", "/"] {
|
||||
let reply = import(xdg, &key);
|
||||
assert!(
|
||||
reply.contains("no such file in the server's import folders"),
|
||||
"{xdg}: {reply}"
|
||||
);
|
||||
assert!(!reply.contains("PRIVATE"), "{reply}");
|
||||
}
|
||||
let reply = import("$HOME/", &home.join("Downloads/receipt.pdf"));
|
||||
assert!(reply.contains("attachment_id"), "{reply}");
|
||||
}
|
||||
|
||||
/// local_files.rs INVARIANT 0, a refused default: a downloads folder
|
||||
/// that holds the books, or one inside them, is dropped, never fatal
|
||||
/// (only a named root stops the server): it serves, with no import
|
||||
/// folder, and an import says so.
|
||||
#[test]
|
||||
fn a_default_download_dir_holding_the_books_is_dropped_not_fatal() {
|
||||
let dir = temp("xdg-books").canonicalize().unwrap();
|
||||
let home = dir.join("home");
|
||||
let downloads = dir.join("downloads");
|
||||
std::fs::create_dir_all(&home).unwrap();
|
||||
std::fs::create_dir_all(downloads.join("books")).unwrap();
|
||||
std::fs::write(downloads.join("receipt.pdf"), "%PDF a receipt").unwrap();
|
||||
let reply = one_call(
|
||||
Command::new(BIN)
|
||||
.arg("--data-dir")
|
||||
.arg(downloads.join("books/books-data"))
|
||||
.env("HOME", &home)
|
||||
.env("XDG_DOWNLOAD_DIR", &downloads)
|
||||
.env("XDG_CONFIG_HOME", dir.join("config"))
|
||||
.env("XDG_RUNTIME_DIR", dir.join("config")),
|
||||
"books.import_local_file",
|
||||
serde_json::json!({"path": downloads.join("receipt.pdf").to_str().unwrap(), "category": "document"}),
|
||||
);
|
||||
assert!(reply.contains("has no import folder"), "{reply}");
|
||||
// A downloads folder inside the books dir is dropped the same way.
|
||||
let books = dir.join("books");
|
||||
std::fs::create_dir_all(books.join("Downloads")).unwrap();
|
||||
std::fs::write(books.join("Downloads/receipt.pdf"), "%PDF a receipt").unwrap();
|
||||
let reply = one_call(
|
||||
Command::new(BIN)
|
||||
.arg("--data-dir")
|
||||
.arg(books.join("books-data"))
|
||||
.env("HOME", &home)
|
||||
.env("XDG_DOWNLOAD_DIR", books.join("Downloads"))
|
||||
.env("XDG_CONFIG_HOME", dir.join("config"))
|
||||
.env("XDG_RUNTIME_DIR", dir.join("config")),
|
||||
"books.import_local_file",
|
||||
serde_json::json!({"path": books.join("Downloads/receipt.pdf").to_str().unwrap(), "category": "document"}),
|
||||
);
|
||||
assert!(reply.contains("has no import folder"), "{reply}");
|
||||
}
|
||||
@@ -0,0 +1,665 @@
|
||||
//! Files that carry full TINs never enter the books (rules.md B-26;
|
||||
//! tin_files.rs).
|
||||
//!
|
||||
//! ```text
|
||||
//! GOAL: no file holding a full TIN can be filed as a receipt or document
|
||||
//! (books.get_receipt would hand its bytes to any agent), however it
|
||||
//! comes back: the W-9 books.set_w9 read, books.get_w9's copy, a CPA
|
||||
//! package or a file from one, or text with a TIN in it.
|
||||
//! SOURCE: rules.md B-26; DECISION (P0 review round 2, 2026-10-16).
|
||||
//! INVARIANTS (oracle):
|
||||
//! 1. Every file the server read or wrote with full TINs is refused by
|
||||
//! every way a file enters the books (books.import_local_file,
|
||||
//! books.attach_receipt, books.file_document), from any session and
|
||||
//! after the server restarts.
|
||||
//! 2. Text holding a full TIN is refused, whoever made it: one the vault
|
||||
//! holds, in every common rendering (nine digits; 3-2-4 joined by
|
||||
//! hyphens, spaces or dots; 2-7 joined by a hyphen or a space), and,
|
||||
//! with or without the vault, a number printed as an SSN or EIN is
|
||||
//! (123-45-6789, 12-3456789) standing alone.
|
||||
//! 3. Text probing for a TIN (more than two TIN-shaped numbers ending
|
||||
//! in a last four the books know) is refused alike, byte for byte,
|
||||
//! whether or not one of them is a TIN the vault holds; one or two
|
||||
//! such numbers are checked against the vault.
|
||||
//! 4. A refusal stores nothing.
|
||||
//! 5. Ordinary text goes in: a bank export with routing numbers, long
|
||||
//! references, and dates next to amounts (DECISION, Stephen,
|
||||
//! 2026-10-16: bank exports are filed for reconciliation).
|
||||
//! ```
|
||||
|
||||
use rmcp::ServiceExt;
|
||||
use rmcp::model::{CallToolRequestParams, ClientConfig};
|
||||
use rmcp::service::{RoleClient, RunningService};
|
||||
use rmcp::transport::StreamableHttpClientTransport;
|
||||
use serde_json::{Value, json};
|
||||
use std::io::Read;
|
||||
use std::path::{Path, PathBuf};
|
||||
use std::process::{Child, Command, Stdio};
|
||||
use std::time::{Duration, Instant};
|
||||
|
||||
type Client = RunningService<RoleClient, ClientConfig>;
|
||||
|
||||
const SSN: &str = "571-93-2846";
|
||||
const MEMBER_SSN: &str = "412-70-5531";
|
||||
|
||||
/// The refusal for a file the server read or wrote with TINs.
|
||||
const TIN_FILE: &str = "read or wrote with full TINs";
|
||||
/// The refusal for text holding a TIN the vault holds.
|
||||
const TIN_HELD: &str = "a full TIN the books keep in the TIN vault";
|
||||
/// The refusal for text probing for a TIN.
|
||||
const TIN_PROBE: &str = "more than two numbers shaped like a TIN";
|
||||
/// The refusal for text holding a number printed as an SSN or EIN is.
|
||||
const TIN_PRINTED: &str = "printed the way an SSN or EIN is";
|
||||
|
||||
struct Server(Child);
|
||||
impl Drop for Server {
|
||||
fn drop(&mut self) {
|
||||
let _ = self.0.kill();
|
||||
let _ = self.0.wait();
|
||||
}
|
||||
}
|
||||
|
||||
/// The books dir, the import root, a folder outside both, and the
|
||||
/// settings (a member, so the CPA package has a K-1 worksheet).
|
||||
struct Books {
|
||||
dir: PathBuf,
|
||||
inbox: PathBuf,
|
||||
out: PathBuf,
|
||||
toml: PathBuf,
|
||||
}
|
||||
|
||||
fn books(tag: &str) -> Books {
|
||||
let base =
|
||||
std::env::temp_dir().join(format!("ledger-mcp-tin-files-{}-{tag}", std::process::id()));
|
||||
let _ = std::fs::remove_dir_all(&base);
|
||||
let dir = base.join("books");
|
||||
let inbox = base.join("inbox");
|
||||
let out = base.join("out");
|
||||
for d in [&dir, &inbox, &out, &base.join("config")] {
|
||||
std::fs::create_dir_all(d).unwrap();
|
||||
}
|
||||
let toml = dir.join("wanderbooks.toml");
|
||||
std::fs::write(
|
||||
&toml,
|
||||
format!(
|
||||
"[company]\nname = \"Tin Co\"\n[books]\nreceipt_threshold = \"0.00\"\ncash_accounts = [\"1000\"]\n\
|
||||
[[company.members]]\nname = \"Kat\"\nshare = \"100%\"\ncapital_account = \"3000\"\n\
|
||||
[vault]\nkey_file = \"{}\"\n",
|
||||
base.join("config/vault.key").display()
|
||||
),
|
||||
)
|
||||
.unwrap();
|
||||
Books {
|
||||
dir,
|
||||
inbox,
|
||||
out,
|
||||
toml,
|
||||
}
|
||||
}
|
||||
|
||||
fn free_port() -> u16 {
|
||||
std::net::TcpListener::bind("127.0.0.1:0")
|
||||
.unwrap()
|
||||
.local_addr()
|
||||
.unwrap()
|
||||
.port()
|
||||
}
|
||||
|
||||
/// Start the server over HTTP on these books; every client is a session
|
||||
/// of its own.
|
||||
fn serve(b: &Books) -> (Server, String) {
|
||||
let addr = format!("127.0.0.1:{}", free_port());
|
||||
let base = b.dir.parent().unwrap();
|
||||
let child = Command::new(env!("CARGO_BIN_EXE_ledger-mcp"))
|
||||
.arg("--data-dir")
|
||||
.arg(b.dir.join("books-data"))
|
||||
.arg("--books-toml")
|
||||
.arg(&b.toml)
|
||||
.arg("--import-root")
|
||||
.arg(&b.inbox)
|
||||
.arg("--http")
|
||||
.arg(&addr)
|
||||
.env("XDG_CONFIG_HOME", base.join("config"))
|
||||
.env("XDG_RUNTIME_DIR", base.join("config"))
|
||||
.stdin(Stdio::null())
|
||||
.stdout(Stdio::null())
|
||||
.stderr(Stdio::null())
|
||||
.spawn()
|
||||
.unwrap();
|
||||
(Server(child), format!("http://{addr}/mcp"))
|
||||
}
|
||||
|
||||
async fn connect(url: &str) -> Client {
|
||||
let deadline = Instant::now() + Duration::from_secs(30);
|
||||
loop {
|
||||
let transport = StreamableHttpClientTransport::from_uri(url.to_string());
|
||||
match ClientConfig::default().serve(transport).await {
|
||||
Ok(c) => return c,
|
||||
Err(e) if Instant::now() > deadline => panic!("connect: {e}"),
|
||||
Err(_) => tokio::time::sleep(Duration::from_millis(100)).await,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Call a tool: Ok(structured result) or Err(the tool's error text).
|
||||
async fn call(c: &Client, tool: &str, args: Value) -> Result<Value, String> {
|
||||
let args = args.as_object().cloned().unwrap_or_default();
|
||||
let r = c
|
||||
.call_tool(CallToolRequestParams::new(tool.to_string()).with_arguments(args))
|
||||
.await
|
||||
.map_err(|e| format!("protocol: {e}"))?;
|
||||
let text = r
|
||||
.content
|
||||
.iter()
|
||||
.find_map(|c| c.as_text().map(|t| t.text.clone()))
|
||||
.unwrap_or_default();
|
||||
if r.is_error == Some(true) {
|
||||
Err(text)
|
||||
} else {
|
||||
Ok(r.structured_content
|
||||
.unwrap_or_else(|| serde_json::from_str(&text).unwrap()))
|
||||
}
|
||||
}
|
||||
|
||||
async fn ok(c: &Client, tool: &str, args: Value) -> Value {
|
||||
call(c, tool, args)
|
||||
.await
|
||||
.unwrap_or_else(|e| panic!("{tool}: {e}"))
|
||||
}
|
||||
|
||||
fn b64(bytes: &[u8]) -> String {
|
||||
use base64::Engine;
|
||||
base64::engine::general_purpose::STANDARD.encode(bytes)
|
||||
}
|
||||
|
||||
/// Every way the file at `path` (copied into the import root as `name`)
|
||||
/// could enter the books is refused with `why`, and nothing is stored:
|
||||
/// the refusals, tool by tool.
|
||||
async fn refused_everywhere(
|
||||
c: &Client,
|
||||
b: &Books,
|
||||
path: &Path,
|
||||
name: &str,
|
||||
why: &str,
|
||||
) -> Vec<String> {
|
||||
let bytes = std::fs::read(path).unwrap();
|
||||
let copy = b.inbox.join(name);
|
||||
std::fs::copy(path, ©).unwrap();
|
||||
let journal = b.dir.join("books-data").join(ledger_store::JOURNAL_FILE);
|
||||
let before = std::fs::read(&journal).unwrap();
|
||||
let mut refusals = Vec::new();
|
||||
for (tool, args) in [
|
||||
(
|
||||
"books.import_local_file",
|
||||
json!({"path": copy.to_str().unwrap(), "category": "document", "document_category": "tax"}),
|
||||
),
|
||||
(
|
||||
"books.attach_receipt",
|
||||
json!({"file_name": name, "mime_type": "application/octet-stream", "content_base64": b64(&bytes)}),
|
||||
),
|
||||
(
|
||||
"books.file_document",
|
||||
json!({"category": "tax", "file_name": name, "mime_type": "application/pdf", "content_base64": b64(&bytes)}),
|
||||
),
|
||||
] {
|
||||
let err = call(c, tool, args).await.expect_err(tool);
|
||||
assert!(err.contains(why), "{tool} {name}: {err}");
|
||||
refusals.push(err);
|
||||
}
|
||||
assert_eq!(
|
||||
std::fs::read(&journal).unwrap(),
|
||||
before,
|
||||
"a refusal stored something"
|
||||
);
|
||||
std::fs::remove_file(copy).unwrap();
|
||||
refusals
|
||||
}
|
||||
|
||||
/// INVARIANT 1: the W-9 books.set_w9 read (binary, no TIN in its text), a
|
||||
/// books.get_w9 copy of it, a 1099 worksheet and a CPA package with TINs,
|
||||
/// and the K-1 worksheet extracted from that package are each refused,
|
||||
/// from another session and after a restart; INVARIANT 2: a CSV holding a
|
||||
/// TIN that the server never saw is refused, sent as base64.
|
||||
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
|
||||
async fn a_tin_bearing_file_is_refused_from_every_session_and_after_a_restart() {
|
||||
let b = books("sessions");
|
||||
// A W-9 scan: binary bytes, no TIN a text scan would see.
|
||||
let w9 = b.inbox.join("w9.pdf");
|
||||
std::fs::write(
|
||||
&w9,
|
||||
b"%PDF-1.4\n\xff\xfe\x00 scanned W-9 \x01\x02\x03\n%%EOF\n",
|
||||
)
|
||||
.unwrap();
|
||||
let (server, url) = serve(&b);
|
||||
let one = connect(&url).await;
|
||||
for (code, name, ty) in [
|
||||
("1000", "Cash", "asset"),
|
||||
("3000", "Capital", "equity"),
|
||||
("6000", "Design", "expense"),
|
||||
] {
|
||||
ok(
|
||||
&one,
|
||||
"books.add_account",
|
||||
json!({"code": code, "name": name, "account_type": ty}),
|
||||
)
|
||||
.await;
|
||||
}
|
||||
ok(
|
||||
&one,
|
||||
"books.add_party",
|
||||
json!({"name": "Acme", "roles": ["contractor"]}),
|
||||
)
|
||||
.await;
|
||||
ok(
|
||||
&one,
|
||||
"books.add_party",
|
||||
json!({"name": "Kat", "roles": ["member"]}),
|
||||
)
|
||||
.await;
|
||||
ok(
|
||||
&one,
|
||||
"books.set_w9",
|
||||
json!({"party": "Acme", "received_on": "2026-01-03", "entity_type": "Individual",
|
||||
"tin": SSN, "tin_type": "ssn", "w9_file_path": w9.to_str().unwrap()}),
|
||||
)
|
||||
.await;
|
||||
ok(
|
||||
&one,
|
||||
"books.set_tin",
|
||||
json!({"party": "Kat", "tin": MEMBER_SSN, "tin_type": "ssn"}),
|
||||
)
|
||||
.await;
|
||||
// A bank statement filed in the books: the package carries it, and it
|
||||
// is no TIN file (its routing numbers are not TINs).
|
||||
accepted_everywhere(&one, &b, "statement.csv", BANK_CSV).await;
|
||||
// What the server writes with TINs, from the first session.
|
||||
let copy = b.out.join("w9-copy.pdf");
|
||||
ok(
|
||||
&one,
|
||||
"books.get_w9",
|
||||
json!({"party": "Acme", "save_to": copy.to_str().unwrap()}),
|
||||
)
|
||||
.await;
|
||||
let csv = b.out.join("1099.csv");
|
||||
ok(
|
||||
&one,
|
||||
"books.vendor_1099",
|
||||
json!({"year": 2026, "include_tins": true, "save_csv_to": csv.to_str().unwrap()}),
|
||||
)
|
||||
.await;
|
||||
let zip = b.out.join("cpa.zip");
|
||||
ok(
|
||||
&one,
|
||||
"books.export_cpa_package",
|
||||
json!({"cash_accounts": ["1000"], "save_to": zip.to_str().unwrap(), "as_of": "2026-12-31"}),
|
||||
)
|
||||
.await;
|
||||
let k1 = b.out.join("k1-members.csv");
|
||||
{
|
||||
let mut archive = zip::ZipArchive::new(std::fs::File::open(&zip).unwrap()).unwrap();
|
||||
let mut member = archive.by_name("k1-members.csv").unwrap();
|
||||
let mut bytes = Vec::new();
|
||||
member.read_to_end(&mut bytes).unwrap();
|
||||
assert!(
|
||||
String::from_utf8_lossy(&bytes).contains(MEMBER_SSN),
|
||||
"the K-1 worksheet holds the TIN"
|
||||
);
|
||||
std::fs::write(&k1, bytes).unwrap();
|
||||
}
|
||||
let files = [
|
||||
(w9.clone(), "receipt.pdf"),
|
||||
(copy.clone(), "invoice.pdf"),
|
||||
(csv.clone(), "statement.csv"),
|
||||
(zip.clone(), "bundle.zip"),
|
||||
(k1.clone(), "k1-members.csv"),
|
||||
];
|
||||
// A second session refuses each.
|
||||
let two = connect(&url).await;
|
||||
for (path, name) in &files {
|
||||
refused_everywhere(&two, &b, path, name, TIN_FILE).await;
|
||||
}
|
||||
// Text with a TIN the server never wrote: refused by its text.
|
||||
let fresh = b.out.join("payees.csv");
|
||||
std::fs::write(&fresh, format!("name,ssn\nDana,{}\n", "634-28-1907")).unwrap();
|
||||
refused_everywhere(&two, &b, &fresh, "payees.csv", TIN_PRINTED).await;
|
||||
// An ordinary file still goes in, every way.
|
||||
let fine = b.inbox.join("lunch.pdf");
|
||||
std::fs::write(&fine, b"%PDF-1.4\n\xff lunch receipt, order 12-34\n").unwrap();
|
||||
ok(
|
||||
&two,
|
||||
"books.import_local_file",
|
||||
json!({"path": fine.to_str().unwrap(), "category": "receipt"}),
|
||||
)
|
||||
.await;
|
||||
// The books' own files the package carried are not marked: the
|
||||
// statement still goes in.
|
||||
{
|
||||
let archive = zip::ZipArchive::new(std::fs::File::open(&zip).unwrap()).unwrap();
|
||||
assert!(
|
||||
archive
|
||||
.file_names()
|
||||
.filter_map(Result::ok)
|
||||
.any(|n| n.starts_with("documents/") && n.ends_with("statement.csv")),
|
||||
"the package carries the statement"
|
||||
);
|
||||
}
|
||||
accepted_everywhere(&two, &b, "statement-again.csv", BANK_CSV).await;
|
||||
drop((one, two));
|
||||
drop(server);
|
||||
|
||||
// A server started afresh on the same books refuses them all too.
|
||||
let (_server, url) = serve(&b);
|
||||
let three = connect(&url).await;
|
||||
for (path, name) in &files {
|
||||
refused_everywhere(&three, &b, path, name, TIN_FILE).await;
|
||||
}
|
||||
// The registry holds hashes only.
|
||||
let registry = std::fs::read_to_string(b.dir.join("vault/tin-files.sha256")).unwrap();
|
||||
assert!(registry.lines().count() >= files.len(), "{registry}");
|
||||
assert!(
|
||||
registry
|
||||
.lines()
|
||||
.all(|l| l.len() == 64 && l.chars().all(|c| c.is_ascii_hexdigit())),
|
||||
"{registry}"
|
||||
);
|
||||
}
|
||||
|
||||
/// INVARIANT 1, the other way: a books.set_w9 that is refused (an unknown
|
||||
/// party, a party without a 1099 role, a file that is no PDF, PNG or
|
||||
/// JPEG) never marks the file it names: the same bytes are then filed as
|
||||
/// an ordinary document. Once a set_w9 with the file succeeds, they are
|
||||
/// refused everywhere.
|
||||
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
|
||||
async fn a_refused_set_w9_never_marks_its_file() {
|
||||
let b = books("w9-refused");
|
||||
let w9 = b.inbox.join("w9.pdf");
|
||||
let w9_bytes = b"%PDF-1.4\n\xff\xfe\x00 a scanned W-9 \x04\x05\n%%EOF\n".to_vec();
|
||||
std::fs::write(&w9, &w9_bytes).unwrap();
|
||||
let notes = b.inbox.join("notes.txt");
|
||||
std::fs::write(¬es, b"Acme sent their W-9 on the 3rd.\n").unwrap();
|
||||
let (_server, url) = serve(&b);
|
||||
let c = connect(&url).await;
|
||||
for (code, name, ty) in [("1000", "Cash", "asset"), ("3000", "Capital", "equity")] {
|
||||
ok(
|
||||
&c,
|
||||
"books.add_account",
|
||||
json!({"code": code, "name": name, "account_type": ty}),
|
||||
)
|
||||
.await;
|
||||
}
|
||||
for (name, role) in [("Acme", "contractor"), ("Kat", "member")] {
|
||||
ok(
|
||||
&c,
|
||||
"books.add_party",
|
||||
json!({"name": name, "roles": [role]}),
|
||||
)
|
||||
.await;
|
||||
}
|
||||
let w9_args = |party: &str, path: &Path| {
|
||||
json!({"party": party, "received_on": "2026-01-03", "entity_type": "Individual",
|
||||
"tin": SSN, "tin_type": "ssn", "w9_file_path": path.to_str().unwrap()})
|
||||
};
|
||||
for (party, path, why) in [
|
||||
("Nobody", &w9, "unknown party"),
|
||||
("Kat", &w9, "1099"),
|
||||
("Acme", ¬es, "PDF, PNG, or JPEG"),
|
||||
] {
|
||||
let err = call(&c, "books.set_w9", w9_args(party, path))
|
||||
.await
|
||||
.expect_err("refused");
|
||||
assert!(err.contains(why), "{party}: {err}");
|
||||
}
|
||||
// Neither file was marked: each is filed as any document is.
|
||||
for (name, bytes) in [
|
||||
("w9-scan.pdf", w9_bytes.clone()),
|
||||
("notes.txt", std::fs::read(¬es).unwrap()),
|
||||
] {
|
||||
let out = ok(
|
||||
&c,
|
||||
"books.file_document",
|
||||
json!({"category": "other", "file_name": name, "mime_type": "application/pdf",
|
||||
"content_base64": b64(&bytes)}),
|
||||
)
|
||||
.await;
|
||||
assert!(out["attachment_id"].is_u64(), "{name}: {out}");
|
||||
}
|
||||
// A set_w9 that succeeds marks it.
|
||||
ok(&c, "books.set_w9", w9_args("Acme", &w9)).await;
|
||||
let err = call(
|
||||
&c,
|
||||
"books.file_document",
|
||||
json!({"category": "other", "file_name": "again.pdf", "mime_type": "application/pdf",
|
||||
"content_base64": b64(&w9_bytes)}),
|
||||
)
|
||||
.await
|
||||
.expect_err("marked");
|
||||
assert!(err.contains(TIN_FILE), "{err}");
|
||||
}
|
||||
|
||||
/// Every way a file enters the books takes the text `name` holding
|
||||
/// `text`, and the journal shows it.
|
||||
async fn accepted_everywhere(c: &Client, b: &Books, name: &str, text: &str) {
|
||||
let path = b.inbox.join(name);
|
||||
std::fs::write(&path, text).unwrap();
|
||||
for (tool, args) in [
|
||||
(
|
||||
"books.import_local_file",
|
||||
json!({"path": path.to_str().unwrap(), "category": "document", "document_category": "statement"}),
|
||||
),
|
||||
(
|
||||
"books.attach_receipt",
|
||||
json!({"file_name": name, "mime_type": "text/csv", "content_base64": b64(text.as_bytes())}),
|
||||
),
|
||||
(
|
||||
"books.file_document",
|
||||
json!({"category": "import_source", "file_name": name, "mime_type": "text/csv", "content_base64": b64(text.as_bytes())}),
|
||||
),
|
||||
] {
|
||||
let out = ok(c, tool, args).await;
|
||||
assert!(out["attachment_id"].is_u64(), "{tool}: {out}");
|
||||
}
|
||||
std::fs::remove_file(path).unwrap();
|
||||
}
|
||||
|
||||
/// A real bank export: ABA routing numbers (nine digits), account and
|
||||
/// trace numbers, long references, dates run into amounts, a ZIP+4, a
|
||||
/// phone number, and the number 12345 in a ten-digit run.
|
||||
const BANK_CSV: &str = "\
|
||||
Date,Description,Amount,Balance,Reference
|
||||
2026-10-01,ACH CREDIT APPLE INC 021000021 ID 9876543210123456,1499.00,\"12,345.67\",20261001000123456789
|
||||
2026-10-02,WIRE IN 026009593 ACCT 4417123456789 TRACE 0210000210012345,250000.00,262345.67,FT26275987654321
|
||||
2026-10-03 12.50,POS 2026-10-03 801-555-1234 SALT LAKE UT 84101-1234,-12.50,262333.17,1002345678
|
||||
2026-10-04,ZELLE 5551234567 CONF 1123-45-6789 REF 123-45-67890,-40.00,262293.17,000123456789012
|
||||
2026-10-05,CHECK 1042 SEQ 026 00 9593 ITEM 112-3456789,-100.00,262193.17,ROUTING 121000358
|
||||
";
|
||||
|
||||
/// INVARIANTS 2-4 through the tools: a member's TIN the vault holds is
|
||||
/// refused in each rendering by every filing tool; a printed SSN or EIN
|
||||
/// shape is refused with the vault locked as with it open, while the
|
||||
/// vault's TIN written bare then goes in (only the shapes are left); a
|
||||
/// bank export goes in either way.
|
||||
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
|
||||
async fn text_with_a_vault_tin_or_a_printed_one_is_refused_and_a_bank_export_is_not() {
|
||||
let b = books("text");
|
||||
let (server, url) = serve(&b);
|
||||
let c = connect(&url).await;
|
||||
ok(
|
||||
&c,
|
||||
"books.add_party",
|
||||
json!({"name": "Kat", "roles": ["member"]}),
|
||||
)
|
||||
.await;
|
||||
ok(
|
||||
&c,
|
||||
"books.set_tin",
|
||||
json!({"party": "Kat", "tin": MEMBER_SSN, "tin_type": "ssn"}),
|
||||
)
|
||||
.await;
|
||||
let renderings = [
|
||||
"412705531",
|
||||
"412-70-5531",
|
||||
"412 70 5531",
|
||||
"412.70.5531",
|
||||
"41-2705531",
|
||||
"41 2705531",
|
||||
];
|
||||
for (n, tin) in renderings.iter().enumerate() {
|
||||
let path = b.out.join(format!("members-{n}.csv"));
|
||||
std::fs::write(&path, format!("member,tin\nKat,{tin}\n")).unwrap();
|
||||
refused_everywhere(&c, &b, &path, &format!("members-{n}.csv"), TIN_HELD).await;
|
||||
}
|
||||
for (n, printed) in ["Dana,634-28-1907", "Acme LLC,47-3920615"]
|
||||
.iter()
|
||||
.enumerate()
|
||||
{
|
||||
let path = b.out.join(format!("payees-{n}.csv"));
|
||||
std::fs::write(&path, format!("payee,tin\n{printed}\n")).unwrap();
|
||||
refused_everywhere(&c, &b, &path, &format!("payees-{n}.csv"), TIN_PRINTED).await;
|
||||
}
|
||||
accepted_everywhere(&c, &b, "bank.csv", BANK_CSV).await;
|
||||
drop(c);
|
||||
drop(server);
|
||||
|
||||
// The vault locked (its key gone): the printed shapes are still
|
||||
// refused, and the bank export still goes in; the vault's TIN written
|
||||
// bare is no longer recognized.
|
||||
std::fs::remove_file(b.dir.parent().unwrap().join("config/vault.key")).unwrap();
|
||||
let (_server, url) = serve(&b);
|
||||
let c = connect(&url).await;
|
||||
let path = b.out.join("payees-0.csv");
|
||||
refused_everywhere(&c, &b, &path, "payees-0.csv", TIN_PRINTED).await;
|
||||
let path = b.out.join("members-1.csv");
|
||||
refused_everywhere(&c, &b, &path, "members-1.csv", TIN_PRINTED).await;
|
||||
accepted_everywhere(
|
||||
&c,
|
||||
&b,
|
||||
"bank-2.csv",
|
||||
&format!("{BANK_CSV}2026-10-06,x,1.00,1.00,1\n"),
|
||||
)
|
||||
.await;
|
||||
accepted_everywhere(&c, &b, "members-0.csv", "member,tin\nKat,412705531\n").await;
|
||||
}
|
||||
|
||||
/// INVARIANT 3 through the tools: UTF-16 text written without a
|
||||
/// byte-order mark (ASCII so written is valid UTF-8, each digit followed
|
||||
/// or led by a NUL) is read as the text it is, either way round: a vault
|
||||
/// TIN and a printed SSN in it are refused by every filing tool,
|
||||
/// `books.file_document` included, and nothing is stored.
|
||||
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
|
||||
async fn utf16_text_without_a_byte_order_mark_is_scanned_either_way_round() {
|
||||
let b = books("utf16");
|
||||
let (_server, url) = serve(&b);
|
||||
let c = connect(&url).await;
|
||||
ok(
|
||||
&c,
|
||||
"books.add_party",
|
||||
json!({"name": "Kat", "roles": ["member"]}),
|
||||
)
|
||||
.await;
|
||||
ok(
|
||||
&c,
|
||||
"books.set_tin",
|
||||
json!({"party": "Kat", "tin": MEMBER_SSN, "tin_type": "ssn"}),
|
||||
)
|
||||
.await;
|
||||
let bare = |text: &str, le: bool| -> Vec<u8> {
|
||||
text.encode_utf16()
|
||||
.flat_map(|u| if le { u.to_le_bytes() } else { u.to_be_bytes() })
|
||||
.collect()
|
||||
};
|
||||
for (le, side) in [(true, "le"), (false, "be")] {
|
||||
for (text, why, tag) in [
|
||||
("member,tin\nKat,412705531\n", TIN_HELD, "held"),
|
||||
("payee,tin\nDana,634-28-1907\n", TIN_PRINTED, "printed"),
|
||||
] {
|
||||
let bytes = bare(text, le);
|
||||
assert!(
|
||||
le && bytes[1] == 0 || !le && bytes[0] == 0,
|
||||
"NUL-interleaved, no byte-order mark"
|
||||
);
|
||||
let name = format!("utf16-{side}-{tag}.csv");
|
||||
let path = b.out.join(&name);
|
||||
std::fs::write(&path, &bytes).unwrap();
|
||||
refused_everywhere(&c, &b, &path, &name, why).await;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// INVARIANT 3 through the tools: text with three numbers ending in the
|
||||
/// last four of a TIN the books know (a member's TIN in the vault, a
|
||||
/// payee's W-9 kept elsewhere) is refused by every filing tool, byte for
|
||||
/// byte alike whether one of them is the vault's TIN or none is, with the
|
||||
/// vault open or locked; one such number goes in unless it is the TIN; a
|
||||
/// bank export goes in.
|
||||
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
|
||||
async fn text_probing_for_a_tin_is_refused_alike_by_every_filing_tool() {
|
||||
let b = books("probe");
|
||||
let (server, url) = serve(&b);
|
||||
let c = connect(&url).await;
|
||||
ok(
|
||||
&c,
|
||||
"books.add_party",
|
||||
json!({"name": "Kat", "roles": ["member"]}),
|
||||
)
|
||||
.await;
|
||||
ok(
|
||||
&c,
|
||||
"books.set_tin",
|
||||
json!({"party": "Kat", "tin": MEMBER_SSN, "tin_type": "ssn"}),
|
||||
)
|
||||
.await;
|
||||
// A W-9 kept at the CPA's: the books know its last four, the vault
|
||||
// holds nothing for it.
|
||||
ok(
|
||||
&c,
|
||||
"books.add_party",
|
||||
json!({"name": "Acme", "roles": ["contractor"]}),
|
||||
)
|
||||
.await;
|
||||
ok(
|
||||
&c,
|
||||
"books.set_w9",
|
||||
json!({"party": "Acme", "received_on": "2026-01-03", "entity_type": "C corporation",
|
||||
"tin_last4": "7788", "kept_at": "CPA portal"}),
|
||||
)
|
||||
.await;
|
||||
let write = |name: &str, text: &str| {
|
||||
let path = b.out.join(name);
|
||||
std::fs::write(&path, text).unwrap();
|
||||
path
|
||||
};
|
||||
let with_tin = write(
|
||||
"with.csv",
|
||||
"member,ref\nKat,412705531\nA,100005531\nB,100015531\n",
|
||||
);
|
||||
let without = write(
|
||||
"without.csv",
|
||||
"member,ref\nKat,100025531\nA,100005531\nB,100015531\n",
|
||||
);
|
||||
let payee = write("payee.csv", "ref\n100007788\n100017788\n100027788\n");
|
||||
let one = write("one.csv", "member,ref\nKat,100025531\n");
|
||||
let tin = write("tin.csv", "member,ref\nKat,412705531\n");
|
||||
let probes = async |c: &Client| {
|
||||
let a = refused_everywhere(c, &b, &with_tin, "with.csv", TIN_PROBE).await;
|
||||
let z = refused_everywhere(c, &b, &without, "without.csv", TIN_PROBE).await;
|
||||
assert_eq!(a, z, "the refusal tells whether the vault's TIN is there");
|
||||
refused_everywhere(c, &b, &payee, "payee.csv", TIN_PROBE).await;
|
||||
a
|
||||
};
|
||||
let open = probes(&c).await;
|
||||
refused_everywhere(&c, &b, &tin, "tin.csv", TIN_HELD).await;
|
||||
accepted_everywhere(&c, &b, "one.csv", &std::fs::read_to_string(&one).unwrap()).await;
|
||||
accepted_everywhere(&c, &b, "bank.csv", BANK_CSV).await;
|
||||
drop(c);
|
||||
drop(server);
|
||||
|
||||
// The vault locked: the same refusals, word for word.
|
||||
std::fs::remove_file(b.dir.parent().unwrap().join("config/vault.key")).unwrap();
|
||||
let (_server, url) = serve(&b);
|
||||
let c = connect(&url).await;
|
||||
assert_eq!(
|
||||
probes(&c).await,
|
||||
open,
|
||||
"the refusal tells whether the vault is open"
|
||||
);
|
||||
}
|
||||
Reference in new issue
Block a user