e-arveldaja-mcp 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## [Unreleased]
 
+## [0.20.0] - 2026-07-10
+
+### Added
+- **`TransactionsApi.confirm` now recovers from an ambiguous network failure on the register call.** Confirming a transaction issues `PATCH /transactions/{id}/register`, which creates a journal server-side, so a dropped connection or timeout is ambiguous — the registration may have committed. Previously such a failure ran the `clients_id` rollback (which would corrupt a *committed* journal's buyer/supplier) and threw, signalling a false failure that could prompt a duplicating retry. On a network error the method now re-reads the transaction (busting the stale cache) and checks its status: if `CONFIRMED` the registration landed, so it keeps `clients_id`, flushes the journal cache, and reports success (with no `created_object_id` — callers already record the sentinel journal id); if still `PROJECT` it rolls back and rethrows as before. A non-network HTTP status is propagated unchanged.
+- **`BookingGuard.createJournalOnce` now recovers from ambiguous network failures (verify-then-retry).** A journal-create POST that fails with a *network* error (timeout / dropped connection, `HttpError.status === "network"`) is ambiguous — the RIK API signs only the request path, not the body, so it has no server-side idempotency and the write may or may not have committed. Rather than blindly retrying (risking a duplicate) or blindly failing (risking an orphan plus a user retry that duplicates), the guard busts the stale journals cache and re-scans the ledger by the create's `document_number` key: if the journal is found the ambiguous write committed, so it is recovered (`recovered: true`) and confirmed if it landed in `PROJECT`, with no retry; if it is not found the create is retried exactly once. A non-network HTTP status (4xx/5xx) is propagated unchanged, since the server saw and rejected the request. The generic http-client keeps its no-retry gate for non-idempotent methods — recovery lives at the guard level, the only place with a checkable key. `reconcile_currency_rounding` and the Lightyear booking sites inherit this automatically.
+
+### Changed
+- **Journal idempotency is now centralized in a single `BookingGuard` layer (`src/booking-guard.ts`).** The RIK API signs only the request path, not the body, so it offers no server-side idempotency — every booking tool had to hand-roll its own "did I already book this?" scan of the ledger, and subtle divergences between those copies (deleted-journal handling, in-run vs cross-run dedup, sentinel journal ids) were the dominant duplicate-booking bug class. `BookingGuard` loads one journal snapshot per run and exposes two lanes: Lane A for namespaced `document_number` keys (`FX:{id}`, `LY:{ref}`) with `find`/`record`/`createJournalOnce`, and Lane B for structural inter-account transfers (`sourceDim|targetDim|amount|date` with reference disambiguation and an optional nearest-first date window). Migrated `reconcile_currency_rounding` (Lane A), the Lightyear buy/sell/cash-equivalent/distribution booking sites (Lane A, preserving the legacy bare-reference date-cross-check), and the Wise and bank-reconciliation inter-account paths (Lane B). Behavior is preserved, with two incidental hardening improvements: `reconcile_currency_rounding` now treats a concurrently-created `FX:` journal as already-reconciled instead of double-posting, and Lightyear booking now dedups repeated references within a single CSV. Lane-A-only callers use the cheaper `listAll` (no per-journal posting fetches); Lane B loads postings only when bank dimensions are supplied.
+
+## [0.19.1] - 2026-07-10
+
+### Fixed
+- **Duplicate-booking and balance-drift hardening (whole-codebase review).** Seven high-severity correctness fixes, each with regression tests:
+  - **Non-idempotent HTTP requests are no longer retried after a network error or timeout.** A `POST`/`PATCH`/`DELETE` that times out or drops its connection is ambiguous — the server may already have committed the mutation — so retrying risked a duplicate invoice, journal, or transaction. Only `GET` and `PUT` (full replace) retry now; the 5xx retry path was already `GET`-only.
+  - **`update_purchase_invoice` re-sends the existing line items when the caller updates header fields only.** The API rejects an item-less PATCH with "Products/services are missing", so every metadata-only update (notes, dates, bank refs) previously failed; the handler now backfills `items` from the current invoice, while a caller that supplies items to change the lines keeps theirs.
+  - **The single-PDF flow now applies the same self-supplier defenses as the receipt batch.** `extract_pdf_invoice` resolves the active company's own VAT number and registry code and excludes them from the extracted supplier fields, and `resolve_supplier` threads them into resolution so the previously-dormant self-match guards fire — refusing to resolve or auto-create the buyer's own company as a supplier, which would otherwise book a purchase against self.
+  - **`reconcile_currency_rounding` FX-difference journals are now idempotent.** The paid-vs-booked residual does not clear when the `FX:{invoice_id}` journal is posted, so a second `execute` run re-detected the same difference and double-booked it; the tool now skips any invoice that already carries an `FX:` journal.
+  - **Inter-account reconciliation no longer confirms both legs of one transfer in a single run.** The in-run journal index was built once at the start and never refreshed, so confirming one leg left the opposite leg looking un-journalized and it was confirmed into a duplicate; each newly-created journal is now recorded into the index immediately.
+  - **Receipt auto-link skips cross-currency (base-amount-only) transaction matches.** When a match survived only on base-currency evidence, the transaction amount is in a different currency than the invoice gross, so auto-confirming posted the wrong distribution amount; the guard the sibling bank-reconciliation path already applied now covers the receipt path too, routing such matches to manual review.
+  - **Lightyear buy trades capitalize the trade platform fee into investment cost.** The fee was expensed instead of added to cost basis, contradicting the FIFO capital-gains report (which bakes the trade fee into cost basis) and stranding a residual on the investment account after every full sell; only the FX conversion fee — which the report excludes — is expensed.
+
 ## [0.19.0] - 2026-07-10
 
 ### Added

package/dist/api/journals.api.d.ts

@@ -11,5 +11,16 @@ export declare class JournalsApi extends BaseResource<Journal> {
     listAllWithPostings(): Promise<Journal[]>;
     confirm(id: number): Promise<ApiResponse>;
     invalidate(id: number): Promise<ApiResponse>;
+    /**
+     * Force-drop the journals list cache so the next `listAll()` /
+     * `listAllWithPostings()` re-reads from the server.
+     *
+     * `create()` only invalidates the cache *after* a successful POST, so a
+     * create that fails with a network error never clears it and the cached
+     * snapshot can still predate the ambiguous write. BookingGuard's
+     * verify-then-retry calls this before re-scanning to check whether the
+     * ambiguous journal actually committed.
+     */
+    invalidateListCache(): void;
 }
 //# sourceMappingURL=journals.api.d.ts.map

package/dist/api/journals.api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"journals.api.d.ts","sourceRoot":"","sources":["../../src/api/journals.api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAS,MAAM,oBAAoB,CAAC;AAEzD,qBAAa,WAAY,SAAQ,YAAY,CAAC,OAAO,CAAC;IACpD,YAAY,MAAM,EAAE,UAAU,EAE7B;IAED;;;;OAIG;IACG,mBAAmB,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CA6B9C;IAEK,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAQ9C;IAEK,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAKjD;CAEF"}
+{"version":3,"file":"journals.api.d.ts","sourceRoot":"","sources":["../../src/api/journals.api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAS,MAAM,oBAAoB,CAAC;AAEzD,qBAAa,WAAY,SAAQ,YAAY,CAAC,OAAO,CAAC;IACpD,YAAY,MAAM,EAAE,UAAU,EAE7B;IAED;;;;OAIG;IACG,mBAAmB,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CA6B9C;IAEK,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAQ9C;IAEK,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAKjD;IAED;;;;;;;;;OASG;IACH,mBAAmB,IAAI,IAAI,CAE1B;CAEF"}

package/dist/api/journals.api.js

@@ -51,5 +51,18 @@ export class JournalsApi extends BaseResource {
         this.invalidateCache("/transactions");
         return result;
     }
+    /**
+     * Force-drop the journals list cache so the next `listAll()` /
+     * `listAllWithPostings()` re-reads from the server.
+     *
+     * `create()` only invalidates the cache *after* a successful POST, so a
+     * create that fails with a network error never clears it and the cached
+     * snapshot can still predate the ambiguous write. BookingGuard's
+     * verify-then-retry calls this before re-scanning to check whether the
+     * ambiguous journal actually committed.
+     */
+    invalidateListCache() {
+        this.invalidateCache();
+    }
 }
 //# sourceMappingURL=journals.api.js.map

package/dist/api/journals.api.js.map

@@ -1 +1 @@
-{"version":3,"file":"journals.api.js","sourceRoot":"","sources":["../../src/api/journals.api.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEzD,MAAM,OAAO,WAAY,SAAQ,YAAqB;IACpD,YAAY,MAAkB;QAC5B,KAAK,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC7B,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,mBAAmB;QACvB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,QAAQ,kBAAkB,CAAC,CAAC;QACnE,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAY,QAAQ,CAAC,CAAC;QAC9C,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;QAE1B,MAAM,GAAG,GAAG,KAAK,CAAC,UAAU,CAAC;QAC7B,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QAEjC,mEAAmE;QACnE,MAAM,YAAY,GAAa,EAAE,CAAC;QAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACpC,MAAM,OAAO,GAAG,GAAG,CAAC,CAAC,CAAE,CAAC;YACxB,IAAI,CAAC,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACvD,IAAI,OAAO,CAAC,EAAE,IAAI,IAAI;oBAAE,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAC/C,CAAC;QACH,CAAC;QAED,+DAA+D;QAC/D,MAAM,SAAS,GAAG,CAAC,CAAC;QACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,YAAY,CAAC,MAAM,EAAE,CAAC,IAAI,SAAS,EAAE,CAAC;YACxD,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC;YACnD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC,EAAG,CAAC,CAAC,CAAC,CAAC;YAC7E,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACtC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAE,CAAC;YAC/B,CAAC;QACH,CAAC;QAED,KAAK,CAAC,mBAAmB,CAAC,QAAQ,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QACnD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,EAAU;QACtB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAc,aAAa,EAAE,WAAW,EAAE,EAAE,CAAC,CAAC;QACpF,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,2EAA2E;QAC3E,wEAAwE;QACxE,yDAAyD;QACzD,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC,CAAC;QACtC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,EAAU;QACzB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAc,aAAa,EAAE,aAAa,EAAE,EAAE,CAAC,CAAC;QACtF,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC,CAAC;QACtC,OAAO,MAAM,CAAC;IAChB,CAAC;CAEF"}
+{"version":3,"file":"journals.api.js","sourceRoot":"","sources":["../../src/api/journals.api.ts"],"names":[],"mappings":"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"}

package/dist/api/transactions.api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transactions.api.d.ts","sourceRoot":"","sources":["../../src/api/transactions.api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,uBAAuB,EAAgC,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACvH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,qBAAa,eAAgB,SAAQ,YAAY,CAAC,WAAW,CAAC;IAC5D,YAAY,MAAM,EAAE,UAAU,EAE7B;IAED;;;;;;OAMG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,uBAAuB,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAsDzF;IAEK,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAOjD;CAEF"}
+{"version":3,"file":"transactions.api.d.ts","sourceRoot":"","sources":["../../src/api/transactions.api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,KAAK,EAAE,WAAW,EAAE,uBAAuB,EAAgC,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACvH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,qBAAa,eAAgB,SAAQ,YAAY,CAAC,WAAW,CAAC;IAC5D,YAAY,MAAM,EAAE,UAAU,EAE7B;IAED;;;;;;OAMG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,uBAAuB,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CA6EzF;IAEK,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAOjD;CAEF"}

package/dist/api/transactions.api.js

@@ -1,3 +1,4 @@
+import { HttpError } from "../http-client.js";
 import { BaseResource } from "./base-resource.js";
 export class TransactionsApi extends BaseResource {
     constructor(client) {
@@ -46,6 +47,30 @@ export class TransactionsApi extends BaseResource {
             return result;
         }
         catch (error) {
+            // A network error on the register PATCH is ambiguous: the registration
+            // creates a journal server-side, so a lost response may mean it actually
+            // committed. Re-read the transaction (busting the stale cache — the
+            // failed PATCH never reached its own invalidateCache) and check its
+            // status before deciding. If it is CONFIRMED the registration landed, so
+            // we must NOT roll back clients_id (that would corrupt the committed
+            // journal's buyer/supplier) and must report success instead of a false
+            // failure that invites a duplicating retry.
+            if (error instanceof HttpError && error.status === "network") {
+                this.invalidateCache();
+                let confirmed = false;
+                try {
+                    confirmed = (await this.get(id)).status === "CONFIRMED";
+                }
+                catch {
+                    // Re-read failed — fall through to the rollback + rethrow path.
+                }
+                if (confirmed) {
+                    this.invalidateCache("/journals");
+                    // The tx re-read does not carry the new journal id; callers already
+                    // tolerate an absent created_object_id (recording the sentinel id).
+                    return { code: 200, messages: ["Registration recovered after network error"] };
+                }
+            }
             if (clientsIdWasSet) {
                 try {
                     await this.update(id, { clients_id: null });

package/dist/api/transactions.api.js.map

@@ -1 +1 @@
-{"version":3,"file":"transactions.api.js","sourceRoot":"","sources":["../../src/api/transactions.api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"transactions.api.js","sourceRoot":"","sources":["../../src/api/transactions.api.ts"],"names":[],"mappings":"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"}

package/dist/booking-guard.d.ts

@@ -0,0 +1,148 @@
+import type { ApiContext } from "./tools/crud-tools.js";
+import type { Journal } from "./types/api.js";
+/**
+ * BookingGuard — a single-snapshot idempotency layer for journal creation.
+ *
+ * The RIK e-Financials API signs only the request path (not the body), so it
+ * offers no server-side idempotency: a retried or re-run POST creates a second
+ * journal. Every booking tool therefore has to detect "did I already book
+ * this?" against the existing ledger before writing. Historically each tool
+ * grew its own scan of `journals.listAll()`, its own `document_number`
+ * convention, and its own create/confirm/record dance — with subtle
+ * divergences (deleted-journal handling, in-run vs cross-run dedup, sentinel
+ * journal ids) that were the dominant source of duplicate-booking bugs.
+ *
+ * BookingGuard centralises that into one snapshot loaded per run, with two
+ * lanes:
+ *
+ *   Lane A — namespaced `document_number` keys (`FX:{id}`, `LY:{ref}`, …).
+ *            Exact-key dedup: one document_number ⇒ at most one live journal.
+ *
+ *   Lane B — structural inter-account transfers keyed
+ *            `sourceDim|targetDim|amount|date` with reference disambiguation.
+ *            Delegates to the existing inter-account-utils index/matcher.
+ *
+ * `createJournalOnce` is the guarded write: find first, create with the
+ * document_number stamped, best-effort confirm, then record into the in-run
+ * index so a second call in the same run is also deduped.
+ *
+ * NOTE: the network-level verify-then-retry (re-scan after a network error to
+ * recover a journal that may have been created despite a failed response) is
+ * intentionally deferred to the http-client migration step. Today the
+ * http-client does not retry non-idempotent POSTs at all, so a POST either
+ * succeeds (we see the id) or throws (nothing created). The guard's find pass
+ * still protects against cross-run and in-run duplicates.
+ */
+export type DocNamespace = "FX" | "LY";
+export interface DocKey {
+    ns: DocNamespace;
+    /** The identifier within the namespace — invoice id, Lightyear reference, … */
+    id: string;
+}
+/** "FX:123" / "LY:OR-EVN9C76R7A" */
+export declare function formatDocNumber(key: DocKey): string;
+/**
+ * Parse a raw `document_number` into a DocKey, or `undefined` when it does not
+ * carry a known namespace prefix (manual journals, legacy entries, …).
+ *
+ * Only the first ":" is treated as the separator, so a reference that itself
+ * contains a colon (unusual, but possible for external ids) round-trips.
+ */
+export declare function parseDocNumber(raw: string | null | undefined): DocKey | undefined;
+export interface ExistingArtifact {
+    journal_id: number;
+    document_number: string;
+    registered: boolean;
+    is_deleted: boolean;
+}
+/**
+ * Liveness filter applied at `find` time.
+ * - `any`             — every artifact, including deleted/invalidated ones.
+ * - `not_deleted`     — exclude deleted/invalidated journals (default). A
+ *                       deleted FX/LY journal means the operator invalidated it
+ *                       to re-post, so it must NOT block re-booking.
+ * - `registered_only` — only confirmed, non-deleted journals.
+ */
+export type Liveness = "any" | "not_deleted" | "registered_only";
+export interface InterAccountQuery {
+    sourceDim: number;
+    targetDim: number;
+    amount: number;
+    date: string;
+    /** Optional +/- day window around `date` (default 0 — exact date only). */
+    maxGapDays?: number;
+    /** Reference number for disambiguating same-amount/date/dims transfers. */
+    reference?: string | null;
+}
+export interface CreateOnceOptions {
+    /** Liveness used for the pre-create dedup check (default `not_deleted`). */
+    liveness?: Liveness;
+    /** Attempt to confirm/register the created journal (default true). */
+    confirm?: boolean;
+}
+export type CreateOnceResult = {
+    status: "created";
+    journal_id: number;
+    registered: boolean;
+    recovered?: boolean;
+} | {
+    status: "duplicate";
+    journal_id: number;
+};
+export declare class BookingGuard {
+    /** The raw snapshot, exposed read-only for callers that still scan directly. */
+    readonly journals: readonly Journal[];
+    private readonly api;
+    private readonly ownDimensionIds;
+    private readonly docIndex;
+    private readonly interAccountIndex;
+    private constructor();
+    /**
+     * Load one snapshot of all journals (with postings, needed for Lane B) and
+     * build both indexes. `ownDimensionIds` is only required for Lane B
+     * inter-account matching — Lane A works without it.
+     */
+    static load(api: ApiContext, opts?: {
+        ownDimensionIds?: Set<number>;
+    }): Promise<BookingGuard>;
+    /** First artifact for `key` passing `liveness` (default `not_deleted`). */
+    find(key: DocKey, liveness?: Liveness): ExistingArtifact | undefined;
+    /** Record a freshly-created journal into the in-run Lane A index. */
+    record(key: DocKey, journalId: number, meta?: {
+        registered?: boolean;
+        is_deleted?: boolean;
+    }): void;
+    /**
+     * Guarded journal write. Returns `duplicate` (with the existing journal id)
+     * when a live artifact already carries this key; otherwise creates the
+     * journal with the document_number stamped, best-effort confirms it (unless
+     * `confirm:false`), records it, and returns `created`.
+     *
+     * The caller's `payload.document_number` is ignored — the guard stamps it
+     * from `key` so the key and the stored document_number can never diverge.
+     */
+    createJournalOnce(key: DocKey, payload: Omit<Partial<Journal>, "document_number">, opts?: CreateOnceOptions): Promise<CreateOnceResult>;
+    /**
+     * Scan a raw journal array for the first live (not-deleted) journal carrying
+     * `key`'s document_number. Used by the verify-then-retry path against a
+     * freshly-fetched snapshot, so it applies the same parse + `not_deleted`
+     * liveness that `find` uses without disturbing the in-memory index.
+     */
+    private static findKeyInJournals;
+    /**
+     * Find an existing inter-account journal for the given transfer, or
+     * `undefined`. Delegates candidate selection to `findMatchingJournal`
+     * (reference disambiguation). When `maxGapDays > 0`, scans the exact date
+     * first, then outward day-by-day within the window.
+     */
+    findInterAccount(q: InterAccountQuery): number | undefined;
+    /** Record a freshly-created inter-account journal into the Lane B index. */
+    recordInterAccount(q: Pick<InterAccountQuery, "sourceDim" | "targetDim" | "amount" | "date" | "reference">, journalId: number | undefined): void;
+    /**
+     * Candidate ISO dates around `date`, ordered nearest-first: the exact date,
+     * then -1/+1, -2/+2, … out to `gap` days. Uses UTC day arithmetic so the
+     * offsets never drift across DST or timezones.
+     */
+    private candidateDates;
+}
+//# sourceMappingURL=booking-guard.d.ts.map

package/dist/booking-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"booking-guard.d.ts","sourceRoot":"","sources":["../src/booking-guard.ts"],"names":[],"mappings":"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"}

package/dist/booking-guard.js

@@ -0,0 +1,279 @@
+import { HttpError } from "./http-client.js";
+import { roundMoney } from "./money.js";
+import { buildInterAccountJournalIndex, findMatchingJournal, toUtcDay, UNKNOWN_JOURNAL_ID, } from "./tools/inter-account-utils.js";
+/** "FX:123" / "LY:OR-EVN9C76R7A" */
+export function formatDocNumber(key) {
+    return `${key.ns}:${key.id}`;
+}
+const KNOWN_NAMESPACES = ["FX", "LY"];
+/**
+ * Parse a raw `document_number` into a DocKey, or `undefined` when it does not
+ * carry a known namespace prefix (manual journals, legacy entries, …).
+ *
+ * Only the first ":" is treated as the separator, so a reference that itself
+ * contains a colon (unusual, but possible for external ids) round-trips.
+ */
+export function parseDocNumber(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    const sep = raw.indexOf(":");
+    if (sep <= 0)
+        return undefined;
+    const ns = raw.slice(0, sep);
+    const id = raw.slice(sep + 1);
+    if (id === "")
+        return undefined;
+    if (!KNOWN_NAMESPACES.includes(ns))
+        return undefined;
+    return { ns: ns, id };
+}
+function passesLiveness(a, liveness) {
+    switch (liveness) {
+        case "any":
+            return true;
+        case "registered_only":
+            return a.registered && !a.is_deleted;
+        case "not_deleted":
+        default:
+            return !a.is_deleted;
+    }
+}
+function interAccountKey(sourceDim, targetDim, amount, date) {
+    return `${sourceDim}|${targetDim}|${roundMoney(amount)}|${date}`;
+}
+export class BookingGuard {
+    /** The raw snapshot, exposed read-only for callers that still scan directly. */
+    journals;
+    api;
+    ownDimensionIds;
+    // Lane A: document_number -> artifacts (arrays, since duplicates can exist).
+    docIndex = new Map();
+    // Lane B: bidirectional "sourceDim|targetDim|amount|date" -> journal entries.
+    interAccountIndex;
+    constructor(api, journals, ownDimensionIds) {
+        this.api = api;
+        this.journals = journals;
+        this.ownDimensionIds = ownDimensionIds;
+        this.interAccountIndex = buildInterAccountJournalIndex(journals, ownDimensionIds);
+        for (const j of journals) {
+            if (j.id == null)
+                continue;
+            const key = parseDocNumber(j.document_number);
+            if (!key)
+                continue;
+            const dn = formatDocNumber(key);
+            const artifact = {
+                journal_id: j.id,
+                document_number: dn,
+                registered: j.registered === true,
+                is_deleted: j.is_deleted === true,
+            };
+            const existing = this.docIndex.get(dn);
+            if (existing)
+                existing.push(artifact);
+            else
+                this.docIndex.set(dn, [artifact]);
+        }
+    }
+    /**
+     * Load one snapshot of all journals (with postings, needed for Lane B) and
+     * build both indexes. `ownDimensionIds` is only required for Lane B
+     * inter-account matching — Lane A works without it.
+     */
+    static async load(api, opts) {
+        const ownDimensionIds = opts?.ownDimensionIds ?? new Set();
+        // Lane B (inter-account) needs postings to find the two bank legs, and it
+        // is only meaningful when the caller supplies its own bank dimension ids.
+        // Lane A only reads document_number/id/registered/is_deleted, all of which
+        // the cheaper list endpoint carries — so a Lane-A-only caller avoids the
+        // per-journal posting fetches that listAllWithPostings performs.
+        const needsPostings = ownDimensionIds.size > 0;
+        const journals = needsPostings
+            ? await api.journals.listAllWithPostings()
+            : await api.journals.listAll();
+        return new BookingGuard(api, journals, ownDimensionIds);
+    }
+    // ---- Lane A: namespaced document_number keys ---------------------------
+    /** First artifact for `key` passing `liveness` (default `not_deleted`). */
+    find(key, liveness = "not_deleted") {
+        const artifacts = this.docIndex.get(formatDocNumber(key));
+        if (!artifacts)
+            return undefined;
+        return artifacts.find(a => passesLiveness(a, liveness));
+    }
+    /** Record a freshly-created journal into the in-run Lane A index. */
+    record(key, journalId, meta) {
+        const dn = formatDocNumber(key);
+        const artifact = {
+            journal_id: journalId,
+            document_number: dn,
+            registered: meta?.registered ?? true,
+            is_deleted: meta?.is_deleted ?? false,
+        };
+        const existing = this.docIndex.get(dn);
+        if (existing)
+            existing.push(artifact);
+        else
+            this.docIndex.set(dn, [artifact]);
+    }
+    /**
+     * Guarded journal write. Returns `duplicate` (with the existing journal id)
+     * when a live artifact already carries this key; otherwise creates the
+     * journal with the document_number stamped, best-effort confirms it (unless
+     * `confirm:false`), records it, and returns `created`.
+     *
+     * The caller's `payload.document_number` is ignored — the guard stamps it
+     * from `key` so the key and the stored document_number can never diverge.
+     */
+    async createJournalOnce(key, payload, opts) {
+        const liveness = opts?.liveness ?? "not_deleted";
+        const existing = this.find(key, liveness);
+        if (existing)
+            return { status: "duplicate", journal_id: existing.journal_id };
+        const stamped = { ...payload, document_number: formatDocNumber(key) };
+        const wantConfirm = opts?.confirm !== false;
+        let created;
+        try {
+            created = await this.api.journals.create(stamped);
+        }
+        catch (err) {
+            // Only a network error is ambiguous — the POST may or may not have
+            // committed. An HTTP status (4xx/5xx with a body) means the server saw
+            // and rejected the request, so nothing was created: propagate as-is.
+            if (!(err instanceof HttpError) || err.status !== "network")
+                throw err;
+            // The document_number is a checkable key, so re-scan the server to see
+            // whether the ambiguous write actually landed. create() only invalidates
+            // its cache on success, so bust the stale journals cache first — the
+            // snapshot could otherwise predate the write we are verifying.
+            this.api.journals.invalidateListCache();
+            const found = BookingGuard.findKeyInJournals(await this.api.journals.listAll(), key);
+            if (found) {
+                // The ambiguous write DID commit — recover its id, do NOT retry. create()
+                // does not auto-confirm, so the recovered journal is typically left in
+                // PROJECT; confirm it now (when wanted) exactly as a fresh create would.
+                let registered = found.registered;
+                if (!registered && wantConfirm) {
+                    try {
+                        await this.api.journals.confirm(found.journal_id);
+                        registered = true;
+                    }
+                    catch {
+                        // Leave the recovered journal in PROJECT for the operator to inspect.
+                    }
+                }
+                this.record(key, found.journal_id, { registered, is_deleted: false });
+                return { status: "created", journal_id: found.journal_id, registered, recovered: true };
+            }
+            // The write did not commit — safe to retry exactly once. A second
+            // network failure propagates; the key is not double-booked because the
+            // next run's find pass (or another recovery) catches it by its
+            // document_number.
+            created = await this.api.journals.create(stamped);
+        }
+        const journalId = created.created_object_id;
+        let registered = false;
+        if (journalId != null && wantConfirm) {
+            try {
+                await this.api.journals.confirm(journalId);
+                registered = true;
+            }
+            catch {
+                // Leave the journal in PROJECT for the operator to inspect if confirm
+                // fails — mirrors the established currency-rounding / Lightyear path.
+            }
+        }
+        if (journalId != null) {
+            this.record(key, journalId, { registered, is_deleted: false });
+            return { status: "created", journal_id: journalId, registered };
+        }
+        // The API accepted the create but returned no object id. We cannot dedup a
+        // future run against an unknown id, but we still record the key so a second
+        // call within THIS run is deduped.
+        this.record(key, UNKNOWN_JOURNAL_ID, { registered, is_deleted: false });
+        return { status: "created", journal_id: UNKNOWN_JOURNAL_ID, registered };
+    }
+    /**
+     * Scan a raw journal array for the first live (not-deleted) journal carrying
+     * `key`'s document_number. Used by the verify-then-retry path against a
+     * freshly-fetched snapshot, so it applies the same parse + `not_deleted`
+     * liveness that `find` uses without disturbing the in-memory index.
+     */
+    static findKeyInJournals(journals, key) {
+        const target = formatDocNumber(key);
+        for (const j of journals) {
+            if (j.id == null)
+                continue;
+            const k = parseDocNumber(j.document_number);
+            if (!k || formatDocNumber(k) !== target)
+                continue;
+            if (j.is_deleted === true)
+                continue;
+            return {
+                journal_id: j.id,
+                document_number: target,
+                registered: j.registered === true,
+                is_deleted: false,
+            };
+        }
+        return undefined;
+    }
+    // ---- Lane B: structural inter-account transfers ------------------------
+    /**
+     * Find an existing inter-account journal for the given transfer, or
+     * `undefined`. Delegates candidate selection to `findMatchingJournal`
+     * (reference disambiguation). When `maxGapDays > 0`, scans the exact date
+     * first, then outward day-by-day within the window.
+     */
+    findInterAccount(q) {
+        const gap = Math.max(0, Math.floor(q.maxGapDays ?? 0));
+        for (const date of this.candidateDates(q.date, gap)) {
+            const key = interAccountKey(q.sourceDim, q.targetDim, q.amount, date);
+            const match = findMatchingJournal(this.interAccountIndex.get(key), q.reference);
+            if (match !== undefined)
+                return match;
+        }
+        return undefined;
+    }
+    /** Record a freshly-created inter-account journal into the Lane B index. */
+    recordInterAccount(q, journalId) {
+        const entry = {
+            journal_id: journalId ?? UNKNOWN_JOURNAL_ID,
+            document_number: q.reference ?? null,
+        };
+        const amount = roundMoney(q.amount);
+        const key1 = `${q.sourceDim}|${q.targetDim}|${amount}|${q.date}`;
+        const key2 = `${q.targetDim}|${q.sourceDim}|${amount}|${q.date}`;
+        for (const key of [key1, key2]) {
+            const existing = this.interAccountIndex.get(key);
+            if (existing)
+                existing.push(entry);
+            else
+                this.interAccountIndex.set(key, [entry]);
+        }
+    }
+    /**
+     * Candidate ISO dates around `date`, ordered nearest-first: the exact date,
+     * then -1/+1, -2/+2, … out to `gap` days. Uses UTC day arithmetic so the
+     * offsets never drift across DST or timezones.
+     */
+    candidateDates(date, gap) {
+        if (gap === 0)
+            return [date];
+        const baseMs = toUtcDay(date); // UTC-midnight epoch millis
+        if (!Number.isFinite(baseMs))
+            return [date];
+        const DAY_MS = 86400000;
+        const dates = [date];
+        for (let d = 1; d <= gap; d++) {
+            dates.push(msToIso(baseMs - d * DAY_MS));
+            dates.push(msToIso(baseMs + d * DAY_MS));
+        }
+        return dates;
+    }
+}
+/** Epoch millis at UTC midnight -> "YYYY-MM-DD". */
+function msToIso(ms) {
+    return new Date(ms).toISOString().slice(0, 10);
+}
+//# sourceMappingURL=booking-guard.js.map

package/dist/booking-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"booking-guard.js","sourceRoot":"","sources":["../src/booking-guard.ts"],"names":[],"mappings":"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"}

package/dist/http-client.d.ts

@@ -62,6 +62,15 @@ export declare class HttpClient {
     private static recoveryActionsForConflict;
     private static buildRecoveryAdvice;
     private static isRetryableError;
+    /**
+     * Only idempotent methods may be retried after a network error / timeout.
+     * A timed-out or connection-dropped POST/PATCH/DELETE is ambiguous: the
+     * server may have already committed the mutation, so a blind retry risks a
+     * duplicate booking (invoice, journal, transaction). GET and PUT (full
+     * replace) are safe to repeat. Mirrors the GET-only gate in
+     * shouldRetryStatus for 5xx responses.
+     */
+    private static isIdempotentMethod;
     private static formatNetworkError;
     request<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
     get<T = unknown>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T>;

package/dist/http-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-client.d.ts","sourceRoot":"","sources":["../src/http-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"http-client.d.ts","sourceRoot":"","sources":["../src/http-client.ts"],"names":[],"mappings":"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"}