@crewhaus/tool-ledger 0.7.0

package/dist/lib/reconcile.js

@@ -0,0 +1,335 @@
+import { LedgerError, assertIsoDate, byString, dayDiff, formatMajor } from "./amount";
+export const MATCH_KINDS = ["reference", "amount-date", "grouped", "grouped-with-fee"];
+export const RECONCILE_LIMITS = {
+    rowsPerSide: 20_000,
+    maxSubsetSize: 8,
+    /** Subsets examined for ONE right-hand row before the search gives up. */
+    maxCombinations: 200_000,
+};
+/** Rows in a fixed order, and a refusal when two of them share an id. */
+function prepare(rows, side) {
+    if (rows.length > RECONCILE_LIMITS.rowsPerSide) {
+        throw new LedgerError(`the ${side} side has ${rows.length} rows, over the ${RECONCILE_LIMITS.rowsPerSide} limit`);
+    }
+    const seen = new Set();
+    for (const row of rows) {
+        if (seen.has(row.id)) {
+            throw new LedgerError(`two rows on the ${side} side share the id "${row.id}" — a match against an ambiguous id cannot be acted on, so fix the ids rather than have this pick one`);
+        }
+        seen.add(row.id);
+        assertIsoDate(row.date, `${side} row "${row.id}" date`);
+        if (!Number.isSafeInteger(row.amountMinor)) {
+            throw new LedgerError(`${side} row "${row.id}" has amountMinor ${row.amountMinor}, which is not a whole number of minor units`);
+        }
+    }
+    // Date then id: the order every later pass iterates in, so "the first
+    // candidate" means the same thing on every run and on every machine.
+    return [...rows].sort((a, b) => byString(a.date, b.date) || byString(a.id, b.id));
+}
+const normalizeReference = (value) => value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, "");
+const absolute = (v) => (v < 0n ? -v : v);
+export function reconcile(leftRows, rightRows, options) {
+    const left = prepare(leftRows, "left");
+    const right = prepare(rightRows, "right");
+    const money = (v) => formatMajor(v, options.exponent);
+    const amountOf = (t) => BigInt(t.amountMinor);
+    const rightDates = new Map(right.map((r) => [r.id, r.date]));
+    const claimedLeft = new Set();
+    const claimedRight = new Set();
+    const matched = [];
+    const nearMisses = [];
+    const groupingTruncated = [];
+    const inWindow = (a, b) => Math.abs(dayDiff(a.date, b.date)) <= options.windowDays;
+    // --- pass 1: the reference both sides carry --------------------------------
+    // An identifier that matches is the strongest evidence there is, which is
+    // exactly why a matching reference with a DIFFERENT amount is reported as a
+    // near miss and not matched: that pair is the most interesting row in the
+    // file, and pairing it would hide it.
+    for (const l of left) {
+        if (claimedLeft.has(l.id))
+            continue;
+        const key = normalizeReference(l.reference);
+        if (key === "")
+            continue;
+        const candidates = right.filter((r) => !claimedRight.has(r.id) && normalizeReference(r.reference) === key);
+        const exact = candidates.find((r) => amountOf(r) === amountOf(l));
+        if (exact !== undefined) {
+            claimedLeft.add(l.id);
+            claimedRight.add(exact.id);
+            matched.push({
+                kind: "reference",
+                leftIds: [l.id],
+                rightId: exact.id,
+                amountMinor: amountOf(l).toString(),
+                amount: money(amountOf(l)),
+                dateDeltaDays: dayDiff(l.date, exact.date),
+                feeMinor: "0",
+                why: `reference "${l.reference}" and an identical amount`,
+            });
+            continue;
+        }
+        const candidate = candidates[0];
+        if (candidate !== undefined) {
+            const delta = amountOf(l) - amountOf(candidate);
+            nearMisses.push({
+                kind: "reference",
+                leftId: l.id,
+                rightId: candidate.id,
+                amountDeltaMinor: delta.toString(),
+                amountDelta: money(delta),
+                dateDeltaDays: dayDiff(l.date, candidate.date),
+                why: `reference "${l.reference}" is the same on both sides but the amounts differ by ${money(delta)} — neither row is matched, because the disagreement is the finding`,
+            });
+        }
+    }
+    if (options.requireReferenceMatch) {
+        return assemble();
+    }
+    // --- pass 2: identical amount inside the date window -----------------------
+    for (const l of left) {
+        if (claimedLeft.has(l.id))
+            continue;
+        const candidates = right
+            .filter((r) => !claimedRight.has(r.id) && amountOf(r) === amountOf(l) && inWindow(l, r))
+            .sort((a, b) => Math.abs(dayDiff(l.date, a.date)) - Math.abs(dayDiff(l.date, b.date)) ||
+            byString(a.date, b.date) ||
+            byString(a.id, b.id));
+        const pick = candidates[0];
+        if (pick === undefined)
+            continue;
+        claimedLeft.add(l.id);
+        claimedRight.add(pick.id);
+        matched.push({
+            kind: "amount-date",
+            leftIds: [l.id],
+            rightId: pick.id,
+            amountMinor: amountOf(l).toString(),
+            amount: money(amountOf(l)),
+            dateDeltaDays: dayDiff(l.date, pick.date),
+            feeMinor: "0",
+            why: `identical amount within ${options.windowDays} day(s)`,
+        });
+    }
+    // --- pass 3: near misses ---------------------------------------------------
+    if (options.toleranceMinor > 0n) {
+        for (const l of left) {
+            if (claimedLeft.has(l.id))
+                continue;
+            const candidates = right
+                .filter((r) => {
+                if (claimedRight.has(r.id) || !inWindow(l, r))
+                    return false;
+                const delta = absolute(amountOf(l) - amountOf(r));
+                return delta > 0n && delta <= options.toleranceMinor;
+            })
+                .sort((a, b) => {
+                const da = absolute(amountOf(l) - amountOf(a));
+                const dbb = absolute(amountOf(l) - amountOf(b));
+                return da < dbb ? -1 : da > dbb ? 1 : byString(a.date, b.date) || byString(a.id, b.id);
+            });
+            const pick = candidates[0];
+            if (pick === undefined)
+                continue;
+            const delta = amountOf(l) - amountOf(pick);
+            nearMisses.push({
+                kind: "tolerance",
+                leftId: l.id,
+                rightId: pick.id,
+                amountDeltaMinor: delta.toString(),
+                amountDelta: money(delta),
+                dateDeltaDays: dayDiff(l.date, pick.date),
+                why: `the amounts differ by ${money(delta)}, inside the tolerance — reported for a person to decide, NOT matched`,
+            });
+        }
+    }
+    // --- pass 4: several left rows bundled into one right row ------------------
+    if (options.allowManyToOne) {
+        for (const r of right) {
+            if (claimedRight.has(r.id))
+                continue;
+            const pool = left.filter((l) => !claimedLeft.has(l.id) && inWindow(l, r));
+            const found = findSubset(pool, amountOf(r), options.maxSubsetSize, options.maxCombinations, options.feeToleranceMinor, amountOf);
+            if (found.truncated)
+                groupingTruncated.push(r.id);
+            if (found.subset === null)
+                continue;
+            for (const l of found.subset)
+                claimedLeft.add(l.id);
+            claimedRight.add(r.id);
+            const sum = found.subset.reduce((s, l) => s + amountOf(l), 0n);
+            const fee = sum - amountOf(r);
+            matched.push({
+                kind: fee === 0n ? "grouped" : "grouped-with-fee",
+                leftIds: found.subset.map((l) => l.id),
+                rightId: r.id,
+                amountMinor: amountOf(r).toString(),
+                amount: money(amountOf(r)),
+                dateDeltaDays: Math.max(...found.subset.map((l) => Math.abs(dayDiff(l.date, r.date)))),
+                feeMinor: fee.toString(),
+                why: fee === 0n
+                    ? `${found.subset.length} rows sum exactly to this one`
+                    : `${found.subset.length} rows sum to ${money(sum)} against ${money(amountOf(r))}; the ${money(fee)} difference is within the fee tolerance and is proposed as a fee entry, never absorbed silently`,
+            });
+        }
+    }
+    return assemble();
+    function assemble() {
+        const unmatchedLeft = left.filter((l) => !claimedLeft.has(l.id)).map((l) => describe(l, money));
+        const unmatchedRight = right
+            .filter((r) => !claimedRight.has(r.id))
+            .map((r) => describe(r, money));
+        // A row flagged on AMOUNT alone and then explained by a later pass is no
+        // longer a near miss; reporting it in both lists would have a reviewer
+        // chasing a row that is already accounted for.
+        //
+        // A REFERENCE disagreement is never dropped, whatever claims the rows
+        // afterwards. Pass 2 will happily pair the left row with some other row of
+        // the same amount, and dropping the near miss then would delete the only
+        // record that two documents carrying one identifier disagree about the
+        // money — which is the finding this module says it exists to preserve, and
+        // "the amounts happened to match somewhere else" is not an explanation of
+        // it.
+        const openNearMisses = nearMisses.filter((n) => n.kind === "reference" || (!claimedLeft.has(n.leftId) && !claimedRight.has(n.rightId)));
+        const leftTotal = left.reduce((s, l) => s + amountOf(l), 0n);
+        const rightTotal = right.reduce((s, r) => s + amountOf(r), 0n);
+        return {
+            matched,
+            nearMisses: openNearMisses,
+            unmatchedLeft,
+            unmatchedRight,
+            proposedEntries: propose(matched, unmatchedRight, rightDates, options, money),
+            summary: {
+                leftCount: left.length,
+                rightCount: right.length,
+                leftTotalMinor: leftTotal.toString(),
+                rightTotalMinor: rightTotal.toString(),
+                leftTotal: money(leftTotal),
+                rightTotal: money(rightTotal),
+                differenceMinor: (leftTotal - rightTotal).toString(),
+                difference: money(leftTotal - rightTotal),
+                matchedCount: matched.length,
+                nearMissCount: openNearMisses.length,
+                currency: options.currency,
+            },
+            groupingTruncated,
+        };
+    }
+}
+function describe(t, money) {
+    return {
+        id: t.id,
+        date: t.date,
+        description: t.description,
+        amountMinor: String(t.amountMinor),
+        amount: money(BigInt(t.amountMinor)),
+        reference: t.reference,
+    };
+}
+/**
+ * The first subset, in canonical order, that sums to `target` — or to
+ * `target` plus a residue no larger than `feeTolerance` when that is on.
+ *
+ * "First in canonical order" is the whole design. Subsets are walked by
+ * ascending SIZE and then lexicographically over a pool already sorted by
+ * (date, id), and the search returns immediately on a hit. So when three
+ * different bundles of charges add up to the same payout — which happens
+ * constantly with round numbers — the same bundle is chosen every time, and
+ * the fee entry proposed next to it does not move between runs. Collecting
+ * every solution and then picking would give the same answer and cost the
+ * exponential blow-up this cap exists to avoid.
+ */
+function findSubset(pool, target, maxSize, maxCombinations, feeTolerance, amountOf) {
+    let examined = 0;
+    const acceptable = (sum) => {
+        if (sum === target)
+            return true;
+        if (feeTolerance === 0n)
+            return false;
+        const residue = sum - target;
+        // A fee is withheld FROM the bundle, so the payout is smaller in
+        // magnitude. A residue the other way means the payout exceeds the charges
+        // it supposedly bundles, which is not a fee and is not quietly absorbed.
+        if (residue === 0n)
+            return false;
+        if (absolute(sum) <= absolute(target))
+            return false;
+        return absolute(residue) <= feeTolerance;
+    };
+    for (let size = 2; size <= Math.min(maxSize, pool.length); size++) {
+        const indices = Array.from({ length: size }, (_, i) => i);
+        for (;;) {
+            examined += 1;
+            if (examined > maxCombinations)
+                return { subset: null, truncated: true };
+            const subset = indices.map((i) => pool[i]);
+            if (acceptable(subset.reduce((s, t) => s + amountOf(t), 0n))) {
+                return { subset, truncated: false };
+            }
+            // Standard lexicographic successor over combinations.
+            let cursor = size - 1;
+            while (cursor >= 0 && indices[cursor] === pool.length - size + cursor)
+                cursor--;
+            if (cursor < 0)
+                break;
+            indices[cursor] = indices[cursor] + 1;
+            for (let j = cursor + 1; j < size; j++)
+                indices[j] = indices[j - 1] + 1;
+        }
+    }
+    return { subset: null, truncated: false };
+}
+/**
+ * Entries a caller could post, returned and never posted.
+ *
+ * Nothing in this package writes to the ledger from a reconciliation, and
+ * nothing anywhere in it transmits a payment instruction. These are drafts:
+ * the fee a payout withheld, and a statement line the ledger has never seen,
+ * parked in suspense for a person to code.
+ */
+function propose(matched, unmatchedRight, rightDates, options, money) {
+    const accounts = options.propose;
+    if (accounts === undefined)
+        return [];
+    const out = [];
+    for (const match of matched) {
+        const fee = BigInt(match.feeMinor);
+        if (fee === 0n)
+            continue;
+        const magnitude = absolute(fee);
+        out.push({
+            // The payout's own date, not an empty string: a draft entry has to be
+            // something LedgerPost would actually accept.
+            date: rightDates.get(match.rightId) ?? "",
+            memo: `processor fee withheld from ${match.rightId}`,
+            reference: match.rightId,
+            lines: [
+                { account: accounts.feeAccount, debitMinor: magnitude.toString() },
+                { account: accounts.bankAccount, creditMinor: magnitude.toString() },
+            ],
+            why: `the bundle exceeds the payout by ${money(fee)}`,
+        });
+    }
+    for (const row of unmatchedRight) {
+        const amount = BigInt(row.amountMinor);
+        const magnitude = absolute(amount);
+        out.push({
+            date: row.date,
+            memo: row.description === "" ? `unmatched statement line ${row.id}` : row.description,
+            reference: row.reference,
+            lines: amount >= 0n
+                ? [
+                    { account: accounts.bankAccount, debitMinor: magnitude.toString() },
+                    { account: accounts.suspenseAccount, creditMinor: magnitude.toString() },
+                ]
+                : [
+                    { account: accounts.suspenseAccount, debitMinor: magnitude.toString() },
+                    { account: accounts.bankAccount, creditMinor: magnitude.toString() },
+                ],
+            why: "the ledger has no line for this statement row; parked in suspense for a person to code",
+        });
+    }
+    return out;
+}

