Saltar a contenido

Modelo formal del ciclo de vida del pago

Modelo TLA+ del ciclo de vida de un pago de GatewayPrismaQR, verificado de forma exhaustiva con TLC. Complementa a las pruebas: una prueba ejecuta un camino que alguien pensó; el modelo recorre todos los caminos posibles dentro de su alcance, incluidos los entrelazados entre dos nodos y los vencimientos de lease que nadie escribiría a mano.

Fecha de las corridas: 2026-10-31. Las corridas 5, 6 y 7 son anteriores a la corrección de D-134 y se hicieron con la especificación que reflejaba el código de main en el commit 2361681; se conservan como evidencia del hallazgo. La especificación actual modela esa corrección (PR #7, 9c5f619) y la corrida 8 la verifica. La versión anterior de PaymentLifecycle.tla está en el historial de git, en el primer commit de esta carpeta.

Qué hay aquí

Archivo Qué es
PaymentLifecycle.tla La especificación. Cada acción lleva en un comentario la clase o el método de Java que representa (por ejemplo JdbcChargeLedger.saleReversal, PosApprovalGuard.answer, ReversalSettlement.settleMoneyBack). Ese mapa acción → Java es la forma de revisar si el modelo dice lo mismo que el código.
PaymentLifecycle.cfg Configuración completa: Prisma deja pagar una intención ya cancelada (PayAfterCancel = TRUE) y el cajero puede reintentar más allá de la ventana de consulta (Reintenta = TRUE). Todas las reglas.
Remaining.cfg Igual que la anterior sin las dos reglas que esa configuración rompe (MarkedSaleKeepsItsMoney y EveryChargeCanBeNamed), para comprobar que las demás se sostienen y que el recorrido no se corta en el primer error.
PrismaRefusesNoReintenta.cfg Prisma rechaza el pago de una intención cancelada y el cajero no reintenta (PayAfterCancel = FALSE, Reintenta = FALSE). Es el mundo en el que Prisma responde bien la pregunta 17g.
AfterD134.cfg Igual que Remaining.cfg más MarkedSaleKeepsItsMoney: la configuración con la que se verifica la corrección de D-134 (PayAfterCancel = TRUE, Reintenta = TRUE). Deja fuera EveryChargeCanBeNamed (D-132, que depende de Prisma y se detiene en el primer error) y mantiene OnlyIntentSetReachesAPerson (D-135).
view.mjs Traduce los estados y las acciones del modelo a frases legibles para el informe y el diagrama.
run.sh Corre TLC con una configuración y deja el informe (report.md) y el diagrama (chart.mmd).
resultados/out-5, out-6, out-7 (antes de la corrección de D-134) y out-8 (después) Informe, diagrama y salida de TLC (tlc*.out, con las rutas locales reemplazadas por <local>) de las corridas finales (en inglés, tal como los produce la herramienta). Ver más abajo.

Alcance

Una intención de pago, un cobro de la billetera, dos nodos del gateway, dos consultas del POS (MaxPolls = 2), dos intentos de la tarea de compensación (MaxAttempts = 2) y un vencimiento de lease (MaxExpiries = 1). El tiempo se abstrae en tres fases: antes del tope de espera, después del tope y después de la ventana de consulta del POS (gateway.compensation.pos-polling-window).

Lo que no se modeló:

  • La anulación del cajero (trxanulacion).
  • La cadena rechazo → devolución.
  • El resultado desconocido al crear la intención.
  • El reemplazo de un pago por otro (SUPERSEDED).
  • Las fallas al cancelar la intención.
  • PurchaseCheck en estado UNKNOWN.
  • La caída de un nodo.
  • Un segundo cobro de la billetera sobre la misma intención.
  • Las notificaciones perdidas.
  • El desfase de relojes entre nodos y las duraciones reales.
  • INV-06 (la imputación en el POS), que es del lado del POS.

Un modelo con este alcance no demuestra que el sistema sea correcto; demuestra que dentro de ese alcance las reglas de abajo se cumplen o se rompen por el camino indicado.

Reglas comprobadas y resultados

TLC revisa seis invariantes (CodeNeverAnnulsAMarkedSale, MarkedSaleKeepsItsMoney, ApprovedAnswerHasIntent, NoSaleAnswerIsBacked, AtMostOneReversalPerCharge, EveryChargeCanBeNamed), dos propiedades de vivacidad (NoSaleChargeGoesBackOrToAPerson, OnlyIntentSetReachesAPerson) y la ausencia de bloqueo (NoDeadlock).

Regla Resultado
A lo sumo una reversa por cobro llega a Prisma (AtMostOneReversalPerCharge, ADR-002 D-79), también cuando otro nodo toma el lease de la tarea Se cumple (corridas 6 y 7)
Sin bloqueo (NoDeadlock) Se cumple (corridas 6 y 7)
INV-02, vivacidad: un cobro que no es una venta vuelve a la billetera o una persona recibe una alerta (NoSaleChargeGoesBackOrToAPerson) Se cumple (corridas 6 y 7). No es trivial: una mutación que quitó la nota local de D-124 la rompió.
INV-02: la intención de compensación está persistida antes de que el POS oiga «sin venta» (NoSaleAnswerIsBacked) Se cumple (corridas 6 y 7)
INV-01, reglas de programación: el código nunca programa como «sin venta» la anulación de una venta marcada (CodeNeverAnnulsAMarkedSale) y ninguna aprobación sale sin la intención escrita (ApprovedAnswerHasIntent) Se cumplen (corridas 6 y 7). Reflejan en buena parte los bloqueos del código, así que aportan menos que las anteriores.
INV-01, resultado: el dinero de una venta que el POS pudo oír aprobada nunca vuelve por el código (MarkedSaleKeepsItsMoney) Se rompía: D-134, con Reintenta = TRUE (corrida 5, antes de la corrección). Se cumple con la corrección de PR #7 (corrida 8, misma combinación PayAfterCancel = TRUE y Reintenta = TRUE). También se cumplía con PrismaRefusesNoReintenta.cfg (corrida 7).
Todo cobro puede nombrarse a Prisma en una anulación forzada (EveryChargeCanBeNamed) Se rompe: D-132 si Prisma deja pagar tras el DELETE (corrida 5). Se cumple si Prisma lo rechaza (corrida 7).
INV-01, vivacidad: con solo la intención escrita y el dinero afuera, una persona recibe una alerta (OnlyIntentSetReachesAPerson) Se rompe: D-135 (corridas 6 y 7), con y sin la pregunta 17g.

Qué corrida usa qué configuración:

Corrida Configuración Qué muestra
resultados/out-5 PaymentLifecycle.cfg Los caminos de D-134 (16 pasos) y D-132 (5 pasos). Tras el primer error TLC se detiene en 100.000 estados distintos, por eso el informe lista las demás reglas como «no comprobadas».
resultados/out-6 Remaining.cfg 194.013 estados. Las reglas restantes se cumplen salvo D-135.
resultados/out-7 PrismaRefusesNoReintenta.cfg 124.975 estados. Todo se cumple salvo D-135.
resultados/out-8 AfterD134.cfg (con la especificación corregida) 190.783 estados. MarkedSaleKeepsItsMoney y las demás reglas de seguridad se cumplen, igual que NoDeadlock y la vivacidad de INV-02. Solo se rompe D-135.

Hallazgos

  • D-134 (INV-01, dinero; corregido en el PR #7, 9c5f619). La escritura de la intención de aprobación falla, así que el POS oye «aprobación diferida». El reconciliador programa la anulación, el trabajo se rinde con la reversa en IN_PROGRESS y una consulta tardía escribe la intención, porque recordApprovalIntent solo bloqueaba las reversas en IN_FLIGHT o DONE (saleReversal informaba FAILED). Prisma la completa más tarde y settleMoneyBack anula una venta que el POS oyó como aprobada. Necesitaba una falla de escritura en la base, Prisma en silencio unos 20 minutos y el cajero reintentando entre 30 y 40 minutos después. Regla integrada: JdbcPosApprovals.recordApprovalIntent rechaza la intención mientras la venta tenga una reversa de la que el trabajo se rindió (SaleReversal.GAVE_UP), pero solo si la intención todavía no estaba registrada. Con la intención ya registrada, el POS sigue oyendo lo que oyó, porque esa reversa solo puede ser la del cajero. La especificación lo modela en Answer y GaveUpReversal; la corrida 8 lo verifica.
  • D-132 depende de la pregunta 17g a Prisma (docs/PRISMA-PREGUNTAS.md): ¿puede una billetera pagar una intención después del DELETE? Si Prisma la rechaza, la regla se cumple (corrida 7).
  • D-135 (diferido). Se pierde la respuesta aprobada y no queda ninguna línea de alerta (PosApprovalMarkerFilter). Es la variante sin caída de proceso de D-124.

Cómo correrlo en Windows

Herramienta: el skill statechart del repositorio pstack (licencia MIT), que arma el modelo, lo pasa por TLC y redacta el informe.

  1. Tener un JDK y Git Bash.
  2. Bajar tla2tools.jar v1.7.4 del release oficial de tlaplus (https://github.com/tlaplus/tlaplus/releases/download/v1.7.4/tla2tools.jar) y verificar su huella antes de usarlo. El jar no se guarda en este repositorio.
sha256sum tla2tools.jar
936a262061c914694dfd669a543be24573c45d5aa0ff20a8b96b23d01e050e88

(Es la misma huella que fija scripts/run.ts del skill.) 3. Desde Git Bash, en la raíz del repositorio, con rutas C:/... (no /c/...):

export JAVA="C:/ruta/al/jdk/bin/java.exe"
export TLA2TOOLS="C:/ruta/a/tla2tools.jar"
docs/modelo/run.sh /tmp/salida-7 PrismaRefusesNoReintenta.cfg

El primer argumento es una carpeta que no debe existir; el segundo es la configuración (por omisión PaymentLifecycle.cfg). La variable opcional STATECHART_SKILL apunta a la carpeta del skill (por omisión ~/.claude/skills/statechart).

El script resuelve dos problemas de Windows:

  • Ejecuta worker.ts del skill directamente, porque statechart.ts invoca /bin/sh, que un node.exe nativo no encuentra.
  • Fija JAVA_TOOL_OPTIONS con el separador de línea LF: TLC termina sus mensajes con CRLF en Windows y el analizador del skill no los acepta.

El código de salida 1 no indica una falla de la herramienta: significa que TLC encontró una regla que se rompe; el motivo está en report.md. Una corrida de PrismaRefusesNoReintenta.cfg reprodujo el informe de resultados/out-7 sin diferencias.

Regla de uso

Un camino contraejemplo se reproduce contra el código. El modelo propone el camino; la prueba o la lectura del código lo confirman. Si no se reproduce, es un error del modelo y se corrige el modelo, no el código. Los tres hallazgos de arriba se verificaron así antes de registrarse.

Cuando cambie el código que una acción representa (el comentario de la acción dice cuál), hay que actualizar la especificación y volver a correr las configuraciones. Las corridas 5, 6 y 7 no se rehacen: documentan el estado anterior a la corrección de D-134.