actual-mcp-server 0.13.0 → 0.14.0

package/README.md

@@ -774,7 +774,7 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.13.0 | **Tool Count:** 74 (verified LibreChat-compatible)
+**Version:** 0.14.0 | **Tool Count:** 74 (verified LibreChat-compatible)
 
 ## Sponsor
 

package/dist/src/lib/actual-adapter.js

@@ -11,7 +11,8 @@ import { EventEmitter } from 'events';
 import observability from '../observability.js';
 import { retry, isRetryableError } from './retry.js';
 import { withOpTimeout } from './opTimeout.js';
-import { notFoundMsg } from './errors.js';
+import { NotFoundRefusal, OutOfRangeRefusal, constraintErrorMsg } from './errors.js';
+import { findMatchingRule } from './rule-matching.js';
 import logger from '../logger.js';
 import { checkServerVersionOnce } from './server-version-guard.js';
 import config from '../config.js';
@@ -833,8 +834,7 @@ export async function addTransactions(txs, options = {}) {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const accountExists = accounts.some((a) => a?.id === accountId);
         if (!accountExists) {
-            throw new Error(`Account "${accountId}" not found. Use actual_accounts_list to find valid accounts. ` +
-                'No transactions were created: Actual would otherwise have written them against an ' +
+            throw new NotFoundRefusal('Account', accountId, 'actual_accounts_list', 'No transactions were created: Actual would otherwise have written them against an ' +
                 'account that does not exist, where no tool could retrieve them.');
         }
         // Remove account/accountId from transaction objects as they're passed separately
@@ -997,7 +997,13 @@ export async function setBudgetAmount(month, categoryId, amount) {
         const categories = await withConcurrency(() => retry(() => rawGetCategories(), { retries: 2, backoffMs: 200 }));
         const exists = categories.some((c) => c.id === categoryId);
         if (!exists) {
-            throw new Error(`Category "${categoryId}" not found. Use actual_categories_get to list available categories.`);
+            // #377: MUST be a typed refusal. `budgets_setAmount` is one of the two tools whose
+            // published contract is the SHAPE (#89: an unknown category returns
+            // { success: false, error }, it does not throw), and the tool decides that by type
+            // now. Leaving this as a bare Error silently undid #89, and the unit test did not
+            // catch it because it stubbed the adapter and threw the refusal itself, reproducing
+            // the fixture on both sides. There is a real-adapter case for it now.
+            throw new NotFoundRefusal('Category', String(categoryId), 'actual_categories_get');
         }
         // #361: the MONTH is unvalidated, in format AND range. `api/budget-set-amount` is the
         // one budget handler that does not call upstream's `validateMonth`, unlike
@@ -1011,8 +1017,8 @@ export async function setBudgetAmount(month, categoryId, amount) {
         // exactly, and a malformed string cannot be a member either.
         const months = await withConcurrency(() => retry(() => rawGetBudgetMonths(), { retries: 2, backoffMs: 200 }));
         if (Array.isArray(months) && months.length > 0 && !months.includes(String(month))) {
-            throw new Error(`Month "${month}" is not in this budget. It runs from ${months[0]} to ${months[months.length - 1]}. ` +
-                'Use actual_budgets_getMonths to see the months you can budget to.');
+            throw new OutOfRangeRefusal(`Month "${month}" is outside this budget's range, which runs from ${months[0]} to ` +
+                `${months[months.length - 1]}. Use actual_budgets_getMonths to see the months you can budget to.`, String(month));
         }
         const result = await withConcurrency(() => retry(() => rawSetBudgetAmount(month, categoryId, amount), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
         return result;
@@ -1074,7 +1080,7 @@ export async function updateAccount(id, fields) {
         // `closed = 0`, so this refuses only ids that genuinely do not exist.
         const accounts = await withConcurrency(() => retry(() => rawGetAccounts(), { retries: 2, backoffMs: 200 }));
         if (!(Array.isArray(accounts) && accounts.some((a) => a?.id === id))) {
-            throw new Error(notFoundMsg('Account', id, 'actual_accounts_list'));
+            throw new NotFoundRefusal('Account', id, 'actual_accounts_list');
         }
         await withConcurrency(() => retry(() => rawUpdateAccount(id, fields), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
         return null;
@@ -1244,7 +1250,7 @@ export async function updateCategory(id, fields) {
         // included, so a hidden category is not misreported as missing.
         const categories = await withConcurrency(() => retry(() => rawGetCategories(), { retries: 2, backoffMs: 200 }));
         if (!(Array.isArray(categories) && categories.some((c) => c?.id === id))) {
-            throw new Error(notFoundMsg('Category', id, 'actual_categories_get'));
+            throw new NotFoundRefusal('Category', id, 'actual_categories_get');
         }
         await withConcurrency(() => retry(() => rawUpdateCategory(id, fields), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
     });
@@ -1256,7 +1262,7 @@ export async function deleteCategory(id) {
         const categories = await withConcurrency(() => retry(() => rawGetCategories(), { retries: 2, backoffMs: 200 }));
         const exists = categories.some((c) => c.id === id);
         if (!exists) {
-            throw new Error(`Category "${id}" not found. Use actual_categories_get to list available categories.`);
+            throw new NotFoundRefusal('Category', id, 'actual_categories_get');
         }
         await withConcurrency(() => retry(() => rawDeleteCategory(id), { retries: 0, backoffMs: 200 }));
     });
@@ -1276,7 +1282,7 @@ export async function updatePayee(id, fields) {
         // is leaving four tools able to create phantom rows.
         const payees = await withConcurrency(() => retry(() => rawGetPayees(), { retries: 2, backoffMs: 200 }));
         if (!(Array.isArray(payees) && payees.some((p) => p?.id === id))) {
-            throw new Error(notFoundMsg('Payee', id, 'actual_payees_get'));
+            throw new NotFoundRefusal('Payee', id, 'actual_payees_get');
         }
         const fieldsObj = fields;
         // Extract `category` — it is NOT a direct column on the payees table in Actual Budget.
@@ -1339,7 +1345,7 @@ export async function deletePayee(id) {
         const found = payees.find((p) => p.id === id);
         const exists = Boolean(found);
         if (!exists) {
-            throw new Error(`Payee "${id}" not found. Use actual_payees_get to list available payees.`);
+            throw new NotFoundRefusal('Payee', id, 'actual_payees_get');
         }
         // #356: the existence check above is not enough. Actual refuses to delete a
         // TRANSFER payee (the payee it auto-creates for each account) and refuses
@@ -1423,10 +1429,96 @@ export async function updateRule(id, fields) {
  * the correct contract instead of rediscovering this the hard way. Neither widening is
  * exercised by a test today, for the same reason: nothing calls them.
  */
+/**
+ * Idempotent rule upsert (#376): update the rule whose conditions match, or create one.
+ *
+ * Moved here from `src/tools/rules_create_or_update.ts`, which ran the read and the write
+ * inside its own `withWriteSession` using raw api calls. Same single-cycle property, but the
+ * read now goes through `retry` and there is one observability call site.
+ *
+ * The caller has already validated the payload; this owns identity and merge only.
+ */
+export async function upsertRule(input, stageWasSupplied) {
+    observability.incrementToolCall('actual.rules.create_or_update').catch(() => { });
+    return queueWriteOperation(async () => {
+        const existingRules = await withConcurrency(() => retry(() => rawGetRules(), { retries: 2, backoffMs: 200 }));
+        const matchedRule = findMatchingRule(existingRules, input.conditions, input.conditionsOp);
+        const ruleData = JSON.parse(JSON.stringify(input)); // deep clone for the API call
+        if (matchedRule) {
+            // The Actual Budget API expects the FULL merged rule object as one argument.
+            //
+            // #342: `??` is WRONG for stage. null is a MEANINGFUL value here (Actual's default
+            // stage), not an absent one, so `ruleData.stage ?? existing` would silently discard
+            // an explicit `stage: null` and keep the old stage, making it impossible to move a
+            // rule back to the default. Decide on PRESENCE instead. That presence test used to
+            // be `'stage' in ruleData`, which worked only because the tool passed its parsed
+            // input straight through; it is now an explicit parameter so the meaning survives
+            // the extra call boundary.
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const merged = {
+                id: matchedRule.id,
+                stage: stageWasSupplied ? ruleData.stage : matchedRule.stage,
+                conditionsOp: ruleData.conditionsOp ?? matchedRule.conditionsOp,
+                conditions: ruleData.conditions ?? matchedRule.conditions ?? [],
+                actions: ruleData.actions ?? matchedRule.actions ?? [],
+            };
+            // Non-idempotent from upstream's point of view: do not retry the write.
+            await withConcurrency(() => retry(() => rawUpdateRule(merged), { retries: 0, backoffMs: 200 }));
+            return { id: matchedRule.id, created: false };
+        }
+        // #342: stage has no Zod default on this tool, so an omitted stage arrives as
+        // undefined. Actual's validator ALWAYS runs on a create and rejects undefined with
+        // `Invalid rule stage: undefined`, so the key must be present. null is the correct
+        // value: Actual's default stage.
+        if (ruleData.stage === undefined)
+            ruleData.stage = null;
+        const rawId = await withConcurrency(() => retry(() => rawCreateRule(ruleData), { retries: 0, backoffMs: 200 }));
+        return { id: normalizeToId(rawId), created: true };
+    });
+}
+/**
+ * #376: the existence guard and the schedule-owned refusal moved here from
+ * `src/tools/rules_delete.ts`, which held them inside its own `withWriteSession`.
+ *
+ * WHY THE ADAPTER. Doing it in the tool meant reaching past `adapter.*` for the read, so
+ * the read had no `retry` at all, and it left THIS method reachable and unguarded: calling
+ * it directly silently failed to delete a schedule-owned rule, which is the #355 defect the
+ * tool had already fixed. See "Where a read-then-write guard belongs" in CLAUDE.md.
+ *
+ * Both halves stay inside ONE `queueWriteOperation`, so the read, the decision and the
+ * write share a single api lock cycle (#142). That excludes other SESSIONS; it does not
+ * serialise against other operations in the same drain (see `reopenAccount` for the long
+ * form of that caveat).
+ */
 export async function deleteRule(id) {
     observability.incrementToolCall('actual.rules.delete').catch(() => { });
     return queueWriteOperation(async () => {
-        return await withConcurrency(() => retry(() => rawDeleteRule(id), { retries: 0, backoffMs: 200 }));
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const allRules = await withConcurrency(() => retry(() => rawGetRules(), { retries: 2, backoffMs: 200 }));
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        if (!Array.isArray(allRules) || !allRules.some((r) => r?.id === id)) {
+            throw new NotFoundRefusal('Rule', id, 'actual_rules_get');
+        }
+        // #355: the raw call RETURNS a verdict and it used to be discarded. Upstream
+        // `deleteRule` returns `false`, without throwing, when a schedule owns this rule:
+        // Actual keeps a schedule and its generated rule in step and refuses to remove the
+        // rule on its own. The existence check above cannot catch that case, because the rule
+        // genuinely exists. Reporting success there was a lie (CWE-252).
+        //
+        // Only an EXPLICIT `false` is a refusal. A build that returns `undefined` (the
+        // published reference documents this method as `Promise<null>`) is treated as success,
+        // so this stays correct against older and future versions.
+        //
+        // Not a PreflightRefusal: the write WAS attempted and upstream declined it. A
+        // PreflightRefusal means nothing was tried. See the taxonomy in
+        // .claude/skills/api-design-principles/SKILL.md.
+        const deleted = await withConcurrency(() => retry(() => rawDeleteRule(id), { retries: 0, backoffMs: 200 }));
+        if (deleted === false) {
+            throw new Error(`Rule "${id}" belongs to a schedule and cannot be deleted on its own. ` +
+                'Actual keeps a schedule and its generated rule in step. Delete the schedule ' +
+                'instead with actual_schedules_delete (find it with actual_schedules_get), ' +
+                'which removes this rule too.');
+        }
     });
 }
 export async function getSchedules() {
@@ -1452,10 +1544,28 @@ export async function updateSchedule(id, fields, resetNextDate) {
         await withConcurrency(() => retry(() => rawUpdateSchedule(id, fields, resetNextDate), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
     });
 }
+/**
+ * #376: the existence guard and the constraint-error translation moved here from
+ * `src/tools/schedules_delete.ts`. The translation stays wrapped tightly around the delete
+ * call so the message cannot regress into the raw SQLite text.
+ */
 export async function deleteSchedule(id) {
     observability.incrementToolCall('actual.schedules.delete').catch(() => { });
     return queueWriteOperation(async () => {
-        await withConcurrency(() => retry(() => rawDeleteSchedule(id), { retries: 0, backoffMs: 200 }));
+        const schedules = await withConcurrency(() => retry(() => rawGetSchedules(), { retries: 2, backoffMs: 200 }));
+        if (!Array.isArray(schedules) || !schedules.some((sch) => sch?.id === id)) {
+            throw new NotFoundRefusal('Schedule', id, 'actual_schedules_get');
+        }
+        try {
+            await withConcurrency(() => retry(() => rawDeleteSchedule(id), { retries: 0, backoffMs: 200 }));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg.includes('NOT NULL constraint') || msg.includes('messages_crdt')) {
+                throw new Error(constraintErrorMsg('Schedule', id, 'actual_schedules_get'));
+            }
+            throw err;
+        }
     });
 }
 export async function setBudgetCarryover(month, categoryId, flag) {
@@ -1555,34 +1665,6 @@ export async function closeAccount(id, transferAccountId, transferCategoryId) {
         return { outcome: 'closed', name: survivor.name };
     });
 }
-/**
- * #358, at the adapter layer since #371.
- *
- * Upstream `reopenAccount` is a bare `db.update('accounts', {id, closed: 0})`. `db.update`
- * does not run a SQL UPDATE: it sends CRDT messages, and the apply path INSERTs when the
- * row was absent. The accounts table has no NOT NULL columns and `tombstone` defaults to 0,
- * while `getAccounts()` filters `tombstone = 0`, so reopening an id that is not an account
- * CREATES a visible nameless account that syncs to every client.
- *
- * A pre-check is right here and was wrong in #347: there, the caller's intent ("make this
- * account not exist") could already be satisfied by an absent row, so refusing on absence
- * would have failed a complete request. Here the intent ("reopen this account") cannot be
- * satisfied by an absent row, and proceeding actively creates one.
- *
- * TWO DELIBERATE LIMITS, carried over from the tool-layer version so they are not
- * rediscovered as oversights.
- *
- * One `queueWriteOperation` keeps this read, write and re-read in a single api lock cycle.
- * It does NOT serialise against other operations in the same batch: `processWriteQueue`
- * dispatches with `Promise.allSettled`, so operations queued in the same drain window
- * interleave at await points. The cycle excludes other SESSIONS, not batch siblings.
- *
- * The not-found message covers both reasons an id can be missing (never existed, or removed
- * by a close while it had no transactions) rather than distinguishing them. `q().withDead()`
- * would tell them apart by reading tombstoned rows, at the cost of an extra query on the
- * failure path. Collapsing them was chosen because the message names both cases and the
- * remedy is the same either way.
- */
 export async function reopenAccount(id) {
     observability.incrementToolCall('actual.accounts.reopen').catch(() => { });
     return queueWriteOperation(async () => {
@@ -1594,6 +1676,15 @@ export async function reopenAccount(id) {
                 'Actual removed it rather than closing it, and it cannot be reopened: create a new ' +
                 'one with actual_accounts_create.');
         }
+        // #369 item 5: an already-open account needs no write. Upstream `reopenAccount` is a
+        // db.update, which in Actual means a CRDT MESSAGE that syncs to every other client, so
+        // issuing it for a no-op is not free: it is sync traffic and a device-state bump for a
+        // change nobody made. Reporting the non-change is also the taxonomy's rule 1 (the
+        // requested end state already holds, so this is a SUCCESS naming what did not happen),
+        // and it matches what closeAccount already does with `already-closed`.
+        if (target.closed !== true) {
+            return { outcome: 'already-open', name: target.name };
+        }
         await withConcurrency(() => retry(() => rawReopenAccount(id), { retries: 2, backoffMs: 200 }));
         const after = await withConcurrency(() => retry(() => rawGetAccounts(), { retries: 2, backoffMs: 200 }));
         const survivor = (Array.isArray(after) ? after : []).find((a) => a?.id === id);
@@ -1604,6 +1695,7 @@ export async function reopenAccount(id) {
             throw new Error(`Account "${survivor.name ?? id}" (${id}) is still closed after the reopen. The call ` +
                 'was accepted but had no effect; check the account state in Actual.');
         }
+        return { outcome: 'reopened', name: survivor.name };
     });
 }
 export async function getCategoryGroups() {
@@ -1632,14 +1724,23 @@ export async function updateCategoryGroup(id, fields) {
         // can rely on this listing).
         const groups = await withConcurrency(() => retry(() => rawGetCategoryGroups(), { retries: 2, backoffMs: 200 }));
         if (!(Array.isArray(groups) && groups.some((g) => g?.id === id))) {
-            throw new Error(notFoundMsg('Category group', id, 'actual_category_groups_get'));
+            throw new NotFoundRefusal('Category group', id, 'actual_category_groups_get');
         }
         await withConcurrency(() => retry(() => rawUpdateCategoryGroup(id, fields), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
     });
 }
+/**
+ * #376: the existence guard moved here from `src/tools/category_groups_delete.ts`. Same
+ * reasoning as `deleteRule` above: the tool-layer version forwent `retry` on the read and
+ * left this method reachable with no guard at all.
+ */
 export async function deleteCategoryGroup(id) {
     observability.incrementToolCall('actual.category_groups.delete').catch(() => { });
     return queueWriteOperation(async () => {
+        const groups = await withConcurrency(() => retry(() => rawGetCategoryGroups(), { retries: 2, backoffMs: 200 }));
+        if (!Array.isArray(groups) || !groups.some((g) => g?.id === id)) {
+            throw new NotFoundRefusal('Category group', id, 'actual_category_groups_get');
+        }
         // Non-idempotent: do not retry (#165).
         await withConcurrency(() => retry(() => rawDeleteCategoryGroup(id), { retries: 0, backoffMs: 200 }));
     });
@@ -2330,7 +2431,7 @@ export async function updateTag(id, fields) {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const exists = tags.some((t) => t.id === id);
         if (!exists) {
-            throw new Error(notFoundMsg('Tag', id, 'actual_tags_list'));
+            throw new NotFoundRefusal('Tag', id, 'actual_tags_list');
         }
         await withConcurrency(() => retry(() => rawUpdateTag(id, fields), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
     });
@@ -2343,7 +2444,7 @@ export async function deleteTag(id) {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const exists = tags.some((t) => t.id === id);
         if (!exists) {
-            throw new Error(notFoundMsg('Tag', id, 'actual_tags_list'));
+            throw new NotFoundRefusal('Tag', id, 'actual_tags_list');
         }
         await withConcurrency(() => retry(() => rawDeleteTag(id), { retries: 0, backoffMs: 200 }));
     });
@@ -2354,9 +2455,42 @@ export async function getNote(id) {
         return await withConcurrency(() => retry(() => rawGetNote(id), { retries: 2, backoffMs: 200 }));
     });
 }
+/** A note id of this shape is a budget MONTH note and resolves to no entity row. */
+const BUDGET_MONTH_NOTE_RE = /^budget-\d{4}-\d{2}$/;
+/**
+ * #376: the orphan-id guard moved here from `src/tools/notes_update.ts`.
+ *
+ * WHY THIS ONE MATTERS MOST OF THE FIVE. The tool version issued FOUR `adapter.get*` calls
+ * through `Promise.all`, each opening its own `withActualApi` cycle, and then a fifth cycle
+ * for the write: five api lock acquisitions for one logical operation. `Promise.all` made it
+ * look concurrent, but the api mutex is process-global, so they serialised anyway. Reading
+ * inside one `queueWriteOperation` makes it ONE cycle, and the guard now sees the same
+ * snapshot the write lands on.
+ *
+ * The refusal is a NotFoundRefusal so the tool can recognise it by type (#377). The tool
+ * converts it to its published `{ error }` shape, which is a known deviation from the
+ * refusal taxonomy and is tracked on #377 rather than changed here.
+ */
 export async function updateNote(id, note) {
     observability.incrementToolCall('actual.notes.update').catch(() => { });
     return queueWriteOperation(async () => {
+        // A budget-YYYY-MM id is synthetic: it names a month, not a row, so there is nothing
+        // to look up and the four reads below would all miss.
+        if (!BUDGET_MONTH_NOTE_RE.test(id)) {
+            const has = (rows) => Array.isArray(rows) && rows.some((e) => e?.id === id);
+            const [accounts, categories, categoryGroups, payees] = await Promise.all([
+                withConcurrency(() => retry(() => rawGetAccounts(), { retries: 2, backoffMs: 200 })),
+                withConcurrency(() => retry(() => rawGetCategories(), { retries: 2, backoffMs: 200 })),
+                withConcurrency(() => retry(() => rawGetCategoryGroups(), { retries: 2, backoffMs: 200 })),
+                withConcurrency(() => retry(() => rawGetPayees(), { retries: 2, backoffMs: 200 })),
+            ]);
+            if (!has(accounts) && !has(categories) && !has(categoryGroups) && !has(payees)) {
+                // Guarding matters here for the same reason as #360: upstream's note write is a
+                // CRDT message, and the apply path INSERTs when the row is absent, so an unknown
+                // id creates an orphan note that no tool can ever read back.
+                throw new NotFoundRefusal('Entity', id, 'actual_accounts_list, actual_categories_get, actual_category_groups_get or actual_payees_get', 'A budget month note uses an id like "budget-2026-01".');
+            }
+        }
         await withConcurrency(() => retry(() => rawUpdateNote(id, note), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
     });
 }
@@ -2482,6 +2616,7 @@ export default {
     createRule,
     updateRule,
     deleteRule,
+    upsertRule,
     setBudgetCarryover,
     closeAccount,
     reopenAccount,

package/dist/src/lib/errors.js

@@ -1,11 +1,113 @@
 /**
- * Build a "not found" error message with a next-step hint.
+ * Refusal messages and the typed refusals that carry them.
+ *
+ * #377: the WORDING helpers below came first, and two tools ended up deciding their
+ * published response shape by substring-matching that wording:
+ *
+ *   const isCategoryRefusal = lower.includes('not found') && lower.includes('category');
+ *
+ * which means a copy-edit to a message in `actual-adapter.ts` silently flips a tool from
+ * returning a structured refusal to throwing. The classes here make that decision a type
+ * question instead, so the prose is free to change.
+ *
+ * THE TAXONOMY these encode (the full version, with the reasoning, lives in
+ * `.claude/skills/api-design-principles/SKILL.md`):
+ *
+ *   - The requested end state ALREADY HOLDS (already-closed, delete-what-is-absent):
+ *     SUCCESS, with a field naming the non-change. That is #347's idempotence argument,
+ *     and it is not a refusal, so nothing here represents it.
+ *   - The request NAMES SOMETHING THAT DOES NOT EXIST, or asks for something upstream
+ *     will not do: a PreflightRefusal. It is a caller error and the caller can fix it.
+ *   - Anything else is a genuine failure and must keep propagating as an ordinary Error.
+ *
+ * A PreflightRefusal is thrown, like any other error. What the type buys is that a tool
+ * needing the structured `{ success: false }` shape can recognise one without reading the
+ * message, and that a tool must NEVER swallow a non-refusal into that shape.
+ */
+/**
+ * Cross-realm brand. `instanceof` is the primary check and is correct in normal operation,
+ * where every caller resolves the same `dist/src/lib/errors.js`. The brand covers the case
+ * where two copies of this module exist at once (a bundler, or a test that loads the source
+ * while the runtime loaded the build). That failure is worth guarding because it is SILENT:
+ * a bare `instanceof` would simply return false, and the tool would rethrow a refusal as a
+ * generic failure, changing its published contract with nothing red to show for it.
+ */
+const REFUSAL_BRAND = Symbol.for('actual-mcp-server.PreflightRefusal');
+/**
+ * A pre-flight refusal: the operation was NOT attempted, because the request named
+ * something that cannot be acted on. Nothing was written.
+ */
+export class PreflightRefusal extends Error {
+    refusalKind;
+    constructor(message, refusalKind) {
+        super(message);
+        this.name = new.target.name;
+        this.refusalKind = refusalKind;
+        Object.defineProperty(this, REFUSAL_BRAND, { value: true, enumerable: false });
+        // Restores the prototype chain when this is compiled down for an older target, so
+        // `instanceof` keeps working on a subclass.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** The entity named by the request does not exist. */
+export class NotFoundRefusal extends PreflightRefusal {
+    entity;
+    id;
+    listTool;
+    /**
+     * @param entity    Human-readable entity name, e.g. "Account", "Category"
+     * @param id        The id that was not found
+     * @param listTool  MCP tool name the caller should use to get valid ids
+     * @param detail    Optional extra sentence, e.g. what was NOT written as a result
+     */
+    constructor(entity, id, listTool, detail) {
+        super(notFoundMsg(entity, id, listTool) + (detail ? ` ${detail}` : ''), 'not-found');
+        this.entity = entity;
+        this.id = id;
+        this.listTool = listTool;
+    }
+}
+/** The request is well-formed but falls outside a range the budget actually has. */
+export class OutOfRangeRefusal extends PreflightRefusal {
+    value;
+    constructor(message, value) {
+        super(message, 'out-of-range');
+        this.value = value;
+    }
+}
+/**
+ * The check a tool uses to decide "structured refusal" versus "rethrow". Prefer this over
+ * a bare `instanceof` so the brand fallback above applies.
+ */
+export function isPreflightRefusal(error) {
+    if (error instanceof PreflightRefusal)
+        return true;
+    return (typeof error === 'object' &&
+        error !== null &&
+        error[REFUSAL_BRAND] === true);
+}
+/**
+ * Build a "not found" message with a next-step hint.
+ *
+ * Prefer THROWING a `NotFoundRefusal` (which builds this string itself) over throwing a
+ * bare Error carrying it: the message is for the human or model reading the response, and
+ * the type is for the code deciding what to do about it.
+ *
  * @param entityType  Human-readable entity name, e.g. "Account", "Category"
  * @param id          The ID that was not found
  * @param listTool    MCP tool name the caller should use to get valid IDs
  */
 export function notFoundMsg(entityType, id, listTool) {
-    return `${entityType} "${id}" not found. Use ${listTool} to list available ${entityType.toLowerCase()}s.`;
+    return `${entityType} "${id}" not found. Use ${listTool} to list available ${pluralize(entityType.toLowerCase())}.`;
+}
+/**
+ * Pluralise an entity name for the message above. This used to be a bare `+ 's'`, which
+ * produced "list available categorys" and, once #376 added an `Entity` refusal,
+ * "list available entitys". The consonant-plus-y rule covers every entity name this
+ * codebase uses (account, category, payee, category group, tag, rule, schedule, entity).
+ */
+function pluralize(word) {
+    return /[^aeiou]y$/.test(word) ? `${word.slice(0, -1)}ies` : `${word}s`;
 }
 /**
  * Build a "constraint error" message for SQLite-level failures.

package/dist/src/lib/rejection-allowlist.js

@@ -29,7 +29,15 @@
 export function isKnownBenignRejection(reason) {
     const reasonStr = String(reason);
     const reasonObj = reason;
-    return (reasonStr.includes('does not exist in table') ||
+    return (
+    // #377: a pre-flight refusal is benign by construction (the operation was not
+    // attempted and nothing was written), so recognise it by BRAND rather than by prose.
+    // The brand is read via `Symbol.for`, not by importing `isPreflightRefusal`, because
+    // this file's INVARIANT is that it has no project imports (enforced by
+    // rejection-allowlist-purity.test.js). The prose lines below remain as the fallback
+    // for errors this server does not raise itself.
+    reason?.[Symbol.for('actual-mcp-server.PreflightRefusal')] === true ||
+        reasonStr.includes('does not exist in table') ||
         (reasonStr.includes('Field') && reasonStr.includes('does not exist')) ||
         reasonStr.includes('Expression stack') ||
         reasonStr.includes('Date is required') ||

package/dist/src/lib/rule-matching.js

@@ -0,0 +1,62 @@
+/**
+ * Rule identity for the idempotent upsert behind `actual_rules_create_or_update`.
+ *
+ * #376 moved this out of `src/tools/rules_create_or_update.ts` so `adapter.upsertRule` can
+ * own the read-match-write cycle. The logic is unchanged; extracting it keeps the matching
+ * rules unit-testable on their own and keeps `actual-adapter.ts` from growing a second
+ * concern.
+ *
+ * Two rules are "the same rule" when they carry the same SET of (field, op, value) triples
+ * and the same `conditionsOp`. Order within the conditions array is deliberately irrelevant:
+ * an AI client that regenerates the same rule with its conditions in a different order must
+ * not create a duplicate, which is the whole point of the tool.
+ */
+/** Canonical JSON for one object: keys sorted, `undefined` values dropped. */
+export function canonicalize(obj) {
+    const sorted = {};
+    for (const key of Object.keys(obj).sort()) {
+        if (obj[key] !== undefined)
+            sorted[key] = obj[key];
+    }
+    return JSON.stringify(sorted);
+}
+/** True when two rules have semantically equivalent conditions (set-based, order-free). */
+export function conditionsMatch(existingConditions, existingConditionsOp, newConditions, newConditionsOp) {
+    if ((existingConditionsOp || 'and') !== newConditionsOp)
+        return false;
+    if (!Array.isArray(existingConditions))
+        return false;
+    if (existingConditions.length !== newConditions.length)
+        return false;
+    const existingSet = new Set(existingConditions.map((c) => {
+        const cond = c;
+        return canonicalize({ field: cond.field, op: cond.op, value: cond.value });
+    }));
+    const newSet = new Set(newConditions.map((c) => canonicalize({ field: c.field, op: c.op, value: c.value })));
+    if (existingSet.size !== newSet.size)
+        return false;
+    for (const item of newSet) {
+        if (!existingSet.has(item))
+            return false;
+    }
+    return true;
+}
+/**
+ * Find the rule an upsert should update, or null to create a new one.
+ * Returns the FIRST match, which is the pre-existing behaviour.
+ */
+export function findMatchingRule(existingRules, newConditions, newConditionsOp) {
+    if (!Array.isArray(existingRules))
+        return null;
+    for (const rule of existingRules) {
+        const r = rule;
+        if (!r?.id || typeof r.id !== 'string')
+            continue;
+        const existingConditions = Array.isArray(r.conditions) ? r.conditions : [];
+        const existingConditionsOp = r.conditionsOp || 'and';
+        if (conditionsMatch(existingConditions, existingConditionsOp, newConditions, newConditionsOp)) {
+            return r;
+        }
+    }
+    return null;
+}

package/dist/src/tools/accounts_close.js

@@ -43,7 +43,10 @@ const tool = {
         'IMPORTANT: an account with NO transactions is REMOVED by Actual rather than closed, and cannot ' +
         'be reopened; an account that has transactions keeps them. If the account has a non-zero balance, ' +
         'transferAccountId is required and the remaining balance is moved there as a dated "Closing account" ' +
-        'transaction. Closing an already-closed account reports that rather than claiming a change.',
+        'transaction. Closing an already-closed account reports that rather than claiming a change. ' +
+        'If this call reports an error, re-read the account with actual_accounts_list before retrying: ' +
+        'the state is verified AFTER the write, so a failure of that verification read is reported ' +
+        'even though the close itself may have succeeded.',
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});

package/dist/src/tools/accounts_reopen.js

@@ -14,19 +14,34 @@ const InputSchema = z.object({
  * #371 moved it there from this file. The read-then-write property never needed the raw
  * api: doing it in the adapter keeps `retry` on the reads, keeps one observability call
  * site, and leaves no unguarded `adapter.reopenAccount` for a future caller to reach for.
+ *
+ * #369 item 5: an already-open account is now reported as a non-change and issues NO write.
+ * Upstream's reopen is a db.update, which in Actual is a CRDT message that syncs to every
+ * client, so a no-op write is real sync traffic.
  */
 const tool = {
     name: 'actual_accounts_reopen',
     description: 'Reopen a previously closed account in Actual Budget. The account becomes active again and ' +
         'visible in all views, and all historical transactions remain intact. An id that is not an ' +
         'account is refused: Actual would otherwise create an empty account under that id. Note that ' +
-        'an account closed while it had NO transactions was removed by Actual rather than closed, and ' +
-        'cannot be reopened.',
+        'an account closed while it had NO transactions was removed by Actual, not closed, and ' +
+        'cannot be reopened. Reopening an account that is already open reports that rather than ' +
+        'claiming a change, and issues no write. ' +
+        'If this call reports an error, re-read the account with actual_accounts_list before ' +
+        'retrying: the state is verified AFTER the write, so a failure of that verification read ' +
+        'is reported even though the reopen itself may have succeeded.',
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
-        await adapter.reopenAccount(input.id);
-        return { success: true };
+        const result = await adapter.reopenAccount(input.id);
+        if (result.outcome === 'already-open') {
+            return {
+                success: true,
+                alreadyOpen: true,
+                message: `Account "${result.name ?? input.id}" was already open. Nothing changed.`,
+            };
+        }
+        return { success: true, reopened: true };
     },
 };
 export default tool;

package/dist/src/tools/budgets_holdForNextMonth.js

@@ -24,7 +24,11 @@ const tool = {
         'Actual can hold LESS than requested: it clamps the hold to the amount still left to budget, ' +
         'and holds nothing at all when that is zero or negative. The response reports the amount ' +
         'actually held and flags a partial hold, rather than reporting plain success.\n\n' +
-        'Note: This operates on the month as a whole, not on a specific category.',
+        'Note: This operates on the month as a whole, not on a specific category.\n\n' +
+        'If this call reports an error, re-read the month with actual_budgets_getMonth before ' +
+        'retrying: the amount held is measured by reading the month AFTER the write, so a failure ' +
+        'of that verification read is reported even though the hold itself may have succeeded. ' +
+        'Retrying blindly would hold the amount twice, because Actual ADDS to the existing buffer.',
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});

package/dist/src/tools/budgets_setAmount.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
+import { isPreflightRefusal } from '../lib/errors.js';
 const InputSchema = z.object({
     // #361: this was a bare z.string().min(1), so 'banana' parsed and reached the API. The
     // regex matches actual_budgets_holdForNextMonth and the other month-taking tools; the
@@ -23,20 +24,19 @@ const tool = {
         }
         catch (error) {
             const msg = error instanceof Error ? error.message : String(error);
-            const lower = msg.toLowerCase();
             // Both PRE-FLIGHT refusals from adapter.setBudgetAmount return the same structured
-            // shape, so a caller can handle "you asked for something that does not exist" once
-            // rather than parsing two forms:
+            // shape, so a caller can handle "you asked for something that cannot be acted on"
+            // once rather than parsing two forms:
             //
-            //   Category "<id>" not found. Use actual_categories_get ...            (#89)
-            //   Month "<month>" is not in this budget. It runs from X to Y ...      (#361)
+            //   NotFoundRefusal    the category id does not exist               (#89)
+            //   OutOfRangeRefusal  the month is outside the budget's range      (#361)
             //
-            // #361 added the second one, and before this it fell through to the rethrow below,
-            // so one tool answered two identical situations in two different shapes. Anything
-            // else (a genuine upstream or transport failure) still throws.
-            const isCategoryRefusal = lower.includes('not found') && lower.includes('category');
-            const isMonthRefusal = lower.includes('not in this budget');
-            if (isCategoryRefusal || isMonthRefusal) {
+            // #377: this used to ask `msg.includes('not found') && msg.includes('category')`,
+            // so rewording either message in the adapter silently flipped this tool from a
+            // structured refusal to a thrown error, with nothing to catch it. The decision is
+            // now made by TYPE, and the message is free to change. Anything that is not a
+            // refusal (a genuine upstream or transport failure) still throws.
+            if (isPreflightRefusal(error)) {
                 return { success: false, error: msg };
             }
             throw new Error(`Failed to set budget amount: ${msg}`);

package/dist/src/tools/category_groups_delete.js

@@ -1,32 +1,21 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
-import { notFoundMsg } from '../lib/errors.js';
-import api from '@actual-app/api';
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const { getCategoryGroups: rawGetCategoryGroups, deleteCategoryGroup: rawDeleteCategoryGroup } = api;
 const InputSchema = z.object({
     id: z.string().describe('Category group ID to delete'),
 });
+/**
+ * #376: the existence guard lives in `adapter.deleteCategoryGroup`, which reads and writes
+ * in one write-queue cycle. It used to sit here inside the tool's own `withWriteSession`,
+ * which cost `retry` on the read and left the adapter method unguarded.
+ */
 const tool = {
     name: 'actual_category_groups_delete',
     description: `Delete a category group from Actual Budget. Note: Categories within the group will be moved to a default group or ungrouped. This operation cannot be undone.`,
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
-        // Read+write inside one withWriteSession cycle (#142).
-        return await adapter.withWriteSession(async () => {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const groups = await rawGetCategoryGroups();
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const groupExists = groups.some((g) => g.id === input.id);
-            if (!groupExists) {
-                // Throw (not return {success:false}) so a non-existent id surfaces as an MCP
-                // error, consistent with every other delete tool's not-found behavior.
-                throw new Error(notFoundMsg('Category group', input.id, 'actual_category_groups_get'));
-            }
-            await rawDeleteCategoryGroup(input.id);
-            return { success: true };
-        });
+        await adapter.deleteCategoryGroup(input.id);
+        return { success: true };
     },
 };
 export default tool;

package/dist/src/tools/notes_update.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { createTool } from '../lib/toolFactory.js';
 import adapter from '../lib/actual-adapter.js';
-const BUDGET_MONTH_RE = /^budget-\d{4}-\d{2}$/;
+import { isPreflightRefusal } from '../lib/errors.js';
 export default createTool({
     name: 'actual_notes_update',
     description: 'Set or clear the note attached to an entity in Actual Budget. ' +
@@ -17,30 +17,25 @@ export default createTool({
         note: z.string().describe('Note text to set. Pass an empty string to clear the note.'),
     }),
     handler: async ({ id, note }) => {
-        // Fast path: budget-YYYY-MM synthetic ids need no entity lookup.
-        if (!BUDGET_MONTH_RE.test(id)) {
-            // Validate that the id resolves to a known entity.
-            // Fetch in parallel to minimise latency.
-            const [accounts, categories, categoryGroups, payees] = await Promise.all([
-                adapter.getAccounts(),
-                adapter.getCategories(),
-                adapter.getCategoryGroups(),
-                adapter.getPayees(),
-            ]);
-            const known = (Array.isArray(accounts) && accounts.some((e) => e.id === id)) ||
-                (Array.isArray(categories) && categories.some((e) => e.id === id)) ||
-                (Array.isArray(categoryGroups) && categoryGroups.some((e) => e.id === id)) ||
-                (Array.isArray(payees) && payees.some((e) => e.id === id));
-            if (!known) {
-                return {
-                    error: `Entity "${id}" not found. ` +
-                        'The id must be a UUID from actual_accounts_list, actual_categories_get, ' +
-                        'actual_category_groups_get, or actual_payees_get, ' +
-                        'or a budget month id like "budget-2026-01".',
-                };
+        // #376: the orphan-id guard lives in `adapter.updateNote`, which reads and writes in
+        // ONE write-queue cycle. It used to sit here as four `adapter.get*` calls plus the
+        // write, which was five api lock acquisitions for one operation; `Promise.all` made
+        // that look concurrent, but the api mutex is process-global so they serialised anyway.
+        //
+        // This tool answers a refusal with `{ error }` rather than throwing. That shape is a
+        // documented deviation from the refusal taxonomy (see the api-design-principles skill)
+        // and it is this tool's PUBLISHED contract, so it is preserved here rather than
+        // quietly changed; #377 tracks the decision. What did change is that the shape is
+        // chosen by TYPE now, not by matching the message.
+        try {
+            await adapter.updateNote(id, note);
+        }
+        catch (error) {
+            if (isPreflightRefusal(error)) {
+                return { error: error.message };
             }
+            throw error;
         }
-        await adapter.updateNote(id, note);
         return {
             success: true,
             id,

package/dist/src/tools/payees_delete.js

@@ -1,8 +1,13 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
+import { CommonSchemas } from '../lib/schemas/common.js';
 const InputSchema = z.object({
-    // #356: bounded, because the id is echoed into the error message and the logs.
-    id: z.string().min(1).max(64).describe('Payee ID to delete'),
+    // #365: the shared payee-id schema, which is the UUID pattern. #356 bounded this at
+    // .max(64) (the id is echoed into the error message and the logs) but deliberately
+    // stopped short of the regex, because adopting it meant rewriting non-UUID fixtures in
+    // two test files and that was not the transfer-payee bug #356 existed to fix. The
+    // regex is strictly tighter than the bound it replaces, so the echo is still bounded.
+    id: CommonSchemas.payeeId.describe('Payee ID to delete'),
 });
 const tool = {
     name: 'actual_payees_delete',

package/dist/src/tools/payees_merge.js

@@ -1,13 +1,16 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
-// #356: bounded on both axes. The ids are echoed back in error messages and into the
-// structured logs, so an unbounded string or array is an unbounded echo. Actual's ids
-// are UUIDs, so 64 characters is already generous, and no legitimate merge consolidates
-// more than a few hundred payees in one call.
-const PayeeIdSchema = z.string().min(1).max(64);
+import { CommonSchemas } from '../lib/schemas/common.js';
+// #365: the shared payee-id schema (the UUID pattern) on both axes, replacing the
+// #356 length bound. #356 bounded rather than typed these because the regex would have
+// rejected the non-UUID fixtures the existing tests fed these exact tools, and that
+// sweep was not the transfer-payee bug it existed to fix. The array bound is unchanged
+// and is a separate concern: the ids are echoed back in error messages and into the
+// structured logs, and no legitimate merge consolidates more than a few dozen payees in
+// one call.
 const InputSchema = z.object({
-    targetId: PayeeIdSchema.describe('ID of the target payee to merge into (this payee will be retained)'),
-    mergeIds: z.array(PayeeIdSchema).min(1).max(50)
+    targetId: CommonSchemas.payeeId.describe('ID of the target payee to merge into (this payee will be retained)'),
+    mergeIds: z.array(CommonSchemas.payeeId).min(1).max(50)
         .describe('Array of payee IDs to merge into the target payee (these will be consolidated)'),
 });
 const tool = {
@@ -18,7 +21,8 @@ const tool = {
         'each account) cannot be merged in either direction: such a merge is refused rather than ' +
         'silently ignored. The response lists the de-duplicated ids that were ACCEPTED for merge ' +
         'after those checks; it is not a post-write read, so verify with actual_payees_get if you ' +
-        'need proof the payees are gone.',
+        'need proof the payees are gone. mergeIds must contain between 1 and 50 ids: an empty array ' +
+        'is an error rather than a no-op, and a larger consolidation must be split across calls.',
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});

package/dist/src/tools/rules_create_or_update.js

@@ -14,14 +14,16 @@
  * Credit: ZanzyTHEbar (https://github.com/ZanzyTHEbar)
  *
  * Adapted for this project's conventions:
- * - No wrapToolCall — uses direct call() pattern
- * - Reuses exact same ConditionSchema / ActionSchema / FIELD_OPERATORS as rules_create.ts
+ * - No wrapToolCall: uses the direct call() pattern
+ * - Reuses the exact same ConditionSchema / ActionSchema / FIELD_OPERATORS as rules_create.ts
+ *
+ * #376: the read-match-write cycle lives in `adapter.upsertRule` (identity rules in
+ * `src/lib/rule-matching.ts`). This tool owns the schema, the operator/UUID validation and
+ * the response. It used to run the cycle itself inside `withWriteSession` with raw api
+ * calls, which meant no `retry` on the read and a second observability blind spot.
  */
 import { z } from 'zod';
-import adapter, { normalizeToId } from '../lib/actual-adapter.js';
-import api from '@actual-app/api';
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const { getRules: rawGetRules, createRule: rawCreateRule, updateRule: rawUpdateRule } = api;
+import adapter from '../lib/actual-adapter.js';
 // Mirrors the same schemas used in rules_create.ts
 const ConditionSchema = z.object({
     field: z.string().describe('Field to match (e.g., "payee", "notes", "amount", "category", "imported_payee")'),
@@ -70,42 +72,6 @@ const InputSchema = z.object({
     conditions: z.array(ConditionSchema).describe('Array of conditions that must be met'),
     actions: z.array(ActionSchema).describe('Array of actions to perform when conditions match'),
 });
-/**
- * Normalize a single object for stable JSON comparison by sorting its keys
- * and stripping undefined values.
- */
-function canonicalize(obj) {
-    const sorted = {};
-    for (const key of Object.keys(obj).sort()) {
-        if (obj[key] !== undefined)
-            sorted[key] = obj[key];
-    }
-    return JSON.stringify(sorted);
-}
-/**
- * Return true when two rules have semantically equivalent conditions.
- * Matching is set-based on (field, op, value) triples — order is irrelevant.
- */
-function conditionsMatch(existingConditions, existingConditionsOp, newConditions, newConditionsOp) {
-    if ((existingConditionsOp || 'and') !== newConditionsOp)
-        return false;
-    if (!Array.isArray(existingConditions))
-        return false;
-    if (existingConditions.length !== newConditions.length)
-        return false;
-    const existingSet = new Set(existingConditions.map((c) => {
-        const cond = c;
-        return canonicalize({ field: cond.field, op: cond.op, value: cond.value });
-    }));
-    const newSet = new Set(newConditions.map((c) => canonicalize({ field: c.field, op: c.op, value: c.value })));
-    if (existingSet.size !== newSet.size)
-        return false;
-    for (const item of newSet) {
-        if (!existingSet.has(item))
-            return false;
-    }
-    return true;
-}
 const tool = {
     name: 'actual_rules_create_or_update',
     description: `Create a rule if no matching rule exists, or update the existing rule if one with the same conditions already exists. Prevents duplicate rules.
@@ -163,57 +129,25 @@ Returns: { id, created: boolean } — created=true if new rule was created, fals
                 throw new Error(`Action "${action.op}" requires a string value.`);
             }
         }
-        // Fetch existing rules and either update (matched) or create (no match) inside
-        // ONE withWriteSession cycle so the read and the write share a single lock
-        // acquisition (#142).
-        return await adapter.withWriteSession(async () => {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const existingRules = await rawGetRules();
-            let matchedRule = null;
-            for (const rule of existingRules) {
-                const r = rule;
-                if (!r.id || typeof r.id !== 'string')
-                    continue;
-                const existingConditions = Array.isArray(r.conditions) ? r.conditions : [];
-                const existingConditionsOp = r.conditionsOp || 'and';
-                if (conditionsMatch(existingConditions, existingConditionsOp, input.conditions, input.conditionsOp)) {
-                    matchedRule = r;
-                    break;
-                }
-            }
-            const ruleData = JSON.parse(JSON.stringify(input)); // deep clone for API call
-            if (matchedRule) {
-                // UPDATE existing rule. The Actual Budget API expects the FULL merged rule
-                // object passed as a single argument (matches adapter.updateRule's behaviour).
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                const merged = {
-                    id: matchedRule.id,
-                    // #342: `??` is WRONG for stage. null is a MEANINGFUL value here (Actual's
-                    // default stage), not an absent one, so `ruleData.stage ?? existing` would
-                    // silently discard an explicit `stage: null` and keep the old stage,
-                    // making it impossible to move a rule back to the default stage. Decide on
-                    // PRESENCE of the key instead. Every other field below is fine with `??`
-                    // because none of them treats null as a distinct legal value.
-                    stage: 'stage' in ruleData ? ruleData.stage : matchedRule.stage,
-                    conditionsOp: ruleData.conditionsOp ?? matchedRule.conditionsOp,
-                    conditions: ruleData.conditions ?? matchedRule.conditions ?? [],
-                    actions: ruleData.actions ?? matchedRule.actions ?? [],
-                };
-                await rawUpdateRule(merged);
-                return { id: matchedRule.id, created: false };
-            }
-            else {
-                // CREATE new rule.
-                // #342: stage has no Zod default on this tool (see the schema note), so an
-                // omitted stage arrives as undefined. Actual's validator ALWAYS runs on a
-                // create and rejects undefined with `Invalid rule stage: undefined`, so the
-                // key must be present. null is the correct value: Actual's default stage.
-                if (ruleData.stage === undefined)
-                    ruleData.stage = null;
-                const rawId = await rawCreateRule(ruleData);
-                return { id: normalizeToId(rawId), created: true };
-            }
-        });
+        // The read, the match and the write happen in ONE write-queue cycle inside
+        // adapter.upsertRule (#142, relocated in #376).
+        //
+        // `stage` is passed as an explicit presence flag, because null is a MEANINGFUL stage
+        // (Actual's default) and "omitted" must stay distinguishable from "explicitly null"
+        // across the call boundary (#342).
+        //
+        // Derived from the PARSED value, not from `hasOwnProperty` on the raw args. The schema
+        // is `.nullable().optional()` with no default, so `undefined` means omitted and `null`
+        // means the default stage; a raw-args key test would call an explicit
+        // `{ stage: undefined }` "supplied" and send `undefined` into the update, which is the
+        // exact value #342 records Actual rejecting with `Invalid rule stage: undefined`.
+        // Unreachable over JSON-RPC (which cannot carry undefined) but reachable in-process.
+        return await adapter.upsertRule({
+            stage: input.stage,
+            conditionsOp: input.conditionsOp,
+            conditions: input.conditions,
+            actions: input.actions,
+        }, input.stage !== undefined);
     },
 };
 export default tool;

package/dist/src/tools/rules_delete.js

@@ -1,14 +1,21 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
-import { notFoundMsg } from '../lib/errors.js';
-import api from '@actual-app/api';
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const { getRules: rawGetRules, deleteRule: rawDeleteRule } = api;
 const InputSchema = z.object({
     // Bounded for the same reason as the payee ids in #356: this value is echoed into the
-    // not-found message, into the schedule-owned refusal below, and into logger.error.
+    // not-found message, into the schedule-owned refusal, and into logger.error.
     id: z.string().min(1).max(64).describe('Rule ID to delete'),
 });
+/**
+ * #355 fixed two defects here (a silent no-op on an unknown id, and success reported for a
+ * schedule-owned rule that upstream declined to delete). #376 moved both guards into
+ * `adapter.deleteRule`, which performs the read, the decision and the write in one
+ * write-queue cycle.
+ *
+ * This tool now owns only the published schema and the response wording, which is where the
+ * rest of the tool surface keeps them. Doing the guard in the adapter restores `retry` on
+ * the read, keeps ONE observability call site, and leaves no unguarded `adapter.deleteRule`
+ * for a future caller to reach for. See "Where a read-then-write guard belongs" in CLAUDE.md.
+ */
 const tool = {
     name: 'actual_rules_delete',
     description: 'Delete a budget rule from Actual Budget. The rule will no longer be applied to new or ' +
@@ -17,36 +24,8 @@ const tool = {
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
-        // Read+write inside one withWriteSession cycle (#142).
-        return await adapter.withWriteSession(async () => {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const allRules = await rawGetRules();
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const ruleExists = allRules.some((r) => r.id === input.id);
-            if (!ruleExists) {
-                // Throw (not return {success:false}) so a non-existent id surfaces as an MCP
-                // error, consistent with every other delete tool's not-found behavior.
-                throw new Error(notFoundMsg('Rule', input.id, 'actual_rules_get'));
-            }
-            // #355: the raw call RETURNS a verdict and it used to be discarded.
-            // Upstream `deleteRule` returns `false`, without throwing, when a schedule owns
-            // this rule: Actual keeps a schedule and its generated rule in step and refuses
-            // to remove the rule on its own. The existence pre-check above cannot catch that
-            // case, because the rule genuinely exists. Reporting success there was a lie
-            // (CWE-252, unchecked return value).
-            //
-            // Only an EXPLICIT `false` is a refusal. A build that returns `undefined` (the
-            // published reference documents this method as `Promise<null>`) is treated as
-            // success, so this stays correct against older and future versions.
-            const deleted = await rawDeleteRule(input.id);
-            if (deleted === false) {
-                throw new Error(`Rule "${input.id}" belongs to a schedule and cannot be deleted on its own. ` +
-                    'Actual keeps a schedule and its generated rule in step. Delete the schedule ' +
-                    'instead with actual_schedules_delete (find it with actual_schedules_get), ' +
-                    'which removes this rule too.');
-            }
-            return { success: true };
-        });
+        await adapter.deleteRule(input.id);
+        return { success: true };
     },
 };
 export default tool;

package/dist/src/tools/schedules_delete.js

@@ -1,46 +1,23 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
 import { UUID_PATTERN } from '../lib/constants.js';
-import { notFoundMsg, constraintErrorMsg } from '../lib/errors.js';
-import api from '@actual-app/api';
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const { getSchedules: rawGetSchedules, deleteSchedule: rawDeleteSchedule } = api;
 const InputSchema = z.object({
     id: z.string().regex(UUID_PATTERN, 'Invalid UUID format')
         .describe('UUID of the schedule to delete (from actual_schedules_get)'),
 });
+/**
+ * #376: the existence guard and the SQLite constraint-error translation live in
+ * `adapter.deleteSchedule`, which reads and writes in one write-queue cycle. They used to
+ * sit here inside the tool's own `withWriteSession`.
+ */
 const tool = {
     name: 'actual_schedules_delete',
     description: `Permanently delete a schedule from Actual Budget. The schedule's underlying rule is also removed. This operation cannot be undone.`,
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
-        // Read+write inside one withWriteSession cycle (#142). The constraint-error
-        // translation stays right around the delete call so error messages do not regress.
-        return await adapter.withWriteSession(async () => {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const schedules = await rawGetSchedules();
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const scheduleExists = schedules.some((s) => s.id === input.id);
-            if (!scheduleExists) {
-                // Throw (not return {success:false}) so a non-existent id surfaces as an MCP
-                // error, consistent with every other delete tool's not-found behavior.
-                throw new Error(notFoundMsg('Schedule', input.id, 'actual_schedules_get'));
-            }
-            try {
-                await rawDeleteSchedule(input.id);
-                return { success: true };
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                if (msg.includes('NOT NULL constraint') || msg.includes('messages_crdt')) {
-                    // Translate the raw SQLite constraint error into an actionable message, thrown
-                    // for the same consistency reason as the not-found case above.
-                    throw new Error(constraintErrorMsg('Schedule', input.id, 'actual_schedules_get'));
-                }
-                throw err;
-            }
-        });
+        await adapter.deleteSchedule(input.id);
+        return { success: true };
     },
 };
 export default tool;

package/dist/src/tools/transactions_create.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
+import { isPreflightRefusal } from '../lib/errors.js';
 import { CommonSchemas, subtransactionsSum } from '../lib/schemas/common.js';
 const InputSchema = z
     .object({
@@ -69,8 +70,11 @@ const tool = {
         }
         catch (error) {
             const msg = error instanceof Error ? error.message : String(error);
-            if (msg.toLowerCase().includes('not found') && msg.toLowerCase().includes('account')) {
-                // Return structured error (not throw) so callers receive { success: false, error }
+            // #377: decided by TYPE, not by substring-matching the adapter's prose. The refusal
+            // this catches is adapter.addTransactions' account-existence guard, which throws a
+            // NotFoundRefusal and writes nothing. Returning it structured (rather than throwing)
+            // is this tool's published contract; a genuine failure still throws.
+            if (isPreflightRefusal(error)) {
                 return { success: false, error: msg, id: null };
             }
             throw new Error(`Failed to create transaction: ${msg}`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "engines": {
     "node": ">=22.0.0",
     "npm": ">=10.0.0"
@@ -61,6 +61,7 @@
     "tool-count": "node scripts/tool-count.mjs",
     "config-drift": "npm run build && node scripts/config-drift.mjs",
     "node-version-drift": "node scripts/node-version-drift.mjs",
+    "typecheck:e2e": "tsc --noEmit --project tests/e2e/tsconfig.json",
     "knip": "knip",
     "actionlint": "bash scripts/install-actionlint.sh && ./actionlint -shellcheck= -color",
     "audit:write-effect": "node scripts/check-write-effect-audit.mjs"