package/dist/paths.d.ts

@@ -0,0 +1,42 @@
+import { CrewhausError } from "@crewhaus/errors";
+/** Raised when a caller-supplied path resolves outside the workspace root. */
+export declare class ToolPermissionError extends CrewhausError {
+    readonly name = "ToolPermissionError";
+    readonly toolName: string;
+    readonly path: string;
+    constructor(toolName: string, attemptedPath: string);
+}
+/**
+ * A validated path, in both forms the tools need.
+ *
+ * `real` has every in-workspace symlink already resolved and is what I/O
+ * should use — operating on it closes most of the check-to-use window.
+ * `abs` is the lexical resolution, which is what a tool must use when the
+ * question is about the link ITSELF (`Stat` reporting a symlink target,
+ * `RemovePath` deleting a link rather than its destination).
+ */
+export type SafePath = {
+    readonly abs: string;
+    readonly real: string;
+    /** The path as the caller wrote it, for echoing back in results. */
+    readonly given: string;
+    /** Slash-separated path relative to the workspace root. */
+    readonly rel: string;
+};
+/** The workspace root, resolved. Every path is contained within it. */
+export declare function workspaceRoot(): string;
+export declare function resolveSafe(toolName: string, rel: string, root?: string): SafePath;
+/** A path relative to the workspace root, with `/` separators on every OS. */
+export declare function toPosix(p: string): string;
+/**
+ * True when `candidate` is `parent` or lives underneath it. Both must already
+ * be absolute. Used to keep an archive entry, or a symlink inside an
+ * extracted tree, from reaching outside its destination.
+ */
+export declare function isInside(parent: string, candidate: string): boolean;
+/**
+ * Reject an archive member name that would escape its destination: an
+ * absolute path, a Windows drive prefix, or any `..` segment. Checked on the
+ * NAME, before extraction, because after extraction the damage is done.
+ */
+export declare function archiveEntryEscapes(name: string): boolean;

