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.
PurchaseChecken estadoUNKNOWN.- 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 enIN_PROGRESSy una consulta tardía escribe la intención, porquerecordApprovalIntentsolo bloqueaba las reversas enIN_FLIGHToDONE(saleReversalinformabaFAILED). Prisma la completa más tarde ysettleMoneyBackanula 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.recordApprovalIntentrechaza 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 enAnsweryGaveUpReversal; 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 delDELETE? 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.
- Tener un JDK y Git Bash.
- Bajar
tla2tools.jarv1.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.tsdel skill directamente, porquestatechart.tsinvoca/bin/sh, que unnode.exenativo no encuentra. - Fija
JAVA_TOOL_OPTIONScon 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.