@dizzlkheinz/ynab-mcpb 0.12.1

package/src/tools/schemas/outputs/reconciliationOutputs.ts

@@ -0,0 +1,796 @@
+/**
+ * @fileoverview Reconciliation analysis output schemas for YNAB MCP server.
+ * Defines Zod validation schemas for account reconciliation including transaction matching,
+ * balance verification, insights, actionable recommendations, and optional execution results.
+ *
+ * @see src/tools/reconciliation/index.ts - Main reconciliation handler (lines 147-362)
+ * @see src/tools/reconciliation/types.ts - Type definitions for reconciliation entities
+ * @see src/tools/reconciliation/executor.ts - Execution engine for auto-applying recommendations
+ * @see src/tools/reconcileAdapter.ts - Adapter for building reconciliation payloads
+ * @see src/utils/money.ts - Money value formatting utilities
+ *
+ * @example
+ * // Human-readable narrative only (default)
+ * {
+ *   human: "Successfully matched 45 of 50 bank transactions. Found 3 suggested matches..."
+ * }
+ *
+ * @example
+ * // With structured data (include_structured_data=true)
+ * {
+ *   human: "Successfully matched 45 of 50 bank transactions...",
+ *   structured: {
+ *     success: true,
+ *     phase: "analysis",
+ *     summary: {
+ *       statement_date_range: "2025-10-01 to 2025-10-31",
+ *       bank_transactions_count: 50,
+ *       ynab_transactions_count: 52,
+ *       auto_matched: 45,
+ *       suggested_matches: 3,
+ *       unmatched_bank: 2,
+ *       unmatched_ynab: 4,
+ *       discrepancy: { amount: -25.50, currency: "USD", formatted: "-$25.50" }
+ *     },
+ *     balance_info: {
+ *       current_cleared: { amount: 1250.00, currency: "USD", formatted: "$1,250.00" },
+ *       target_statement: { amount: 1275.50, currency: "USD", formatted: "$1,275.50" },
+ *       discrepancy: { amount: -25.50, currency: "USD", formatted: "-$25.50" },
+ *       on_track: false
+ *     },
+ *     recommendations: [...],
+ *     audit_metadata: { data_freshness: "real-time", ... }
+ *   }
+ * }
+ */
+
+import { z } from 'zod';
+
+// ============================================================================
+// NESTED SCHEMAS FOR COMPOSITION
+// ============================================================================
+
+/**
+ * Structured monetary value with formatting.
+ * Used throughout reconciliation for balances and discrepancies.
+ *
+ * @see src/utils/money.ts - MoneyValue type definition
+ */
+export const MoneyValueSchema = z.object({
+  amount: z.number().finite(),
+  currency: z.string(),
+  formatted: z.string(),
+  memo: z.string().optional(),
+});
+
+export type MoneyValue = z.infer<typeof MoneyValueSchema>;
+
+/**
+ * ISO 8601 date string with calendar validation.
+ * Ensures dates are in YYYY-MM-DD format and represent valid calendar dates.
+ *
+ * @remarks
+ * This schema validates both format (regex) and calendar validity (refinement).
+ * It catches invalid dates like "2025-02-31" which Date.parse might coerce to "2025-03-03".
+ *
+ * @example
+ * ```typescript
+ * IsoDateWithCalendarValidationSchema.parse("2025-01-15"); // ✓ Valid
+ * IsoDateWithCalendarValidationSchema.parse("2025-02-31"); // ✗ Invalid (no Feb 31st)
+ * IsoDateWithCalendarValidationSchema.parse("2025-13-01"); // ✗ Invalid (month > 12)
+ * IsoDateWithCalendarValidationSchema.parse("2025-1-15");  // ✗ Invalid (must be zero-padded)
+ * ```
+ */
+export const IsoDateWithCalendarValidationSchema = z
+  .string()
+  .regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in ISO format (YYYY-MM-DD)')
+  .refine(
+    (dateStr) => {
+      const parsed = Date.parse(dateStr);
+      if (isNaN(parsed)) {
+        return false;
+      }
+      // Verify that the parsed date components match the original string
+      // This catches cases like "2025-02-31" which Date.parse might coerce to "2025-03-03"
+      const date = new Date(parsed);
+      const year = date.getUTCFullYear();
+      const month = String(date.getUTCMonth() + 1).padStart(2, '0');
+      const day = String(date.getUTCDate()).padStart(2, '0');
+      const reconstructed = `${year}-${month}-${day}`;
+      return reconstructed === dateStr;
+    },
+    {
+      message: 'Invalid calendar date (e.g., month must be 01-12, day must be valid for the month)',
+    },
+  );
+
+/**
+ * Bank transaction from CSV import (output format with money formatting).
+ * Represents a single transaction from the user's bank statement.
+ *
+ * @remarks
+ * The adapter adds `amount_money` field with formatted money value.
+ * Date field is always serialized as an ISO 8601 date string (YYYY-MM-DD) in tool output,
+ * even though the internal type may use Date objects during analysis.
+ *
+ * @see src/tools/reconciliation/types.ts - BankTransaction interface (internal type)
+ * @see src/tools/reconcileAdapter.ts:77-80 - toBankTransactionView function
+ */
+export const BankTransactionSchema = z.object({
+  id: z.string().uuid(),
+  date: IsoDateWithCalendarValidationSchema,
+  amount: z.number(),
+  payee: z.string(),
+  memo: z.string().optional(),
+  original_csv_row: z.number(),
+  amount_money: MoneyValueSchema, // Added by adapter
+});
+
+export type BankTransaction = z.infer<typeof BankTransactionSchema>;
+
+/**
+ * Simplified YNAB transaction for reconciliation matching (output format with money formatting).
+ * Contains essential fields for transaction comparison.
+ *
+ * @remarks
+ * The adapter adds `amount_money` field with formatted money value.
+ * Date field is always serialized as an ISO 8601 date string (YYYY-MM-DD) in tool output,
+ * even though the internal type may use Date objects during analysis.
+ *
+ * @see src/tools/reconciliation/types.ts - YNABTransaction interface (internal type)
+ * @see src/tools/reconcileAdapter.ts:82-85 - toYNABTransactionView function
+ */
+export const YNABTransactionSimpleSchema = z.object({
+  id: z.string(),
+  date: IsoDateWithCalendarValidationSchema,
+  amount: z.number(),
+  payee_name: z.string().nullable(),
+  category_name: z.string().nullable(),
+  cleared: z.enum(['cleared', 'uncleared', 'reconciled']),
+  approved: z.boolean(),
+  memo: z.string().nullable().optional(),
+  amount_money: MoneyValueSchema, // Added by adapter
+});
+
+export type YNABTransactionSimple = z.infer<typeof YNABTransactionSimpleSchema>;
+
+/**
+ * Potential match candidate with confidence scoring.
+ * Represents a possible match between bank and YNAB transactions.
+ *
+ * @see src/tools/reconciliation/types.ts - MatchCandidate interface
+ */
+export const MatchCandidateSchema = z.object({
+  ynab_transaction: YNABTransactionSimpleSchema,
+  confidence: z.number().min(0).max(100),
+  match_reason: z.string(),
+  explanation: z.string(),
+});
+
+export type MatchCandidate = z.infer<typeof MatchCandidateSchema>;
+
+/**
+ * Derives the confidence enum value from a numeric confidence score.
+ * Used to enforce consistency between confidence and confidence_score fields.
+ *
+ * @param score - Numeric confidence score (0-100)
+ * @returns Corresponding confidence level enum value
+ *
+ * @remarks
+ * Export this function to use in application logic when constructing
+ * TransactionMatch objects to ensure consistency between the two fields.
+ *
+ * Thresholds:
+ * - 'high': score >= 90
+ * - 'medium': score >= 60
+ * - 'low': score >= 1
+ * - 'none': score === 0
+ *
+ * @example
+ * ```typescript
+ * const confidenceScore = 85;
+ * const transactionMatch = {
+ *   // ... other fields
+ *   confidence: deriveConfidenceFromScore(confidenceScore),
+ *   confidence_score: confidenceScore,
+ * };
+ * ```
+ */
+export function deriveConfidenceFromScore(score: number): 'high' | 'medium' | 'low' | 'none' {
+  if (score >= 90) return 'high';
+  if (score >= 60) return 'medium';
+  if (score >= 1) return 'low';
+  return 'none';
+}
+
+/**
+ * Transaction match result with confidence and candidates.
+ * Links a bank transaction to a YNAB transaction or suggests candidates.
+ *
+ * @see src/tools/reconciliation/types.ts - TransactionMatch interface
+ *
+ * @remarks
+ * This schema contains both `confidence` (enum) and `confidence_score` (0-100)
+ * for backwards compatibility. A validation rule enforces consistency between
+ * the two fields by deriving the expected enum value from the numeric score
+ * and rejecting mismatches.
+ *
+ * Confidence thresholds:
+ * - 'high': confidence_score >= 90
+ * - 'medium': confidence_score >= 60
+ * - 'low': confidence_score >= 1
+ * - 'none': confidence_score === 0
+ */
+export const TransactionMatchSchema = z
+  .object({
+    bank_transaction: BankTransactionSchema,
+    ynab_transaction: YNABTransactionSimpleSchema.optional(),
+    candidates: z.array(MatchCandidateSchema).optional(),
+    confidence: z.enum(['high', 'medium', 'low', 'none']),
+    confidence_score: z.number().min(0).max(100),
+    match_reason: z.string(),
+    top_confidence: z.number().optional(),
+    action_hint: z.string().optional(),
+    recommendation: z.string().optional(),
+  })
+  .refine(
+    (data) => {
+      const expectedConfidence = deriveConfidenceFromScore(data.confidence_score);
+      return data.confidence === expectedConfidence;
+    },
+    {
+      message: 'Confidence mismatch: confidence enum does not match confidence_score',
+      path: ['confidence'],
+    },
+  );
+
+export type TransactionMatch = z.infer<typeof TransactionMatchSchema>;
+
+/**
+ * Balance reconciliation status.
+ * Compares current account balances to target statement balance.
+ *
+ * @see src/tools/reconciliation/types.ts - BalanceInfo interface
+ */
+export const BalanceInfoSchema = z.object({
+  current_cleared: MoneyValueSchema,
+  current_uncleared: MoneyValueSchema,
+  current_total: MoneyValueSchema,
+  target_statement: MoneyValueSchema,
+  discrepancy: MoneyValueSchema,
+  on_track: z.boolean(),
+});
+
+export type BalanceInfo = z.infer<typeof BalanceInfoSchema>;
+
+/**
+ * Reconciliation summary statistics.
+ * High-level overview of matching results and balance status.
+ *
+ * @see src/tools/reconciliation/types.ts - ReconciliationSummary interface
+ */
+export const ReconciliationSummarySchema = z.object({
+  statement_date_range: z.string(),
+  bank_transactions_count: z.number(),
+  ynab_transactions_count: z.number(),
+  auto_matched: z.number(),
+  suggested_matches: z.number(),
+  unmatched_bank: z.number(),
+  unmatched_ynab: z.number(),
+  current_cleared_balance: MoneyValueSchema,
+  target_statement_balance: MoneyValueSchema,
+  discrepancy: MoneyValueSchema,
+  discrepancy_explanation: z.string(),
+});
+
+export type ReconciliationSummary = z.infer<typeof ReconciliationSummarySchema>;
+
+/**
+ * Reconciliation analysis insight.
+ * Highlights patterns, anomalies, or issues discovered during analysis.
+ *
+ * @see src/tools/reconciliation/types.ts - ReconciliationInsight interface
+ */
+export const ReconciliationInsightSchema = z.object({
+  id: z.string(),
+  type: z.enum(['repeat_amount', 'near_match', 'anomaly']),
+  severity: z.enum(['info', 'warning', 'critical']),
+  title: z.string(),
+  description: z.string(),
+  evidence: z.record(z.string(), z.unknown()).optional(),
+});
+
+export type ReconciliationInsight = z.infer<typeof ReconciliationInsightSchema>;
+
+/**
+ * Actionable recommendation discriminated union.
+ * Suggests specific actions to resolve discrepancies (create, update, review).
+ *
+ * @see src/tools/reconciliation/types.ts - ActionableRecommendation union type
+ */
+export const ActionableRecommendationSchema = z.discriminatedUnion('action_type', [
+  // Create transaction recommendation
+  z.object({
+    id: z.string(),
+    action_type: z.literal('create_transaction'),
+    priority: z.enum(['high', 'medium', 'low']),
+    confidence: z.number().min(0).max(1),
+    message: z.string(),
+    reason: z.string(),
+    estimated_impact: MoneyValueSchema,
+    account_id: z.string(),
+    source_insight_id: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+    parameters: z.object({
+      account_id: z.string(),
+      date: IsoDateWithCalendarValidationSchema,
+      amount: z.number(),
+      payee_name: z.string(),
+      memo: z.string().optional(),
+      cleared: z.enum(['cleared', 'uncleared']),
+      approved: z.boolean(),
+      category_id: z.string().optional(),
+    }),
+  }),
+  // Update cleared status recommendation
+  z.object({
+    id: z.string(),
+    action_type: z.literal('update_cleared'),
+    priority: z.enum(['high', 'medium', 'low']),
+    confidence: z.number().min(0).max(1),
+    message: z.string(),
+    reason: z.string(),
+    estimated_impact: MoneyValueSchema,
+    account_id: z.string(),
+    source_insight_id: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+    parameters: z.object({
+      transaction_id: z.string(),
+      cleared: z.enum(['cleared', 'uncleared', 'reconciled']),
+    }),
+  }),
+  // Review duplicate recommendation
+  z.object({
+    id: z.string(),
+    action_type: z.literal('review_duplicate'),
+    priority: z.enum(['high', 'medium', 'low']),
+    confidence: z.number().min(0).max(1),
+    message: z.string(),
+    reason: z.string(),
+    estimated_impact: MoneyValueSchema,
+    account_id: z.string(),
+    source_insight_id: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+    parameters: z.object({
+      candidate_ids: z.array(z.string()),
+      bank_transaction: BankTransactionSchema,
+      suggested_match_id: z.string().optional(),
+    }),
+  }),
+  // Manual review recommendation
+  z.object({
+    id: z.string(),
+    action_type: z.literal('manual_review'),
+    priority: z.enum(['high', 'medium', 'low']),
+    confidence: z.number().min(0).max(1),
+    message: z.string(),
+    reason: z.string(),
+    estimated_impact: MoneyValueSchema,
+    account_id: z.string(),
+    source_insight_id: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+    parameters: z.object({
+      issue_type: z.string(),
+      related_transactions: z.array(z.string()),
+    }),
+  }),
+]);
+
+export type ActionableRecommendation = z.infer<typeof ActionableRecommendationSchema>;
+
+/**
+ * Account balance snapshot with money formatting.
+ * Used in execution result to show before/after balance states.
+ *
+ * @see src/tools/reconcileAdapter.ts:138-142 - convertAccountSnapshot function
+ */
+export const AccountSnapshotSchema = z.object({
+  balance: MoneyValueSchema,
+  cleared_balance: MoneyValueSchema,
+  uncleared_balance: MoneyValueSchema,
+});
+
+export type AccountSnapshot = z.infer<typeof AccountSnapshotSchema>;
+
+/**
+ * Transaction data shapes for different execution action types.
+ * Provides stronger typing than generic Record<string, unknown>.
+ */
+
+/**
+ * Created transaction from YNAB API response.
+ * Used when a transaction is successfully created.
+ */
+export const CreatedTransactionSchema = z
+  .object({
+    id: z.string(),
+    date: z.string(),
+    amount: z.number(),
+    memo: z.string().nullable().optional(),
+    cleared: z.enum(['cleared', 'uncleared', 'reconciled']).optional(),
+    approved: z.boolean().optional(),
+    payee_name: z.string().nullable().optional(),
+    category_name: z.string().nullable().optional(),
+    import_id: z.string().nullable().optional(),
+  })
+  .passthrough(); // Allow additional YNAB API fields
+
+/**
+ * Transaction creation payload.
+ * Used when documenting what would be created (dry run) or what failed to create.
+ */
+export const TransactionCreationPayloadSchema = z.object({
+  account_id: z.string(),
+  date: z.string(),
+  amount: z.number(),
+  payee_name: z.string().optional(),
+  memo: z.string().optional(),
+  cleared: z.enum(['cleared', 'uncleared']).optional(),
+  approved: z.boolean().optional(),
+  import_id: z.string().optional(),
+});
+
+/**
+ * Transaction update payload.
+ * Used when documenting status or date changes.
+ */
+export const TransactionUpdatePayloadSchema = z.object({
+  transaction_id: z.string(),
+  new_date: z.string().optional(),
+  cleared: z.enum(['cleared', 'uncleared', 'reconciled']).optional(),
+});
+
+/**
+ * Duplicate detection payload.
+ * Used when a transaction creation is skipped due to duplicate detection.
+ */
+export const DuplicateDetectionPayloadSchema = z.object({
+  transaction_id: z.string().nullable(),
+  import_id: z.string().optional(),
+});
+
+/**
+ * Execution action record with correlation tracking.
+ * Documents individual actions taken during reconciliation execution.
+ *
+ * Uses discriminated union based on action type for stronger type safety.
+ * Each action type has its own transaction payload schema.
+ *
+ * @see src/tools/reconciliation/executor.ts:29-36 - ExecutionActionRecord interface
+ * @see src/tools/reconciliation/executor.ts:226-238 - create_transaction action
+ * @see src/tools/reconciliation/executor.ts:278-290 - create_transaction_failed action
+ * @see src/tools/reconciliation/executor.ts:339-351 - create_transaction_duplicate action
+ * @see src/tools/reconciliation/executor.ts:472-480 - update_transaction action (dry run)
+ * @see src/tools/reconciliation/executor.ts:515-520 - update_transaction action (real)
+ */
+export const ExecutionActionRecordSchema = z.discriminatedUnion('type', [
+  // Successful transaction creation
+  z.object({
+    type: z.literal('create_transaction'),
+    transaction: CreatedTransactionSchema.nullable(),
+    reason: z.string(),
+    bulk_chunk_index: z.number().optional(),
+    correlation_key: z.string().optional(),
+  }),
+  // Failed transaction creation
+  z.object({
+    type: z.literal('create_transaction_failed'),
+    transaction: TransactionCreationPayloadSchema,
+    reason: z.string(),
+    bulk_chunk_index: z.number().optional(),
+    correlation_key: z.string().optional(),
+  }),
+  // Duplicate transaction detected
+  z.object({
+    type: z.literal('create_transaction_duplicate'),
+    transaction: DuplicateDetectionPayloadSchema,
+    reason: z.string(),
+    bulk_chunk_index: z.number(),
+    correlation_key: z.string().optional(),
+    duplicate: z.literal(true),
+  }),
+  // Transaction update (status/date change)
+  z.object({
+    type: z.literal('update_transaction'),
+    transaction: z.union([
+      CreatedTransactionSchema.nullable(), // Real execution
+      TransactionUpdatePayloadSchema, // Dry run
+    ]),
+    reason: z.string(),
+  }),
+  // Balance alignment checkpoint
+  z.object({
+    type: z.literal('balance_checkpoint'),
+    transaction: z.null(),
+    reason: z.string(),
+  }),
+  // Bulk create fallback to sequential
+  z.object({
+    type: z.literal('bulk_create_fallback'),
+    transaction: z.null(),
+    reason: z.string(),
+    bulk_chunk_index: z.number(),
+  }),
+]);
+
+export type ExecutionActionRecord = z.infer<typeof ExecutionActionRecordSchema>;
+
+/**
+ * Execution summary statistics.
+ * High-level overview of reconciliation execution results.
+ *
+ * @see src/tools/reconciliation/executor.ts:38-48 - ExecutionSummary interface
+ */
+export const ExecutionSummarySchema = z.object({
+  bank_transactions_count: z.number(),
+  ynab_transactions_count: z.number(),
+  matches_found: z.number(),
+  missing_in_ynab: z.number(),
+  missing_in_bank: z.number(),
+  transactions_created: z.number(),
+  transactions_updated: z.number(),
+  dates_adjusted: z.number(),
+  dry_run: z.boolean(),
+});
+
+export type ExecutionSummary = z.infer<typeof ExecutionSummarySchema>;
+
+/**
+ * Bulk operation metrics for reconciliation transaction creation.
+ * Tracks performance and correlation behavior during bulk transaction operations.
+ *
+ * @remarks
+ * Note on failure counters:
+ * - `transaction_failures` is the canonical counter for per-transaction failures
+ * - `failed_transactions` is maintained for backward compatibility and should always
+ *   mirror `transaction_failures` rather than represent an independent count
+ *
+ * @see src/tools/reconciliation/executor.ts:50-68 - BulkOperationDetails interface
+ */
+export const BulkOperationDetailsSchema = z
+  .object({
+    chunks_processed: z.number(),
+    bulk_successes: z.number(),
+    sequential_fallbacks: z.number(),
+    duplicates_detected: z.number(),
+    failed_transactions: z.number(),
+    bulk_chunk_failures: z.number(),
+    transaction_failures: z.number(),
+    sequential_attempts: z.number().optional(),
+  })
+  .refine((data) => data.failed_transactions === data.transaction_failures, {
+    message: 'failed_transactions must equal transaction_failures',
+  });
+
+export type BulkOperationDetails = z.infer<typeof BulkOperationDetailsSchema>;
+
+/**
+ * Execution result (present if auto-execution enabled).
+ * Documents actions taken and resulting balance changes.
+ *
+ * @remarks
+ * This schema matches the actual payload shape built by convertExecution()
+ * in reconcileAdapter.ts, which differs from the legacy ExecutionResult interface.
+ * The adapter converts the ExecutionResult to a structured payload with formatted
+ * money values and nested balance snapshots.
+ *
+ * @see src/tools/reconcileAdapter.ts:199-232 - convertExecution function
+ * @see src/tools/reconciliation/executor.ts:69-79 - ExecutionResult interface
+ */
+export const ExecutionResultSchema = z.object({
+  summary: ExecutionSummarySchema,
+  account_balance: z.object({
+    before: AccountSnapshotSchema,
+    after: AccountSnapshotSchema,
+  }),
+  actions_taken: z.array(ExecutionActionRecordSchema),
+  recommendations: z.array(z.string()),
+  balance_reconciliation: z.unknown().optional(),
+  bulk_operation_details: BulkOperationDetailsSchema.optional(),
+});
+
+export type ExecutionResult = z.infer<typeof ExecutionResultSchema>;
+
+/**
+ * Data freshness audit metadata.
+ * Documents data sources, cache status, and staleness.
+ *
+ * @remarks
+ * This schema uses `.catchall(z.unknown())` to support forward-compatible extensions
+ * through the AdapterOptions.auditMetadata pattern. Known keys are typed explicitly,
+ * but additional fields can be passed through without validation errors.
+ *
+ * @see src/tools/reconciliation/index.ts:272-284 - Audit metadata construction
+ * @see src/tools/reconcileAdapter.ts:19-25 - AdapterOptions interface with extensible auditMetadata
+ */
+export const AuditMetadataSchema = z
+  .object({
+    data_freshness: z.string(),
+    data_source: z.string(),
+    server_knowledge: z.number().optional(),
+    fetched_at: z.string(),
+    accounts_count: z.number().optional(),
+    transactions_count: z.number().optional(),
+    cache_status: z.object({
+      accounts_cached: z.boolean(),
+      transactions_cached: z.boolean(),
+      delta_merge_applied: z.boolean(),
+    }),
+  })
+  .catchall(z.unknown());
+
+export type AuditMetadata = z.infer<typeof AuditMetadataSchema>;
+
+// ============================================================================
+// MAIN OUTPUT SCHEMA
+// ============================================================================
+
+/**
+ * Complete reconciliation analysis output.
+ * Discriminated union for human-only vs human+structured response modes.
+ *
+ * @see src/tools/reconciliation/index.ts:147-362 - Main handler
+ * @see src/tools/reconcileAdapter.ts - buildReconciliationPayload function
+ *
+ * @example
+ * // Human-readable narrative only (default)
+ * {
+ *   human: "Successfully matched 45 of 50 bank transactions. Current cleared balance..."
+ * }
+ *
+ * @example
+ * // With structured data (include_structured_data=true)
+ * {
+ *   human: "Successfully matched 45 of 50 bank transactions...",
+ *   structured: {
+ *     success: true,
+ *     phase: "analysis",
+ *     summary: {
+ *       statement_date_range: "2025-10-01 to 2025-10-31",
+ *       bank_transactions_count: 50,
+ *       auto_matched: 45,
+ *       suggested_matches: 3,
+ *       unmatched_bank: 2,
+ *       discrepancy: { amount: -25.50, currency: "USD", formatted: "-$25.50" }
+ *     },
+ *     auto_matches: [...],
+ *     suggested_matches: [...],
+ *     unmatched_bank: [...],
+ *     unmatched_ynab: [...],
+ *     balance_info: {
+ *       current_cleared: { amount: 1250.00, currency: "USD", formatted: "$1,250.00" },
+ *       target_statement: { amount: 1275.50, currency: "USD", formatted: "$1,275.50" },
+ *       on_track: false
+ *     },
+ *     insights: [
+ *       { id: "ins-1", type: "repeat_amount", severity: "warning", title: "Duplicate amount detected" }
+ *     ],
+ *     recommendations: [
+ *       {
+ *         id: "rec-1",
+ *         action_type: "create_transaction",
+ *         priority: "high",
+ *         confidence: 0.95,
+ *         message: "Create missing transaction for bank entry",
+ *         parameters: { account_id: "acct-1", date: "2025-10-15", amount: -25500, ... }
+ *       }
+ *     ],
+ *     execution_result: {
+ *       executed: true,
+ *       actions_taken: [{ action_type: "create_transaction", status: "success", transaction_id: "txn-new" }],
+ *       reconciliation_complete: false,
+ *       remaining_discrepancy: { amount: 0, currency: "USD", formatted: "$0.00" }
+ *     },
+ *     audit_metadata: {
+ *       data_freshness: "real-time",
+ *       data_source: "YNAB API + CSV",
+ *       fetched_at: "2025-11-18T10:30:00Z",
+ *       cache_status: { accounts_cached: false, transactions_cached: false }
+ *     }
+ *   }
+ * }
+ */
+/**
+ * CSV format configuration metadata.
+ * Documents the CSV format detected or specified by the user.
+ *
+ * @see src/tools/reconciliation/index.ts:364-402 - mapCsvFormatForPayload function
+ */
+export const CsvFormatMetadataSchema = z.object({
+  delimiter: z.string(),
+  decimal_separator: z.string(),
+  thousands_separator: z.string().nullable(),
+  date_format: z.string(),
+  header_row: z.boolean(),
+  date_column: z.string().nullable(),
+  amount_column: z.string().nullable(),
+  payee_column: z.string().nullable(),
+});
+
+export type CsvFormatMetadata = z.infer<typeof CsvFormatMetadataSchema>;
+
+// Define the structured data schema without refinement first
+const StructuredReconciliationDataBaseSchema = z.object({
+  version: z.string(),
+  schema_url: z.string(),
+  generated_at: z.string(),
+  account: z.object({
+    id: z.string().optional(),
+    name: z.string().optional(),
+  }),
+  summary: ReconciliationSummarySchema,
+  balance: BalanceInfoSchema.extend({
+    discrepancy_direction: z.enum(['balanced', 'ynab_higher', 'bank_higher']),
+  }),
+  insights: z.array(ReconciliationInsightSchema),
+  next_steps: z.array(z.string()),
+  matches: z.object({
+    auto: z.array(TransactionMatchSchema),
+    suggested: z.array(TransactionMatchSchema),
+  }),
+  unmatched: z.object({
+    bank: z.array(BankTransactionSchema),
+    ynab: z.array(YNABTransactionSimpleSchema),
+  }),
+  recommendations: z.array(ActionableRecommendationSchema).optional(),
+  csv_format: CsvFormatMetadataSchema.optional(),
+  execution: ExecutionResultSchema.optional(),
+  audit: AuditMetadataSchema.optional(),
+});
+
+export const ReconcileAccountOutputSchema = z
+  .union([
+    // Human + structured data (when include_structured_data=true) - check this FIRST
+    z.object({
+      human: z.string(),
+      structured: StructuredReconciliationDataBaseSchema,
+    }),
+    // Human narrative only (default mode) - check this SECOND
+    z.object({
+      human: z.string(),
+    }),
+  ])
+  .refine(
+    (data) => {
+      // Only validate if this is the structured variant (has 'structured' property)
+      if ('structured' in data && data.structured) {
+        const discrepancyAmount = data.structured.balance.discrepancy.amount;
+        const direction = data.structured.balance.discrepancy_direction;
+
+        // If absolute discrepancy < 0.01, direction must be 'balanced'
+        if (Math.abs(discrepancyAmount) < 0.01) {
+          return direction === 'balanced';
+        }
+
+        // If discrepancy > 0, direction must be 'ynab_higher'
+        if (discrepancyAmount > 0) {
+          return direction === 'ynab_higher';
+        }
+
+        // If discrepancy < 0, direction must be 'bank_higher'
+        if (discrepancyAmount < 0) {
+          return direction === 'bank_higher';
+        }
+      }
+
+      // Human-only variant always passes validation
+      return true;
+    },
+    {
+      message:
+        'Discrepancy direction mismatch: direction must match the numeric discrepancy amount',
+      path: ['balance', 'discrepancy_direction'],
+    },
+  );
+
+export type ReconcileAccountOutput = z.infer<typeof ReconcileAccountOutputSchema>;