package/dist/paths.js

@@ -0,0 +1,158 @@
+/**
+ * Path containment — the gate every caller-supplied path in this package
+ * passes through before any syscall touches it.
+ *
+ * The approach is the one `@crewhaus/tool-fs` uses, and for the same reasons:
+ * a lexical check alone is fooled by a symlink that lives inside the
+ * workspace and points outside it (CWE-59), so the real path is checked too.
+ * The workspace root is `process.cwd()`, matching tool-fs, so a harness that
+ * trusts one tool's boundary gets the same boundary here.
+ */
+import { lstatSync, readlinkSync, realpathSync } from "node:fs";
+import * as path from "node:path";
+import { CrewhausError } from "@crewhaus/errors";
+/** Raised when a caller-supplied path resolves outside the workspace root. */
+export class ToolPermissionError extends CrewhausError {
+    name = "ToolPermissionError";
+    toolName;
+    path;
+    constructor(toolName, attemptedPath) {
+        super("tool", `tool "${toolName}" rejected path "${attemptedPath}": resolved location escapes the workspace root`);
+        this.toolName = toolName;
+        this.path = attemptedPath;
+    }
+}
+/** The workspace root, resolved. Every path is contained within it. */
+export function workspaceRoot() {
+    return path.resolve(process.cwd());
+}
+/**
+ * Resolve `rel` inside the workspace, or throw `ToolPermissionError`.
+ *
+ * The leaf is allowed not to exist — every tool here that creates something
+ * needs to validate a destination before it is made — so the deepest
+ * EXISTING ancestor is realpath'd and the missing tail re-appended. Any
+ * failure other than that walk fails closed.
+ */
+/**
+ * True when the NAME exists, whether or not it leads anywhere.
+ *
+ * `existsSync` FOLLOWS symlinks, so it answers false for a link whose target
+ * is missing — and that is exactly the case that matters: a dangling link is
+ * still a door, because `open(…, "w")` through `evil -> /outside/x` CREATES
+ * `/outside/x`. Probing with `lstat` keeps the link's name in the part of the
+ * path that gets resolved, rather than in the "does not exist yet" tail that
+ * is re-appended to the root verbatim and so passes the containment check.
+ */
+function nameExists(p) {
+    try {
+        lstatSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Where `target` would actually land, with every symlink on the way already
+ * followed — including one whose own target does not exist yet.
+ *
+ * `realpathSync` gives up with ENOENT on a dangling link, which would leave
+ * that link unresolved and let it stand in for a plain missing file. So the
+ * deepest ancestor that exists as a NAME is resolved, a dangling one is
+ * followed a hop by hand, and the components that do not exist are appended.
+ * The result is the path an `open` would create, which is the only path worth
+ * checking containment against.
+ */
+function resolveLocation(target, depth = 0) {
+    if (depth > 40)
+        throw new Error(`symlink chain at "${target}" is too long to resolve`);
+    let probe = target;
+    const tail = [];
+    while (!nameExists(probe)) {
+        tail.unshift(path.basename(probe));
+        const parent = path.dirname(probe);
+        if (parent === probe)
+            break; // reached the filesystem root
+        probe = parent;
+    }
+    let probeReal;
+    try {
+        probeReal = realpathSync(probe);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+        // The name is there but `realpath` cannot finish it: a symlink with a
+        // missing target. `readlinkSync` throws EINVAL on anything else, which
+        // fails closed.
+        const link = readlinkSync(probe);
+        // A RELATIVE target resolves against the directory that actually CONTAINS
+        // the link, which is not the link's lexical parent when that parent is
+        // itself reached through a symlink. `<root>/dirlink/x -> ../y` with
+        // `dirlink` pointing out of the root really lands at `<elsewhere>/y`, but
+        // measured from the lexical parent it reads as `<root>/y` — an in-root
+        // path the caller's path does not lead to. So the parent is made real
+        // first. An absolute target ignores the base.
+        const base = realpathSync(path.dirname(probe));
+        probeReal = resolveLocation(path.resolve(base, link), depth + 1);
+    }
+    return tail.length > 0 ? path.join(probeReal, ...tail) : probeReal;
+}
+export function resolveSafe(toolName, rel, root = workspaceRoot()) {
+    const rootResolved = path.resolve(root);
+    const abs = path.resolve(rootResolved, rel);
+    // 1) Lexical containment — rejects `..` and absolute escapes. The trailing
+    //    separator avoids the `/root` vs `/root-sibling` prefix pitfall.
+    if (abs !== rootResolved && !abs.startsWith(`${rootResolved}${path.sep}`)) {
+        throw new ToolPermissionError(toolName, rel);
+    }
+    let real;
+    try {
+        const rootReal = realpathSync(rootResolved);
+        real = resolveLocation(abs);
+        // 2) Symlink-aware containment. The real path must land inside the real
+        //    root, so an in-workspace symlink pointing at /etc is refused here.
+        if (real !== rootReal && !real.startsWith(`${rootReal}${path.sep}`)) {
+            throw new ToolPermissionError(toolName, rel);
+        }
+    }
+    catch (err) {
+        if (err instanceof ToolPermissionError)
+            throw err;
+        throw new ToolPermissionError(toolName, rel);
+    }
+    return {
+        abs,
+        real,
+        given: rel,
+        rel: toPosix(path.relative(rootResolved, abs)),
+    };
+}
+/** A path relative to the workspace root, with `/` separators on every OS. */
+export function toPosix(p) {
+    return path.sep === "/" ? p : p.split(path.sep).join("/");
+}
+/**
+ * True when `candidate` is `parent` or lives underneath it. Both must already
+ * be absolute. Used to keep an archive entry, or a symlink inside an
+ * extracted tree, from reaching outside its destination.
+ */
+export function isInside(parent, candidate) {
+    const p = path.resolve(parent);
+    const c = path.resolve(candidate);
+    return c === p || c.startsWith(`${p}${path.sep}`);
+}
+/**
+ * Reject an archive member name that would escape its destination: an
+ * absolute path, a Windows drive prefix, or any `..` segment. Checked on the
+ * NAME, before extraction, because after extraction the damage is done.
+ */
+export function archiveEntryEscapes(name) {
+    const normalized = name.replace(/\\/g, "/");
+    if (normalized.startsWith("/"))
+        return true;
+    if (/^[A-Za-z]:/.test(normalized))
+        return true;
+    return normalized.split("/").some((segment) => segment === "..");
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@crewhaus/tool-ledger",
+  "version": "0.7.0",
+  "type": "module",
+  "description": "Deterministic double-entry ledger: hash-chained postings, queries, reconciliation and invoice rendering",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.7.0",
+    "@crewhaus/tool-builder": "0.7.0",
+    "@crewhaus/tool-catalog": "0.7.0",
+    "@crewhaus/tool-datetime": "0.7.0",
+    "@crewhaus/tool-math": "0.7.0",
+    "@crewhaus/tool-money": "0.7.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@crewhaus/tool-executor": "workspace:*"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/tool-ledger"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/tool-ledger#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
+}