@dizzlkheinz/ynab-mcpb 0.18.3 → 0.19.0

package/src/tools/transactionTools.ts

@@ -1,2995 +1,112 @@
-import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
-import * as ynab from 'ynab';
-import { SaveTransaction } from 'ynab/dist/models/SaveTransaction.js';
-import { SaveSubTransaction } from 'ynab/dist/models/SaveSubTransaction.js';
-import type { SaveTransactionsResponseData } from 'ynab/dist/models/SaveTransactionsResponseData.js';
-import { z } from 'zod/v4';
-import { createHash } from 'crypto';
-import { ValidationError, withToolErrorHandling } from '../types/index.js';
-import type { ToolFactory } from '../types/toolRegistration.js';
-import { createAdapters, createBudgetResolver } from './adapters.js';
-import { ToolAnnotationPresets } from './toolCategories.js';
-import { responseFormatter } from '../server/responseFormatter.js';
-import { amountToMilliunits, milliunitsToAmount } from '../utils/amountUtils.js';
-import { cacheManager, CACHE_TTLS, CacheManager } from '../server/cacheManager.js';
-import { globalRequestLogger } from '../server/requestLogger.js';
-import type { DeltaFetcher } from './deltaFetcher.js';
-import type { DeltaCache } from '../server/deltaCache.js';
-import type { ServerKnowledgeStore } from '../server/serverKnowledgeStore.js';
-import { resolveDeltaFetcherArgs, resolveDeltaWriteArgs } from './deltaSupport.js';
-import { handleExportTransactions, ExportTransactionsSchema } from './exportTransactions.js';
-
-/**
- * Utility function to ensure transaction is not null/undefined
- */
-function ensureTransaction<T>(transaction: T | undefined, errorMessage: string): T {
-  if (!transaction) {
-    throw new Error(errorMessage);
-  }
-  return transaction;
-}
-
-const toMonthKey = (date: string): string => `${date.slice(0, 7)}-01`;
-
-interface CategorySource {
-  category_id?: string | null;
-  subtransactions?: { category_id?: string | null }[] | null | undefined;
-}
-
-function appendCategoryIds(source: CategorySource | undefined, target: Set<string>): void {
-  if (!source) {
-    return;
-  }
-  if (source.category_id) {
-    target.add(source.category_id);
-  }
-  if (Array.isArray(source.subtransactions)) {
-    for (const sub of source.subtransactions) {
-      if (sub?.category_id) {
-        target.add(sub.category_id);
-      }
-    }
-  }
-}
-
-function collectCategoryIdsFromSources(...sources: (CategorySource | undefined)[]): Set<string> {
-  const result = new Set<string>();
-  for (const source of sources) {
-    appendCategoryIds(source, result);
-  }
-  return result;
-}
-
-function setsEqual<T>(a: Set<T>, b: Set<T>): boolean {
-  if (a.size !== b.size) {
-    return false;
-  }
-  for (const value of a) {
-    if (!b.has(value)) {
-      return false;
-    }
-  }
-  return true;
-}
-
-interface TransactionCacheInvalidationOptions {
-  affectedCategoryIds?: Set<string>;
-  invalidateAllCategories?: boolean;
-  accountTotalsChanged?: boolean;
-  invalidateMonths?: boolean;
-}
-
-function invalidateTransactionCaches(
-  deltaCache: DeltaCache,
-  knowledgeStore: ServerKnowledgeStore,
-  budgetId: string,
-  serverKnowledge: number | undefined,
-  affectedAccountIds: Set<string>,
-  affectedMonths: Set<string>,
-  options: TransactionCacheInvalidationOptions = {},
-): void {
-  deltaCache.invalidate(budgetId, 'transactions');
-  cacheManager.delete(CacheManager.generateKey('transactions', 'list', budgetId));
-
-  for (const accountId of affectedAccountIds) {
-    const accountPrefix = CacheManager.generateKey('transactions', 'account', budgetId, accountId);
-    cacheManager.deleteByPrefix(accountPrefix);
-  }
-
-  const invalidateAccountsList = options.accountTotalsChanged ?? true;
-  if (invalidateAccountsList) {
-    cacheManager.delete(CacheManager.generateKey('accounts', 'list', budgetId));
-  }
-  for (const accountId of affectedAccountIds) {
-    cacheManager.delete(CacheManager.generateKey('account', 'get', budgetId, accountId));
-  }
-
-  const affectedCategoryIds = options.affectedCategoryIds ?? new Set<string>();
-  const shouldInvalidateCategories =
-    options.invalidateAllCategories || affectedCategoryIds.size > 0;
-  if (shouldInvalidateCategories) {
-    cacheManager.delete(CacheManager.generateKey('categories', 'list', budgetId));
-    for (const categoryId of affectedCategoryIds) {
-      cacheManager.delete(CacheManager.generateKey('category', 'get', budgetId, categoryId));
-    }
-  }
-
-  const shouldInvalidateMonths = options.invalidateMonths ?? affectedMonths.size > 0;
-  if (shouldInvalidateMonths) {
-    cacheManager.delete(CacheManager.generateKey('months', 'list', budgetId));
-    deltaCache.invalidate(budgetId, 'months');
-    for (const month of affectedMonths) {
-      cacheManager.delete(CacheManager.generateKey('month', 'get', budgetId, month));
-    }
-  }
-
-  if (serverKnowledge !== undefined) {
-    const transactionCacheKey = CacheManager.generateKey('transactions', 'list', budgetId);
-    knowledgeStore.update(transactionCacheKey, serverKnowledge);
-    if (invalidateAccountsList) {
-      const accountsCacheKey = CacheManager.generateKey('accounts', 'list', budgetId);
-      knowledgeStore.update(accountsCacheKey, serverKnowledge);
-    }
-    if (shouldInvalidateMonths && affectedMonths.size > 0) {
-      const monthsCacheKey = CacheManager.generateKey('months', 'list', budgetId);
-      knowledgeStore.update(monthsCacheKey, serverKnowledge);
-    }
-  }
-}
-
-/**
- * Schema for ynab:list_transactions tool parameters
- */
-export const ListTransactionsSchema = z
-  .object({
-    budget_id: z.string().min(1, 'Budget ID is required'),
-    account_id: z.string().optional(),
-    category_id: z.string().optional(),
-    since_date: z
-      .string()
-      .regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in ISO format (YYYY-MM-DD)')
-      .optional(),
-    type: z.enum(['uncategorized', 'unapproved']).optional(),
-  })
-  .strict();
-
-export type ListTransactionsParams = z.infer<typeof ListTransactionsSchema>;
-
-/**
- * Schema for ynab:get_transaction tool parameters
- */
-export const GetTransactionSchema = z
-  .object({
-    budget_id: z.string().min(1, 'Budget ID is required'),
-    transaction_id: z.string().min(1, 'Transaction ID is required'),
-  })
-  .strict();
-
-export type GetTransactionParams = z.infer<typeof GetTransactionSchema>;
-
-/**
- * Schema for ynab:create_transaction tool parameters
- */
-export const CreateTransactionSchema = z
-  .object({
-    budget_id: z.string().min(1, 'Budget ID is required'),
-    account_id: z.string().min(1, 'Account ID is required'),
-    amount: z.number().int('Amount must be an integer in milliunits'),
-    date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in ISO format (YYYY-MM-DD)'),
-    payee_name: z.string().optional(),
-    payee_id: z.string().optional(),
-    category_id: z.string().optional(),
-    memo: z.string().optional(),
-    cleared: z.enum(['cleared', 'uncleared', 'reconciled']).optional(),
-    approved: z.boolean().optional(),
-    flag_color: z.enum(['red', 'orange', 'yellow', 'green', 'blue', 'purple']).optional(),
-    import_id: z.string().min(1, 'Import ID cannot be empty').optional(),
-    dry_run: z.boolean().optional(),
-    subtransactions: z
-      .array(
-        z
-          .object({
-            amount: z.number().int('Subtransaction amount must be an integer in milliunits'),
-            payee_name: z.string().optional(),
-            payee_id: z.string().optional(),
-            category_id: z.string().optional(),
-            memo: z.string().optional(),
-          })
-          .strict(),
-      )
-      .min(1, 'At least one subtransaction is required when provided')
-      .optional(),
-  })
-  .strict()
-  .superRefine((data, ctx) => {
-    if (data.subtransactions && data.subtransactions.length > 0) {
-      const total = data.subtransactions.reduce((sum, sub) => sum + sub.amount, 0);
-      if (total !== data.amount) {
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: 'Amount must equal the sum of subtransaction amounts',
-          path: ['amount'],
-        });
-      }
-    }
-  });
-
-export type CreateTransactionParams = z.infer<typeof CreateTransactionSchema>;
-
-const BulkTransactionInputSchemaBase = CreateTransactionSchema.pick({
-  account_id: true,
-  amount: true,
-  date: true,
-  payee_name: true,
-  payee_id: true,
-  category_id: true,
-  memo: true,
-  cleared: true,
-  approved: true,
-  flag_color: true,
-  import_id: true,
-});
-
-type BulkTransactionInput = Omit<
-  CreateTransactionParams,
-  'budget_id' | 'dry_run' | 'subtransactions'
->;
-
-// Schema for bulk transaction creation - subtransactions are not supported
-// The .strict() modifier automatically rejects any fields not in the schema
-const BulkTransactionInputSchema = BulkTransactionInputSchemaBase.strict();
-
-export const CreateTransactionsSchema = z
-  .object({
-    budget_id: z.string().min(1, 'Budget ID is required'),
-    transactions: z
-      .array(BulkTransactionInputSchema)
-      .min(1, 'At least one transaction is required')
-      .max(100, 'A maximum of 100 transactions may be created at once'),
-    dry_run: z.boolean().optional(),
-  })
-  .strict();
-
-export type CreateTransactionsParams = z.infer<typeof CreateTransactionsSchema>;
-
-export interface BulkTransactionResult {
-  request_index: number;
-  status: 'created' | 'duplicate' | 'failed';
-  transaction_id?: string | undefined;
-  correlation_key: string;
-  error_code?: string | undefined;
-  error?: string | undefined;
-}
-
-export interface BulkCreateResponse {
-  success: boolean;
-  server_knowledge?: number;
-  summary: {
-    total_requested: number;
-    created: number;
-    duplicates: number;
-    failed: number;
-  };
-  results: BulkTransactionResult[];
-  transactions?: ynab.TransactionDetail[];
-  duplicate_import_ids?: string[];
-  message?: string;
-  mode?: 'full' | 'summary' | 'ids_only';
-}
-
-const FULL_RESPONSE_THRESHOLD = 64 * 1024;
-const SUMMARY_RESPONSE_THRESHOLD = 96 * 1024;
-const MAX_RESPONSE_BYTES = 100 * 1024;
-
-export function generateCorrelationKey(transaction: {
-  account_id?: string;
-  date?: string;
-  amount?: number;
-  payee_id?: string | null;
-  payee_name?: string | null;
-  category_id?: string | null;
-  memo?: string | null;
-  cleared?: ynab.TransactionClearedStatus;
-  approved?: boolean;
-  flag_color?: ynab.TransactionFlagColor | null;
-  import_id?: string | null;
-}): string {
-  if (transaction.import_id) {
-    return transaction.import_id;
-  }
-
-  const segments = [
-    `account:${transaction.account_id ?? ''}`,
-    `date:${transaction.date ?? ''}`,
-    `amount:${transaction.amount ?? 0}`,
-    `payee:${transaction.payee_id ?? transaction.payee_name ?? ''}`,
-    `category:${transaction.category_id ?? ''}`,
-    `memo:${transaction.memo ?? ''}`,
-    `cleared:${transaction.cleared ?? ''}`,
-    `approved:${transaction.approved ?? false}`,
-    `flag:${transaction.flag_color ?? ''}`,
-  ];
-
-  const normalized = segments.join('|');
-  const hash = createHash('sha256').update(normalized).digest('hex').slice(0, 16);
-  return `hash:${hash}`;
-}
-
-type CorrelationPayload = Parameters<typeof generateCorrelationKey>[0];
-
-interface CorrelationPayloadInput {
-  account_id?: string | undefined;
-  date?: string | undefined;
-  amount?: number | undefined;
-  payee_id?: string | null | undefined;
-  payee_name?: string | null | undefined;
-  category_id?: string | null | undefined;
-  memo?: string | null | undefined;
-  cleared?: ynab.TransactionClearedStatus | undefined;
-  approved?: boolean | undefined;
-  flag_color?: ynab.TransactionFlagColor | null | undefined;
-  import_id?: string | null | undefined;
-}
-
-export function toCorrelationPayload(transaction: CorrelationPayloadInput): CorrelationPayload {
-  const payload: CorrelationPayload = {};
-  if (transaction.account_id !== undefined) {
-    payload.account_id = transaction.account_id;
-  }
-  if (transaction.date !== undefined) {
-    payload.date = transaction.date;
-  }
-  if (transaction.amount !== undefined) {
-    payload.amount = transaction.amount;
-  }
-  if (transaction.cleared !== undefined) {
-    payload.cleared = transaction.cleared;
-  }
-  if (transaction.approved !== undefined) {
-    payload.approved = transaction.approved;
-  }
-  if (transaction.flag_color !== undefined) {
-    payload.flag_color = transaction.flag_color;
-  }
-  payload.payee_id = transaction.payee_id ?? null;
-  payload.payee_name = transaction.payee_name ?? null;
-  payload.category_id = transaction.category_id ?? null;
-  payload.memo = transaction.memo ?? null;
-  payload.import_id = transaction.import_id ?? null;
-  return payload;
-}
-
-export function correlateResults(
-  requests: BulkTransactionInput[],
-  responseData: SaveTransactionsResponseData,
-  duplicateImportIds: Set<string>,
-): BulkTransactionResult[] {
-  const createdByImportId = new Map<string, string[]>();
-  const createdByHash = new Map<string, string[]>();
-  const responseTransactions = responseData.transactions ?? [];
-
-  const register = (map: Map<string, string[]>, key: string, transactionId: string): void => {
-    const existing = map.get(key);
-    if (existing) {
-      existing.push(transactionId);
-      return;
-    }
-    map.set(key, [transactionId]);
-  };
-
-  for (const transaction of responseTransactions) {
-    if (!transaction.id) {
-      continue;
-    }
-    const key = generateCorrelationKey(transaction);
-    if (key.startsWith('hash:')) {
-      register(createdByHash, key, transaction.id);
-    } else {
-      register(createdByImportId, key, transaction.id);
-    }
-  }
-
-  const popId = (map: Map<string, string[]>, key: string): string | undefined => {
-    const bucket = map.get(key);
-    if (!bucket || bucket.length === 0) {
-      return undefined;
-    }
-    const [transactionId] = bucket.splice(0, 1);
-    if (bucket.length === 0) {
-      map.delete(key);
-    }
-    return transactionId;
-  };
-
-  const correlatedResults: BulkTransactionResult[] = [];
-
-  for (const [index, transaction] of requests.entries()) {
-    const normalizedRequest = toCorrelationPayload(transaction);
-    const correlationKey = generateCorrelationKey(normalizedRequest);
-
-    if (transaction.import_id && duplicateImportIds.has(transaction.import_id)) {
-      correlatedResults.push({
-        request_index: index,
-        status: 'duplicate',
-        correlation_key: correlationKey,
-      });
-      continue;
-    }
-
-    let transactionId: string | undefined;
-    if (correlationKey.startsWith('hash:')) {
-      transactionId = popId(createdByHash, correlationKey);
-    } else {
-      transactionId = popId(createdByImportId, correlationKey);
-    }
-
-    if (!transactionId && !correlationKey.startsWith('hash:')) {
-      // Attempt hash-based fallback if import_id was not matched.
-      const hashKey = generateCorrelationKey(
-        toCorrelationPayload({ ...transaction, import_id: undefined }),
-      );
-      transactionId = popId(createdByHash, hashKey);
-    }
-
-    if (transactionId) {
-      const successResult: BulkTransactionResult = {
-        request_index: index,
-        status: 'created',
-        correlation_key: correlationKey,
-      };
-      successResult.transaction_id = transactionId;
-      correlatedResults.push(successResult);
-      continue;
-    }
-
-    globalRequestLogger.logError(
-      'ynab:create_transactions',
-      'correlate_results',
-      {
-        request_index: index,
-        correlation_key: correlationKey,
-        request: {
-          account_id: transaction.account_id,
-          date: transaction.date,
-          amount: transaction.amount,
-          import_id: transaction.import_id,
-        },
-      },
-      'correlation_failed',
-    );
-
-    correlatedResults.push({
-      request_index: index,
-      status: 'failed',
-      correlation_key: correlationKey,
-      error_code: 'correlation_failed',
-      error: 'Unable to correlate request transaction with YNAB response',
-    });
-  }
-
-  return correlatedResults;
-}
-
-function estimatePayloadSize(payload: BulkCreateResponse | BulkUpdateResponse): number {
-  return Buffer.byteLength(JSON.stringify(payload), 'utf8');
-}
-
-function finalizeResponse(response: BulkCreateResponse): BulkCreateResponse {
-  const appendMessage = (message: string | undefined, addition: string): string => {
-    if (!message) {
-      return addition;
-    }
-    if (message.includes(addition)) {
-      return message;
-    }
-    return `${message} ${addition}`;
-  };
-
-  const fullSize = estimatePayloadSize({ ...response, mode: 'full' });
-  if (fullSize <= FULL_RESPONSE_THRESHOLD) {
-    return { ...response, mode: 'full' };
-  }
-
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  const { transactions, ...summaryResponse } = response;
-  const summaryPayload: BulkCreateResponse = {
-    ...summaryResponse,
-    message: appendMessage(
-      response.message,
-      'Response downgraded to summary to stay under size limits.',
-    ),
-    mode: 'summary',
-  };
-
-  if (estimatePayloadSize(summaryPayload) <= SUMMARY_RESPONSE_THRESHOLD) {
-    return summaryPayload;
-  }
-
-  const idsOnlyPayload: BulkCreateResponse = {
-    ...summaryPayload,
-    results: summaryResponse.results.map((result) => ({
-      request_index: result.request_index,
-      status: result.status,
-      transaction_id: result.transaction_id,
-      correlation_key: result.correlation_key,
-      error: result.error,
-    })),
-    message: appendMessage(
-      summaryResponse.message,
-      'Response downgraded to ids_only to meet 100KB limit.',
-    ),
-    mode: 'ids_only',
-  };
-
-  if (estimatePayloadSize(idsOnlyPayload) <= MAX_RESPONSE_BYTES) {
-    return idsOnlyPayload;
-  }
-
-  throw new ValidationError(
-    'RESPONSE_TOO_LARGE: Unable to format bulk create response within 100KB limit',
-    `Batch size: ${response.summary.total_requested} transactions`,
-    ['Reduce the batch size and retry', 'Consider splitting into multiple smaller batches'],
-  );
-}
-
-const ReceiptSplitItemSchema = z
-  .object({
-    name: z.string().min(1, 'Item name is required'),
-    amount: z.number().finite('Item amount must be a finite number'),
-    quantity: z
-      .number()
-      .finite('Quantity must be a finite number')
-      .positive('Quantity must be greater than zero')
-      .optional(),
-    memo: z.string().optional(),
-  })
-  .strict();
-
-const ReceiptSplitCategorySchema = z
-  .object({
-    category_id: z.string().min(1, 'Category ID is required'),
-    category_name: z.string().optional(),
-    items: z.array(ReceiptSplitItemSchema).min(1, 'Each category must include at least one item'),
-  })
-  .strict();
-
-export const CreateReceiptSplitTransactionSchema = z
-  .object({
-    budget_id: z.string().min(1, 'Budget ID is required'),
-    account_id: z.string().min(1, 'Account ID is required'),
-    payee_name: z.string().min(1, 'Payee name is required'),
-    date: z
-      .string()
-      .regex(/^[0-9]{4}-[0-9]{2}-[0-9]{2}$/, 'Date must be in ISO format (YYYY-MM-DD)')
-      .optional(),
-    memo: z.string().optional(),
-    receipt_subtotal: z
-      .number()
-      .finite('Receipt subtotal must be a finite number')
-      .refine((value) => value >= 0, 'Receipt subtotal must be zero or greater')
-      .optional(),
-    receipt_tax: z.number().finite('Receipt tax must be a finite number'),
-    receipt_total: z
-      .number()
-      .finite('Receipt total must be a finite number')
-      .refine((value) => value > 0, 'Receipt total must be greater than zero'),
-    categories: z
-      .array(ReceiptSplitCategorySchema)
-      .min(1, 'At least one categorized group is required to create a split transaction'),
-    cleared: z.enum(['cleared', 'uncleared', 'reconciled']).optional(),
-    approved: z.boolean().optional(),
-    flag_color: z.enum(['red', 'orange', 'yellow', 'green', 'blue', 'purple']).optional(),
-    dry_run: z.boolean().optional(),
-  })
-  .strict()
-  .superRefine((data, ctx) => {
-    const itemsSubtotal = data.categories
-      .flatMap((category) => category.items)
-      .reduce((sum, item) => sum + item.amount, 0);
-
-    if (data.receipt_subtotal !== undefined) {
-      const delta = Math.abs(data.receipt_subtotal - itemsSubtotal);
-      if (delta > 0.01) {
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: `Receipt subtotal (${data.receipt_subtotal.toFixed(2)}) does not match categorized items total (${itemsSubtotal.toFixed(2)})`,
-          path: ['receipt_subtotal'],
-        });
-      }
-    }
-
-    const expectedTotal = itemsSubtotal + data.receipt_tax;
-    const deltaTotal = Math.abs(expectedTotal - data.receipt_total);
-    if (deltaTotal > 0.01) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: `Receipt total (${data.receipt_total.toFixed(2)}) does not match subtotal plus tax (${expectedTotal.toFixed(2)})`,
-        path: ['receipt_total'],
-      });
-    }
-  });
-
-export type CreateReceiptSplitTransactionParams = z.infer<
-  typeof CreateReceiptSplitTransactionSchema
->;
-
-/**
- * Schema for ynab:update_transaction tool parameters
- */
-export const UpdateTransactionSchema = z
-  .object({
-    budget_id: z.string().min(1, 'Budget ID is required'),
-    transaction_id: z.string().min(1, 'Transaction ID is required'),
-    account_id: z.string().optional(),
-    amount: z.number().int('Amount must be an integer in milliunits').optional(),
-    date: z
-      .string()
-      .regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in ISO format (YYYY-MM-DD)')
-      .optional(),
-    payee_name: z.string().optional(),
-    payee_id: z.string().optional(),
-    category_id: z.string().optional(),
-    memo: z.string().optional(),
-    cleared: z.enum(['cleared', 'uncleared', 'reconciled']).optional(),
-    approved: z.boolean().optional(),
-    flag_color: z.enum(['red', 'orange', 'yellow', 'green', 'blue', 'purple']).optional(),
-    dry_run: z.boolean().optional(),
-  })
-  .strict();
-
-export type UpdateTransactionParams = z.infer<typeof UpdateTransactionSchema>;
-
-/**
- * Schema for bulk transaction updates - each item in the array
- * Note: account_id is intentionally excluded as account moves are not supported in bulk updates
- */
-const BulkUpdateTransactionInputSchema = z
-  .object({
-    id: z.string().min(1, 'Transaction ID is required'),
-    amount: z.number().int('Amount must be an integer in milliunits').optional(),
-    date: z
-      .string()
-      .regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in ISO format (YYYY-MM-DD)')
-      .optional(),
-    payee_name: z.string().optional(),
-    payee_id: z.string().optional(),
-    category_id: z.string().optional(),
-    memo: z.string().optional(),
-    cleared: z.enum(['cleared', 'uncleared', 'reconciled']).optional(),
-    approved: z.boolean().optional(),
-    flag_color: z.enum(['red', 'orange', 'yellow', 'green', 'blue', 'purple']).optional(),
-    // Metadata fields for cache invalidation
-    original_account_id: z.string().optional(),
-    original_date: z
-      .string()
-      .regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in ISO format (YYYY-MM-DD)')
-      .optional(),
-  })
-  .strict();
-
-export type BulkUpdateTransactionInput = z.infer<typeof BulkUpdateTransactionInputSchema>;
-
 /**
- * Schema for ynab:update_transactions tool parameters
- */
-export const UpdateTransactionsSchema = z
-  .object({
-    budget_id: z.string().min(1, 'Budget ID is required'),
-    transactions: z
-      .array(BulkUpdateTransactionInputSchema)
-      .min(1, 'At least one transaction is required')
-      .max(100, 'A maximum of 100 transactions may be updated at once'),
-    dry_run: z.boolean().optional(),
-  })
-  .strict();
-
-export type UpdateTransactionsParams = z.infer<typeof UpdateTransactionsSchema>;
-
-export interface BulkUpdateResult {
-  request_index: number;
-  status: 'updated' | 'failed';
-  transaction_id: string;
-  correlation_key: string;
-  error_code?: string;
-  error?: string;
-}
-
-export interface BulkUpdateResponse {
-  success: boolean;
-  server_knowledge?: number;
-  summary: {
-    total_requested: number;
-    updated: number;
-    failed: number;
-  };
-  results: BulkUpdateResult[];
-  transactions?: ynab.TransactionDetail[];
-  message?: string;
-  mode?: 'full' | 'summary' | 'ids_only';
-}
-
-/**
- * Schema for ynab:delete_transaction tool parameters
- */
-export const DeleteTransactionSchema = z
-  .object({
-    budget_id: z.string().min(1, 'Budget ID is required'),
-    transaction_id: z.string().min(1, 'Transaction ID is required'),
-    dry_run: z.boolean().optional(),
-  })
-  .strict();
-
-export type DeleteTransactionParams = z.infer<typeof DeleteTransactionSchema>;
-
-/**
- * Handles the ynab:list_transactions tool call
- * Lists transactions for a budget with optional filtering
- */
-
-export async function handleListTransactions(
-  ynabAPI: ynab.API,
-  deltaFetcher: DeltaFetcher,
-  params: ListTransactionsParams,
-): Promise<CallToolResult>;
-export async function handleListTransactions(
-  ynabAPI: ynab.API,
-  params: ListTransactionsParams,
-): Promise<CallToolResult>;
-export async function handleListTransactions(
-  ynabAPI: ynab.API,
-  deltaFetcherOrParams: DeltaFetcher | ListTransactionsParams,
-  maybeParams?: ListTransactionsParams,
-): Promise<CallToolResult> {
-  const { deltaFetcher, params } = resolveDeltaFetcherArgs(
-    ynabAPI,
-    deltaFetcherOrParams,
-    maybeParams,
-  );
-  return await withToolErrorHandling(
-    async () => {
-      // Always use cache
-      let transactions: (ynab.TransactionDetail | ynab.HybridTransaction)[];
-      let cacheHit = false;
-      let usedDelta = false;
-
-      if (params.account_id) {
-        // Validate that the account exists before fetching transactions
-        // YNAB API returns empty array for invalid account IDs instead of an error
-        const accountsResult = await deltaFetcher.fetchAccounts(params.budget_id);
-        const accountExists = accountsResult.data.some(
-          (account) => account.id === params.account_id,
-        );
-        if (!accountExists) {
-          throw new Error(`Account ${params.account_id} not found in budget ${params.budget_id}`);
-        }
-
-        const result = await deltaFetcher.fetchTransactionsByAccount(
-          params.budget_id,
-          params.account_id,
-          params.since_date,
-        );
-        transactions = result.data;
-        cacheHit = result.wasCached;
-        usedDelta = result.usedDelta;
-      } else if (params.category_id) {
-        const response = await ynabAPI.transactions.getTransactionsByCategory(
-          params.budget_id,
-          params.category_id,
-          params.since_date,
-        );
-        transactions = response.data.transactions;
-      } else {
-        const result = await deltaFetcher.fetchTransactions(
-          params.budget_id,
-          params.since_date,
-          params.type as ynab.GetTransactionsTypeEnum | undefined,
-        );
-        transactions = result.data;
-        cacheHit = result.wasCached;
-        usedDelta = result.usedDelta;
-      }
-
-      // Check if response might be too large for MCP
-      const estimatedSize = JSON.stringify(transactions).length;
-      const sizeLimit = 90000; // Conservative limit under 100KB
-
-      if (estimatedSize > sizeLimit) {
-        // Return summary and suggest export
-        const preview = transactions.slice(0, 50);
-        return {
-          content: [
-            {
-              type: 'text',
-              text: responseFormatter.format({
-                message: `Found ${transactions.length} transactions (${Math.round(estimatedSize / 1024)}KB). Too large to display all.`,
-                suggestion: "Use 'export_transactions' tool to save all transactions to a file.",
-                showing: `First ${preview.length} transactions:`,
-                total_count: transactions.length,
-                estimated_size_kb: Math.round(estimatedSize / 1024),
-                cached: cacheHit,
-                cache_info: cacheHit
-                  ? `Data retrieved from cache for improved performance${usedDelta ? ' (delta merge applied)' : ''}`
-                  : 'Fresh data retrieved from YNAB API',
-                preview_transactions: preview.map((transaction) => ({
-                  id: transaction.id,
-                  date: transaction.date,
-                  amount: milliunitsToAmount(transaction.amount),
-                  memo: transaction.memo,
-                  payee_name: transaction.payee_name,
-                  category_name: transaction.category_name,
-                })),
-              }),
-            },
-          ],
-        };
-      }
-
-      return {
-        content: [
-          {
-            type: 'text',
-            text: responseFormatter.format({
-              total_count: transactions.length,
-              cached: cacheHit,
-              cache_info: cacheHit
-                ? `Data retrieved from cache for improved performance${usedDelta ? ' (delta merge applied)' : ''}`
-                : 'Fresh data retrieved from YNAB API',
-              transactions: transactions.map((transaction) => ({
-                id: transaction.id,
-                date: transaction.date,
-                amount: milliunitsToAmount(transaction.amount),
-                memo: transaction.memo,
-                cleared: transaction.cleared,
-                approved: transaction.approved,
-                flag_color: transaction.flag_color,
-                account_id: transaction.account_id,
-                payee_id: transaction.payee_id,
-                category_id: transaction.category_id,
-                transfer_account_id: transaction.transfer_account_id,
-                transfer_transaction_id: transaction.transfer_transaction_id,
-                matched_transaction_id: transaction.matched_transaction_id,
-                import_id: transaction.import_id,
-                deleted: transaction.deleted,
-              })),
-            }),
-          },
-        ],
-      };
-    },
-    'ynab:list_transactions',
-    'listing transactions',
-  );
-}
-
-/**
- * Handles the ynab:get_transaction tool call
- * Gets detailed information for a specific transaction
- */
-export async function handleGetTransaction(
-  ynabAPI: ynab.API,
-  params: GetTransactionParams,
-): Promise<CallToolResult> {
-  try {
-    const useCache = process.env['NODE_ENV'] !== 'test';
-
-    let transaction: ynab.TransactionDetail;
-    let cacheHit = false;
-
-    if (useCache) {
-      // Use enhanced CacheManager wrap method
-      const cacheKey = CacheManager.generateKey(
-        'transaction',
-        'get',
-        params.budget_id,
-        params.transaction_id,
-      );
-      cacheHit = cacheManager.has(cacheKey);
-      transaction = await cacheManager.wrap<ynab.TransactionDetail>(cacheKey, {
-        ttl: CACHE_TTLS.TRANSACTIONS,
-        loader: async () => {
-          const response = await ynabAPI.transactions.getTransactionById(
-            params.budget_id,
-            params.transaction_id,
-          );
-          return ensureTransaction(response.data.transaction, 'Transaction not found');
-        },
-      });
-    } else {
-      // Bypass cache in test environment
-      const response = await ynabAPI.transactions.getTransactionById(
-        params.budget_id,
-        params.transaction_id,
-      );
-      transaction = ensureTransaction(response.data.transaction, 'Transaction not found');
-    }
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: responseFormatter.format({
-            transaction: {
-              id: transaction.id,
-              date: transaction.date,
-              amount: milliunitsToAmount(transaction.amount),
-              memo: transaction.memo,
-              cleared: transaction.cleared,
-              approved: transaction.approved,
-              flag_color: transaction.flag_color,
-              account_id: transaction.account_id,
-              payee_id: transaction.payee_id,
-              category_id: transaction.category_id,
-              transfer_account_id: transaction.transfer_account_id,
-              transfer_transaction_id: transaction.transfer_transaction_id,
-              matched_transaction_id: transaction.matched_transaction_id,
-              import_id: transaction.import_id,
-              deleted: transaction.deleted,
-              account_name: transaction.account_name,
-              payee_name: transaction.payee_name,
-              category_name: transaction.category_name,
-            },
-            cached: cacheHit,
-            cache_info: cacheHit
-              ? 'Data retrieved from cache for improved performance'
-              : 'Fresh data retrieved from YNAB API',
-          }),
-        },
-      ],
-    };
-  } catch (error) {
-    return handleTransactionError(error, 'Failed to get transaction');
-  }
-}
-
-/**
- * Handles the ynab:create_transaction tool call
- * Creates a new transaction in the specified budget and account
- */
-export async function handleCreateTransaction(
-  ynabAPI: ynab.API,
-  deltaCache: DeltaCache,
-  knowledgeStore: ServerKnowledgeStore,
-  params: CreateTransactionParams,
-): Promise<CallToolResult>;
-export async function handleCreateTransaction(
-  ynabAPI: ynab.API,
-  params: CreateTransactionParams,
-): Promise<CallToolResult>;
-export async function handleCreateTransaction(
-  ynabAPI: ynab.API,
-  deltaCacheOrParams: DeltaCache | CreateTransactionParams,
-  knowledgeStoreOrParams?: ServerKnowledgeStore | CreateTransactionParams,
-  maybeParams?: CreateTransactionParams,
-): Promise<CallToolResult> {
-  const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(
-    deltaCacheOrParams,
-    knowledgeStoreOrParams,
-    maybeParams,
-  );
-  try {
-    if (params.dry_run) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: responseFormatter.format({
-              dry_run: true,
-              action: 'create_transaction',
-              request: params,
-            }),
-          },
-        ],
-      };
-    }
-    // Prepare transaction data
-    const transactionData: SaveTransaction = {
-      account_id: params.account_id,
-      amount: params.amount, // Already validated as integer milliunits
-      date: params.date,
-      cleared: params.cleared as ynab.TransactionClearedStatus,
-      flag_color: params.flag_color as ynab.TransactionFlagColor,
-    };
-    if (params.payee_name !== undefined) transactionData.payee_name = params.payee_name;
-    if (params.payee_id !== undefined) transactionData.payee_id = params.payee_id;
-    if (params.category_id !== undefined) transactionData.category_id = params.category_id;
-    if (params.memo !== undefined) transactionData.memo = params.memo;
-    if (params.approved !== undefined) transactionData.approved = params.approved;
-    if (params.import_id !== undefined) transactionData.import_id = params.import_id;
-    if (params.subtransactions && params.subtransactions.length > 0) {
-      const subtransactions: SaveSubTransaction[] = params.subtransactions.map((subtransaction) => {
-        const mapped: SaveSubTransaction = {
-          amount: subtransaction.amount,
-        };
-
-        if (subtransaction.payee_name !== undefined) mapped.payee_name = subtransaction.payee_name;
-        if (subtransaction.payee_id !== undefined) mapped.payee_id = subtransaction.payee_id;
-        if (subtransaction.category_id !== undefined) {
-          mapped.category_id = subtransaction.category_id;
-        }
-        if (subtransaction.memo !== undefined) mapped.memo = subtransaction.memo;
-
-        return mapped;
-      });
-
-      transactionData.subtransactions = subtransactions;
-    }
-
-    const response = await ynabAPI.transactions.createTransaction(params.budget_id, {
-      transaction: transactionData,
-    });
-
-    const transaction = ensureTransaction(response.data.transaction, 'Transaction creation failed');
-
-    const affectedAccountIds = new Set<string>([transaction.account_id]);
-    const affectedMonths = new Set<string>([toMonthKey(transaction.date)]);
-    const affectedCategoryIds = collectCategoryIdsFromSources(transaction);
-    invalidateTransactionCaches(
-      deltaCache,
-      knowledgeStore,
-      params.budget_id,
-      response.data.server_knowledge,
-      affectedAccountIds,
-      affectedMonths,
-      {
-        affectedCategoryIds,
-        accountTotalsChanged: true,
-        invalidateMonths: true,
-      },
-    );
-
-    // Get the updated account balance
-    const accountResponse = await ynabAPI.accounts.getAccountById(
-      params.budget_id,
-      transaction.account_id,
-    );
-    const account = accountResponse.data.account;
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: responseFormatter.format({
-            transaction: {
-              id: transaction.id,
-              date: transaction.date,
-              amount: milliunitsToAmount(transaction.amount),
-              memo: transaction.memo,
-              cleared: transaction.cleared,
-              approved: transaction.approved,
-              flag_color: transaction.flag_color,
-              account_id: transaction.account_id,
-              payee_id: transaction.payee_id,
-              category_id: transaction.category_id,
-              transfer_account_id: transaction.transfer_account_id,
-              transfer_transaction_id: transaction.transfer_transaction_id,
-              matched_transaction_id: transaction.matched_transaction_id,
-              import_id: transaction.import_id,
-              deleted: transaction.deleted,
-              // New fields for account balance
-              account_balance: account.balance,
-              account_cleared_balance: account.cleared_balance,
-              subtransactions: transaction.subtransactions?.map((subtransaction) => ({
-                id: subtransaction.id,
-                transaction_id: subtransaction.transaction_id,
-                amount: milliunitsToAmount(subtransaction.amount),
-                memo: subtransaction.memo,
-                payee_id: subtransaction.payee_id,
-                payee_name: subtransaction.payee_name,
-                category_id: subtransaction.category_id,
-                category_name: subtransaction.category_name,
-                transfer_account_id: subtransaction.transfer_account_id,
-                transfer_transaction_id: subtransaction.transfer_transaction_id,
-                deleted: subtransaction.deleted,
-              })),
-            },
-          }),
-        },
-      ],
-    };
-  } catch (error) {
-    return handleTransactionError(error, 'Failed to create transaction');
-  }
-}
-
-interface ReceiptCategoryCalculation {
-  category_id: string;
-  category_name: string | undefined;
-  subtotal_milliunits: number;
-  tax_milliunits: number;
-  items: {
-    name: string;
-    amount_milliunits: number;
-    quantity: number | undefined;
-    memo: string | undefined;
-  }[];
-}
-
-interface SubtransactionInput {
-  amount: number;
-  payee_name?: string;
-  payee_id?: string;
-  category_id?: string;
-  memo?: string;
-}
-
-/**
- * Constants for smart collapse logic
- */
-const BIG_TICKET_THRESHOLD_MILLIUNITS = 50000; // $50.00
-const COLLAPSE_THRESHOLD = 5; // Collapse if 5 or more remaining items
-const MAX_ITEMS_PER_MEMO = 5;
-const MAX_MEMO_LENGTH = 150;
-
-/**
- * Truncates a string to fit within maxLength, adding ellipsis if truncated
- */
-function truncateToLength(str: string, maxLength: number): string {
-  if (str.length <= maxLength) {
-    return str;
-  }
-  const ellipsis = '...';
-  return str.substring(0, maxLength - ellipsis.length) + ellipsis;
-}
-
-function buildItemMemo(item: {
-  name: string;
-  quantity: number | undefined;
-  memo: string | undefined;
-}): string | undefined {
-  const quantitySuffix = item.quantity ? ` (x${item.quantity})` : '';
-  let result: string;
-  if (item.memo && item.memo.trim().length > 0) {
-    result = `${item.name}${quantitySuffix} - ${item.memo}`;
-  } else if (quantitySuffix) {
-    result = `${item.name}${quantitySuffix}`;
-  } else {
-    result = item.name;
-  }
-  // Truncate to MAX_MEMO_LENGTH if needed
-  return truncateToLength(result, MAX_MEMO_LENGTH);
-}
-
-/**
- * Applies smart collapse logic to receipt items according to the specification:
- * 1. Extract special items (big ticket, returns, discounts)
- * 2. Apply threshold to remaining items
- * 3. Collapse by category if needed
- * 4. Handle tax allocation
- */
-function applySmartCollapseLogic(
-  categoryCalculations: ReceiptCategoryCalculation[],
-  taxMilliunits: number,
-): SubtransactionInput[] {
-  // Step 1: Extract special items and classify remaining items
-  interface SpecialItem {
-    item: ReceiptCategoryCalculation['items'][0];
-    category_id: string;
-    category_name: string | undefined;
-  }
-
-  interface CategoryItems {
-    category_id: string;
-    category_name: string | undefined;
-    items: ReceiptCategoryCalculation['items'][0][];
-  }
-
-  const specialItems: SpecialItem[] = [];
-  const remainingItemsByCategory: CategoryItems[] = [];
-
-  for (const category of categoryCalculations) {
-    const categorySpecials: ReceiptCategoryCalculation['items'][0][] = [];
-    const categoryRemaining: ReceiptCategoryCalculation['items'][0][] = [];
-
-    for (const item of category.items) {
-      const isNegative = item.amount_milliunits < 0;
-      const unitPrice = item.quantity
-        ? item.amount_milliunits / item.quantity
-        : item.amount_milliunits;
-      const isBigTicket = unitPrice > BIG_TICKET_THRESHOLD_MILLIUNITS;
-
-      if (isNegative || isBigTicket) {
-        categorySpecials.push(item);
-      } else {
-        categoryRemaining.push(item);
-      }
-    }
-
-    // Add specials to the special items list (preserving category order)
-    for (const item of categorySpecials) {
-      specialItems.push({
-        item,
-        category_id: category.category_id,
-        category_name: category.category_name,
-      });
-    }
-
-    // Track remaining items by category
-    if (categoryRemaining.length > 0) {
-      remainingItemsByCategory.push({
-        category_id: category.category_id,
-        category_name: category.category_name,
-        items: categoryRemaining,
-      });
-    }
-  }
-
-  // Step 2: Count total remaining positive items
-  const totalRemainingItems = remainingItemsByCategory.reduce(
-    (sum, cat) => sum + cat.items.length,
-    0,
-  );
-
-  // Step 3: Decide whether to collapse
-  const shouldCollapse = totalRemainingItems >= COLLAPSE_THRESHOLD;
-
-  // Build subtransactions
-  const subtransactions: SubtransactionInput[] = [];
-
-  // Add special items first (returns, discounts, big tickets)
-  for (const special of specialItems) {
-    const memo = buildItemMemo({
-      name: special.item.name,
-      quantity: special.item.quantity,
-      memo: special.item.memo,
-    });
-    const payload: SubtransactionInput = {
-      amount: -special.item.amount_milliunits,
-      category_id: special.category_id,
-    };
-    if (memo) payload.memo = memo;
-    subtransactions.push(payload);
-  }
-
-  // Add remaining items (collapsed or itemized)
-  if (shouldCollapse) {
-    // Collapse by category
-    for (const categoryGroup of remainingItemsByCategory) {
-      const collapsedSubtransactions = collapseItemsByCategory(categoryGroup);
-      subtransactions.push(...collapsedSubtransactions);
-    }
-  } else {
-    // Itemize each remaining item individually
-    for (const categoryGroup of remainingItemsByCategory) {
-      for (const item of categoryGroup.items) {
-        const memo = buildItemMemo({
-          name: item.name,
-          quantity: item.quantity,
-          memo: item.memo,
-        });
-        const payload: SubtransactionInput = {
-          amount: -item.amount_milliunits,
-          category_id: categoryGroup.category_id,
-        };
-        if (memo) payload.memo = memo;
-        subtransactions.push(payload);
-      }
-    }
-  }
-
-  // Step 4: Handle tax allocation
-  const taxSubtransactions = allocateTax(categoryCalculations, taxMilliunits);
-  subtransactions.push(...taxSubtransactions);
-
-  return subtransactions;
-}
-
-/**
- * Collapses items within a category into groups of up to MAX_ITEMS_PER_MEMO
- */
-function collapseItemsByCategory(categoryGroup: {
-  category_id: string;
-  category_name: string | undefined;
-  items: ReceiptCategoryCalculation['items'][0][];
-}): SubtransactionInput[] {
-  const subtransactions: SubtransactionInput[] = [];
-  const items = categoryGroup.items;
-
-  let currentBatch: ReceiptCategoryCalculation['items'][0][] = [];
-  let currentBatchTotal = 0;
-
-  for (const item of items) {
-    // Check if we've hit the max items per memo
-    if (currentBatch.length >= MAX_ITEMS_PER_MEMO) {
-      // Flush current batch
-      const memo = buildCollapsedMemo(currentBatch);
-      subtransactions.push({
-        amount: -currentBatchTotal,
-        category_id: categoryGroup.category_id,
-        memo,
-      });
-      currentBatch = [];
-      currentBatchTotal = 0;
-    }
-
-    // Try adding this item to the current batch
-    const testBatch = [...currentBatch, item];
-    const testMemo = buildCollapsedMemo(testBatch);
-
-    if (testMemo.length <= MAX_MEMO_LENGTH) {
-      // Fits - add to batch
-      currentBatch.push(item);
-      currentBatchTotal += item.amount_milliunits;
-    } else {
-      // Doesn't fit - flush current batch and start new one
-      if (currentBatch.length > 0) {
-        const memo = buildCollapsedMemo(currentBatch);
-        subtransactions.push({
-          amount: -currentBatchTotal,
-          category_id: categoryGroup.category_id,
-          memo,
-        });
-        currentBatch = [item];
-        currentBatchTotal = item.amount_milliunits;
-      } else {
-        // Edge case: single item is too long, use it anyway
-        currentBatch = [item];
-        currentBatchTotal = item.amount_milliunits;
-      }
-    }
-  }
-
-  // Flush remaining batch
-  if (currentBatch.length > 0) {
-    const memo = buildCollapsedMemo(currentBatch);
-    subtransactions.push({
-      amount: -currentBatchTotal,
-      category_id: categoryGroup.category_id,
-      memo,
-    });
-  }
-
-  return subtransactions;
-}
-
-/**
- * Truncates an item name to fit within available space
- * Preserves the amount suffix and adds "..." to indicate truncation
- */
-function truncateItemName(name: string, amountSuffix: string, maxLength: number): string {
-  const ellipsis = '...';
-  // We need: truncatedName + ellipsis + amountSuffix <= maxLength
-  const availableForName = maxLength - ellipsis.length - amountSuffix.length;
-
-  if (availableForName <= 0) {
-    // Edge case: amount suffix alone is too long, just return what we can
-    return amountSuffix.substring(0, maxLength);
-  }
-
-  return name.substring(0, availableForName) + ellipsis + amountSuffix;
-}
-
-/**
- * Builds a collapsed memo from a list of items
- * Format: "Item1 $X.XX, Item2 $Y.YY, Item3 $Z.ZZ"
- * Truncates with "..." if needed (either individual items or the list)
- */
-function buildCollapsedMemo(items: ReceiptCategoryCalculation['items'][0][]): string {
-  const parts: string[] = [];
-  let currentLength = 0;
-
-  for (let i = 0; i < items.length; i++) {
-    const item = items[i];
-    if (!item) continue;
-    const amount = milliunitsToAmount(item.amount_milliunits);
-    const amountSuffix = ` $${amount.toFixed(2)}`;
-    let itemStr = `${item.name}${amountSuffix}`;
-    const separator = i > 0 ? ', ' : '';
-
-    // For the first item, check if it alone exceeds the limit
-    if (parts.length === 0 && itemStr.length > MAX_MEMO_LENGTH) {
-      itemStr = truncateItemName(item.name, amountSuffix, MAX_MEMO_LENGTH);
-    }
-
-    const testLength = currentLength + separator.length + itemStr.length;
-
-    // Check if adding this item would exceed limit
-    if (parts.length > 0 && testLength + 4 > MAX_MEMO_LENGTH) {
-      // Would exceed - stop here and add "..."
-      break;
-    }
-
-    parts.push(itemStr);
-    currentLength = testLength;
-  }
-
-  let result = parts.join(', ');
-
-  // Add "..." if we didn't include all items
-  if (parts.length < items.length) {
-    result += '...';
-  }
-
-  return result;
-}
-
-/**
- * Allocates tax across categories
- * - Positive categories get proportional tax subtransactions
- * - Negative tax creates a single tax refund subtransaction
- */
-function allocateTax(
-  categoryCalculations: ReceiptCategoryCalculation[],
-  taxMilliunits: number,
-): SubtransactionInput[] {
-  const subtransactions: SubtransactionInput[] = [];
-
-  // Handle tax = 0
-  if (taxMilliunits === 0) {
-    return subtransactions;
-  }
-
-  // Handle negative tax (refund)
-  if (taxMilliunits < 0) {
-    // Find category with largest return
-    let largestReturnCategory: ReceiptCategoryCalculation | undefined = undefined;
-    let largestReturnAmount = 0;
-
-    for (const category of categoryCalculations) {
-      const categoryReturnAmount = category.items
-        .filter((item) => item.amount_milliunits < 0)
-        .reduce((sum, item) => sum + Math.abs(item.amount_milliunits), 0);
-
-      if (categoryReturnAmount > largestReturnAmount) {
-        largestReturnAmount = categoryReturnAmount;
-        largestReturnCategory = category;
-      }
-    }
-
-    // Default to first category if no returns found
-    if (!largestReturnCategory) {
-      largestReturnCategory = categoryCalculations[0];
-    }
-
-    if (largestReturnCategory) {
-      subtransactions.push({
-        amount: -taxMilliunits,
-        category_id: largestReturnCategory.category_id,
-        memo: 'Tax refund',
-      });
-    }
-
-    return subtransactions;
-  }
-
-  // Positive tax - allocate proportionally to positive categories only
-  const positiveCategorySubtotals = categoryCalculations
-    .map((cat) => ({
-      category: cat,
-      positiveSubtotal: cat.items
-        .filter((item) => item.amount_milliunits > 0)
-        .reduce((sum, item) => sum + item.amount_milliunits, 0),
-    }))
-    .filter((x) => x.positiveSubtotal > 0);
-
-  if (positiveCategorySubtotals.length === 0) {
-    // No positive items, no tax allocation
-    return subtransactions;
-  }
-
-  const totalPositiveSubtotal = positiveCategorySubtotals.reduce(
-    (sum, x) => sum + x.positiveSubtotal,
-    0,
-  );
-
-  // Distribute tax using largest remainder method
-  let allocatedTax = 0;
-  const taxAllocations: {
-    category: ReceiptCategoryCalculation;
-    taxAmount: number;
-  }[] = [];
-
-  for (let i = 0; i < positiveCategorySubtotals.length; i++) {
-    const entry = positiveCategorySubtotals[i];
-    if (!entry) continue;
-
-    const { category, positiveSubtotal } = entry;
-
-    if (i === positiveCategorySubtotals.length - 1) {
-      // Last category gets remainder
-      const taxAmount = taxMilliunits - allocatedTax;
-      if (taxAmount > 0) {
-        taxAllocations.push({ category, taxAmount });
-      }
-    } else {
-      const taxAmount = Math.round((taxMilliunits * positiveSubtotal) / totalPositiveSubtotal);
-      if (taxAmount > 0) {
-        taxAllocations.push({ category, taxAmount });
-        allocatedTax += taxAmount;
-      }
-    }
-  }
-
-  // Create tax subtransactions
-  for (const { category, taxAmount } of taxAllocations) {
-    subtransactions.push({
-      amount: -taxAmount,
-      category_id: category.category_id,
-      memo: `Tax - ${category.category_name ?? 'Uncategorized'}`,
-    });
-  }
-
-  return subtransactions;
-}
-
-export async function handleCreateReceiptSplitTransaction(
-  ynabAPI: ynab.API,
-  deltaCache: DeltaCache,
-  knowledgeStore: ServerKnowledgeStore,
-  params: CreateReceiptSplitTransactionParams,
-): Promise<CallToolResult>;
-export async function handleCreateReceiptSplitTransaction(
-  ynabAPI: ynab.API,
-  params: CreateReceiptSplitTransactionParams,
-): Promise<CallToolResult>;
-export async function handleCreateReceiptSplitTransaction(
-  ynabAPI: ynab.API,
-  deltaCacheOrParams: DeltaCache | CreateReceiptSplitTransactionParams,
-  knowledgeStoreOrParams?: ServerKnowledgeStore | CreateReceiptSplitTransactionParams,
-  maybeParams?: CreateReceiptSplitTransactionParams,
-): Promise<CallToolResult> {
-  const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(
-    deltaCacheOrParams,
-    knowledgeStoreOrParams,
-    maybeParams,
-  );
-  const date = params.date ?? new Date().toISOString().slice(0, 10);
-
-  const categoryCalculations: ReceiptCategoryCalculation[] = params.categories.map((category) => {
-    const items = category.items.map((item) => ({
-      name: item.name,
-      amount_milliunits: amountToMilliunits(item.amount),
-      quantity: item.quantity,
-      memo: item.memo,
-    }));
-    const subtotalMilliunits = items.reduce((sum, item) => sum + item.amount_milliunits, 0);
-    return {
-      category_id: category.category_id,
-      category_name: category.category_name,
-      subtotal_milliunits: subtotalMilliunits,
-      tax_milliunits: 0,
-      items,
-    };
-  });
-
-  const subtotalMilliunits = categoryCalculations.reduce(
-    (sum, category) => sum + category.subtotal_milliunits,
-    0,
-  );
-
-  const declaredSubtotalMilliunits =
-    params.receipt_subtotal !== undefined ? amountToMilliunits(params.receipt_subtotal) : undefined;
-  if (
-    declaredSubtotalMilliunits !== undefined &&
-    Math.abs(declaredSubtotalMilliunits - subtotalMilliunits) > 1
-  ) {
-    throw new Error(
-      `Categorized items subtotal (${milliunitsToAmount(subtotalMilliunits)}) does not match receipt subtotal (${milliunitsToAmount(declaredSubtotalMilliunits)})`,
-    );
-  }
-
-  const taxMilliunits = amountToMilliunits(params.receipt_tax);
-  const totalMilliunits = amountToMilliunits(params.receipt_total);
-  const computedTotal = subtotalMilliunits + taxMilliunits;
-  if (Math.abs(computedTotal - totalMilliunits) > 1) {
-    throw new Error(
-      `Receipt total (${milliunitsToAmount(totalMilliunits)}) does not equal subtotal plus tax (${milliunitsToAmount(computedTotal)})`,
-    );
-  }
-
-  // Apply smart collapse logic
-  const subtransactions = applySmartCollapseLogic(categoryCalculations, taxMilliunits);
-
-  // Distribute tax proportionally for receipt_summary (only for positive categories)
-  if (taxMilliunits > 0) {
-    const positiveSubtotal = categoryCalculations.reduce(
-      (sum, cat) => sum + Math.max(0, cat.subtotal_milliunits),
-      0,
-    );
-    if (positiveSubtotal > 0) {
-      let remainingTax = taxMilliunits;
-      const positiveCats = categoryCalculations.filter((cat) => cat.subtotal_milliunits > 0);
-      positiveCats.forEach((cat, index) => {
-        if (index === positiveCats.length - 1) {
-          cat.tax_milliunits = remainingTax;
-        } else {
-          const share = Math.round((cat.subtotal_milliunits / positiveSubtotal) * taxMilliunits);
-          cat.tax_milliunits = share;
-          remainingTax -= share;
-        }
-      });
-    }
-  }
-
-  const receiptSummary = {
-    subtotal: milliunitsToAmount(subtotalMilliunits),
-    tax: milliunitsToAmount(taxMilliunits),
-    total: milliunitsToAmount(totalMilliunits),
-    categories: categoryCalculations.map((category) => ({
-      category_id: category.category_id,
-      category_name: category.category_name,
-      items: category.items.map((item) => ({
-        name: item.name,
-        quantity: item.quantity,
-        amount: milliunitsToAmount(item.amount_milliunits),
-        memo: item.memo,
-      })),
-      subtotal: milliunitsToAmount(category.subtotal_milliunits),
-      tax: milliunitsToAmount(category.tax_milliunits),
-      total: milliunitsToAmount(category.subtotal_milliunits + category.tax_milliunits),
-    })),
-  };
-
-  if (params.dry_run) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: responseFormatter.format({
-            dry_run: true,
-            action: 'create_receipt_split_transaction',
-            transaction_preview: {
-              account_id: params.account_id,
-              payee_name: params.payee_name,
-              date,
-              amount: milliunitsToAmount(totalMilliunits),
-              cleared: params.cleared ?? 'uncleared',
-            },
-            receipt_summary: receiptSummary,
-            subtransactions: subtransactions.map((subtransaction) => ({
-              amount: milliunitsToAmount(-subtransaction.amount),
-              category_id: subtransaction.category_id,
-              memo: subtransaction.memo,
-            })),
-          }),
-        },
-      ],
-    };
-  }
-
-  const createTransactionParams: CreateTransactionParams = {
-    budget_id: params.budget_id,
-    account_id: params.account_id,
-    amount: -totalMilliunits,
-    date,
-    payee_name: params.payee_name,
-    memo: params.memo,
-    cleared: params.cleared ?? 'uncleared',
-    flag_color: params.flag_color,
-    subtransactions: subtransactions,
-  };
-
-  if (params.approved !== undefined) {
-    createTransactionParams.approved = params.approved;
-  }
-
-  const baseResult = await handleCreateTransaction(
-    ynabAPI,
-    deltaCache,
-    knowledgeStore,
-    createTransactionParams,
-  );
-
-  const firstContent = baseResult.content?.[0];
-  if (!firstContent || firstContent.type !== 'text') {
-    return baseResult;
-  }
-
-  try {
-    const parsed = JSON.parse(firstContent.text) as Record<string, unknown>;
-    parsed['receipt_summary'] = receiptSummary;
-    firstContent.text = responseFormatter.format(parsed);
-  } catch {
-    // If parsing fails, return the original result without augmentation.
-  }
-
-  return baseResult;
-}
-
-/**
- * Handles the ynab:update_transaction tool call
- * Updates an existing transaction with the provided fields
- */
-export async function handleUpdateTransaction(
-  ynabAPI: ynab.API,
-  deltaCache: DeltaCache,
-  knowledgeStore: ServerKnowledgeStore,
-  params: UpdateTransactionParams,
-): Promise<CallToolResult>;
-export async function handleUpdateTransaction(
-  ynabAPI: ynab.API,
-  params: UpdateTransactionParams,
-): Promise<CallToolResult>;
-export async function handleUpdateTransaction(
-  ynabAPI: ynab.API,
-  deltaCacheOrParams: DeltaCache | UpdateTransactionParams,
-  knowledgeStoreOrParams?: ServerKnowledgeStore | UpdateTransactionParams,
-  maybeParams?: UpdateTransactionParams,
-): Promise<CallToolResult> {
-  const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(
-    deltaCacheOrParams,
-    knowledgeStoreOrParams,
-    maybeParams,
-  );
-  try {
-    if (params.dry_run) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: responseFormatter.format({
-              dry_run: true,
-              action: 'update_transaction',
-              request: params,
-            }),
-          },
-        ],
-      };
-    }
-
-    // Get the original transaction before updating to capture the original account_id
-    const originalTransactionResponse = await ynabAPI.transactions.getTransactionById(
-      params.budget_id,
-      params.transaction_id,
-    );
-    const originalTransaction = ensureTransaction(
-      originalTransactionResponse.data.transaction,
-      'Original transaction not found',
-    );
-
-    // Prepare transaction update data - only include fields that are provided
-    const transactionData: SaveTransaction = {};
-
-    // Only include fields that are provided in the update
-    if (params.account_id !== undefined) {
-      transactionData.account_id = params.account_id;
-    }
-    if (params.amount !== undefined) {
-      transactionData.amount = params.amount;
-    }
-    if (params.date !== undefined) {
-      transactionData.date = params.date;
-    }
-    if (params.payee_name !== undefined) {
-      transactionData.payee_name = params.payee_name;
-    }
-    if (params.payee_id !== undefined) {
-      transactionData.payee_id = params.payee_id;
-    }
-    if (params.category_id !== undefined) {
-      transactionData.category_id = params.category_id;
-    }
-    if (params.memo !== undefined) {
-      transactionData.memo = params.memo;
-    }
-    if (params.cleared !== undefined) {
-      transactionData.cleared = params.cleared as ynab.TransactionClearedStatus;
-    }
-    if (params.approved !== undefined) {
-      transactionData.approved = params.approved;
-    }
-    if (params.flag_color !== undefined) {
-      transactionData.flag_color = params.flag_color as ynab.TransactionFlagColor;
-    }
-
-    const response = await ynabAPI.transactions.updateTransaction(
-      params.budget_id,
-      params.transaction_id,
-      {
-        transaction: transactionData,
-      },
-    );
-
-    const transaction = ensureTransaction(response.data.transaction, 'Transaction update failed');
-
-    const specificTransactionCacheKey = CacheManager.generateKey(
-      'transaction',
-      'get',
-      params.budget_id,
-      params.transaction_id,
-    );
-    cacheManager.delete(specificTransactionCacheKey);
-
-    const affectedAccountIds = new Set<string>([
-      originalTransaction.account_id,
-      transaction.account_id,
-    ]);
-
-    if (originalTransaction.transfer_account_id) {
-      affectedAccountIds.add(originalTransaction.transfer_account_id);
-    }
-    if (transaction.transfer_account_id) {
-      affectedAccountIds.add(transaction.transfer_account_id);
-    }
-
-    const affectedMonths = new Set<string>([
-      toMonthKey(originalTransaction.date),
-      toMonthKey(transaction.date),
-    ]);
-    const originalCategoryIds = collectCategoryIdsFromSources(originalTransaction);
-    const updatedCategoryIds = collectCategoryIdsFromSources(transaction);
-    const affectedCategoryIds = new Set<string>([...originalCategoryIds, ...updatedCategoryIds]);
-    const categoryChanged = !setsEqual(originalCategoryIds, updatedCategoryIds);
-    const amountChanged = transaction.amount !== originalTransaction.amount;
-    const accountChanged = transaction.account_id !== originalTransaction.account_id;
-    const clearedChanged = transaction.cleared !== originalTransaction.cleared;
-    const transferAccountChanged =
-      transaction.transfer_account_id !== originalTransaction.transfer_account_id;
-    const transferLinkChanged =
-      transaction.transfer_transaction_id !== originalTransaction.transfer_transaction_id;
-    const dateChanged = transaction.date !== originalTransaction.date;
-
-    invalidateTransactionCaches(
-      deltaCache,
-      knowledgeStore,
-      params.budget_id,
-      response.data.server_knowledge,
-      affectedAccountIds,
-      affectedMonths,
-      {
-        affectedCategoryIds,
-        accountTotalsChanged:
-          amountChanged ||
-          accountChanged ||
-          clearedChanged ||
-          transferAccountChanged ||
-          transferLinkChanged,
-        invalidateMonths: amountChanged || categoryChanged || dateChanged,
-      },
-    );
-
-    // Get the updated account balance
-    const accountResponse = await ynabAPI.accounts.getAccountById(
-      params.budget_id,
-      transaction.account_id,
-    );
-    const account = accountResponse.data.account;
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: responseFormatter.format({
-            transaction: {
-              id: transaction.id,
-              date: transaction.date,
-              amount: milliunitsToAmount(transaction.amount),
-              memo: transaction.memo,
-              cleared: transaction.cleared,
-              approved: transaction.approved,
-              flag_color: transaction.flag_color,
-              account_id: transaction.account_id,
-              payee_id: transaction.payee_id,
-              category_id: transaction.category_id,
-              transfer_account_id: transaction.transfer_account_id,
-              transfer_transaction_id: transaction.transfer_transaction_id,
-              matched_transaction_id: transaction.matched_transaction_id,
-              import_id: transaction.import_id,
-              deleted: transaction.deleted,
-            },
-            updated_balance: account.balance,
-            updated_cleared_balance: account.cleared_balance,
-          }),
-        },
-      ],
-    };
-  } catch (error) {
-    return handleTransactionError(error, 'Failed to update transaction');
-  }
-}
-
-/**
- * Handles the ynab:delete_transaction tool call
- * Deletes a transaction from the specified budget
- */
-export async function handleDeleteTransaction(
-  ynabAPI: ynab.API,
-  deltaCache: DeltaCache,
-  knowledgeStore: ServerKnowledgeStore,
-  params: DeleteTransactionParams,
-): Promise<CallToolResult>;
-export async function handleDeleteTransaction(
-  ynabAPI: ynab.API,
-  params: DeleteTransactionParams,
-): Promise<CallToolResult>;
-export async function handleDeleteTransaction(
-  ynabAPI: ynab.API,
-  deltaCacheOrParams: DeltaCache | DeleteTransactionParams,
-  knowledgeStoreOrParams?: ServerKnowledgeStore | DeleteTransactionParams,
-  maybeParams?: DeleteTransactionParams,
-): Promise<CallToolResult> {
-  const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(
-    deltaCacheOrParams,
-    knowledgeStoreOrParams,
-    maybeParams,
-  );
-  try {
-    if (params.dry_run) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: responseFormatter.format({
-              dry_run: true,
-              action: 'delete_transaction',
-              request: params,
-            }),
-          },
-        ],
-      };
-    }
-    const response = await ynabAPI.transactions.deleteTransaction(
-      params.budget_id,
-      params.transaction_id,
-    );
-
-    const transaction = ensureTransaction(response.data.transaction, 'Transaction deletion failed');
-
-    const specificTransactionCacheKey = CacheManager.generateKey(
-      'transaction',
-      'get',
-      params.budget_id,
-      params.transaction_id,
-    );
-    cacheManager.delete(specificTransactionCacheKey);
-
-    const affectedAccountIds = new Set<string>([transaction.account_id]);
-    if (transaction.transfer_account_id) {
-      affectedAccountIds.add(transaction.transfer_account_id);
-    }
-
-    const affectedMonths = new Set<string>([toMonthKey(transaction.date)]);
-    const affectedCategoryIds = collectCategoryIdsFromSources(transaction);
-    invalidateTransactionCaches(
-      deltaCache,
-      knowledgeStore,
-      params.budget_id,
-      response.data.server_knowledge,
-      affectedAccountIds,
-      affectedMonths,
-      {
-        affectedCategoryIds,
-        accountTotalsChanged: true,
-        invalidateMonths: true,
-      },
-    );
-
-    // Get the updated account balance
-    const accountResponse = await ynabAPI.accounts.getAccountById(
-      params.budget_id,
-      transaction.account_id,
-    );
-    const account = accountResponse.data.account;
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: responseFormatter.format({
-            message: 'Transaction deleted successfully',
-            transaction: {
-              id: transaction.id,
-              deleted: transaction.deleted,
-            },
-            updated_balance: account.balance,
-            updated_cleared_balance: account.cleared_balance,
-          }),
-        },
-      ],
-    };
-  } catch (error) {
-    return handleTransactionError(error, 'Failed to delete transaction');
-  }
-}
-
-export async function handleCreateTransactions(
-  ynabAPI: ynab.API,
-  deltaCache: DeltaCache,
-  knowledgeStore: ServerKnowledgeStore,
-  params: CreateTransactionsParams,
-): Promise<CallToolResult>;
-export async function handleCreateTransactions(
-  ynabAPI: ynab.API,
-  params: CreateTransactionsParams,
-): Promise<CallToolResult>;
-export async function handleCreateTransactions(
-  ynabAPI: ynab.API,
-  deltaCacheOrParams: DeltaCache | CreateTransactionsParams,
-  knowledgeStoreOrParams?: ServerKnowledgeStore | CreateTransactionsParams,
-  maybeParams?: CreateTransactionsParams,
-): Promise<CallToolResult> {
-  const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(
-    deltaCacheOrParams,
-    knowledgeStoreOrParams,
-    maybeParams,
-  );
-  return (await withToolErrorHandling(
-    async () => {
-      const validationResult = CreateTransactionsSchema.safeParse(params);
-      if (!validationResult.success) {
-        type TransactionIssueIndex = number | null;
-        const issuesByIndex = new Map<TransactionIssueIndex, string[]>();
-        const validationIssues = validationResult.error.issues ?? [];
-        for (const issue of validationIssues) {
-          const transactionIndex = issue.path.find(
-            (segment): segment is number => typeof segment === 'number',
-          );
-          const message = issue.message;
-          const issueIndex: TransactionIssueIndex =
-            transactionIndex !== undefined ? transactionIndex : null;
-          const existing = issuesByIndex.get(issueIndex) ?? [];
-          existing.push(message);
-          issuesByIndex.set(issueIndex, existing);
-        }
-
-        const details = Array.from(issuesByIndex.entries()).map(([index, errors]) => ({
-          transaction_index: index,
-          errors,
-        }));
-
-        throw new ValidationError(
-          'Bulk transaction validation failed',
-          JSON.stringify(details, null, 2),
-          ['Ensure each transaction includes required fields', 'Limit batches to 100 items'],
-        );
-      }
-
-      const { budget_id, transactions, dry_run } = validationResult.data;
-
-      // Pre-flight duplicate import_id detection within batch
-      const importIdMap = new Map<string, number[]>();
-      for (const [index, transaction] of transactions.entries()) {
-        if (transaction.import_id && transaction.import_id.trim().length > 0) {
-          const existing = importIdMap.get(transaction.import_id);
-          if (existing) {
-            existing.push(index);
-          } else {
-            importIdMap.set(transaction.import_id, [index]);
-          }
-        }
-      }
-
-      const duplicates = Array.from(importIdMap.entries())
-        .filter(([, indices]) => indices.length > 1)
-        .map(([importId, indices]) => ({ import_id: importId, indices }));
-
-      if (duplicates.length > 0) {
-        const details = duplicates.map(({ import_id, indices }) => ({
-          import_id,
-          transaction_indices: indices,
-          count: indices.length,
-        }));
-
-        throw new ValidationError(
-          'Duplicate import_id values detected within batch',
-          JSON.stringify(details, null, 2),
-          [
-            'Ensure each transaction has a unique import_id within the batch',
-            'Remove duplicate import_id values or omit import_id to use hash-based correlation',
-          ],
-        );
-      }
-
-      if (dry_run) {
-        const totalAmount = transactions.reduce((sum, transaction) => sum + transaction.amount, 0);
-        const accountsAffected = Array.from(
-          new Set(transactions.map((transaction) => transaction.account_id)),
-        );
-        const categoriesAffected = Array.from(
-          new Set(
-            transactions
-              .map((transaction) => transaction.category_id)
-              .filter((id): id is string => id !== undefined),
-          ),
-        );
-        const sortedDates = [...transactions.map((transaction) => transaction.date)].sort();
-        const dateRange =
-          sortedDates.length > 0
-            ? { earliest: sortedDates[0], latest: sortedDates[sortedDates.length - 1] }
-            : undefined;
-
-        const transactionsPreview = transactions.slice(0, 10).map((transaction, index) => ({
-          request_index: index,
-          account_id: transaction.account_id,
-          date: transaction.date,
-          amount: milliunitsToAmount(transaction.amount),
-          memo: transaction.memo,
-          payee_id: transaction.payee_id,
-          payee_name: transaction.payee_name,
-          category_id: transaction.category_id,
-          import_id: transaction.import_id,
-        }));
-
-        return {
-          content: [
-            {
-              type: 'text',
-              text: responseFormatter.format({
-                dry_run: true,
-                action: 'create_transactions',
-                validation: 'passed',
-                summary: {
-                  total_transactions: transactions.length,
-                  total_amount: milliunitsToAmount(totalAmount),
-                  accounts_affected: accountsAffected,
-                  date_range: dateRange,
-                  categories_affected: categoriesAffected,
-                },
-                transactions_preview: transactionsPreview,
-                note: 'Dry run complete. No transactions created. No caches invalidated. No server_knowledge updated.',
-              }),
-            },
-          ],
-        };
-      }
-
-      const saveTransactions: SaveTransaction[] = transactions.map((transaction) => {
-        const payload: SaveTransaction = {
-          account_id: transaction.account_id,
-          amount: transaction.amount,
-          date: transaction.date,
-        };
-
-        if (transaction.payee_id !== undefined) payload.payee_id = transaction.payee_id;
-        if (transaction.payee_name !== undefined) payload.payee_name = transaction.payee_name;
-        if (transaction.category_id !== undefined) payload.category_id = transaction.category_id;
-        if (transaction.memo !== undefined) payload.memo = transaction.memo;
-        if (transaction.cleared !== undefined) payload.cleared = transaction.cleared;
-        if (transaction.approved !== undefined) payload.approved = transaction.approved;
-        if (transaction.flag_color !== undefined) payload.flag_color = transaction.flag_color;
-        if (transaction.import_id !== undefined) payload.import_id = transaction.import_id;
-
-        return payload;
-      });
-
-      const response = await ynabAPI.transactions.createTransactions(budget_id, {
-        transactions: saveTransactions,
-      });
-
-      const responseData = response.data;
-      const duplicateImportIds = new Set(responseData.duplicate_import_ids ?? []);
-      const results = correlateResults(transactions, responseData, duplicateImportIds);
-
-      const summary = {
-        total_requested: transactions.length,
-        created: responseData.transaction_ids?.length ?? 0,
-        duplicates: duplicateImportIds.size,
-        failed: results.filter((result) => result.status === 'failed').length,
-      };
-
-      const baseResponse: BulkCreateResponse = {
-        success: summary.failed === 0,
-        server_knowledge: responseData.server_knowledge,
-        summary,
-        results,
-        transactions: responseData.transactions ?? [],
-        duplicate_import_ids: responseData.duplicate_import_ids ?? [],
-        message: `Processed ${summary.total_requested} transactions: ${summary.created} created, ${summary.duplicates} duplicates, ${summary.failed} failed.`,
-      };
-
-      const accountIds = new Set<string>(transactions.map((transaction) => transaction.account_id));
-      const affectedMonths = new Set<string>(
-        transactions.map((transaction) => toMonthKey(transaction.date)),
-      );
-      const affectedCategoryIds = new Set<string>();
-      for (const created of responseData.transactions ?? []) {
-        appendCategoryIds(created, affectedCategoryIds);
-      }
-      invalidateTransactionCaches(
-        deltaCache,
-        knowledgeStore,
-        budget_id,
-        responseData.server_knowledge,
-        accountIds,
-        affectedMonths,
-        {
-          affectedCategoryIds,
-          accountTotalsChanged: true,
-          invalidateMonths: true,
-        },
-      );
-
-      const finalizedResponse = finalizeResponse(baseResponse);
-
-      return {
-        content: [
-          {
-            type: 'text',
-            text: responseFormatter.format(finalizedResponse),
-          },
-        ],
-      };
-    },
-    'ynab:create_transactions',
-    'bulk transaction creation',
-  )) as CallToolResult;
-}
-
-/**
- * Interface for transaction metadata needed for cache invalidation
- */
-interface TransactionMetadata {
-  account_id: string;
-  date: string;
-}
-
-/**
- * Result of metadata resolution including both resolved metadata and unresolved IDs
- */
-interface MetadataResolutionResult {
-  metadata: Map<string, TransactionMetadata>;
-  unresolvedIds: string[];
-  previewDetails: Map<string, ynab.TransactionDetail>;
-}
-
-interface ResolveMetadataOptions {
-  previewTransactionIds?: string[];
-}
-
-/**
- * Resolves metadata for bulk update transactions
- * Uses a multi-tier approach: request metadata -> cache -> limited API calls
- * Returns both the resolved metadata and a list of IDs that could not be resolved
- */
-async function resolveMetadata(
-  ynabAPI: ynab.API,
-  budgetId: string,
-  transactions: BulkUpdateTransactionInput[],
-  options: ResolveMetadataOptions = {},
-): Promise<MetadataResolutionResult> {
-  const metadata = new Map<string, TransactionMetadata>();
-  const needsResolution: string[] = [];
-  const previewIds = new Set(options.previewTransactionIds ?? []);
-  const previewDetails = new Map<string, ynab.TransactionDetail>();
-  const previewIdsNeedingFetch = new Set(previewIds);
-
-  // First pass: Use provided metadata
-  for (const transaction of transactions) {
-    if (transaction.original_account_id && transaction.original_date) {
-      metadata.set(transaction.id, {
-        account_id: transaction.original_account_id,
-        date: transaction.original_date,
-      });
-    } else {
-      needsResolution.push(transaction.id);
-    }
-  }
-
-  if (previewIds.size === 0 && needsResolution.length === 0) {
-    return { metadata, unresolvedIds: [], previewDetails };
-  }
-
-  // Second pass: hydrate from cache for both metadata needs and preview requests
-  const needsResolutionSet = new Set(needsResolution);
-  const cacheLookupIds = new Set<string>([...needsResolution, ...previewIds]);
-  for (const transactionId of cacheLookupIds) {
-    const cacheKey = CacheManager.generateKey('transaction', 'get', budgetId, transactionId);
-    const cached = cacheManager.get<ynab.TransactionDetail>(cacheKey);
-    if (!cached) {
-      continue;
-    }
-
-    if (needsResolutionSet.has(transactionId)) {
-      metadata.set(transactionId, {
-        account_id: cached.account_id,
-        date: cached.date,
-      });
-      needsResolutionSet.delete(transactionId);
-    }
-    if (previewIds.has(transactionId) && !previewDetails.has(transactionId)) {
-      previewDetails.set(transactionId, cached);
-      previewIdsNeedingFetch.delete(transactionId);
-    }
-  }
-
-  const stillNeedsResolution = Array.from(needsResolutionSet);
-  if (stillNeedsResolution.length === 0 && previewIdsNeedingFetch.size === 0) {
-    return { metadata, unresolvedIds: [], previewDetails };
-  }
-
-  // Third pass: Limited API calls with concurrency limit
-  const MAX_CONCURRENT_FETCHES = 5;
-  const fetchPromises: Promise<void>[] = [];
-  const metadataAwaitingResolution = new Set(stillNeedsResolution);
-  const idsNeedingApiFetch = Array.from(
-    new Set([...stillNeedsResolution, ...previewIdsNeedingFetch]),
-  );
-
-  for (let i = 0; i < idsNeedingApiFetch.length; i += MAX_CONCURRENT_FETCHES) {
-    const batch = idsNeedingApiFetch.slice(i, i + MAX_CONCURRENT_FETCHES);
-    const batchPromises = batch.map(async (transactionId) => {
-      try {
-        const response = await ynabAPI.transactions.getTransactionById(budgetId, transactionId);
-        const transaction = response.data.transaction;
-        if (transaction) {
-          if (metadataAwaitingResolution.has(transactionId)) {
-            metadata.set(transactionId, {
-              account_id: transaction.account_id,
-              date: transaction.date,
-            });
-            metadataAwaitingResolution.delete(transactionId);
-          }
-          if (previewIdsNeedingFetch.has(transactionId) && !previewDetails.has(transactionId)) {
-            previewDetails.set(transactionId, transaction);
-            previewIdsNeedingFetch.delete(transactionId);
-          }
-        }
-      } catch {
-        if (metadataAwaitingResolution.has(transactionId)) {
-          globalRequestLogger.logError(
-            'ynab:update_transactions',
-            'resolve_metadata',
-            { transaction_id: transactionId },
-            'Failed to resolve transaction metadata',
-          );
-        }
-      }
-    });
-    fetchPromises.push(...batchPromises);
-  }
-
-  await Promise.all(fetchPromises);
-  return { metadata, unresolvedIds: Array.from(metadataAwaitingResolution), previewDetails };
-}
-
-/**
- * Finalizes bulk update response based on size constraints
- */
-function finalizeBulkUpdateResponse(response: BulkUpdateResponse): BulkUpdateResponse {
-  const appendMessage = (message: string | undefined, addition: string): string => {
-    if (!message) {
-      return addition;
-    }
-    if (message.includes(addition)) {
-      return message;
-    }
-    return `${message} ${addition}`;
-  };
-
-  const fullSize = estimatePayloadSize(response);
-  if (fullSize <= FULL_RESPONSE_THRESHOLD) {
-    return { ...response, mode: 'full' };
-  }
-
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  const { transactions, ...summaryResponse } = response;
-  const summaryPayload: BulkUpdateResponse = {
-    ...summaryResponse,
-    message: appendMessage(
-      response.message,
-      'Response downgraded to summary to stay under size limits.',
-    ),
-    mode: 'summary',
-  };
-
-  if (estimatePayloadSize(summaryPayload) <= SUMMARY_RESPONSE_THRESHOLD) {
-    return summaryPayload;
-  }
-
-  const idsOnlyPayload: BulkUpdateResponse = {
-    ...summaryPayload,
-    results: summaryResponse.results.map((result) => {
-      const simplified: BulkUpdateResult = {
-        request_index: result.request_index,
-        status: result.status,
-        transaction_id: result.transaction_id,
-        correlation_key: result.correlation_key,
-      };
-      if (result.error) {
-        simplified.error = result.error;
-      }
-      if (result.error_code) {
-        simplified.error_code = result.error_code;
-      }
-      return simplified;
-    }),
-    message: appendMessage(
-      summaryResponse.message,
-      'Response downgraded to ids_only to meet 100KB limit.',
-    ),
-    mode: 'ids_only',
-  };
-
-  if (estimatePayloadSize(idsOnlyPayload) <= MAX_RESPONSE_BYTES) {
-    return idsOnlyPayload;
-  }
-
-  throw new ValidationError(
-    'RESPONSE_TOO_LARGE: Unable to format bulk update response within 100KB limit',
-    `Batch size: ${response.summary.total_requested} transactions`,
-    ['Reduce the batch size and retry', 'Consider splitting into multiple smaller batches'],
-  );
-}
-
-/**
- * Handles the ynab:update_transactions tool call
- * Updates multiple transactions in a single batch operation
- */
-export async function handleUpdateTransactions(
-  ynabAPI: ynab.API,
-  deltaCache: DeltaCache,
-  knowledgeStore: ServerKnowledgeStore,
-  params: UpdateTransactionsParams,
-): Promise<CallToolResult>;
-export async function handleUpdateTransactions(
-  ynabAPI: ynab.API,
-  params: UpdateTransactionsParams,
-): Promise<CallToolResult>;
-export async function handleUpdateTransactions(
-  ynabAPI: ynab.API,
-  deltaCacheOrParams: DeltaCache | UpdateTransactionsParams,
-  knowledgeStoreOrParams?: ServerKnowledgeStore | UpdateTransactionsParams,
-  maybeParams?: UpdateTransactionsParams,
-): Promise<CallToolResult> {
-  const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(
-    deltaCacheOrParams,
-    knowledgeStoreOrParams,
-    maybeParams,
-  );
-  return (await withToolErrorHandling(
-    async () => {
-      const validationResult = UpdateTransactionsSchema.safeParse(params);
-      if (!validationResult.success) {
-        type TransactionIssueIndex = number | null;
-        const issuesByIndex = new Map<TransactionIssueIndex, string[]>();
-        const validationIssues = validationResult.error.issues ?? [];
-        for (const issue of validationIssues) {
-          const transactionIndex = issue.path.find(
-            (segment): segment is number => typeof segment === 'number',
-          );
-          const message = issue.message;
-          const issueIndex: TransactionIssueIndex =
-            transactionIndex !== undefined ? transactionIndex : null;
-          const existing = issuesByIndex.get(issueIndex) ?? [];
-          existing.push(message);
-          issuesByIndex.set(issueIndex, existing);
-        }
-
-        const details = Array.from(issuesByIndex.entries()).map(([index, errors]) => ({
-          transaction_index: index,
-          errors,
-        }));
-
-        throw new ValidationError(
-          'Bulk transaction update validation failed',
-          JSON.stringify(details, null, 2),
-          ['Ensure each transaction includes an id field', 'Limit batches to 100 items'],
-        );
-      }
-
-      const { budget_id, transactions, dry_run } = validationResult.data;
-
-      if (dry_run) {
-        const previewTransactions = transactions.slice(0, 10);
-        const previewTransactionIds = previewTransactions.map((transaction) => transaction.id);
-        // Resolve metadata once and reuse any transaction details for preview rendering
-        const { metadata, unresolvedIds, previewDetails } = await resolveMetadata(
-          ynabAPI,
-          budget_id,
-          transactions,
-          {
-            previewTransactionIds,
-          },
-        );
-
-        const transactionsPreview = [];
-        const unavailablePreviewIds: string[] = [];
-
-        for (const transaction of previewTransactions) {
-          const currentState = previewDetails.get(transaction.id);
-          if (!currentState) {
-            unavailablePreviewIds.push(transaction.id);
-            transactionsPreview.push({
-              transaction_id: transaction.id,
-              before: 'unavailable',
-              after: transaction,
-            });
-            continue;
-          }
-
-          const before: Record<string, unknown> = {};
-          const after: Record<string, unknown> = {};
-
-          if (transaction.amount !== undefined && transaction.amount !== currentState.amount) {
-            before['amount'] = milliunitsToAmount(currentState.amount);
-            after['amount'] = milliunitsToAmount(transaction.amount);
-          }
-          if (transaction.date !== undefined && transaction.date !== currentState.date) {
-            before['date'] = currentState.date;
-            after['date'] = transaction.date;
-          }
-          if (transaction.memo !== undefined && transaction.memo !== currentState.memo) {
-            before['memo'] = currentState.memo;
-            after['memo'] = transaction.memo;
-          }
-          if (
-            transaction.payee_id !== undefined &&
-            transaction.payee_id !== currentState.payee_id
-          ) {
-            before['payee_id'] = currentState.payee_id;
-            after['payee_id'] = transaction.payee_id;
-          }
-          if (
-            transaction.payee_name !== undefined &&
-            transaction.payee_name !== currentState.payee_name
-          ) {
-            before['payee_name'] = currentState.payee_name;
-            after['payee_name'] = transaction.payee_name;
-          }
-          if (
-            transaction.category_id !== undefined &&
-            transaction.category_id !== currentState.category_id
-          ) {
-            before['category_id'] = currentState.category_id;
-            after['category_id'] = transaction.category_id;
-          }
-          if (transaction.cleared !== undefined && transaction.cleared !== currentState.cleared) {
-            before['cleared'] = currentState.cleared;
-            after['cleared'] = transaction.cleared;
-          }
-          if (
-            transaction.approved !== undefined &&
-            transaction.approved !== currentState.approved
-          ) {
-            before['approved'] = currentState.approved;
-            after['approved'] = transaction.approved;
-          }
-          if (
-            transaction.flag_color !== undefined &&
-            transaction.flag_color !== currentState.flag_color
-          ) {
-            before['flag_color'] = currentState.flag_color;
-            after['flag_color'] = transaction.flag_color;
-          }
-
-          transactionsPreview.push({
-            transaction_id: transaction.id,
-            before,
-            after,
-          });
-        }
-
-        // Build warnings array
-        const warnings: { code: string; count: number; message: string; sample_ids?: string[] }[] =
-          [];
-        if (unavailablePreviewIds.length > 0 || unresolvedIds.length > 0) {
-          const totalMissing = Math.max(unavailablePreviewIds.length, unresolvedIds.length);
-          const sampleIds =
-            unresolvedIds.length > 0
-              ? unresolvedIds.slice(0, 10)
-              : unavailablePreviewIds.slice(0, 10);
-          warnings.push({
-            code: 'metadata_unavailable',
-            count: totalMissing,
-            message: `Unable to fetch prior state for ${totalMissing} transactions`,
-            sample_ids: sampleIds,
-          });
-        }
-
-        // Collect summary statistics
-        const accountsAffected = Array.from(
-          new Set(Array.from(metadata.values()).map((m) => m.account_id)),
-        );
-        const fieldsToUpdate = new Set<string>();
-        for (const transaction of transactions) {
-          if (transaction.amount !== undefined) fieldsToUpdate.add('amount');
-          if (transaction.date !== undefined) fieldsToUpdate.add('date');
-          if (transaction.memo !== undefined) fieldsToUpdate.add('memo');
-          if (transaction.payee_id !== undefined) fieldsToUpdate.add('payee_id');
-          if (transaction.payee_name !== undefined) fieldsToUpdate.add('payee_name');
-          if (transaction.category_id !== undefined) fieldsToUpdate.add('category_id');
-          if (transaction.cleared !== undefined) fieldsToUpdate.add('cleared');
-          if (transaction.approved !== undefined) fieldsToUpdate.add('approved');
-          if (transaction.flag_color !== undefined) fieldsToUpdate.add('flag_color');
-        }
-
-        const response: Record<string, unknown> = {
-          dry_run: true,
-          action: 'update_transactions',
-          validation: 'passed',
-          summary: {
-            total_transactions: transactions.length,
-            accounts_affected: accountsAffected,
-            fields_to_update: Array.from(fieldsToUpdate),
-          },
-          transactions_preview: transactionsPreview,
-          note: 'Dry run complete. No transactions updated. No caches invalidated. No server_knowledge updated.',
-        };
-
-        if (warnings.length > 0) {
-          response['warnings'] = warnings;
-        }
-
-        return {
-          content: [
-            {
-              type: 'text',
-              text: responseFormatter.format(response),
-            },
-          ],
-        };
-      }
-
-      // Resolve metadata for cache invalidation before making updates
-      const { metadata, unresolvedIds } = await resolveMetadata(ynabAPI, budget_id, transactions);
-
-      // Check metadata completeness threshold (5%)
-      const missingMetadataRatio = unresolvedIds.length / transactions.length;
-      const METADATA_THRESHOLD = 0.05; // 5%
-
-      if (missingMetadataRatio > METADATA_THRESHOLD) {
-        throw new ValidationError(
-          `METADATA_INCOMPLETE: ${(missingMetadataRatio * 100).toFixed(1)}% of transactions have missing metadata (threshold: ${(METADATA_THRESHOLD * 100).toFixed(0)}%)`,
-          JSON.stringify(
-            {
-              unresolved_count: unresolvedIds.length,
-              total_transactions: transactions.length,
-              ratio: (missingMetadataRatio * 100).toFixed(1) + '%',
-              threshold: (METADATA_THRESHOLD * 100).toFixed(0) + '%',
-              sample_unresolved_ids: unresolvedIds.slice(0, 5),
-            },
-            null,
-            2,
-          ),
-          [
-            'Provide original_account_id and original_date for all transactions being updated',
-            'Ensure transactions exist in YNAB before updating them',
-          ],
-        );
-      }
-
-      if (missingMetadataRatio > 0.01) {
-        globalRequestLogger.logRequest(
-          'ynab:update_transactions',
-          'metadata_resolution_warning',
-          {
-            unresolved_count: unresolvedIds.length,
-            total_transactions: transactions.length,
-            ratio: missingMetadataRatio.toFixed(3),
-            sample_ids: unresolvedIds.slice(0, 5),
-            message: 'Metadata resolution incomplete for some transactions',
-          },
-          true,
-        );
-      }
-
-      // Prepare update transactions for the YNAB API
-      const updateTransactions: { id: string; transaction: SaveTransaction }[] = transactions.map(
-        (transaction) => {
-          const transactionData: SaveTransaction = {};
-
-          // Note: account_id is intentionally excluded as account moves are not supported
-          if (transaction.amount !== undefined) {
-            transactionData.amount = transaction.amount;
-          }
-          if (transaction.date !== undefined) {
-            transactionData.date = transaction.date;
-          }
-          if (transaction.payee_name !== undefined) {
-            transactionData.payee_name = transaction.payee_name;
-          }
-          if (transaction.payee_id !== undefined) {
-            transactionData.payee_id = transaction.payee_id;
-          }
-          if (transaction.category_id !== undefined) {
-            transactionData.category_id = transaction.category_id;
-          }
-          if (transaction.memo !== undefined) {
-            transactionData.memo = transaction.memo;
-          }
-          if (transaction.cleared !== undefined) {
-            transactionData.cleared = transaction.cleared as ynab.TransactionClearedStatus;
-          }
-          if (transaction.approved !== undefined) {
-            transactionData.approved = transaction.approved;
-          }
-          if (transaction.flag_color !== undefined) {
-            transactionData.flag_color = transaction.flag_color as ynab.TransactionFlagColor;
-          }
-
-          return {
-            id: transaction.id,
-            transaction: transactionData,
-          };
-        },
-      );
-
-      // Execute bulk update
-      const response = await ynabAPI.transactions.updateTransactions(budget_id, {
-        transactions: updateTransactions,
-      });
-
-      const responseData = response.data;
-      const updatedTransactions = responseData.transactions ?? [];
-
-      // Build results
-      const results: BulkUpdateResult[] = [];
-      const updatedIds = new Set(updatedTransactions.map((t) => t.id));
-
-      for (const [index, transaction] of transactions.entries()) {
-        if (updatedIds.has(transaction.id)) {
-          results.push({
-            request_index: index,
-            status: 'updated',
-            transaction_id: transaction.id,
-            correlation_key: transaction.id,
-          });
-        } else {
-          results.push({
-            request_index: index,
-            status: 'failed',
-            transaction_id: transaction.id,
-            correlation_key: transaction.id,
-            error_code: 'update_failed',
-            error: 'Transaction was not updated by YNAB API',
-          });
-        }
-      }
-
-      const summary = {
-        total_requested: transactions.length,
-        updated: updatedTransactions.length,
-        failed: results.filter((r) => r.status === 'failed').length,
-      };
-
-      const baseResponse: BulkUpdateResponse = {
-        success: summary.failed === 0,
-        server_knowledge: responseData.server_knowledge,
-        summary,
-        results,
-        transactions: updatedTransactions,
-        message: `Processed ${summary.total_requested} transactions: ${summary.updated} updated, ${summary.failed} failed.`,
-      };
-
-      for (const transaction of transactions) {
-        cacheManager.delete(
-          CacheManager.generateKey('transaction', 'get', budget_id, transaction.id),
-        );
-      }
-
-      const affectedAccountIds = new Set<string>();
-      const affectedMonthKeys = new Set<string>();
-      const affectedCategoryIds = new Set<string>();
-      let invalidateAllCategories = false;
-      let accountTotalsChanged = false;
-      let monthsImpacted = false;
-
-      for (const transaction of transactions) {
-        const meta = metadata.get(transaction.id);
-        const amountChanged = transaction.amount !== undefined;
-        const clearedChanged = transaction.cleared !== undefined;
-        const categoryChanged = transaction.category_id !== undefined;
-        const dateChanged = transaction.date !== undefined;
-
-        if ((amountChanged || clearedChanged) && meta) {
-          affectedAccountIds.add(meta.account_id);
-        }
-
-        if (amountChanged) {
-          monthsImpacted = true;
-          accountTotalsChanged = true;
-          invalidateAllCategories = true;
-          if (meta) {
-            affectedMonthKeys.add(toMonthKey(meta.date));
-          }
-        }
-
-        if (categoryChanged) {
-          monthsImpacted = true;
-          invalidateAllCategories = true;
-          if (transaction.category_id) {
-            affectedCategoryIds.add(transaction.category_id);
-          }
-          if (meta) {
-            affectedMonthKeys.add(toMonthKey(meta.date));
-          }
-        }
-
-        if (dateChanged && meta) {
-          monthsImpacted = true;
-          affectedMonthKeys.add(toMonthKey(meta.date));
-        }
-        if (dateChanged && transaction.date) {
-          affectedMonthKeys.add(toMonthKey(transaction.date));
-        }
-      }
-
-      invalidateTransactionCaches(
-        deltaCache,
-        knowledgeStore,
-        budget_id,
-        responseData.server_knowledge,
-        affectedAccountIds,
-        affectedMonthKeys,
-        {
-          affectedCategoryIds,
-          invalidateAllCategories,
-          accountTotalsChanged,
-          invalidateMonths: monthsImpacted,
-        },
-      );
-
-      const finalizedResponse = finalizeBulkUpdateResponse(baseResponse);
-
-      return {
-        content: [
-          {
-            type: 'text',
-            text: responseFormatter.format(finalizedResponse),
-          },
-        ],
-      };
-    },
-    'ynab:update_transactions',
-    'bulk transaction update',
-  )) as CallToolResult;
-}
-
-/**
- * Handles errors from transaction-related API calls
- */
-function handleTransactionError(error: unknown, defaultMessage: string): CallToolResult {
-  let errorMessage = defaultMessage;
-
-  if (error instanceof Error) {
-    if (error.message.includes('401') || error.message.includes('Unauthorized')) {
-      errorMessage = 'Invalid or expired YNAB access token';
-    } else if (error.message.includes('403') || error.message.includes('Forbidden')) {
-      errorMessage = 'Insufficient permissions to access YNAB data';
-    } else if (error.message.includes('404') || error.message.includes('Not Found')) {
-      errorMessage = 'Budget, account, category, or transaction not found';
-    } else if (error.message.includes('429') || error.message.includes('Too Many Requests')) {
-      errorMessage = 'Rate limit exceeded. Please try again later';
-    } else if (error.message.includes('500') || error.message.includes('Internal Server Error')) {
-      errorMessage = 'YNAB service is currently unavailable';
-    }
-  }
-
-  return {
-    content: [
-      {
-        type: 'text',
-        text: responseFormatter.format({
-          error: {
-            message: errorMessage,
-          },
-        }),
-      },
-    ],
-  };
-}
-
-/**
- * Registers transaction-domain tools with the provided registry.
+ * Transaction Tools - Facade Module
+ *
+ * This module delegates to:
+ * - transactionReadTools.ts  — read-only handlers (list, get, export)
+ * - transactionWriteTools.ts — write handlers (create, update, delete)
+ *
+ * Schemas and types live in transactionSchemas.ts.
+ * Utility functions live in transactionUtils.ts.
+ */
+
+import type { ToolFactory } from "../types/toolRegistration.js";
+import {
+	handleGetTransaction,
+	handleListTransactions,
+	registerTransactionReadTools,
+} from "./transactionReadTools.js";
+import {
+	handleCreateReceiptSplitTransaction,
+	handleCreateTransaction,
+	handleCreateTransactions,
+	handleDeleteTransaction,
+	handleUpdateTransaction,
+	handleUpdateTransactions,
+	registerTransactionWriteTools,
+} from "./transactionWriteTools.js";
+
+// ============================================================================
+// Registration facade — called by YNABMCPServer.setupToolRegistry()
+// ============================================================================
+
+/**
+ * Registers all transaction-domain tools with the provided registry.
  */
 export const registerTransactionTools: ToolFactory = (registry, context) => {
-  const { adapt, adaptWithDelta, adaptWrite } = createAdapters(context);
-  const budgetResolver = createBudgetResolver(context);
-
-  registry.register({
-    name: 'list_transactions',
-    description: 'List transactions for a budget with optional filtering',
-    inputSchema: ListTransactionsSchema,
-    handler: adaptWithDelta(handleListTransactions),
-    defaultArgumentResolver: budgetResolver<z.infer<typeof ListTransactionsSchema>>(),
-    metadata: {
-      annotations: {
-        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
-        title: 'YNAB: List Transactions',
-      },
-    },
-  });
-
-  registry.register({
-    name: 'export_transactions',
-    description: 'Export all transactions to a JSON file with descriptive filename',
-    inputSchema: ExportTransactionsSchema,
-    handler: adapt(handleExportTransactions),
-    defaultArgumentResolver: budgetResolver<z.infer<typeof ExportTransactionsSchema>>(),
-    metadata: {
-      annotations: {
-        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
-        title: 'YNAB: Export Transactions',
-      },
-    },
-  });
-
-  registry.register({
-    name: 'get_transaction',
-    description: 'Get detailed information for a specific transaction',
-    inputSchema: GetTransactionSchema,
-    handler: adapt(handleGetTransaction),
-    defaultArgumentResolver: budgetResolver<z.infer<typeof GetTransactionSchema>>(),
-    metadata: {
-      annotations: {
-        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
-        title: 'YNAB: Get Transaction Details',
-      },
-    },
-  });
-
-  registry.register({
-    name: 'create_transaction',
-    description: 'Create a new transaction in the specified budget and account',
-    inputSchema: CreateTransactionSchema,
-    handler: adaptWrite(handleCreateTransaction),
-    defaultArgumentResolver: budgetResolver<z.infer<typeof CreateTransactionSchema>>(),
-    metadata: {
-      annotations: {
-        ...ToolAnnotationPresets.WRITE_EXTERNAL_CREATE,
-        title: 'YNAB: Create Transaction',
-      },
-    },
-  });
-
-  registry.register({
-    name: 'create_transactions',
-    description:
-      'Create multiple transactions in a single batch (1-100 items) with duplicate detection, dry-run validation, and automatic response size management with correlation metadata.',
-    inputSchema: CreateTransactionsSchema,
-    handler: adaptWrite(handleCreateTransactions),
-    defaultArgumentResolver: budgetResolver<z.infer<typeof CreateTransactionsSchema>>(),
-    metadata: {
-      annotations: {
-        ...ToolAnnotationPresets.WRITE_EXTERNAL_CREATE,
-        title: 'YNAB: Create Multiple Transactions',
-      },
-    },
-  });
-
-  registry.register({
-    name: 'create_receipt_split_transaction',
-    description: 'Create a split transaction from receipt items with proportional tax allocation',
-    inputSchema: CreateReceiptSplitTransactionSchema,
-    handler: adaptWrite(handleCreateReceiptSplitTransaction),
-    defaultArgumentResolver: budgetResolver<z.infer<typeof CreateReceiptSplitTransactionSchema>>(),
-    metadata: {
-      annotations: {
-        ...ToolAnnotationPresets.WRITE_EXTERNAL_CREATE,
-        title: 'YNAB: Create Split Transaction from Receipt',
-      },
-    },
-  });
-
-  registry.register({
-    name: 'update_transaction',
-    description: 'Update an existing transaction',
-    inputSchema: UpdateTransactionSchema,
-    handler: adaptWrite(handleUpdateTransaction),
-    defaultArgumentResolver: budgetResolver<z.infer<typeof UpdateTransactionSchema>>(),
-    metadata: {
-      annotations: {
-        ...ToolAnnotationPresets.WRITE_EXTERNAL_UPDATE,
-        title: 'YNAB: Update Transaction',
-      },
-    },
-  });
-
-  registry.register({
-    name: 'update_transactions',
-    description:
-      'Update multiple transactions in a single batch (1-100 items) with dry-run validation, automatic cache invalidation, and response size management. Supports optional original_account_id and original_date metadata for efficient cache invalidation.',
-    inputSchema: UpdateTransactionsSchema,
-    handler: adaptWrite(handleUpdateTransactions),
-    defaultArgumentResolver: budgetResolver<z.infer<typeof UpdateTransactionsSchema>>(),
-    metadata: {
-      annotations: {
-        ...ToolAnnotationPresets.WRITE_EXTERNAL_UPDATE,
-        title: 'YNAB: Update Multiple Transactions',
-      },
-    },
-  });
+	registerTransactionReadTools(registry, context);
+	registerTransactionWriteTools(registry, context);
+};
 
-  registry.register({
-    name: 'delete_transaction',
-    description: 'Delete a transaction from the specified budget',
-    inputSchema: DeleteTransactionSchema,
-    handler: adaptWrite(handleDeleteTransaction),
-    defaultArgumentResolver: budgetResolver<z.infer<typeof DeleteTransactionSchema>>(),
-    metadata: {
-      annotations: {
-        ...ToolAnnotationPresets.WRITE_EXTERNAL_DELETE,
-        title: 'YNAB: Delete Transaction',
-      },
-    },
-  });
+// ============================================================================
+// Re-export handler functions for consumers
+// ============================================================================
+
+export {
+	handleListTransactions,
+	handleGetTransaction,
+	handleCreateTransaction,
+	handleCreateReceiptSplitTransaction,
+	handleUpdateTransaction,
+	handleDeleteTransaction,
+	handleCreateTransactions,
+	handleUpdateTransactions,
 };
+
+// ============================================================================
+// Re-exports for backward compatibility
+// ============================================================================
+
+/**
+ * Re-export schemas and types from transactionSchemas.ts
+ * These exports maintain backward compatibility for code that imports directly from transactionTools.ts
+ */
+export {
+	ListTransactionsSchema,
+	type ListTransactionsParams,
+	GetTransactionSchema,
+	type GetTransactionParams,
+	CreateTransactionSchema,
+	type CreateTransactionParams,
+	CreateTransactionsSchema,
+	type CreateTransactionsParams,
+	CreateReceiptSplitTransactionSchema,
+	type CreateReceiptSplitTransactionParams,
+	UpdateTransactionSchema,
+	type UpdateTransactionParams,
+	UpdateTransactionsSchema,
+	type UpdateTransactionsParams,
+	type BulkUpdateTransactionInput,
+	DeleteTransactionSchema,
+	type DeleteTransactionParams,
+	type BulkTransactionResult,
+	type BulkCreateResponse,
+	type BulkUpdateResult,
+	type BulkUpdateResponse,
+	type CorrelationPayload,
+	type CorrelationPayloadInput,
+	type CategorySource,
+	type TransactionCacheInvalidationOptions,
+	type ReceiptCategoryCalculation,
+	type SubtransactionInput,
+	type BulkTransactionInput,
+} from "./transactionSchemas.js";
+
+/**
+ * Re-export utility functions from transactionUtils.ts
+ * These exports maintain backward compatibility for code that imports directly from transactionTools.ts
+ */
+export {
+	generateCorrelationKey,
+	toCorrelationPayload,
+	correlateResults,
+	estimatePayloadSize,
+	finalizeResponse,
+	finalizeBulkUpdateResponse,
+	handleTransactionError,
+	toMonthKey,
+	ensureTransaction,
+	appendCategoryIds,
+	collectCategoryIdsFromSources,
+	setsEqual,
+	invalidateTransactionCaches,
+} from "./transactionUtils.js";