Saltar a contenido

ISSUES-DEFERRED — GatewayPrismaQR

Findings below the severity gate, or gated findings that belong to a later slice. Each names the slice that must close it.

Status 2026-11-17: 86 closed, 116 open (22 of them blocked on Prisma, the human, the POS team or an operations check), 202 entries (the go-live checklist closed D-14, D-24 and D-S5-6 and opened D-147 to D-149). Before this review: 56 closed, 136 open (21 blocked).

Legend: closed = the Finding starts with "Closed", "Withdrawn" or "Superseded"; open = everything else, including entries closed in part (their note says what is left); blocked = open and the Target waits for Prisma, a human decision, the POS team or an operations check.

ID Source Finding Target
D-01 improve #4 Closed in S5 batch 1 (2026-10-04): a third connector (loopback by default, remote only with allow-remote and HTTPS) and the own-users login, docs/CONVENTIONS.md section 12. An ADR (proposed ADR-005, admin listener and console authentication) still has to be written and accepted by the human. No listener for the console/admin API; console authentication undecided. S5
D-02 improve #5 Closed 2026-11-16: the prisma-emulator module exists (commit 9cf40dd, 2026-10-02): the exec classifier jar (prisma-emulator/pom.xml), HTTPS with a self-signed keystore and the matching test truststore (SelfSignedKeystore, InProcessEmulator.trustStore(), INV-10), a control API for faults, scenarios and late results (ControlController, FaultInjector) and configurable deadlines and delays (EmulatorProperties). The end-to-end tests are the package gateway/src/test/.../e2e (PosFlowsE2EIT, PosAnnulmentE2EIT, PlansE2EIT, CashbackRelaxedE2EIT), not a separate Maven module. Emulator module shape: exec classifier jars, e2e module, HTTPS emulator with test truststore (INV-10), control API for failure/late-approval injection, configurable clock/timeouts. Closed
D-03 improve #3 Closed in S1: webmvc-test/data-jpa-test starters added. Boot 4 slice-test starters (spring-boot-starter-webmvc-test, spring-boot-starter-data-jpa-test). Approved by the human 2026-10-02. S1
D-04 improve #10 Closed in S1: conventions in docs/CONVENTIONS.md §2. Hibernate/SQL Server mapping conventions (nationalized strings, Instant as TIMESTAMP, JDBC time zone UTC) to settle with the first entities. S1
D-05 improve #11, review #19 Leases closed in S4 batch 1: the claim of compensation_task runs in database time (SYSUTCDATETIME) with READPAST, lease_owner and lease_until; CompensationQueue, CONVENTIONS section 11. Inject a UTC Clock; ArchUnit ban on now() in domain/application; leases computed with database time in the claim UPDATE; -Duser.timezone=UTC in NSSM parameters. S1 (Clock), S4 (leases)
D-06 improve #8 Narrowed 2026-11-16: done are "scheduler disabled by default under the test profile" (gateway.inbox, gateway.compensation and gateway.retention have enabled: false in application-test.yml) and the guarded clean of every test context (CleanSchemaFlywayConfiguration, _IT databases only). Still open: a per-test truncate listener, and one clean per JVM instead of one per Spring context (the shared-data hygiene of the tests is also D-97). Per-test truncate listener; clean once per JVM; scheduler disabled by default under the test profile. Hardening (with D-97)
D-07 improve #13, judge A L8 Closed 2026-11-16: ArchitectureGateTest holds the layering rules (applicationDoesNotDependOnAdapters, inboundAdaptersDoNotDependOnOutboundAdapters, the pure domain, no web framework in application) and the named inv01_, inv09_ and inv10_ rules, each with a test that proves the rule fires. Layering rules (application must not depend on adapter..; adapter.in must not depend on adapter.out), INV-09/INV-10 ArchUnit rules, inv.. named tests. Closed
D-08 judge A H3, judge B L5 Closed 2026-11-16: PayloadMaskerTest (named D-08, INV-07, AC-27) and PayloadMaskerBinsSnapshotIT test the masking of wire_log, inbound_notification.raw_body and bins_snapshot.bins (PayloadMasker is used by JdbcWireLog, JdbcInboundNotifications and JdbcCompleteSnapshots); inv07_aMaskingThatFailsInAnyWay... proves a failure stores the redacted placeholder, never the raw body. Masking contract for inbound_notification.raw_body, bins_snapshot.bins and wire_log (no full benefit card number; INV-07) with a test. Closed
D-09 judge B H3, judge A M6 Ticket/trace wrap policy (Prisma question 6). V1 only caps the values. When Prisma answers
D-10 judge B L1, review #17 Closed in S1: failWhenNoMutations=true, non-empty domain asserted. ArchUnit non-empty domain assertion and failWhenNoMutations=true once the domain has classes. S1 first commit
D-11 judge A L7, review #18, judge B L7 Test robustness: free-port race, RawHttp parsing, assumeTrue skipping the non-loopback check, temp keystore cleanup, flaky first-up interface. S1
D-12 review #16 Extra raw-socket bypass tests (%2e%2e, matrix params, //, upper case). S1
D-13 review #12, judge B M8 Pin GitHub Actions by SHA; dependabot; concurrency group; floating SQL Server image tag. S5/hardening
D-14 improve #14 Closed 2026-11-17 (go-live checklist, branch chore/go-live-checklist); what was not done moved to D-147 (expand/contract), D-148 (rehearsal on the server) and D-149 (console tests), and the admin_audit retention stays in D-143. Done: backup step before upgrade (RUNBOOK 15.4: stopped service, copy-only full backup with CHECKSUM and VERIFYONLY, restore steps exercised on a scratch database, recovery model and its tie to the retention log sizing of section 14 and the V4 off-peak build); least-privilege DB login (db/ops/create-gateway-login.sql: a runtime login with db_datareader/db_datawriter and a migration login with db_ddladmin, no password inside; run for real by hand: Flyway migrated V1-V4 with the migration login, the service ran on the runtime login alone and a pending migration without the migration login fails with CREATE TABLE permission denied (that last case is not in CI); CI checks, on every run, the two logins, Flyway on the migration login, a restart on the runtime login alone, a write through the POS API, that the runtime login has no CREATE TABLE/ALTER and cannot write flyway_schema_history; decision: Flyway stays at startup and the migration login is passed as SPRING_FLYWAY_USER/SPRING_FLYWAY_PASSWORD only for the deploy restart, followed by a mandatory restart, RUNBOOK 15.2; the database credentials stay in the icacls-protected config file, not in NSSM's environment, RUNBOOK 15.1; the SQL Server certificate and the JVM truststore, RUNBOOK 15.7); collation guidance and DB settings check (db/ops/check-gateway-database.sql, RUNBOOK 15.3: case-insensitive collation required, tested on SQL_Latin1_General_CP1_CI_AS, RCSI off, compatibility level, recovery model, Express limits, backups; a case-sensitive collation is a FAIL); log retention (RUNBOOK 15.6, a daily task for the NSSM logs, the GC log and the heap dumps; the NSSM rotation was already there); wire_log retention (D-139); application-prod.yml.example (config/, checked by ProductionConfigExampleTest under the prod profile guards and a strict binding of every gateway.* class); JVM flags (RUNBOOK 2c: -Xms256m -Xmx512m, G1, heap dump on OOM and exit on OOM so NSSM restarts, GC log; sized from the 46-104 MB live of the soak, not re-measured with these exact flags); CI smoke of the packaged jar (tools/ci/smoke-jar.sh, a step of ci.yml). Not done: expand/contract for rolling upgrades (D-147), admin_audit retention (D-143), the Windows-side rehearsal (D-148). Before go-live
D-15 review #20 IntegradoresGrandesCuentasQRv27.pdf is tracked in git; confirm redistribution rights. Ask human
D-16 improve LOW Closed 2026-10-02 (S1): pos_api_key_hash dropped; source-IP allowlist stays an ADR-004 option. ADR-004 per-merchant source-IP allowlist has no table; checkout.pos_api_key_hash exists though the POS sends no auth header. S1
D-17 improve #18 Reset script, SQLCMDPASSWORD instead of -P, AC/INV traceability check. S5/hardening
D-18 improve c2 #3 Closed in S1: starter-webmvc in both modules. spring-boot-starter-web is deprecated in Boot 4.1.1 in favor of spring-boot-starter-webmvc; rename approved by the human 2026-10-02. S1
D-19 improve c2 #5 Closed 2026-11-16: both request shapes are pinned in gateway/src/test/resources/pos-golden/native/trxanulacion-request.json and router/trxanulacion-request.json (README: the native shape is derived from pos_ctoq.cpp, because the E2E logs hold no annulment) and exercised by PosAnnulmentWireIT, PosAnnulmentControllerTest and PosAnnulmentE2EIT; the mapping of the id was decided: trxidoriginal when positive, otherwise id (D-S4-6). trxanulacion handle: pin both request shapes against the real POS E2E log as the first S1 golden; decide how a fresh annulment id maps to its reversal (request_payment_id or an ID_ISSUED payment pointing to the reversal). Closed
D-20 improve c2 #6 Closed 2026-11-16: docs/CONVENTIONS.md section 3 (the wait policy, D-20): short transactions and no connection held across the wait, polling of the database, an explicit Hikari pool (maximum-pool-size: 20 in application.yml), PosWaitIT, PosWaitMultiNodeIT, PosWaitStorageFailureIT (pool of four) and the load run of docs/LOAD-FAULTS-REPORT.md (25 and 50 concurrent checkouts, pool exhaustion, soak: all invariants PASS). Blocking POS wait policy: no transaction or connection held across the wait, DB polling, explicit Hikari pool size, load-shaped IT. Closed
D-21 improve c2 #8, review c2 N-12 Closed 2026-11-16: InFlightShutdownIT.d21_aRequestInFlightOnThePosConnectorFinishesBeforeTheApplicationStops (commit e440481, 2026-10-02; narrowed to what graceful shutdown guarantees in 492f040, D-55). Graceful shutdown proven with an in-flight request on the POS connector. Closed
D-22 improve c2 #9 Closed 2026-11-16: the listener tests use test-only probes (ListenerProbeConfiguration: /api/_probe/**, /prisma/v1/_probe/**, /admin/_probe/**; commit 13028fa, 2026-10-02); the production ping endpoints are the liveness probes (docs/CONVENTIONS.md section 7, RUNBOOK section 4). Listener tests on test-only probe controllers instead of the production ping stubs; decide where liveness/readiness live. Closed
D-23 judge B c2 LOW-1 Closed in S4 batch 1 for the compensation task (lease, ux_reversal_one_active_per_charge): the active slot of a reversal is held by its task, whose lease another worker takes over when the holder dies (ac22_aTaskWhoseLeaseRanOutIsClaimedAgainByAnotherWorker); a reversal row itself carries no lease. Reversal rows have no lease/expiry: a crashed node holds the active slot; add lease_until or an S4 sweep on updated_at + index. S4
D-24 judge A c2 L9, judge B c2 LOW-4, improve c2 #11 Closed 2026-11-17 (go-live checklist). The release no longer rebuilds: ci.yml takes the version of the tag as an input (set before the build), so the gate builds, tests, packages and checksums (SHA-256, SHA256SUMS) the one jar, smoke-tests the package, and release.yml only downloads that artifact, checks the checksums again and publishes (jar, bundle, checksums); a step after PIT proves with cmp that the jar was not rebuilt after it was checksummed. The tag is checked against main: the tag job refuses a tag that is not vX.Y.Z or whose commit is not an ancestor of origin/main (full-depth checkout). Verified by review, not by a run: release.yml cannot run without creating a real release, so its first real run is the first tag; everything that builds or checks bytes is in ci.yml and tools/ci/, which every pull request runs. Hardening
D-25 judge A c2 L10 Superseded by D-75 (S2b c1 review): the open question lives there now. The provisional choice of S2a, one trace and ticket number per snapshot entry (method + BIN), capped, is what S2b built (CONVENTIONS section 9, rules 3 and 10); whether Prisma wants one number per method or per intention, and whether the numbers may wrap, is Prisma question 6 (D-09, D-75). AC-26 is ticked for what the gateway controls: under concurrent payments no two entries share a number and a rolled-back allocation gives its numbers back (TerminalNumbersIT.ac26_*). It does not say that every number belongs to a sale: a payment that is denied after its offer was numbered (a refused or unknown complete intention, an expiry) burns its whole block, and the sequence is never rewound, because a forced annulment may need exactly those numbers. Prisma answer (D-75)
D-26 c3: judge A #1, judge B M1, review M-1, improve M-1 Closed in S1: ProductionProfileGuard refuses plain HTTP unless local/test. Plain-HTTP callbacks override honoured outside prod (no profile, staging, typo): refuse a truthy allow-plain-http unless local/test is active, same predicate as DatabaseTlsGuard; tests for no profile and staging. S1 first commit
D-27 c3: improve M-2 Closed 2026-10-02 (S1): intention version + cross-transaction lock, notification claim columns. intention has no version/updated_at (lost updates between BINs callback, POS wait, supersede, compensation); no processing claim on inbound_notification. S1 first commit (V1)
D-28 c3: improve M-3 Closed in S1: ID_ISSUED exits to CANCELLED/EXPIRED without amount. ID_ISSUED has no exit without an amount (abandoned trxid, trxanulacion before trxpago): allow CANCELLED/EXPIRED with NULL amount or define a reaper. S1 first commit (V1)
D-29 c3: review M-2, judge B L5 Closed in S4 batch 1: ReversalNotificationWorker and ReversalSettlement apply a late result of a FAILED reversal as COMPLETED_LATE, or LATE_AFTER_REFUND (with the alert REVERSAL_LATE_AFTER_REFUND) when another reversal of that charge already returned the money (ReversalNotificationWorkerTest). COMPLETED_LATE frees the money-returning slot (annulment late first, then refund ⇒ double credit): split late states (COMPLETED_LATE inside the index, LATE_AFTER_REFUND outside), document in ADR-002; S4 domain rule for a late annulment while a refund is in flight. S1 (V1) / S4 (rule)
D-30 c3: review M-3 Closed in S1: unique (intention_id, round). complete_snapshot UNIQUE(intention_id) blocks a second BINs/complete round (Prisma question 2/Q3): unique on (intention_id, round). S1 first commit (V1)
D-31 c3: improve M-4 Closed 2026-11-16: the convention is RANDOM_PORT plus PosListener.port() (GatewayIntegrationTest), and RawHttp has the HTTP/1.0 forms get10 and post10 with a body, tested by RawHttpTest (commit 13028fa, 2026-10-02). Port-based listener routing breaks MockMvc/@GatewayIntegrationTest (MOCK) and slices bypass it; RawHttp needs an HTTP/1.0 POST with body; convention RANDOM_PORT + PosListener.port(). Closed
D-32 c3: judge A #4, judge B L6 Closed in S1: lease CHECK tied to state. Lease CHECK does not tie lease to state (IN_PROGRESS without lease gets stuck). S1 first commit (V1)
D-33 c3: judge A #9 Closed in S1: trace/ticket range CHECKs. complete_snapshot_method trace/ticket without range CHECK (1..9999999999 / 1..999999). S1 first commit (V1)
D-34 c3: judge A #5, judge B L4 Closed 2026-10-02 (S1): hand-off makes the intention CANCELLED/SUPERSEDED in the same transaction. "Live" intention comment vs UNKNOWN (wallet can still pay); decide whether UNKNOWN is live for AC-32. S1 (state machine)
D-35 c3: judge A #2/#3, judge B L2, review LOW-1/2 Closed 2026-11-16: CleanSchemaFlywayConfiguration.isolatedDatabaseCleanGuardCustomizer appends the guard to the callbacks already configured (commit 2409a93, 2026-10-02), the javadoc states the scope of the guard (only Flyway instances built by a context that imports the class; spring.flyway.clean-disabled=true stays the first line of defense) and the guard is a @TestConfiguration that the integration tests import. Clean-guard customizer replaces Flyway callbacks (append instead); javadoc overstates coverage; guard registered via test auto-configuration. Closed
D-36 c3: judge A #6/#7, judge B L3 Closed 2026-11-16: db/seed/seed-dev.sql needs ALLOW_DEV_SEED=1 and, outside an _IT database, also I_AM_ON_A_DEV_MACHINE=1, and refuses when the merchant table holds a merchant other than ALMACOR-DEMO (THROW 50001, 50003, 50002); the RUNBOOK section 6 reset command refuses without I_AM_ON_A_DEV_MACHINE=1 (THROW 50005); SeedDevIT (commit ac5c031, 2026-10-02). Seed and RUNBOOK reset command can hit a database named like production (env var arms the flag; empty prod DB passes the merchant guard). Closed
D-37 c3: judge A #8, judge B L1, review LOW-4 Closed 2026-11-16: .gitignore ignores **/application-local.*, **/application-prod.*, **/application-*.yml|yaml|properties, .env, .env.*, *.keystore (and *.p12, *.jks, *.pfx, *.pem, *.key), with the *.example* templates and the test profile kept trackable (commit 27dd54d, 2026-10-02; SecretsHygieneTest). .gitignore still misses **/application-local.*, **/application-prod.*, other env profiles, .env.*, *.keystore. Closed
D-38 c3: improve L-1 Closed 2026-11-16: the prefix is the property gateway.listeners.callbacks.path-prefix (default /prisma/v1), used by the controller mapping, CallbackApiKeyFilter and ListenerConfiguration; the purchase notification path is gateway.listeners.callbacks.payment-path (commit c164686, 2026-10-02; PrismaCallbacksSettingsIT, PrismaCallbacksBoundPathTest). Callback path prefix hard-coded (/prisma/v1/); make it one property (Prisma defines {integrator_path}). Closed
D-39 c3: review LOW-3/5/6 Closed 2026-11-16: SecretsHygieneTest skips (assumeGitWorkTree) when the sources are not a git work tree; DOMAIN-MODEL.md describes CompensationTask (lease, attempts) and the claim columns of InboundNotification; DatabaseTlsGuard inspects a URL data-source entry and PosListener requires an acknowledgement for fec0::/10 (commit c38167e, 2026-10-02; PosListenerTest). SecretsHygieneTest needs git (assume a work tree); DOMAIN-MODEL drift (CompensationTask, inbox columns); data-source URL entry and fec0::/10 in the guards. Closed
D-40 S1 c1: improve M7 Closed in S3 batch 2 for what the gateway controls (docs/CONVENTIONS.md section 9c): the sale is original_amount and the cashback is its own field, the adjustment never applies to it, the notified cash is checked (Cashback, PurchaseResults) and answered to the POS as totalcashback; what stays open is Prisma questions 21 and 22 (D-S3-15). Cashback at create intention (cashback_max_amount, absolute_cashback) and whether POS totalitem includes totalcashback (decides original_amount; a notification amount including cashback must not read as a surcharge). Prisma question 19 of research/prisma-gc-v27.md section 10 (question 21 of the consolidated list, docs/PRISMA-PREGUNTAS.md). S2
D-41 S1 c1: improve L7 Withdrawn with Mode A (human decision 2026-10-28; the code is recoverable from the tag mode-a-reference). Original row, kept for the record: Closed in S3 batch 2: promos is validated row by row (PosPromotion, JacksonPosPromotions), refused whole with a 400 that names the row when any row breaks a rule, capped at 500 rows, and stored in its canonical form (bounded whatever the request carried); the field names are pinned in docs/CONVENTIONS.md section 9b but remain provisional until the POS team confirms them (D-S3-13). promos (mode A) stored unbounded; cap size and pin field names. Withdrawn with Mode A
D-42 S1 c1: L9 judge A DOS POS sends OEM-codepage bytes; non-ASCII merchant names fail as invalid UTF-8. Rule: merchant names ASCII-only (console validation + RUNBOOK). S5
D-43 S1 c2: review N1, judge A M1, judge B M4, improve M2 Closed 2026-11-16: a Created answer with an id that cannot be recorded, and any non-conflict failure of the record steps, hand off to compensation instead of leaving a live intention (commits 67e8a96 and 93eaa46, 2026-10-02; StartPaymentServiceTest section D-43, TransactionsIT section D-43, CreateIntentionOutcomesTest). A Created answer with an out-of-range or clashing Prisma id, or any non-conflict failure while recording the outcome, gives a 500 and a stuck live intention: map unusable ids to Unknown, route any non-conflict failure of the record steps to the hand-off. Closed
D-44 S1 c2: review N2, judges A M3 / B M2-M3 Closed 2026-11-16: WalletFacts and PaymentAmounts carry the facts apart from amounts that break INV-04 or do not match, and such a result is applied without them (commit fc34f26, 2026-10-02; WalletFactsTest, PaymentWalletRejectionTest, WalletResultsTest). Wallet results that the domain cannot express: amounts that break INV-04 (ADR-002 says record without amounts) and a different amount in COMPLETE_SENT (store facts, go to compensation). Wallet-facts value without amounts. Closed
D-45 S1 c2: review N3/N4/N7, judges A M4 / B M1, M6 Closed in S4 batch 1: the second charge has its own wallet_charge and reversal (WalletResults, D-79). Duplicate/second wallet results: dedupe by wallet payment id in every state (no reopen of a finished compensation); never overwrite a different prismaPaymentId; a second charge on one payment needs a per-result model (Prisma question 4c). Hand-off on COMPENSATED/COMPENSATION_FAILED must be a no-op. S2 Part A / S4
D-46 S1 c2: review N6, judges A L3 / B M5, improve L1 Closed 2026-11-16: only definite refusals are Failed; 408, 409, 429 and unlisted 4xx are Unknown; the reason is short ASCII (commit 67e8a96, 2026-10-02; CreateIntentionOutcomesTest, PrismaAuthorizerEmulatorTest section D-46, PosApiIT). Only definite refusals (400, 401, 403, 404, non-duplicate 422) are Failed; 408, 409, 429 and unlisted 4xx are Unknown until Prisma answers question 14. Failed.reason contract: short, ASCII, no Prisma internals. Closed
D-47 S1 c2: judge A M2, judge B L1/L2 Closed 2026-11-16: Payment.moveTo refuses the states that have a command of their own (handOverToCompensation, supersede, intentFailed, ...) and CompensationHandOff has the supersede variant (commit fc34f26, 2026-10-02; CompensationHandOffTest section D-47, docs/CONVENTIONS.md section 5). moveTo still enters COMPENSATION_PENDING, SUPERSEDED, INTENT_FAILED without their commands; CompensationHandOff needs a supersede variant (intention SUPERSEDED). Closed
D-48 S1 c2: judge B M7, judge A L1/L2 Closed 2026-11-16: the Prisma id travels with the hand-over and a late id re-schedules the cancel, storePrismaId decides by the payment state too (commits 82d8aa8 and 93eaa46, 2026-10-02; CompensationHandOffTest section D-48, StartPaymentServiceTest section D-48, CompensationJobTest). A Prisma id attached after the hand-off must re-schedule compensation; storePrismaId must decide by the payment state too; step 3 must address the intention by its own id, not "latest". Closed
D-49 S1 c2: improve M1 Closed 2026-11-16: one lock order, payment then intention then the rest, in StartPaymentService, BinsWorker, CompensationJob, AnnulPaymentService and CompensationHandOff; deadlock victims are run again at most three times (commit 93eaa46, 2026-10-02; DeadlockRetryTest, TransactionsIT, WireLogLockOrderIT). One lock order (payment → intention → task) everywhere; deadlock victims (1205) retried in inTransaction; two-thread test. Closed
D-50 S1 c2: improve M3/M4 Closed 2026-11-16: docs/CONVENTIONS.md section 9, "The S2 flow contract (D-50)" (commit e9bba41, 2026-10-02). S2 flow contract in CONVENTIONS: every exit of start() waits to a final state or hands off; expiry racing a late approval answers the final state (tryHandOver); COMPLETE_SENT persisted before the complete call; uncorrelated callbacks go to the inbox and are retried; Prisma question 1 is a dependency. Closed
D-51 S1 c2: improve M5, L8 Closed 2026-11-16: Approval and WalletFacts bound their fields to the column widths, PaymentSnapshot has its builder, and the BINs step and the complete intention have their own read models (CompleteSnapshots port) (commit fc34f26, 2026-10-02). Approval fields bounded to column widths (method type, authorization code); PaymentSnapshot builder/with methods; separate read model for complete-intention data. Closed
D-52 S1 c2: judges A L5/B L3, improve L5 Closed 2026-11-16: ErrorShape and ErrorPageController word each error in the shape of the listener whose path failed: the POS shape with Connection: close for the POS API, a shape of their own for the callbacks (commit c164686, 2026-10-02; ErrorPageControllerTest, PrismaCallbacksIT section D-52, CallbackApiKeyFilterTest). /error page is global: callback-port errors get the POS shape and Connection: close; give the callbacks their own error shape. Closed
D-53 S1 c2: review N5, judge B L5/L4/L7/L8, improve L2/L3/L4/L6 Closed 2026-11-16: the cause of a hand-over is stored in compensation_task.last_error (docs/CONVENTIONS.md section 3), the hand-over is atomic on the real transaction manager and the status poll is read-only (TransactionsIT), the DB-down 500 is documented (CONVENTIONS section 3), an amount-less terminal retry answers the stored denial (CONVENTIONS section 3) and Intention.binsReceived replaced the binsDeadlineAt setter (commit 93eaa46, 2026-10-02). Log/persist Unknown.reason (task last_error); document the DB-down 500 case; IT proving hand-off atomicity with the real transaction manager; amount-less terminal payment retry answers the stored denial; read-only UnitOfWork for polls; binsDeadlineAt setter; DOMAIN-MODEL COMPENSATION_FAILED naming. Closed
D-54 S1 c2: judge B L6 Closed 2026-11-16: PrismaConfigurationGuard refuses to start outside local and test unless gateway.intentions.id-prefix is set and differs from GPQR (commit ccb6abc, 2026-10-02; PrismaConfigurationGuardTest). Intention id prefix default GPQR not forced per environment; require a distinct prefix outside local/test. Closed
D-55 GitHub CI run 37076479272 (ubuntu) Closed in S2a (492f040): asserts only what graceful shutdown guarantees; verify on the next Linux CI. InFlightShutdownIT.d21_aRequestInFlightOnThePosConnectorFinishesBeforeTheApplicationStops fails on Linux at "a new request during the stop" (passes on Windows): the expectation about a NEW connection during graceful shutdown is OS-dependent (Linux closes/refuses the listening socket differently). Assert only what graceful shutdown guarantees (the in-flight request completes; a new request is refused OR not served), not the exact OS behavior. S2 (next fix pass)
D-56 S2a c1: improve M-3/M-4/M-5/L-2/L-3/L-4/L-6, judge B L5/L8, review notes S2b flow rules. Done in batch b (BinsWorker, CONVENTIONS section 9, rule 11): the worker finishes the INTENT_SENDING/INTENT_CREATED follow step before applying the BINs; the complete call is made only while the intention is the live one of its checkout (a superseded or cancelled one gets none); the 27 s are counted from received_at with the one gateway clock and past them nothing is sent and the payment is handed over; COMPLETE_FAILED is entered together with the hand-over in one transaction; lock order payment, intention, task with DeadlockRetry; the call goes through the bounded PrismaHttp with the wire log outside the transaction; an unknown or refused complete hands over. CheckoutRef needed no change in S2b: the catalog is read by checkout id. Done in batch c (PaymentNotificationWorker, CONVENTIONS section 9, rules 12 and 13): the purchase notification is correlated through the intention by Prisma's id, never through prisma_payment_id, checked against the checkout it states and against the offered plan (D-57), applied only through WalletResults, idempotent by wallet payment id; the reversal callbacks are stored and left unprocessed. Done in batch d (PaymentWait, AuthorizePaymentService, CONVENTIONS section 9, rules 14 and 15): payment.wait_deadline_at is persisted in the transaction that starts the authorization, counted from the arrival of the POS request, validated at startup against the caller's read timeout (R-13) and shared by retries, other nodes and restarts; the wait reads the database, not a latch; the expiry is the CompensationHandOff (the POS is denied, never SINRESPUESTA, never a 500); the status query GET /payments/qr before the deadline applies a definite answer only through PurchaseResults and WalletResults. Still open: applying the reversal notifications to the Reversal aggregate, correlated by intention id and never through prisma_payment_id (S4, D-78); (the payment.wait_deadline_at is done in batch d, below); CheckoutRef gains merchant, branch and plan source when the plan rules need them (S3); (the S4 job re-reads the intention's Prisma id before closing a task: done in S4 batch 1;) the supersede path (AC-32) is not wired, so the residual race of a supersede that commits after the prepare and before Prisma reads the call stays (D-77). S3, S4
D-57 S2a c1: improve M-1 Closed in S2b (batch c): OfferCheck compares the notified method, BIN, installments and total with the plans of the latest complete snapshot (CompleteSnapshots.offeredMethods), to the cent (Money.sameCents); a charge that is not an offered plan (AMOUNT_MISMATCH, UNOFFERED_PLAN) is applied without amounts, never approves and goes to compensation with its facts, the cause kept with the task (OfferCheckTest, PaymentNotificationWorkerTest.d57_*, PaymentNotificationIT.d57_*). INV-06 check against the offered plans: the worker compares the notified amount with the offered plan total for (method, bin, installments) from the complete snapshot (D-51 read model); mismatch → facts only + compensation. Assumes the notified amount is the plan's total_amount (Prisma question 12) and excludes the cashback (question 19 of the research list, now question 21 of docs/PRISMA-PREGUNTAS.md, D-40): fail closed. S2b
D-58 S2a c1: review M7 If the inbox write fails (DB down) the callback exists nowhere; INV-03 then relies on Prisma retrying a 500 (unconfirmed, question 3). Local masked spool file replayed at startup, or accept and track as a risk. Hardening (RISKS)
D-59 S2a c1: judge A L7 Refused callbacks write one WARN per request: rate-limit or sample to avoid log flooding from the internet. Hardening
D-60 S2a c1 fix pass Closed in S2b (batch b): BinsWorker decides by the state of the intention, never by the dedupe: an intention past INTENT_CREATED ends the row as ALREADY_PROCESSED (no second complete, no number taken), one that is not live as NOT_LIVE (BinsWorkerTest.d60_*, BinsWorkerDatabaseIT.d60_*). The BINs dedupe favors never swallowing a second round, so a redelivery after processing (outside the window) is processed again: the S2b BINs worker must be idempotent by intention state. S2b
D-61 S2a c2 review Closed in S2b: WalletReport names our intention id, WalletResults addresses it by id (foreign or missing: since batch c nothing is written, the effect is FOREIGN_INTENTION: a result about another payment's money must not cancel or compensate a payment that waits for its own) and retries a lost race on the payment or the intention three times. Wallet results address the payment's latest intention instead of the one the result names (CONVENTIONS §3, D-48): WalletReport carries no intention id; IntentionChangedConcurrentlyException can also escape apply(). Must be fixed before the worker is wired. S2b
D-62 S2a c2 review Closed in S2b: recordWalletResult sets Payment.UNCONFIRMED_MESSAGE when the payment has no denial reason. In COMPENSATE, recordWalletResult moves the payment to COMPENSATION_PENDING without a denialReason, so the later hand-over is a no-op and the POS gets a null mensajevarios. S2b
D-63 S2a c2 review Closed in S2b: the purchase notification is dispatched from the catch-all by the bound ListenerProperties path; the relaxed-binding claim did not reproduce (Boot resolves placeholders with relaxed names), the duplicated default did. PrismaCallbacksController @PostMapping("${gateway.listeners.callbacks.payment-path:/payment}") duplicates the ListenerProperties default; relaxed-binding variants of the property would silently route notifications to the catch-all. S2b
D-64 S2a c2 review PrismaConfigurationGuard applies our 32-character key rule to Prisma's issued gateway.prisma.api-key, whose format is unknown and may block a deploy. Link to PRISMA-PREGUNTAS 19. Hardening
D-65 S2a c2 review JSON-mode masking only masks known keys: bare scalar bodies and PANs under unlisted keys are stored as received, and the PayloadMasker javadoc overclaims. Hardening
D-66 S2a c2 review CallbackApiKeyFilter logs the raw request URI of refused callbacks without masking it. Hardening
D-67 S2a c2 review Oversized callback bodies are hashed after the cut (the same first 1 MiB is a DUPLICATE); the dedupe key omits raw_type; masking runs under the UPDLOCK range lock. Hardening
D-68 S2a c2 review The persistence adapter imports config.ListenerProperties; PosListener duplicates the 16 MiB constant; the "never cuts" masker test is tautological. Hardening
D-69 S2a c2 review Speculative surface: unused CompensationHandOff overloads (handOverSuperseded has no caller), WalletFacts carried-not-stored fields, the Approval wrapper, the 21-argument PaymentSnapshot constructor, the single-key CallbackApiKeyFilter constructor. S5 / cleanup
D-70 S2a c2 review Emulator strict switches have no gateway consumer; the BoundedBody declared-Content-Length branch is untested; PrismaDeadlineIT asserts wall-clock bounds. Hardening
D-71 S2a c2 review StartPaymentService: when storePrismaId and the hand-off both exhaust their conflict retries a 201 id is lost (the javadoc overclaims "never lost"). S4
D-72 S2a c2 review Closed in S3 batch 2, in V1 in place (still editable until the first release; RUNBOOK section 6 says how to reset a development database): ck_complete_snapshot_method_bin is LEN(bin) IN (6, 8) and all digits, and ck_payment_settled_needs_result needs payment_method_type next to the final amount, the method and the installments (FlywayBaselineMigrationIT.theBinOfASnapshotEntryIsDigitsOnly..., aSettledPaymentNeedsItsFinalAmountItsPaymentMethodItsTypeAndItsInstallments). complete_snapshot_method.bin CHECK accepted 1-8 digits against a comment saying "6 or 8"; ck_payment_settled_needs_result omitted payment_method_type. Closed
D-73 S2a c3 review PayloadMasker.guarded falls back to REDACTED silently (no WARN with the exception class, no metric), so a masking regression would erase audit content unnoticed; catching OutOfMemoryError there is not justified now that the patterns are linear. Hardening
D-74 S2a c3 review Masker tests: PrismaUnparseableAnswerIT doesNotContain checks also pass on REDACTED; the 16 MiB cases mask ~18 times (slow, huge diff on failure); the 6,000-digit raw_type case is only ~1.5x the old overflow threshold; the stub HttpServer handler has no try/finally exchange.close(). Hardening
D-75 S2b batch b: numbering A terminal runs out of ticket numbers (6 digits, 999,999) and, with numbers per entry (D-25), one payment burns one number per method and BIN plus one for 112 (up to 100 with 99 BINs). At the limit the gateway fails closed: NumberRangeExhaustedException, nothing is sent, the payment is handed over (NUMBERS_EXHAUSTED, TerminalNumbersIT.inv05_*, BinsWorkerDatabaseIT.inv05_*) and every later payment of that terminal is denied until someone resets the sequence. Whether Prisma lets the numbers wrap or restart, and whether one number per method (not per BIN) is enough, is question 6 of the Prisma list (D-09, D-25). A smaller offer (one entry per method for the BINs the wallet listed) would stretch the range. Prisma answer / before go-live
D-76 S2b batch b The windows of the BINs worker: a node that dies between the commit of the prepare transaction and the call to Prisma, or whose record transaction fails, leaves the payment in COMPLETE_SENT with nothing sent or recorded; the redelivery and the next lease ignore it (ALREADY_PROCESSED). The wait of the POS hands the payment over at its deadline (batch d, done: PosWaitIT) or, when no request holds the wait any more, the reaper of S4 (AC-25, D-81); INV-01 holds because a wallet without plans cannot pay. Also: a row that keeps failing unexpectedly is ABANDONED after ten minutes, with a log line and no alert. S4
D-77 S2b batch b Two v27 gaps the worker cannot close by itself: (a) the complete intention is addressed by CUIT, branch and checkout, so a supersede that commits after the prepare transaction and before Prisma reads the call can make the call land on the newer intention (Prisma question 24; the optimistic lock only closes the race before the commit, and the supersede path of AC-32 is not wired yet); (b) a genuine second BINs round for an intention that already got its complete (COMPLETE_SENT -> BINS_RECEIVED, declared in the tables) is not wired: the redelivery is ALREADY_PROCESSED, and v27 answers a second complete with a 404 anyway (Prisma question 2). Prisma answers / S4
D-78 S2b batch c Closed in S4 batch 1: ReversalNotificationWorker claims the ANNULMENT and REFUND rows from the same InboxQueue, correlates by intention id and type, and settles the reversal and the payment; the rest of this row is the history of the design. The residual ambiguity with several charges is D-S4-4. Reversal notifications are stored, classified and never applied. The ANNULMENT and REFUND callbacks stay unprocessed (no worker of S2b claims them) and a purchase notification whose status is annulled or refunded, or whose transaction type is a reversal, is finished as REVERSAL_RESULT with its payment resolved (CONVENTIONS section 9, rule 13). S4 owns the Reversal aggregate and its worker: it claims the ANNULMENT and REFUND rows from the same InboxQueue, correlates by intention id (never through prisma_payment_id, D-56), moves COMPLETED/FAILED/COMPLETED_LATE/LATE_AFTER_REFUND and settles the payment (APPROVED -> ANNULLED/REFUNDED); the REVERSAL_RESULT rows are its second input. Whether a purchase notification carries annulled/refunded at all is Prisma question 5b. S4
D-79 S2b batch c Closed in S4 batch 1 for SECOND_WALLET_PAYMENT and every late or unoffered charge (per-charge wallet_charge, reversal and REVERSE_CHARGE task, CONVENTIONS section 11): only the second charge is annulled, never the sale; UNCORRELATED and CHECKOUT_MISMATCH rows are still for a person (the correlation by checkout and time of an unknown-outcome create stays open, Prisma question 4b). Money that no payment of ours owns, or that one payment owes twice: UNCORRELATED (an intention Prisma named that the create call never stored: a create call whose outcome was unknown and whose payment is in compensation without a Prisma id, CONVENTIONS section 3, or a stranger), CHECKOUT_MISMATCH (another checkout's notification), FOREIGN_INTENTION, and SECOND_WALLET_PAYMENT (a second, different approved wallet payment for a payment that already has one: ADR-002 says compensate, but the compensation task is per payment and annuls the first wallet payment, which would reverse the legitimate sale, so the second charge is only kept, with an error log, D-45). All of them are stored (INV-03) with an outcome an operator can query (RUNBOOK section 11) and are never applied to a payment. S4 reconciles them: for an approved one, ask GET /payments/qr?intention_id= and issue a forced annulment keyed by that notification's own intention, method, establishment, trace and ticket numbers, which needs a per-result reversal model (Prisma question 4c) and, for the uncorrelated unknown-outcome create, a correlation by checkout and time against the payments in compensation without a Prisma id (question 4b). S4-blocking (S2b c1 review): S4 cannot close, nor can the system go live, while this is open, because the rule it breaks is written in ADR-002 itself. ADR-002 says a second, different charge on a payment is compensated; the compensation task is per payment and annuls the first wallet payment, so doing as the ADR says would reverse the legitimate sale. ADR-002 amended 2026-10-04 (human-approved, commit 22c8cc9): one reversal per wallet charge (Prisma payment_id); the sale's charge is the one that moved the payment to APPROVED, every other charge on the intention is annulled, and a "no sale" answer annuls every charge. S4 builds the compensation job on that wording. S4 (blocking)
D-80 S2b batch c The notification worker applies the result (WalletResults.apply, its own transaction with the retry of a lost race) and finishes the inbox row in a second step: a node that dies between them leaves the row to its lease, and the next worker applies the same result again, which is a DUPLICATE by wallet payment id. The payment is right (AC-10); only the audit row says DUPLICATE instead of what the first node did (APPROVED, COMPENSATE, ...). Making them one transaction would need WalletResults.apply to run inside the caller's transaction, whose retry loop and the rollback-only flag of a lost optimistic race do not compose. Hardening
D-81 S2b batch d Closed in S4 batch 1: OrphanWaitReaper hands over every wait whose deadline passed more than gateway.compensation.reaper-grace ago (filtered index ix_payment_waiting_deadline; OrphanWaitReaperTest, CompensationFlowIT.d81_*). A wait that nobody holds any more is not expired by anyone yet. If the node that held a trxpago dies and the POS never retries it, the payment stays INTENT_SENDING, INTENT_CREATED, BINS_RECEIVED or COMPLETE_SENT with a wait_deadline_at in the past until a retry of trxpago (which hands it over at once) or the reaper of S4 (AC-25) does. GET /api/trxes/{id} does not expire it: polls are read-only on purpose (CONVENTIONS section 3), and the POS that polls it is told the state of a payment that is, from its side, still waiting. The reaper's query is state IN (the four waiting states) AND wait_deadline_at < now (ix_payment_state_updated_at serves it by state; add a filtered index on wait_deadline_at if the table grows). S4
D-82 S2b batch d Narrowed 2026-11-16 with docs/LOAD-FAULTS-REPORT.md (one node, repo defaults, real wait deadlines, Hikari 20; harness tools/load-test, not an IT): a ramp of 1, 10, 25 and 50 concurrent checkouts, each one a blocking trxpago, kept every invariant (PASS, 0 violations, 0 pending); 25 checkouts gave 14.3 payments/s with a BINs callback p95 of 182 ms and the throughput saturates at 13 to 14 payments/s, 2.7 times the design target of 5/s (section 4.3); the 22 minute soak (section 4.6) and the pool exhaustion under three 25 s table locks (section 4.5) PASS too, and the pool (20) is never what loses a payment (F4). Still open, small: the waits of that load were short (the emulated wallet answered at once), so many waits asleep for tens of seconds at the same time are not measured; the rate limit of Prisma for the status query is still a question to ask (v27 gives none: 100 simultaneous waits are about 20 queries per second in the last 15 s); and one status query is not shared between the duplicates of one payment. Hardening
D-83 S2b batch d The defaults come from the development values, not from verified production ones: RouterQR timeout-pago 60 s (read 59 s) gives deadline 45 s + hand-over budget 12 s + safety-margin 2 s = caller-read-timeout 59 s (the budget is what is left, see RUNBOOK section 3). The production RouterQR profile and the read timeout of the DOS POS on the direct VPN (R-13, R-14) are unknown; the gateway refuses to start when the three settings do not fit, but only the person who sets caller-read-timeout knows whether it is true. RUNBOOK section 3 says where; the E2E log shows the POS waiting 80 s for the first trxpago and polling GET /api/trxes/{id} every 10 s afterwards, which the 45 s default leaves room for. Human (verify before go-live)
D-84 S2b batch d (updated in the c3 fix pass) Two decisions of batch d to review. (a) A wait that is interrupted (the server is being stopped past its grace period) gives up like an expiry: the payment is handed over and the POS, if its socket is still there, is denied; the alternative, leaving the payment waiting for a retry on another node, would keep a customer able to pay for as long as the retry takes. An interrupt shortens nothing (c3, G1): the hand-over is tried until the same arrival-based cap as an expiry, arrival + caller-read-timeout - safety-margin (57 s with the defaults, WaitPolicy.giveUpAt), and only when that instant is reached with the storage still out is the POS denied without a persisted intent, with the INV02_UNPERSISTED_DENIAL alert. The 2 s budget counted from the interrupt (interruptedHandOffAllowance) was wider than the approved exception and is gone. If the process is killed first no answer is sent, which is not a breach. Graceful shutdown lets every wait finish first (every request lives at most until its arrival + 57 s, inside timeout-per-shutdown-phase 60 s, which TimingGuard checks against that same maximum); the web server drains before any bean is destroyed, so the wait executor never closes under a wait, and it is stopped with shutdownNow and a 2 s grace instead of close() (WaitExecutorConfiguration) so a stuck JDBC call cannot hold the stop. (b) Nothing asks Prisma after the hand-over: a payment the wallet pays after the expiry is found by its late notification (INV-03) or, if that never comes, by the status query of the compensation job of S4 (GET /payments/qr before the cancel, ADR-002). S4 / review
D-85 S2b batch d Two costs accepted. (a) There is no in-process latch on top of the database poll, so a result applied on the same node still reaches the POS up to one poll interval (250 ms) later; a latch could only shorten the sleep, never replace the read, and is worth adding only if that latency is measured to matter. (b) A result found by the status query leaves no inbound_notification row: its audit is the QUERY_PAYMENT row of the wire log and the effect on the payment (the outcome vocabulary of the inbox, CONVENTIONS section 9 rule 6, does not apply to it). Hardening
D-86 S2b batch e (E2E suite) Closed in batch e (JdbcWireLog.paymentOf, WireLogLockOrderIT.d86_*): found by PosFlowsE2EIT (flow 6 failed in 2 of 3 full runs, the POS denied at the deadline), root-caused from the SQL Server deadlock graphs, fixed test-first. The wire log inserted a callback's row with the payment found by a subselect on intention in the same statement; the read of the intention was still held while the foreign key waited for the payment row, the reverse of the order of every writer (payment, then intention, D-49), so a callback (BINs or notification) racing the worker that moves the same payment was a deadlock of two that SQL Server breaks only after up to five seconds (waittime 3.5 to 4.9 s in the graphs), the callback answered that late and the 3 s wait of the E2E (the 45 s of production would have absorbed it, but AC-07's 200 ms and the 27 s of the BINs would not) lost the payment to the hand-over. The payment id is now read in a statement of its own, before the insert. Money was never at risk (the victim is retried, INV-01 holds); the cost was latency. Review: this is production code changed in the E2E batch, in its own commit; the alternative is a NOLOCK hint on the subselect (one line, dirty correlation) or passing the payment id from the callbacks controller. Other readers that sit in a statement with a write (FIND_EARLIER of the inbox under UPDLOCK, HOLDLOCK) were not seen in a graph and are not changed. Review
D-87 S2b c1 review (H1 fix) Closed in the S2b c2 fix pass, by the amendment of INV-02 and ADR-002 that the human approved on 2026-10-04: the price is paid by an invariant of the domain, not by a window. One line of the original entry: when the expiry of a wait cannot be persisted, the POS is still denied and the payment stays waiting, so a wallet result applied before a retry or the reaper could have approved a sale the POS was told was denied. Payment.recordWalletResult now never approves once now >= wait_deadline_at (and, since c3, never for a payment with no persisted deadline): the result is recorded and compensated, whoever applies it (PaymentLateResultTest.inv02_*, PaymentNotificationWorkerTest.inv02_*, PurchaseStatusFallbackTest.inv02_*, PosWaitStorageFailureIT.inv02_*); every answer without a persisted intent raises the INV02_UNPERSISTED_DENIAL alert (RUNBOOK section 3). What stays open is the approval that another node committed before the deadline while this node could not read it: D-105. Closed (the remainder is D-105)
D-88 S2b c1 review The loop "run the transaction again when the optimistic lock was lost, three attempts" is written five times (BinsWorker.withConflictRetry, PurchaseResults.withConflictRetry, WalletResults, StartPaymentService, and PaymentWait before this pass, now with its own budgeted form): one helper next to UnitOfWork would give them one policy and one test. Cleanup (S5)
D-89 S2b c1 review Fixed Thread.sleep calls stand in for "nothing happens" in PosWaitIT (300 ms), PosWaitMultiNodeIT (300 to 400 ms) and PaymentNotificationIT (300 ms): a slow machine passes them by luck and a fast one wastes the time. They should poll the condition, or assert the absence through a counter the system exposes. Hardening
D-90 S2b c1 review PosWaitIT.ac04_aRetryThatArrivesAfterTheResultReturnsItAtOnce (and its twin for the expiry) asserts an absolute < 800 ms: it measures the machine as much as the code, and fails on a loaded CI runner. Assert it relative to the poll interval, or assert that no second wait began (no extra read of the payment). Hardening
D-91 S2b c1 review WaitPolicy.expired and statusQueryDue take a parameter named deadline that shadows the record component of the same name (the length of the wait): they compile and are right, and read as the opposite. Rename the parameter to endsAt. Cleanup (S5)
D-92 S2b c1 review The range checks are written three times: requireBetween in InboxProperties and PosWaitProperties, requireInRange in PrismaProperties, and WaitPolicy repeats the "poll and lead shorter than the deadline" rules of PosWaitProperties. One validation helper in config (and WaitPolicy trusting its record) would keep them from drifting; TimingGuard now holds the rules that cross records. Cleanup (S5)
D-93 S2b c1 review The NotYet / OtherCheckout / Found switch over PurchaseResults.Resolution is repeated in PaymentNotificationWorker and PurchaseStatusFallback, each with its own log and outcome: a fourth resolution has to be handled in both. A method on Resolution or on PurchaseResults that takes one handler per case would keep them together. Cleanup (S5)
D-94 S2b c1 review PurchaseResults.apply threads a nothingWasOffered boolean through causeOf and outcomeOf and probes notification.facts(null) only to learn whether the facts are usable: parameters that exist to steer a switch. A small result type (verdict plus cause plus outcome) would remove them. Cleanup (S5)
D-95 S2b c1 review BinsWorker.drain() and PaymentNotificationWorker.drain() are called by tests only (the runner calls processNext): production code that exists for the tests. Move the loop into a test helper. Cleanup (S5)
D-96 S2b c1 review @WorkerIntegrationTest closes its context after every class (@DirtiesContext, so a worker of a cached context cannot take another test's rows): every such class pays a full application start (about 8 to 10 s), and the IT stage grew accordingly (PosWaitIT, PosWaitMultiNodeIT, PaymentNotificationIT, PosFlowsE2EIT, InboxLanesIT, PosWaitStorageFailureIT). A cached context where the worker is stopped between classes would cut it. Hardening
D-97 S2b c1 review InboxClaimIT and BinsWorkerDatabaseIT begin by finishing every unprocessed row of the shared database with the outcome TEST_CLEANUP: that is only correct while the IT classes run one after the other (CONVENTIONS section 6 says so now). Two classes in parallel would finish each other's rows. A per-test schema or a row filter by test would lift it. Hardening
D-98 S2b c1 review The purchase notification is dispatched when the request path equals the bound payment-path exactly (D-63): a trailing slash, a double slash or a different case reaches the catch-all (stored as UNKNOWN, nothing lost, but never applied until a person reads it). Whether Prisma normalizes the path is not said (question 5). Hardening
D-99 S2b c1 review JacksonBinsDecoder.binOf turns a numeric BIN into text with String.valueOf(long): a BIN that starts with 0 and arrives as a JSON number loses the zero (six digits become five) and then never matches an offered plan. v27 says a BIN is a number; a text BIN keeps its zeros. Pad to the six or eight digits the bank uses, once Prisma says which. Prisma answer
D-100 S2b c1 review OfferCheck.sameCard accepts a notified BIN that is a prefix of the offered one or the other way round, so a 1-digit (or very short) BIN in a notification matches every entry of the method that begins with it. It fails open for the card, and closed only for method and total. Require at least six digits, as v27 gives them. Hardening
D-101 S2b c1 review Closed 2026-11-16, out of scope: production runs a single node (2026-11-16). The text is kept so the entry can be reopened if HA is ever added. Several nodes share one persisted wait_deadline_at and the 27 s of the BINs counted from received_at, both written and read with the clock of each node, while the claim leases use database time (D-05): a node whose clock is seconds off ends a wait early or late, or sends a complete intention it thinks is on time. The deadline is stamped on the node that received the request and compared on the node that applies the result (Payment.recordWalletResult) and on the one that drains the BINs (BinsWorker.prepare, c3 G3), so a skew moves the instant an approval stops being an approval. NTP on every node is a requirement (RUNBOOK section 2, added in c3: keep the skew well under the 1 s minimum safety margin); a deadline computed with database time would remove the assumption. Closed (out of scope: single node; reopen with HA)
D-102 S2b c1 review When a wait ends, StatusQueries.cancel() interrupts the question that is still out (cancel(true)). If that thread has just got a definite answer and is applying it (PurchaseResults.apply, a transaction), the interrupt can cut the apply: the connection pool refuses a connection to an interrupted thread and the result is left for the late notification or, if there is none, for nobody (D-84b: nothing asks Prisma after the hand-over). Let an apply that has begun finish (interrupt only the call to Prisma), or ask again from the compensation job of S4. S4
D-103 S2b c1 review WireLogLockOrderIT waits until "some session is blocked on a shared lock" by counting sys.dm_exec_requests of the whole database, so another test's wait would satisfy it: it holds today because IT classes are sequential (D-97). Filter by the session of the blocked insert. Hardening
D-104 S2b c1 review PosWaitIT.r13_* and PosWaitStorageFailureIT accept an answer up to 50 ms BEFORE the deadline (deadline.minusMillis(50)): the wait never answers early, so the tolerance hides a regression instead of covering a clock error (both sides use the same millisecond clock). Assert >= deadline. Hardening
D-105 S2b c2 review (INV-02 amendment; updated in the c3 fix pass) Closed in S4 batch 1 and merged with the approval markers of the S2 line (D-S4-5, D-S4-12): UnpersistedDenialReconciler settles the durable local marker of every unpersisted denial (a payment still waiting is handed over; an approved one is annulled through the per-charge reversal only if BOTH pos_told_approved_at and pos_approval_intent_at are empty after wait_deadline_at + gateway.compensation.pos-polling-window; a payment the POS heard as approved is never annulled, INV-01 amended 2026-10-04). The compensation only reads the two markers (PosApprovals); the POS answer path (PosApprovalGuard, PosApprovalMarkerFilter) writes them. RUNBOOK section 3 describes the operator steps, including POS_APPROVAL_UNRECORDED and POS_APPROVAL_DEFERRED. History of the design: S4 reconciliation (S4-blocking). The exception to INV-02 lets a node answer "no sale" with no persisted intent when it cannot reach the database for the whole time left before the caller's read timeout. The domain invariant covers an approval applied at or after the deadline (D-87) and, since c3, a payment with no persisted deadline, and BinsWorker.prepare never sends a complete intention once the deadline has passed (WAIT_EXPIRED: a BINs row stored before the denial and drained when the storage returns sends nothing, handled, BinsWorkerTest.s2b_c3_*, BinsWorkerDatabaseIT.s2b_c3_*). What only a reconciliation can close, because nothing was stored when the POS was answered: an approval committed before the deadline by another node while the answering node could not read the payment: the payment is APPROVED and the POS was told "denied" on trxpago. That is not necessarily an unrecorded sale (S2b c5 judges): a direct-VPN POS keeps polling GET /api/trxes/{id} after the denial and closes the sale as "APROBADA via CONSULTA" when the consulta answers approved (pos_ctoq.cpp 3755 and 3890-3894; the cashier's "Reintenta" prompt can extend the window); via RouterQR the consulta answers 404 for a trx it does not hold as approved. The reconciliation must therefore annul only when the POS never heard "approved": the gateway must durably record that it answered a POS (trxpago or consulta) with an approved estado (e.g. payment.pos_told_approved_at), and the reconciliation annuls an alerted APPROVED payment only when that marker is absent after the POS polling window. Since c3 an interrupted wait denies only at the same cap as an expiry (after the deadline), so what used to be a second case, a denial before the deadline on an interrupt, is this one. Two things make the alert imperfect, both to be handled by hand until the reconciliation exists: (1) a false alert: an attempt that the wait cut at the cap (future.cancel(true)) can still commit later, because the interrupt does not always stop a JDBC call, so the payment is COMPENSATION_PENDING with a task although the alert fired (RUNBOOK section 3, item 2: nothing to do); (2) clock skew between nodes (D-101) moves the deadline an approval is compared with, so an approval a few hundred ms either side of it may be classified differently than the node that answered the POS thought. Detect them through the INV02_UNPERSISTED_DENIAL payment=<id> alert, which is the only record of the denial (RUNBOOK section 3: wire it to an alert and handle every line by hand until this exists), and through a reconciliation query over payments that are APPROVED, or still waiting, with wait_deadline_at in the past, no compensation_task and an id the alert named; then compensate only if pos_told_approved_at is absent after the POS polling window (the forced annulment of an approved payment, the cancel of the intention otherwise). S4 cannot close, nor can the system go live, while this is open: it is the money-leak class that D-87 described, narrowed to a storage outage that spans a deadline. The marker now exists (feat/s2-prisma, INV-01 amended 2026-10-04): payment.pos_told_approved_at DATETIME2(3) NULL (V1, UTC, database time), the first instant the gateway finished writing an AUTORIZACION_DE_PAGO_APROBADA answer to the POS, on trxpago or on the consulta, RouterQR-shaped requests included (PosApprovalMarkerFilter records it after the body was written and flushBuffer() returned without an I/O error; first instant kept; no version or updated_at change; CONVENTIONS §4 and §9 rule 16). What S4 must do with it: read the column with SQL (it is not in PaymentSnapshot), and annul an alerted APPROVED payment only when pos_told_approved_at is absent after the POS polling window ((profile 496 / 3) × 2 s after the denial, longer if the cashier extends it) AND the log holds no POS_APPROVAL_UNRECORDED payment=<id> (the line that says the POS heard "approved" and only the record failed: RUNBOOK §3, it is a sale); a payment with the marker set is a sale and is never compensated as a no-sale. Two limits to carry into the reconciliation: a process that dies between the flush and the record leaves a sale with no marker and no alert (the POS journal is the last check, RUNBOOK §3 step 3), and the flush proves the bytes were handed to the connection, not that the POS read them. Second marker (S2b, S4 judge HIGH, human-approved follow-up): payment.pos_approval_intent_at DATETIME2(3) NULL (V1, UTC, database time), the first instant the gateway durably recorded, BEFORE answering, that it was about to tell the POS AUTORIZACION_DE_PAGO_APROBADA (PosApprovalGuard through PosApprovals.recordApprovalIntent, on trxpago and on the consulta, RouterQR-shaped requests included; CONVENTIONS §4 and §9 rule 16). Why: one database brownout could cause both an INV02_UNPERSISTED_DENIAL and a failed pos_told_approved_at write on the later consulta that told the POS "approved", and the reconciliation above would have annulled a sale the POS printed. Now the gateway never answers approved without a durable intent: if the write fails it answers INTENCION_DE_PAGO_RECIBIDA_APROBADA (statuscode 0, none of the approval's fields) and logs POS_APPROVAL_DEFERRED payment=<id> path=<trxpago|consulta> failure=<class>, and the next consulta (10 s later) retries. S4 rule, replacing the one above that reads only pos_told_approved_at: auto-annul an alerted APPROVED payment only when BOTH pos_told_approved_at AND pos_approval_intent_at are NULL after the POS polling window; when either is set the POS may have heard approved and a person decides (POS journal first, RUNBOOK §3 step 3). With both NULL the POS never heard approved. The residual case of a process that dies between the intent write and the answer is D-124. S4 (blocking)
D-106 S2b c2 review Closed 2026-11-14: the BINs callback is asserted at p95 < 200 ms (with 48 samples p99 equals the max), the max is still printed; AC-07 reads p95. The hard maximum of CompleteIntentionIT.ac07_theBinsCallbackAnswersUnder200ms... (every one of the 48 BINs callbacks under 200 ms, the max, not a percentile) is sensitive to a GC pause or a loaded runner: it measures the machine as much as the code (like D-90). Assert the p99 against 200 ms and print the max. Hardening
D-107 S2b c2 review The rationale that TimingGuard gave for the lease rule ("another drainer claims the row while the first is waiting for Prisma and two complete intentions are sent") is not what CONVENTIONS section 9 rules 8 and 11 say: a second complete for an intention that already got one is a 404 at v27, and a drainer that lost its lease can no longer finish or defer the row (ClaimOwners). The real cost of a short lease is two drainers calling Prisma for one row, and the 5 s LEASE_MARGIN is a rule of thumb for the writes around the call and for clock skew, not a measured value. The javadoc no longer claims "two completes"; state the real reason, and pick the margin, from a measurement under load. Hardening
D-108 S2b c2 review Narrowed 2026-11-16 with docs/LOAD-FAULTS-REPORT.md: measured, not changed. With the defaults (inbox max-concurrent 16 per kind, Hikari 20) the pool is fully used from 10 concurrent checkouts on and nothing is lost: 25 checkouts gave 14.3 payments/s and a BINs callback p95 of 182 ms (section 4.3, F4); with three 25 s table locks the pool is exhausted, trxid is refused 12 times with a 500 (pool timeout 5 s) and no trxpago is lost (section 4.5). What stays open is the decision itself: cap the sum of the drainers under the pool or give them a pool of their own. The load-shaped IT of D-82 is no longer a precondition. Original text: gateway.inbox.max-concurrent is per kind of work: up to 16 BINs plus up to 16 notifications are 32 drainers against a Hikari pool of 20 that also serves the POS requests, the polls of the waits and the compensation job. A burst of both kinds can want more connections than the pool has; the polls then fail with a pool timeout (survived since S2b H1, but each costs up to 5 s of a wait). Cap the sum under the pool or give the drainers a pool of their own, and include it in the load-shaped IT of D-82. Hardening
D-109 S2b c2 review (updated in the c3 fix pass) NSSM's AppStopMethodConsole 65000 was 5 s over timeout-per-shutdown-phase (60 s), but the inbox runner stops after the web server has drained (getPhase()), so the real stop is the drain (up to the longest request: 57 s with the defaults, counted from its arrival) plus the runner's own stop (rows in flight; it waits up to 30 s for its pool, InboxWorkerRunner.STOP_WAIT_SECONDS) plus the 2 s grace of the wait executor: 65 s is not enough for a 57 s drain and a row in flight. The RUNBOOK now says so and gives AppStopMethodConsole 100000 (60 + 30 + 2 + 8 s of slack, section 2); if timeout-per-shutdown-phase changes the value moves with it. Updated (2026-10-28): 100 s still left out CompensationJobRunner.stop(): both runners share the phase below the drain and the lifecycle processor stops them one after the other, so the budget is 60 + 30 (inbox) + 30 (compensation) + 2 = 122 s and the RUNBOOK now gives AppStopMethodConsole 130000 (8 s of slack; keep it 70 s above timeout-per-shutdown-phase). Making the two stops run in parallel was not done: it needs an asynchronous stop(Runnable) and a phase timeout that can cut a runner. Still to do: measure the stop under load and confirm that 130 s is enough or shorten the waits. Before go-live
D-110 S2b c2 review The stalled-pool tests of PaymentWaitTest (s2b_h1_aStalledPoolIsCutAtTheTimeThatIsLeftBeforeTheDeadline, s2b_h1_anExpiryThatStallsIsCutAtTheHandOverBudgetAndThePosIsStillDenied) only assert that the whole wait took under 5 s, which a cut ten times too long would still pass. inv02_aStalledAttemptOfTheExpiryIsCutAtWhatIsLeftOfTheBudget records how long each stalled call lasted and asserts both a lower and an upper bound: give the two older tests the same. Hardening
D-111 S2b c2 review InboxClaimIT calls TimeZone.setDefault(America/New_York) for the whole JVM during a test (PersistenceAdaptersIT does the same, and restores it): the default zone is global state, so any test that ran in parallel would read it (the IT classes are sequential, D-97). Hand the zone to the code under test (the Clock, the jdbc.time_zone setting) instead of changing the JVM's. Hardening
D-112 S2b c2 review InboxShutdownOrderIT coordinates the test and the application through two static final CountDownLatch (ENTERED, RELEASE): they cannot be reset, so the class works once per JVM, and a rerun of a failed test or a second test in the class would find them already spent. Make them per-test fields reachable through the Spring context. Hardening
D-113 S2b c2 review (pre-existing) BinsWorker.handOverAfterTheCall finishes the row with the outcome that caused the hand-over (COMPLETE_REFUSED, COMPLETE_UNKNOWN, PAST_DEADLINE), but when the lease was already lost it only logs "what the call answered is kept": the new holder ends the row as NOT_LIVE and the refused outcome survives only in the compensation task's last_error and the log, never on the audit row (the same family as D-80). The same happens when the hand-over itself loses its optimistic race three times: the exception reaches the caller, the row is deferred, and the next holder finds the intention still COMPLETE_SENT and ends it ALREADY_PROCESSED, so the refusal is dropped altogether and the payment waits for the hand-over of the POS wait at its deadline (or the S4 reaper, D-76). Write the outcome with a conditional update on the row's state, or record it on the task only and say so in RUNBOOK section 10. Hardening
D-114 S2b c3 review PaymentWait.expire treats every RuntimeException of a hand-over attempt as a storage failure and retries until the cap, so a defect that is not the storage (a payment that vanished mid-expiry, the IllegalStateException of "waits for the wallet without an intention", a mapping error) holds the answer to the cap (57 s) and then raises INV02_UNPERSISTED_DENIAL although the database is reachable: a false alert and a slow denial, never a wrong money outcome (the POS is still denied and the payment is left for a retry). Classify the failures (transient storage versus defect) and fail fast on a defect with its own log line. S4 / hardening
D-115 S2b c3 review PosWaitProperties validates deadline + safety-margin + poll-interval <= caller-read-timeout and calls it "room for one real attempt", but an attempt is only cut at what is left of the budget and the pause between attempts is one poll interval: with the defaults (12 s of budget, 5 s Hikari connection-timeout) two or three attempts fit, with a small budget (a read timeout close to the deadline) a single attempt can use all of it and a pool that needs its 5 s to refuse gives the expiry no second try. The validation promises one attempt per poll interval of budget, not that one attempt can finish; a stricter rule would require the budget to be at least the pool's connection-timeout. Before go-live
D-116 S2b c3 review A storage attempt that the wait cuts (future.cancel(true), PaymentWait.bounded) interrupts a virtual thread, but a JDBC call blocked in the driver or in Hikari may not look at the interrupt: the thread, and the connection it holds, can stay out until the driver's own timeout. Repeated cut attempts during a long outage can therefore pile up held connections and starve the pool for the workers that serve the other payments (the wait executor is unbounded, one virtual thread per task, WaitExecutorConfiguration). Measure it against a real database outage and set the datasource socketTimeout/loginTimeout and a cap on concurrent attempts if it shows. Before go-live
D-117 S2b POS E2E The Almacor DLL never shows the mensajevarios of a denial: it reads it only on an approval (the authorization code) and its sterror is never filled from a denied trxpago or consulta, so the reason the gateway stores (79 bytes, D-42, D-62) does not reach the cashier's screen. The cashier sees only the DLL's own "Denegado" texts. Needs a POS release that reads and shows it (R-07, the same POS work as modes A and surcharges). POS team (R-07)
D-118 S2b POS E2E A trxanulacion that times out makes the POS fall back to a consulta (pos_ctoq.cpp about 3831 and 3529), where AUTORIZACION_DE_PAGO_APROBADA counts as "annulled by consulta": a payment that was approved and whose annulment the gateway never answered is shown to the cashier as annulled, with the money still charged. S4 must make trxanulacion answer reliably (idempotent, inside the POS's 5 s read, AUTORIZACION_DE_ANULACION_APROBADA only when the reversal is done or safe); POS team note for the fallback. S4 / POS team
D-119 S2b c4 judges, D-a Closed 2026-11-16, out of scope: production runs a single node (2026-11-16). The text is kept so the entry can be reopened if HA is ever added. On one node the clamp can only happen across a restart that lowers gateway.pos.wait.deadline while waits are in flight: change it in an off-peak window. PaymentWait.clamped ends a request's wait at its own arrival + deadline when the payment's persisted deadline is later (deadlines that differ by more than the 12 s budget across nodes or during a rollout of gateway.pos.wait.deadline). If that request then cannot persist the hand-over it denies the POS before the persisted deadline, and a wallet approval committed in between is still approved: the POS was told "no sale" for a charged and approved payment (RUNBOOK section 3, step 3 of the alert). The alert line now carries persisted_deadline_clamped=true for it (done); the exposure itself stays, so roll a change of the deadline out with one value on every node, or make the approval path refuse a payment whose wait was clamped. Note (S2b c5 judge): an approval here is not necessarily an unrecorded sale; a direct-VPN POS keeps polling the consulta after the trxpago denial and records the sale when it reads approved, so any manual reversal first checks payment.pos_told_approved_at and then the POS journal (RUNBOOK §3 step 3, D-105). Closed (out of scope: single node; reopen with HA)
D-120 S2b c4 judges, D-b A start() of trxpago that overruns latestAnswer (the start transactions, begin and create-intention bookkeeping, have no query or lock timeout of their own) denies the POS without any attempt to persist the hand-over: the wait is entered with no time left. Give the start transactions a lock and query timeout bounded by what is left of the request, or count their time out of the deadline. Hardening
D-121 S2b c4 judges, D-c A BinsWorker prepare that commits late can still send the complete intention after the wait deadline of the payment. Guarantee (1) compensates it: the payment is handed over at its deadline, so a late approval is compensated, never approved. Closing it would mean the worker checks the deadline in the same transaction that claims the row, and again immediately before the call. Hardening
D-122 S2b POS E2E Notes for running the real Almacor POS against the gateway (POSKIT_GPQR README): the POS needs DOSBox-X memsize=32 (it dies at start with 64 or 128), and the profile audit that neutralizes the network addresses must read full dumps of DM_PROFI (a stricter name pattern missed profiles with a space in the name, 506-512 "CAE ..."), or the POS reaches a real address. Keep both in the E2E runbook of S5. S5
D-123 S2b POS E2E PosWaitProperties and TimingGuard do not refuse the RouterQR default deadline (45 s) with the 50 s caller of the direct-VPN Almacor POS: 45 + 2 + 0.25 s fits in 50 s and the guard only asks for one poll interval of hand-over budget, so the expiry gets 3 s instead of 12 s (AlmacorCallerProfileTest). RUNBOOK section 3 gives the profile (deadline: 36s); a stricter rule (a minimum budget, D-115) would stop the wrong one at startup. Before go-live
D-124 S2b approval-intent pass (S4 judge HIGH) A process that dies between the write of pos_approval_intent_at and the answer (a crash, a kill, a restart between PosApprovalGuard and the flush) leaves the intent set with no approved answer sent, so the POS may have heard nothing and a payment that is APPROVED has pos_approval_intent_at set and pos_told_approved_at NULL with no POS_APPROVAL_UNRECORDED and no POS_APPROVAL_DEFERRED line. That is safe: S4 never auto-annuls a payment with either marker set (D-105), a person decides from the POS ticket journal (RUNBOOK §3 step 3); the cost is a manual check, never a wrong reversal. Two accepted costs of the same design: an approved consulta writes one more small UPDATE (a no-op once the intent is set), and with the database down the intent write can hold the request for the pool's connection wait (5 s) before the deferred answer, inside the 10 s the POS waits between consultas. A possible hardening: skip the write when the payment already carries the intent (a read that would fail the same way under a brownout, so it buys little). Hardening pass (2026-10-28): the deferred answer itself (intent write failed, database down for the whole POS consulta loop of about 100 s) used to leave an APPROVED payment with both markers NULL that nothing looked for (only UnpersistedDenials.pending() feeds the reconciliation), so the cashier cancelled and the customer stayed charged with no sale. Now PosApprovalGuard calls UnpersistedDenials.note(paymentId) on the deferred path: once the database is back the existing reconcileApproved rule annuls the sale when both markers are NULL and the polling window is over, and leaves it for a person when either is set. If the marker cannot be written either, POS_APPROVAL_DEFERRED_UNNOTED is logged and the manual step of RUNBOOK §3 is the fallback (PosApprovalGuardTest, CompensationFlowIT d124). S4
D-125 S2b numbering pass (S5 judge, INV-05) Closed in S2b: the terminal number of a complete intention comes from the statement that takes the numbers. BinsWorker.prepare read the terminal number with terminalOf (no lock), ran several statements, and only then allocateNumbers took the row lock while recordComplete stored the stale number: an ADMIN of the S5 console renaming a never-numbered terminal in between made the sale send (oldNumber, 1, 1) while the terminal continued as the new number from trace 2, and a terminal later created with the old number sent (oldNumber, 1, 1) again. UPDATE terminal ... OUTPUT INSERTED.terminal_number, ... now returns the number (NumberBlock.terminalNumber) and the worker uses it in the body and in the snapshot (BinsWorkerTest.d125_*, BinsWorkerTerminalRenameIT, TerminalNumbersIT.d125_*, CONVENTIONS section 9 rule 10). terminalOf stays as the fail-closed check that the checkout has a terminal. S2b
D-S3-1 S3 batch 1 Closed 2026-10-04: the human confirmed branch-first specificity (a branch plan beats a merchant plan before card specificity is compared), which is the implementation; recorded in docs/CONVENTIONS.md section 9a. Mode A has no branch axis (one POS per branch, first row by POS order). The original entry: Specificity order of mode B is a decision of the slice, to confirm with the human: a plan of the branch beats a plan of the merchant whatever they say about the card, and then BIN range > bank > payment method (docs/CONVENTIONS.md section 9a, rule 2). The documents list the two axes without saying which dominates; the other reading (card first, branch as the tie-break) is a change of one Comparator in GatewayConfiguredPlanSource and of the tests ac13_aPlanOfTheBranchBeats.... Closed
D-S3-2 S3 batch 1 Console part closed in S5 batch 3 (2026-10-28): the console refuses to save a plan that ties with another enabled plan of the merchant, a 409 that names the other plan, checked over all the rules of the merchant at once under the merchant lock (PlanTies, PlanAdminService; PlanTiesTest, PlanAdminApiIT.ac13_*, PlanCreateRaceIT); see D-S5-17 for what it is stricter about than the engine. A tie fails the whole offer, not just that installment: two plans that tie for a card are a PlanConfigurationException (an OfferNotPossibleException), so the BINs row is NO_OFFER and the payment is handed over (fail closed, the cause names the plans in compensation_task.last_error). The alternative (leave that installment out) would hide the error and sell with fewer plans. The console (S5, AC-13 last clause) must refuse to save a plan that ties with another one that can apply on the same day to the same card; this check over all the rules of a merchant at once (not per card and day) is not written, only the comparison (InstallmentPlan.ofABranch(), cardSpecificity()) it needs. S5
D-S3-3 S3 batch 1 TNA and CFT are stored, not computed (PLANES-CUOTAS D7). The gateway only checks the structure (a surcharge has both above zero and cost >= rate, any other plan has both at zero) and sends them as percentages with two decimals (40.05): provisional until Prisma answers question 8. It does not compare them with the French-system reference of docs/emulador-qr.html; if the human wants the gateway to derive them (mode A has none, dM_TarPl lacks them) that is a regulatory decision, not a technical one. Prisma question 8
D-S3-4 S3 batch 1 Cuotas MiPyME code is not sent to Prisma: v27 has no field for it (question 9); MipymePlans (13 = 3, 16 = 6) is the seam and the code is kept on the offered plan, the complete snapshot and the payment. A regular plan and a MiPyME plan with the same installments tie unless one is more specific, so a merchant that offers both for one card must separate them by bank or BIN range. Prisma question 9
D-S3-5 S3 batch 1 The remainder of the per-installment rounding is not reconciled (amount_per_installment x quantity can differ from total_amount by a few cents, 112000.00 / 6 gives 112000.02); the notified amount is checked against total_amount. If Prisma charges the sum of the installments (question 11) or the last installment must absorb the difference, PlanFigures is the one place to change. Prisma question 11
D-S3-6 S3 batch 1 The plan catalog is read from the database on every BINs row (two small indexed queries inside the prepare transaction; ix_installment_plan_lookup). AC-07's 3 s p99 is measured against the emulator, not under load with many plans: if the read shows up, cache per merchant with a short TTL (a merchant change must be visible within seconds). Hardening
D-S3-7 S3 batch 1 gateway.plans.zone defaults to America/Argentina/Buenos_Aires and is read at the instant the offer is built (the clock of the BINs worker): a plan valid until a date ends at midnight of the shops, not of the server. The V1 schema has no time of day (valid_from/valid_to are DATE); a plan "from 18:00" would need a migration. If the merchants ask
D-S3-8 S3 batch 1 Withdrawn with Mode A (human decision 2026-10-28; the code is recoverable from the tag mode-a-reference). Original row, kept for the record: Closed in batch 2: PosSuppliedPlanSource exists (docs/CONVENTIONS.md section 9b), the promotions are stored and capped (D-41) and D-72 is fixed in V1 in place. Mode A is batch 2: until PosSuppliedPlanSource exists a POS_SUPPLIED merchant gets BaselinePlanSource (1 installment, no adjustment) and the promos of D-41 are not stored or capped yet; D-72 (the CHECK of complete_snapshot_method.bin, ck_payment_settled_needs_result without payment_method_type) needs a V2 migration and is left to batch 2 so that no migration number is taken while S4 and S5 may add theirs. Withdrawn with Mode A
D-S3-9 S3 batch 2, QA of batch 1 (AC-14), S3 QA fix pass Closed (2026-10-29): AC-14 measured on the real POS for surcharges and discounts, including large-base ties (D-133); the history below is kept. Before the measurement: Measurement plan on the real POS (C:\Work\AI\POSKIT_GPQR). What the source says (read-only, C:\Work\AI\pcpos\20261003\src\ALMACOR; CONVENTIONS 9a rule 1): the POS has three ways to turn an amount and a percentage into an amount. (i) The payment-method promotion engine, ROUND_DOUBLE((ROUND_DOUBLE(base) * pct) / 100), one rounding (pos_prom.cpp PromocionesMdeP_Consultar, called by pos_mppo.cpp:4193 with the installments the cashier picked, and PromocionesMdeP 2343-2365 and 2492): this is what is shown and printed for a card plan, and what a promotion of mode A is, so PosRounding.adjustmentOf uses it for both modes. (ii) RoundExp100, two roundings (pos_mis2.cpp:1287): taxes, change limits and CalculateRecDescMdeP (pos_mppo.cpp:264, the fixed surcharge of a method when PERMITE_PROMO_MDEP is 0); the earlier code and this entry used it for the plan, which is wrong by a cent when the first rounding lands on a half cent (1000.11 at 4.5 % is 45.01 with it, 45.00 with the engine). (iii) dM_TarPl.fRecDescMPP used as an amount in pesos (pos_mis2.cpp:3857-3858), only for a pre-scanned card the engine did not price, while BASES.TXT documents the column as a percentage. The profile of the Almacor client in POSKIT has PERMITE PROMO MDEP = 1 (DM_PROFI parameter 171), so its cuotas go through (i). What is not measured: the POS is Borland C++ 3.1 for DOS on x87, whose intermediates may be wider than a Java double, so (a) which of (i) and (ii) the pinpad really prints, and (b) whether x87 and IEEE double agree on the ties, are open. Plan: (1) in POSKIT_GPQR (README.txt: DOSBox-X, conf\run_gpqr.conf, login 1234) define in the POS promotion tables a card promotion per row below, sell a ticket of the amount, pick the plan and read the recargo or descuento the POS shows and prints, and the log line PLAN <plan> REC:<amount> / DTO:<amount> (LOG_CARD_TRACKS, pos_mppo.cpp, next to dLastRecDesc). (2) Rows that tell the formulas apart (what each would print): 1000.11 at 4.5 % = 45.00 for the engine as the gateway computes it and for exact half-up, 45.01 for RoundExp100; 173244.75 at 10 % = 17324.47 for the engine in IEEE double and for RoundExp100, 17324.48 for exact half-up or an x87 extended computation that lands on the tie; 71504.90 at 55 % = 39327.69 for the engine in IEEE double, 39327.70 for RoundExp100, exact half-up and an extended computation. A result of 45.01 says the plan is (ii); 17324.48 or 39327.70 on the engine says the x87 differs from double and PosRounding must change. (3) Repeat (1) with PERMITE PROMO MDEP = 0 to see what the POS prints when the engine is off (CalculateRecDescMdeP), and with a pre-scanned card, to settle (iii). (4) Read dM_TarPl.fRecDescMPP in each client's DM_TARPL.DAT (percentage or pesos), and where the percentage of a card promotion lives (BT_PROMO), because mode A serializes one of them (docs/PLANES-CUOTAS.md 6.1 says fRecDescMPP). (5) With Turbo Debugger (POSKIT README) evaluate ROUND_DOUBLE on a few thousand random (amount, pct) pairs and compare with PosRounding.adjustmentOf; any difference is a bug of one of the two. The text of AC-14 (ACCEPTANCE.md, SPEC.md) and ADR-003 still say "RoundExp100 double rounding": they are the human's to amend once the measurement settles it. Human / before production
D-S3-10 S3 batch 2, QA of batch 1 (AC-15) TNA and CFT are not checked against the adjustment, only for their structure, and nothing defines the relation. PLANES-CUOTAS section 8 gives the French system with 21 % VAT on the interest (TNA 40.05 % and CFT 61.87 % for 6 installments at +12 %) as an illustration, and docs/emulador-qr.html computes it the same way (365/30 for the CFT); PLANES-CUOTAS D7 says the acquirer or the bank gives the figures and the gateway only verifies coherence, without saying how or with what tolerance. A check against that illustration would refuse real figures of another convention and, failing closed, deny sales. AC-15 is therefore UNTICKED: what is enforced (a surcharge has both rates above zero and a cost not below the rate, any other plan has both at zero, now also when the plan is read) is sanity, not consistency (the sign of the surcharge is judged on the percentage as the engine applies it, PosRounding.roundedPercentage: a +0.004 % plan is applied as 0 % and may not carry rates). To close it, the human must state the convention and the tolerance (or that the figures are the acquirer's and AC-15 means the structure). Human
D-S3-11 S3 batch 2, QA of batch 1 (AC-16) Cuotas MiPyME is not proven: the code never reaches the wire. AC-16 says the plans are offered with their plan code, and v27 has no field for it (Prisma question 9), so nothing is sent; the code is kept on the offered plan, the snapshot and the payment, and the test that passed asserted its absence. AC-16 is UNTICKED until question 9 is answered and the code is sent where Prisma says. Prisma question 9
D-S3-12 S3 batch 2 (mode A), S3 QA fix pass Withdrawn with Mode A (human decision 2026-10-28; the code is recoverable from the tag mode-a-reference). Original row, kept for the record: Where the TNA and CFT of mode A come from is a decision of this batch, to confirm with the human and the POS team. The POS tables (dM_TarPl) have no rates, so a promotion row carries tna and cft (percentages). QA fix pass: a surcharge row without valid rates (missing, below 0.01 as sent, or a cost below the rate) is no longer a 400 for the whole sale: the row is never offered but kept, flagged, with its priority (final fix pass, D-S3-19), logged at WARN with its position in promos, and the sale goes on with the other rows and the 1-installment plan (AC-15 holds: no surcharge is offered without rates); it was a 400 and the documented example of PLANES-CUOTAS 6.1 (rows with recdesc 12 and 25 and no rates) was refused whole, for mode-B merchants too. Decisions to review: a row without surcharge that carries a non-zero rate is still a 400 (it is not a QR-sale blocker the POS would send on purpose, but it could be dropped the same way); the rates of the example of 6.1 are illustrative. The gateway does not derive the rates (PLANES-CUOTAS D7) and does not check them against the adjustment (D-S3-10). The alternative, rates held per merchant and plan in the gateway (a table or a setting that mode A would read when a row has none), is not built: it would be needed if the POS team cannot add two columns to what it serializes. Withdrawn with Mode A
D-S3-13 S3 batch 2 (mode A), S3 QA fix pass Withdrawn with Mode A (human decision 2026-10-28; the code is recoverable from the tag mode-a-reference). Original row, kept for the record: The field names of promos and the precedence of the base are provisional. Spanish names from PLANES-CUOTAS section 6.1 (orden, mediopago, desde, hasta, cuotas, recdesc, base, plus tna, cft, plan) with English aliases, so the POS team may still rename; the one place to change is JacksonPosPromotions. Precedence of the base: the base of a row wins over the base_amount of the trxpago, which is the default of the rows that state none (the draft only has the per-row base); neither means the whole amount. Corrected in the QA fix pass: this entry said base_amount "is what the POS already sends". The Almacor POS sends neither promos nor base_amount: its trxpago is id, totalitem, totalcashback, nropv and nroticketfiscal (pos_ctoq.cpp:3439-3447). base_amount is sent by RouterQR when it forwards (SPEC.md section on RouterQR, docs/research/gatewayqr.md: the RouterQR/GatewayQR trxpago has base_amount as an optional field), so it is a field of that sender, not of the POS; promos has no sender yet, and what the POS team will serialize and from which table (D-S3-9 (4)) is open. A promotion is validated only for a mode-A merchant (QA fix pass): it used to be validated for everybody ("a POS that sends promotions it cannot describe is refused whoever the merchant is"), which gave a mode-B merchant a 400 for rows it does not use; a mode-B merchant now ignores promos entirely (not validated, not stored, DEBUG at most). Withdrawn with Mode A
D-S3-14 S3 batch 2 (mode A) Withdrawn with Mode A (human decision 2026-10-28; the code is recoverable from the tag mode-a-reference). Original row, kept for the record: A mode-A offer is built from promotions that live only in the payment row: if the POS sends different promotions on a retry, the retry is a 409 (AC-04, compared in the canonical form). PosSuppliedPlanSource logs a WARN per undecidable row and payment (R-08): with many cards in the wallet and many long-range rows that is one line per row, not per card, but a merchant whose tables are full of ranges longer than 8 digits will fill the log; the survey of the real tables of Almacor and Becerra (PLANES-CUOTAS R-08) tells whether that matters. Withdrawn with Mode A
D-S3-15 S3 batch 2 (cashback) Cashback is built on the safe reading of v27, and four points wait for Prisma (questions 21 and 22 of docs/PRISMA-PREGUNTAS.md). (a) Whether the notified amount includes the cashback: the gateway assumes it does not; if it does, every cashback payment is an AMOUNT_MISMATCH and is compensated (fails closed, never approved at a wrong amount); the fix is one subtraction in PurchaseResults.approved before the offer check, behind a setting if Prisma says it varies. (b) Whether a user who declines the cashback is a notification without cashback_amount or with a zero: both are read as nothing withdrawn and approved with totalcashback 0. (c) The complete intention has no cashback field, so "only with Visa Debito in 1 payment" is checked on the notification, not offered: a wallet that lets another method withdraw cash is compensated, with the cash returned by the annulment. (d) cashback_amount is read from the purchase notification only; the status query answers the same body (v27 3.5), so it is covered, and the annulment notification's cashback_amount is for S4. AC-17 stays UNTICKED (decision for the human): its second half says cashback is only offered with Visa Debito in 1 payment, v27 gives the complete intention no cashback field, so what is proven is that it is never approved otherwise (the first half, that the adjustment never applies to the cashback, is proven too); tick it if that reading is accepted. (e) Closed in the S3 QA fix pass (both judges): a cashback_amount that is not a number ("5000,00", a boolean) or cannot be held (finer than a cent, above the maximum) used to read as "nothing withdrawn" and the payment was approved with totalcashback 0.00 while the wallet had paid cash out; the three states (absent, stated, unreadable) are now carried to Cashback.check, which refuses the last two, and gateway.prisma.absolute-cashback=false is honored by Cashback.check as well as sent (decision to review: the alternative was to remove the setting). Not built: a per-merchant cashback switch. The POS side must read totalcashback from the answer instead of trusting its own request (pos_ctoq.cpp already does). Prisma questions 21 and 22
D-S3-16 S3 QA fix pass Withdrawn with Mode A (human decision 2026-10-28; the code is recoverable from the tag mode-a-reference). Original row, kept for the record: Mode B no longer stores the promotions it was sent, so the audit that D-S3-13 used to promise ("kept as audit") is gone for those merchants: the POS request is in the wire log, nothing else keeps it. A retry that changes the promotions of a mode-B merchant is the same request (no 409). A merchant that changes plan source between a payment and its retry gets the 409 of whichever side its stored text now disagrees with. If an audit of what a mode-B POS sent is wanted, store it in a capped column of its own, not in pos_promotions. Withdrawn with Mode A
D-S3-17 S3 QA fix pass Withdrawn with Mode A (human decision 2026-10-28; the code is recoverable from the tag mode-a-reference). Original row, kept for the record: Superseded in the final fix pass (D-S3-19): a row that leaves nothing to pay is kept as not offerable with a WARN, no longer a 400. Original text: "Nothing to pay" is checked at trxpago for every kept row of a mode-A sale, even a row no card would ever match (PosPromotionsIntake, with PlanFigures on the amount and the base of the row or of the sale): -100 % with no base is a 400 naming the row, and so is a row whose installment would round to zero for a tiny amount. The alternative was to wait for a card to match it and fail the offer at the BINs (NO_OFFER, the sale denied after the wallet scanned). The same check also runs for a retry. A decision to review: a POS whose tables contain a row that can never apply to the amount of a particular sale cannot sell that sale by QR until the row is removed from what it sends. Withdrawn with Mode A
D-S3-18 S3 QA fix pass gateway.prisma.absolute-cashback=false is honored by the gateway as well as sent (it was only sent, and Cashback.check still compensated every partial withdrawal). With false a withdrawal above zero up to what the POS asked for is approved and answered as totalcashback; the maximum, the method (Visa Debito) and the installments (1) still hold. The alternative was to remove the setting. See D-S3-15 (e) and CONVENTIONS 9c. Human
D-S3-19 S3 final fix pass A row that cannot be offered keeps its priority (the claim rule), and the POS percentage rounding is replicated. (Mode A was removed 2026-10-28: the part about POS promotion rows is withdrawn with it; the claim rule for the plans of the gateway and the rounding stay.) (1) A mode-A surcharge row without valid rates, or a row that leaves nothing to pay of the sale, used to be removed, so the first-match rule gave its installment count to a lower-priority row (bank X 6 installments +15 % without rates, then every Visa 6 installments 0 %: bank X's cards were offered 0 %). The row is now kept in payment.pos_promotions flagged "ofertable":false (written only by the gateway; the wire cannot send it), wins its count for the cards it matches and is not offered (PosPromotion.offerable, PosSuppliedPlanSource); a "nothing to pay" row is no longer a 400 (it may be another card's row). Mode B has the same rule for a plan whose rates are wrong (InstallmentPlan.offerable, GatewayConfiguredPlanSource) and JdbcPlanCatalog no longer fails the whole load for a bad row. Closed (S3 post-judge fix): JdbcPlanCatalog skips a mode-B row only when its card scope or its installment count cannot be read (payment method, bank, BIN bounds, quantity: more than 99 installments, bounds that are not 1 to 8 digits); any other fault (a plan code that is blank or wrong for the quantity, a negative minimum, a surcharge of 1 installment, rates, a percentage that rounds into -100) builds the row with offerable=false, so it still claims its (card, installment count) slot, and logs a WARN throttled to once per row per five minutes. The remaining open point is only for the unreadable rows, which cannot claim: the console (S5) must refuse to save them. Closed in S5 batch 3: the console builds the domain's own InstallmentPlan from every plan it saves and refuses what that record refuses, so an unreadable row (a payment method, bank, BIN bounds or installment count the domain cannot read) can no longer be saved from the console; only a row written by hand into the table can still be one, and the simulator lists it as "no se pudo leer". PosRounding rounds the percentage first, so a mode-B percentage between -99.995 and -99.9999 (rounded to -100.00, nothing to pay) is validated rounded and handled like any other fault, not as a failure of the whole offer at the BINs. Payments stored before this change decode as before (RUNBOOK section 6). (2) PosRounding now rounds the percentage to two decimals first (pos_prom.cpp:4417) and skips the final rounding under 0.0099999 (pos_prom.cpp:4683; what is left under a cent is rounded half up with the total, so the skip is not visible in cents: to be measured on the pinpad with D-S3-9). AC-14 stays UNTICKED. Human (S5 console; D-S3-9 measurement)
D-S4-1 S4 batch 1 COMPENSATION_FAILED is final and the gateway has no supported command to re-open a task, stop an annulment that was scheduled by mistake, or finish a reversal by hand and record it (RUNBOOK section 9 tells the operator to act at Prisma and note the incident). Add a console action (D-01) that re-queues a failed task with attempts = 0, cancels an active one, and marks a reversal completed with the Prisma reference. S5 (console)
D-S4-2 S4 batch 1 "The annulment is no longer possible" is recognised by the job only as the final status of the reversal after Prisma accepted it (201), read from GET /annulments or the POST /annulment notification (status rejected; approved completes it and any other status is still in progress); a forced refund is scheduled only then. Any other answer of POST /forcedannulments (400, 403, 5xx, timeout) is a failed try, retried and never turned into a refund. That is our assumption until Prisma answers question 17b of docs/PRISMA-PREGUNTAS.md; if Prisma refuses the annulment directly in the POST, the task retries until COMPENSATION_FAILED and a person must refund. Before go-live
D-S4-3 S4 batch 1 The marker of the INV-02 exception (gateway.compensation.denial-marker-file) is one file on the disk of the node that denied: if that disk is lost with the node, the reconciliation cannot find the payments it denied and the operator must use the INV02_UNPERSISTED_DENIAL log lines (RUNBOOK section 3). A shared durable location was not chosen on purpose: the database is the thing that is down in that case. Operations review
D-S4-4 S4 batch 1 A reversal notification (POST /annulment, /refund) is matched to the gateway's reversal by intention id and type, and by terminal data when the body carries it; a body without terminal data is about the intention's only reversal of that type. With several charges on one intention and no terminal data the match is ambiguous (the notification stays REVERSAL_UNKNOWN or is applied to the only candidate). Prisma questions 17c and 17d. After Prisma answers
D-S4-5 S4 batch 1 Closed at the merge with the S2 line. S4 only reads the markers of an "approved" answer; the POS answer path of main writes them (PosApprovalGuard the intent, PosApprovalMarkerFilter the told marker, POS_APPROVAL_UNRECORDED on a failure), so the reconciliation no longer annuls an approved payment the POS heard through the consulta. Still open as configuration: set gateway.compensation.pos-polling-window from the POS profile of the deployment (default 10 minutes). Merge of S4
D-S4-6 S4 batch 2 POST /api/trxanulacion annuls by trxidoriginal when it is positive, otherwise by id (D-19). A request that carries a fresh id next to a positive trxidoriginal (the GatewayQR documented form) is served, but the fresh id is stored nowhere: the annulment is idempotent per payment, so nothing has to find the fresh id again and a repeat with another fresh id is the same annulment. If RouterQR or Prisma ever needs request id -> reversal, add a request_payment_id to reversal. A payment id this gateway never issued is a 404, never the acceptance estado: answering "annulled" for money that may be charged somewhere else would be the one dangerous lie. Confirm with RouterQR that its sweeper sends the payment id in both fields. Before go-live
D-S4-7 S4 batch 2 Closed in the S4 batch 2 fix pass: StartPaymentService.resumedStatus gives a trxpago retry the same annulment view as the consulta (PaymentStatusService.asThePosMustSeeIt, D-118). A sale whose annulment is owed or done answers the annulment estado instead of AUTORIZACION_DE_PAGO_APROBADA; one whose annulment failed, or whose job gave up (D-S4-8), stays the sale because the money is still charged. StartPaymentRetryAnnulmentViewTest. S4
D-S4-8 S4 batch 2 The POS is answered "annulment accepted" once the annulment is persisted, and the money returns when Prisma completes it. If Prisma never completes it the POS has already closed the annulment while the customer's money is out. There are two end states, both a second fault after the first. (a) The reversal is FAILED (Prisma refused the annulment and the refund failed too, or nothing could be sent). (b) The job gave up on an annulment it had sent, without learning what Prisma did: after one Prisma timeout and then silence past pollDeadline the task is COMPENSATION_FAILED and the alert of RUNBOOK section 9 is raised, but the reversal stays IN_PROGRESS on purpose (Prisma documents no idempotency and may still hold the request; a late notification completes it as COMPLETED_LATE; nothing is ever sent again). Until this fix pass (b) read as 'in flight', so trxanulacion answered 'being returned' forever and the consulta showed annulled. Now ChargeLedger.saleReversal reads an active reversal whose tasks are all over with one COMPENSATION_FAILED as FAILED (CompensationPersistenceIT.dS48_*): a repeat of trxanulacion is a 409 plus ANNULMENT_NOT_POSSIBLE (RouterQR's sweeper repeats it every 5 s, which is the alert), and the consulta shows the sale. For both, a person finishes it at Prisma (RUNBOOK section 9). A persisted terminal state for (b) was not added: a new ReversalState touches V1 (ck_reversal_state and both filtered unique indexes), isActive/returnsMoney, the notification worker and the qa4 job tests, while the derived read changes no stored fact. A console action to finish it by hand: D-S4-1. S5 (console)
D-S4-9 S4 batch 2 AC-24 reads "forced annulment (same batch) or forced refund (earlier batch) and returns the matching estado". The gateway answers the one annulment estado for both: the POS accepts only REFUND_APROBADO and AUTORIZACION_DE_ANULACION_APROBADA, the job always tries the annulment and schedules the refund only when Prisma says the annulment is no longer possible (D-S4-2), and that is not known when the cashier asks. A distinct REFUND_APROBADO is never sent. Confirm with the human that this is the matching estado. AC-24 is unticked in ACCEPTANCE.md until the human confirms. Accepted by the human 2026-10-28: one annulment estado for both; AC-24 amended and ticked. Review of S4
D-S4-10 S4 batch 2 fix pass Closed: two overlapping trxanulacion (POS + RouterQR's sweeper, or POS + the reconciliation of an unpersisted denial) read the sale reversal as NONE without a lock and the loser got a 409 and a false ANNULMENT_NOT_POSSIBLE while the winner's reversal refunded the customer (the DOS POS keeps the sale on a non-2xx, pos_ctoq.cpp 3466-3470, 3816-3818). AnnulPaymentService now locks the payment row first (the order of the application: payment, reversal, task) and, if a schedule is still refused, re-reads the reversal and answers from it; the reconciliation no longer raises INV02_RECONCILIATION for a sale the cashier already annulled. Proof: AnnulmentRaceIT (real threads released by a barrier against the whole application and the emulator: every answer 200, one reversal, one task, one forced request at Prisma; it failed with a 409 before the fix) and AnnulPaymentServiceTest.dS410_*. Closed at the merge with main's PosApprovalGuard: the write of the approval intent (PosApprovals.recordApprovalIntent) takes the payment lock (CompensationQueue.lockPayment), reads the reversal of the sale charge and is refused while it is in flight or done; the POS is then answered the annulment view of the consulta (D-118), never approved, with a POS_APPROVAL_WITHHELD WARN. Proof: ApprovalVersusReconciliationRaceIT (the real reconciliation runs between the consulta read and the intent write; it failed before the fix with the POS told approved), PosApprovalGuardTest.dS410_*, CompensationPersistenceIT.dS410_*. Merge of S4
D-S4-11 S4 batch 2 fix pass Needs human acceptance. A trxanulacion that never committed (the node crashed, or the connection dropped before the commit, so no reversal exists) leaves the payment APPROVED with nothing owed. RouterQR's sweeper repeats the request every 5 s and heals it. The DOS POS going direct (no RouterQR) does not repeat it: after a trxanulacion that timed out it asks the consulta and reads an approved estado as 'annulled by consulta' (pos_ctoq.cpp 3820-3846), so it closes the annulment while the customer stays charged. The gateway cannot tell this from a sale nobody annulled (nothing is owed, so D-118 does not apply), so the fix is outside it: the supported topology has RouterQR in front of every POS, or the POS stops reading approved as annulled. An operator finds the case as a payment APPROVED with no reversal row whose cashier says it was annulled (RUNBOOK section 9). Accepted by the human 2026-10-28 as a known risk, with a procedure: a daily control in RUNBOOK §9 (annulments recorded in the POS with no reversal in the gateway), and a request to the POS team to repeat trxanulacion instead of trusting the consulta (R-07). Review of S4 / go-live
D-S4-12 S4 batch 2 fix pass Closed at the merge with main. One port, PosApprovals (the writes of the S2 line plus wasToldApproved and approvalWasIntended for the reconciliation); PosAnswers and JdbcPosAnswers are gone. V1 declares the marker columns once, in the order of main (pos_told_approved_at, pos_approval_intent_at). Merge of S4
D-S4-13 Integration of S5 into the S2 line Closed: no totalcashback on an annulment estado. The merge of S3's isSettled (which counts ANNULLED and REFUNDED) with S4's annulment view made the consulta, a trxpago retry and the answer withheld by PosApprovalGuard (D-S4-10) carry totalcashback = cashback_paid on AUTORIZACION_DE_ANULACION_APROBADA, while PosAnnulmentResponses sends none (an annulment hands out no cash). PosResponses now gives the cashback only for an APPROVED sale. Proof: PosResponsesTest.ac17_aCashbackSaleWhoseAnnulmentIsOwedOrDone*, PosApprovalGuardTest.dS410_theWithheldAnswerOfACashbackSale*. Integration
D-S5-1 S5 b1 Closed in S5 batch 1 (2026-10-04): S5 auth: human decision pending. The human decided: own users stored in the database with a password hash behind the AdminAuthentication seam, roles ADMIN and OPERATOR (docs/CONVENTIONS.md section 12, RUNBOOK section 12). The interim "loopback only, remote always refused" became "remote needs allow-remote and HTTPS". S5
D-S5-2 S5 b1 A password change or reset does not end the user's other open sessions (it changes the session that did it): they live until their idle timeout (30 min). Disabling a user does end all of them at their next request. Store a password_changed_at and compare it in AdminSessionFilter if that is not enough. Hardening
D-S5-3 S5 b1 Lockout is per user, not per source: someone who can reach the admin port can lock a known user out by guessing (5 wrong passwords, 15 min). The connector is loopback by default and an ADMIN's password reset lifts a lock; there is no per-source throttle or alert, and a login of a name that is no user is neither throttled by source nor audited (batch 2 stopped auditing it so the table cannot be flooded). Revisit if the console is ever exposed beyond the server. Before exposing remotely
D-S5-4 S5 b1, b2 Argon2id stays deferred (batch 2 checked it). BCrypt is the only encoder registered in DelegatingPasswordHasher; Spring Security's Argon2PasswordEncoder needs the BouncyCastle library, and mvn dependency:tree -Dincludes=org.bouncycastle on the gateway is empty: it is not on the classpath, and bcprov-jdk18on is a new runtime dependency of about 8 MB (a supply-chain decision, not an incidental one). The delegating format already lets Argon2id be added later: register it under its id, make it the id to encode with, and each user is rehashed at their next login. Decision for the human: add BouncyCastle, or accept BCrypt at cost 12 (OWASP's minimum acceptable choice) for this system. Human decision 2026-10-05: keep BCrypt (cost 12); no BouncyCastle for now. Hardening (human decision)
D-S5-5 S5 b1, b2 Narrowed 2026-11-16: the "Auditoría" screen (ADMIN) and GET /audit were delivered in S5 batch 2. Only open: a retention rule for admin_audit (it grows with every human action and is never pruned; tracked with the other tables in D-143). The index for the filter by actor is dropped from this entry: the table holds one row per human action. D-143
D-S5-6 S5 b1 Closed 2026-11-17 (go-live checklist). CI and release build the console (npm ci, lint, npm run build) and the release bundle carries console/dist where gateway.admin.console-dir expects it (./console/dist next to the jar); the dev cockpit stays out: the Vite cockpitGuard plugin fails the build and a new post-build scan (npm run scan:dist, console/dev/scanDist.ts, markers imported from cockpitMarkers.ts) re-reads the files of dist for the cockpit, source maps and the names console-dir refuses; the packaging refuses the same names and the smoke test of the packaged jar checks the console is served from the unzipped bundle. The console is still not inside the jar (a separate directory, by design). Before the first release
D-S5-7 S5 b1 Closed 2026-11-16, out of scope: production runs a single node (2026-11-16). The text is kept so the entry can be reopened if HA is ever added. The admin session lives in the memory of one node (Tomcat's HTTP session). With two nodes behind one name an operator must stay on the node that logged them in (or log in again); the money path never uses sessions. Put the sessions in the database (Spring Session JDBC) or pin the console to one node if more than one serves it. Closed (out of scope: single node; reopen with HA)
D-S5-8 S5 b1 AdminRemoteAddressFilter judges the TCP source address only: a reverse proxy (or a port forward) on the same host connects from loopback and passes it. The login is then the only lock. Do not front the admin connector with a same-host proxy unless allow-remote and ssl-bundle are set; if one is needed, add a trusted-forwarder setting that reads the forwarded address deliberately. Before exposing remotely
D-S5-9 S5 b2 Closed in S5 batch 3 (2026-10-28): the mode-B plan CRUD and the plan simulator exist (PlanAdminService, PlanSimulator, PlansController, the "Planes" and "Simulador" screens; docs/CONVENTIONS.md section 12, RUNBOOK section 12). The tie check of AC-13 is PlanTies under the merchant lock; the simulator is the real MerchantPlanSource and CompleteOffer over the stored plans, read only. The decisions of the batch are D-S5-15 to D-S5-20. S5
D-S5-10 S5 b2 The dashboard counts the compensation tasks that gave up (COMPENSATION_FAILED) over all time: there is no "handled" mark, so the number only grows and a task a person already resolved by hand still shows. Add a handled_at/handled_by to the task (S4's table) and count only the open ones. The past-deadline block cannot see the D-105 case (a): an approval another node committed before the deadline while the POS was told "denied"; only the INV02_UNPERSISTED_DENIAL alert records it, until the S4 reconciliation exists. Merge with S4: the reconciliation exists now and the block is unchanged; the compensation figures gained the part that returns a customer's money (D-S5-21). With D-105 / S4
D-S5-11 S5 b2 The dashboard's "today" is the business day of gateway.admin.business-zone (default America/Argentina/Buenos_Aires), while the payment search takes UTC days (its hint says so), so the dashboard offers no link into the search by day. Make the search take the same zone (or send instants) if the drill-down is wanted. Hardening
D-S5-12 S5 b2 A login flood now costs the console, not the payment path: at most gateway.admin.max-concurrent-logins passwords are hashed at once and the rest get a 503 after a second, so someone who can reach the admin port can make logins fail for everybody (the lock of a known user, D-S5-3, is the other way to do it). The loopback default is the defence; a per-source throttle belongs with exposing the console remotely. Before exposing remotely
D-S5-13 S5 b2 The emulator page only lists (read-only), its descriptions are Spanish text inside the emulator (EmulatorCatalog), and gateway.admin.emulator-url takes one emulator. Starting a scenario or injecting a failure from the console would need write endpoints on the gateway that proxy the emulator's control API (which has no apikey); not done on purpose: keep the console's write surface to the configuration. If a developer asks for it
D-S5-14 S5 judge Closed (2026-10-28): the bootstrap command read its password with Environment.getProperty, which also answers from a -DGPQR_ADMIN_BOOTSTRAP_PASSWORD=... system property (visible in ps) and any other property source, so "never a flag" was not fully true. AdminBootstrapRunner now reads it only from the process environment (ProcessEnvironment, the seam over System.getenv) or the terminal prompt, and refuses the variable's name given as a system property or in a file, with a message that never repeats the value (AdminBootstrapRunnerTest, AdminBootstrapIT; RUNBOOK section 12). S5
D-S5-15 S5 b3 Withdrawn with Mode A (human decision 2026-10-28; the code is recoverable from the tag mode-a-reference). Original row, kept for the record: Plans can be saved for a merchant in mode A, but are never offered (POS_SUPPLIED merchants get the promotions of each sale, not the plans of the table). The console allows the writes (a merchant is often prepared in mode B before it is switched, and a plan must be disabled or deleted after a switch back) and says so on the plan screen and in the simulator ("modo A"). The alternative, a 409 on create for a mode-A merchant, would also block the clean-up after a switch. Decision to review. Withdrawn with Mode A
D-S5-16 S5 b3 The simulator needs a merchant and cannot know the wallet. merchantId is required (the plans belong to a merchant; the spec said "optional merchant"). A branch left out means a sale at no branch, so only the plans of the whole merchant apply (a branch with its own plans needs the branch). With no payment method it tries each method the merchant accepts with the BIN given (the wallet lists the real cards of the customer, which the console cannot know), and the transfer (112) is always added, as in the real offer; an unknown bank is sent as 0, so bank plans do not apply. A date is judged at noon of that day in the zone of the shops (gateway.plans.zone), today by the server clock. The verdicts of all the merchant's plans except those of another payment method are listed for each card: a merchant with hundreds of plans gets a long list (filter or page it if that happens). The one place the simulator is not literally the production path: the real catalog (JdbcPlanCatalog) is keyed by a checkout and filters and skips rows in SQL, and a merchant may have no checkout to ask with, so the simulator feeds the real MerchantPlanSource a fixed catalog built from the stored rows (PlanRow.toPlan() repeats the catalog's rule: offerable, else kept as not offerable, else skipped). The selection, the figures and the offer are the same classes, and PlanSimulatorIT proves parity cent for cent for the offerable rows; the skip rule of unreadable rows is repeated, not shared (they are listed as UNREADABLE). PUT /plans/{id} ignores a merchantId in the body: a plan never changes merchant. Hardening
D-S5-17 S5 b3 The tie check is stricter than the engine in one case. The engine says a tie under a more specific plan is shadowed and harmless (ac13_aTieThatAMoreSpecificPlanShadowsIsNotAnErrorForThatCard); the console refuses two enabled plans that tie whatever other plans exist (AC-13: "refuses two plans that tie"), so a shadowed tie is refused too: the saved set can never fail an offer, whichever plan is later disabled. Also: the check is over the stored plans of the merchant, enabled or not valid today (a window that has not started yet still ties), it ignores amounts (any two minimums share the amounts above the larger) and treats BIN ranges as the engine does (prefixes of 6 and 8 digits, BinMatcher.overlap). A tie that already exists in the table (written by hand) is not repaired by the console: editing one of the two plans keeps the tie, so it is refused until one is disabled. Human
D-S5-18 S5 b3 The plan screen disables, it does not delete. The API has DELETE /plans/{id} (audited; no table points at installment_plan, the snapshots keep their own copy of what was offered) but the console shows only "Deshabilitar/Habilitar": a plan that was offered keeps its history in the audit and can be enabled again. Add a delete button if the merchants ask. If asked
D-S5-19 S5 b3 The merchant lock serializes plan writes and nothing else. PlanAdminStore.lockMerchant reads the merchant row WITH (UPDLOCK, HOLDLOCK) until the transaction ends, so two ADMINs saving plans of the same merchant take turns (PlanCreateRaceIT; without it the test fails); an edit of the merchant's own data (updateMerchant) waits behind a plan write for the few milliseconds it takes, and the payment path never takes the lock. Plans of different merchants do not wait for each other. Hardening
D-S5-20 S5 b3 The Spanish wording of the engine's refusals is a table of fragments (PlanRules): the domain's PlanConfigurationException carries English text and no code, so the console maps each rule of InstallmentPlan to a Spanish message and the field of the form by a fragment of the text. PlanAdminServiceTest.ac29_theRulesOfTheEngine... pins one case per rule, so a reworded rule fails a test instead of reaching the screen in English; a message the table does not know is still refused (a 400 with the domain's text, no field). A stable code on the exception would remove the table. Cleanup
D-S5-21 S5 merge with the S2 line (S4 included) What the merge changed in the console. (1) The admin console section of docs/CONVENTIONS.md is section 12 (section 11 is S4's compensation job); every reference was renumbered. (2) The payment trail now lists the wallet charges and shows, for each reversal, its charge and when it was sent and accepted, and for each task its kind and reversal; the old trail test inserted a reversal of type CANCEL_INTENTION, which the merged schema refuses (ck_reversal_type): the fixture now writes a charge, an annulment and a REVERSE_CHARGE task. (3) The dashboard splits the compensation figures into all tasks and those that return a customer's money (kind = 'REVERSE_CHARGE'): a failed one means the customer is still charged. Still open: D-S4-1 and D-S4-8, the console action to re-queue, cancel or finish a reversal by hand; the console does not write to the compensation tables. (4) EmulatorCatalog describes the two S4 double-charge scenarios. S5
D-126 Final hardening pass (console renames) Closed (2026-10-28): the console no longer renames what correlates a payment while the payment is not over. The console could change a merchant's CUIT, a branch code or a checkout code while payments were in flight (JdbcConfigurationStore). Intentions keep only the checkoutId and the codes are compared live, so a notification, a status query or a forced annulment of such a payment could no longer be correlated. updateMerchant, updateBranch and updateCheckout now refuse the rename with a 409 (AdminConflictException, the message names the CUIT or the code) when it changes the value and any payment of that merchant, branch or checkout is not over (ID_ISSUED, the four waiting states, COMPENSATION_PENDING), or has a reversal in REQUESTED/IN_PROGRESS, or a compensation task in PENDING/IN_PROGRESS. The test is part of the UPDATE statement, the same pattern as the terminal rename guard, and compares the code case-sensitively (a change of case is a rename). A save that keeps the value (a name, MCC, number or enabled flag change) is not a rename and is never refused. An APPROVED sale counts as over: what can still happen to it is a reversal, which is judged by the open reversal. Residual: a payment that starts in the instant between the check and the commit of the UPDATE is not locked out (the check is not a lock on the payment table); the window is the length of one statement and the console is an administrator's tool. (AdminPersistenceIT, AdminApiIT, console tests.) S5
D-127 Final hardening pass (Prisma question 17f) Fail-open risk, pending the answer of Prisma (question 17f in docs/PRISMA-PREGUNTAS.md). When DELETE /intentions/{id} answers 404 the job asks GET /payments/qr (PurchaseCheck) before concluding, and if that also answers 404 it closes the payment as COMPENSATED with nothing annulled. v27 does not say whether GET /payments/qr can answer 404 for an intention whose payment is still being processed (the wallet confirmed, the purchase is not registered yet). If it can, a customer could be charged while the gateway has closed the payment with no reversal; the late notification would still be applied by the late-result rule (INV-03), which reopens compensation, so the exposure lasts until it arrives, and forever if it never does. It is the same family as question 17d (a 404 may mean "not processed yet"), which the reversal path already treats as pending. Until Prisma answers, a COMPENSATED payment whose cancel and purchase query both answered 404 must be read as "no charge seen", not "no charge exists". Before go-live
D-128 Final hardening pass (complete PUT addressing) The complete-intention PUT is addressed by CUIT, branch and checkout only (v27 3.4: there is no intention id in the path), so a supersede in the window between BinsWorker.prepare (which reads the offer for the payment) and the call to Prisma can land a stale offer on the new intention of the same checkout. It fails closed: the notification of the payment is checked against the offer the gateway stored for that intention (OfferCheck: method, BIN, plan and total), a mismatch is not applied and the payment is compensated, so the cost is a rejected sale, never a wrong charge accepted. A narrower window needs Prisma to accept an intention id in the PUT. Before go-live
D-129 Final hardening pass (schema) payment.state now has ck_payment_state (V1 edited in place; PaymentStateSchemaTest keeps it equal to PaymentState). No index for pos_fiscal_ticket / pos_point_of_sale: the payment search and the trail select those columns but never filter or sort by them (JdbcPaymentQueries), so an index would only cost writes; add one together with the filter if the console gets a search by fiscal ticket. SQL Server compares strings with the case-insensitive collation of the database, so approved passes the check like APPROVED: the code only writes the enum names. S5
D-130 Final hardening confirm judge (M1) Closed (2026-10-28): an existing intention, its charges and their reversals are addressed with the CUIT and the codes the intention was created with, never with the current configuration. A forced annulment or refund read the CUIT live from the merchant (JdbcCheckoutDirectory through CompensationJob), so after an ADMIN renamed a CUIT the cashier's trxanulacion or an automatic reversal of a sale (which the D-126 guard counts as over) went to Prisma with the new one and was refused. The same live read fed the complete PUT (CUIT, branch, checkout, BinsWorker) and the comparison of the checkout a notification or a status answer names (PurchaseResults): a late charge of an intention whose checkout had been renamed was CHECKOUT_MISMATCH and never annulled. intention now stores merchant_cuit, branch_code and checkout_code (NOT NULL, ck_intention_address; V1 edited in place) from the CheckoutRef the create call is built from (Intention.open(..., IntentionAddress, ...), one transaction), and the three uses read them from the intention (CompensationJob.load, CheckoutRef.addressedAs in BinsWorker, PaymentNotification.namesCheckout(IntentionAddress)); CompensationJob and PurchaseResults no longer take a CheckoutDirectory. The identifiers are stored once, on the intention, not copied to wallet_charge: a charge belongs to one intention (intention_id), the create call is the only place they are chosen, and a copy could only disagree. Already by stored ids: cancel intention, purchase status query and annulment/refund status queries (they take only the Prisma intention id). The D-126 guard stays as it is (it still stops a rename while a payment is in flight). New intentions keep using the live configuration. (RenamedConfigurationIT with the emulator: cashier trxanulacion after a rename, a late charge after the denial and the rename, the complete PUT after a rename; CompensationJobTest.d130_*, BinsWorkerTest.d130_*, PaymentNotificationWorkerTest.d130_*, PersistenceAdaptersIT.d130_*, FlywayBaselineMigrationIT.d130_*.) Before go-live
D-131 Final hardening confirm judge (M2-M5) (1) Possible deadlock, not verified: the admin rename UPDATE holds the merchant, branch or checkout row and then reads payment rows; a payment transaction that holds a payment row and then reads the checkout directory under a lock would deadlock with it (error 1205, the console answers 500 and the operator retries). Confirm the lock order or retry on 1205. (2) The callback refusal throttle clears its table past 1,000 sources, so a flood of distinct sources logs one line per request again; the scheduled log cleanup in the RUNBOOK keeps the disk bounded. (3) The 130 s NSSM stop budget leaves out each runner's 30 s thread join: one stuck database call makes NSSM kill the process, which the leases make safe (RUNBOOK). (4) The developer-profile warning does not fire when server.address is unset (bind-all), the most common way a developer profile ends up reachable. Before go-live
D-132 Real Almacor POS E2E on the integrated build (2026-10-28, scenario d-int a) A wallet that pays after the intention was cancelled ends COMPENSATION_FAILED. If the wallet scans and pays only after the compensation job cancelled the intention, that charge never received the plans, so it cannot be named to Prisma for a forced annulment: the reversal fails, the payment ends COMPENSATION_FAILED with an operator alert and the customer stays charged until a person acts (fail-closed, CONVENTIONS 12.2). The POS still hears REFUND_DENEGADO. Only the emulator's contrived scenario reaches it; a real wallet is expected to refuse paying a cancelled intention (to confirm with Prisma). Before go-live
D-133 Real Almacor POS E2E on the integrated build (2026-10-28, AC-14 and INV-06) AC-14 closed (2026-10-29). INV-06 fixed in the POS code by PR #1 (feat/qr-imputation) of tipre/POS_ALMACOR; narrowed on 2026-11-16 to its deployment. Through the POS's own promotion engine (Cabal manual card, 2 installments, client promo +11%) the POS and the gateway gave the same adjustment for a sub-cent case (1234.56 -> 135.80) and a .5-cent tie (1250.50 -> 137.56); the gateway sales were sent by curl, not from the POS. The discount was measured on 2026-10-29 through the same Cabal card promo with its percentage re-signed in the local copy of the bases (restored byte-identical afterwards): 1234.56 at -10% -> -123.46, 1250.00 at -10.01% (tie) -> -125.13, 1251.37 at -10.01% -> -125.26, and the large-base ties 163850.00 at -10.01% -> -16401.38 and 173244.75 at -10% -> -17324.47, all equal to the gateway (PosRounding); exact half-up would give one cent more on the last two, so the POS rounds IEEE doubles like the gateway (answers D-S3-9). Evidence: C:\Work\AI\POSKIT_GPQR\evidence\RESULTS_ac14d.txt (local only). POS side, verified 2026-11-16 (read-only: QR-IMPUTACION.md, pos_ctoq.cpp and pos_tic2.cpp of C:\Work\AI\POS_ALMACOR, main at 5049830): the new build imputes a wallet discount (importe_recdesc < 0: it charges importe_final, writes the negative detail rows by VAT rate, prints the Rec/Desc line, and the voucher shows the original amount, the discount and the amount paid; PagoQR_ImputarAjuste), and it annuls the payment with trxanulacion (localReversaPagoNoRegistrado) when importe_recdesc > 0 (a surcharge) or when importe + importe_recdesc differs from importe_final by 0.005 or more, on trxpago and on the consulta (localAprobadaNoRegistrable); it also annuls the QR when the ticket is cancelled. So with the new build the silent mismatch of INV-06 (the sale recorded at the original amount while the wallet charged base plus adjustment) can no longer happen. What remains: (1) the new build is not deployed: terminals in stores that still run an older build keep the behaviour below, so a plan with a nonzero adjustment stays off for a merchant until every terminal of it runs the new build; (2) the new build was run in the DOSBox-X kit against the gateway and the emulator, not on real hardware; (3) surcharges are annulled, not imputed: a plan with a positive adjustment can never complete at the POS; (4) POS deployment requirements: profile 171 (PermitePromosXMdeP) at 1 (at 0 the discount is annulled) and profiles 564 to 567 with values of their own; (5) the QR amount prompt still truncates the prefilled amount (G-14, outside PR #1): amounts with cents must be retyped. Original INV-06 finding (POS builds before PR #1): the then-current Almacor POS build parses importe_recdesc but ignores it and records the QR sale at the original amount, silently (ticket, payment line and QR voucher show the base while the wallet charged base + adjustment). Plans with a nonzero adjustment must not be enabled for a merchant until the POS imputes the adjustment or fails explicitly (POS handoff). The QR amount prompt also truncates the prefilled amount to its visible width, so amounts with cents must be retyped. Evidence: C:\Work\AI\POSKIT_GPQR\evidence\RESULTS_int.txt (local only, real client data). Before go-live (rollout of the POS build)
D-134 TLA+ model of the approval intent and the annulment of the sale (2026-10-31), confirmed by reading Closed (2026-10-31): the approval intent is refused while the job has given up on the annulment of the sale but Prisma may still complete it. The sequence: (1) the write of the approval intent fails, so the POS hears the deferred INTENCION_DE_PAGO_RECIBIDA_APROBADA; (2) after the POS polling window the reconciler schedules the annulment of the sale; (3) the compensation job sends it, Prisma does not answer, and the job gives up: the reversal stays IN_PROGRESS with all its tasks over and one COMPENSATION_FAILED; (4) the POS polls its consulta much later: JdbcPosApprovals.recordApprovalIntent refused only IN_FLIGHT and DONE (JdbcChargeLedger.saleReversal reported such a reversal as FAILED), so it wrote the intent and the POS heard APPROVED; (5) Prisma completed the annulment late and ReversalNotificationWorker annulled the payment through ReversalSettlement.settleMoneyBack: the POS recorded a sale whose money went back to the customer, a breach of INV-01. Fix: SaleReversal has a new value GAVE_UP, returned by JdbcChargeLedger.saleReversal for the given-up reversal that is still active (REQUESTED or IN_PROGRESS, tasks over, one COMPENSATION_FAILED) where it returned FAILED; recordApprovalIntent refuses it under the payment lock like IN_FLIGHT and DONE, so the POS keeps hearing the deferred estado. A reversal that is really over without returning money (state FAILED, refused) keeps allowing the intent, and every other caller (AnnulPaymentService, UnpersistedDenialReconciler, PaymentStatusService) treats GAVE_UP exactly as it treated FAILED. (CompensationPersistenceIT.d134_* and dS48_*, PosWaitIT.d134_*.) Before go-live
D-135 TLA+ model of the approval intent and the annulment of the sale (2026-10-31) Open, medium (re-rated from low on 2026-11-16: it is the only gap that leaves a possible sale without a trace, because PosApprovalMarkerFilter has no log call for a failed flush; its one LOG.error covers only a marker that could not be stored; no code changed here): when the flush of an approved answer fails, PosApprovalMarkerFilter lets the IOException out without an ERROR marker line. The intent is already set and the answer never reached the POS (it gave up), so a payment with only pos_approval_intent_at set and a POS that heard nothing reaches no person: no log line names it and the reconciliation does not annul it (the intent says the POS may have heard approved). It is the no-crash variant of D-124 (there the process dies; here it lives and the write out fails). Log an ERROR line with the payment id, like POS_APPROVAL_UNRECORDED, when the flush fails, so the manual step of RUNBOOK section 3 finds it. Before go-live
D-136 Comparison with GatewayMP-JH8 (2026-10-31), approved as deferred by the human Open, medium: add a low-frequency sweep of given-up reversals. When the compensation job gives up (COMPENSATION_FAILED plus the operator alert) the reversal stays open (REQUESTED or IN_PROGRESS) and waits for a late Prisma notification or for a person; if that notification is lost, only a person resolves it. Proposal: a scheduled sweep, for example hourly and leased so that only one node runs it, over the active reversals whose tasks all gave up. It only queries Prisma, with the same queries the job runs before any re-send (GET /annulments and /refunds for the charge), and settles what Prisma reports as resolved through the existing settlement path (ReversalSettlement and the late-result handling, INV-03). It never re-sends a reversal. Origin: GatewayMP-JH8 re-reads the provider state on every tick, so it converges, but it retries forever with an in-memory queue per node and no alerts. Tradeoff: fewer cases left to a person and a smaller window for the D-134 situation, against one more scheduled component and a few extra Prisma calls. Not implemented. Before go-live
D-137 Load and fault campaign, finding F2 (2026-11-16) Manual action delivered (2026-11-16); automation stays open, medium, pending Prisma. A forced annulment or refund whose send got an ambiguous failure (5xx, timeout, reset) and whose status query answers 404 is only polled: CompensationJob asks GET /annulments or /refunds and, on a 404, polls for poll-deadline (30 minutes) and gives up with COMPENSATION_FAILED and the operator alert, so one 503 on POST /forcedannulments that Prisma never started ends with a person. An automatic resend was tried and withdrawn after review (PR 34) because it can double-reverse: HIGH 1, it could put the reversal back to REQUESTED (notSent), erasing the earlier ambiguous send, so a later give-up marked it FAILED instead of GAVE_UP and bypassed the D-134 guard; HIGH 2, it also fired after a timeout or a reset, where Prisma may have received the request and still answer 404 (not processed yet); MEDIUM 1, accepted_at is saved after the 201 in a separate transaction; MEDIUM 2, after a double send a rejected duplicate could schedule a forced refund on an already annulled charge. Delivered: "Reenviar anulación" / "Reenviar devolución", a manual action for an ADMIN (payment detail of the console, POST /admin/api/v1/payments/{id}/reversals/{reversalId}/resend, RUNBOOK section 9). It is allowed only for a reversal that is IN_PROGRESS, never accepted by Prisma (no accepted_at), whose task gave up, with no resend in flight and no other reversal of the charge that returned the money; it records the resend IN_FLIGHT (reversal_resend, one per reversal) before calling Prisma, asks Prisma afresh and sends the request once only if that answers 404, keeps the reversal IN_PROGRESS with its first sent_at whatever the send answers (so D-134 holds), re-arms the task so the result is tracked (its polls count from the resend), and audits who, why and what Prisma said. After a resend a refusal never schedules a refund by itself (MEDIUM 2: the gateway stops with REVERSAL_REFUSED_AFTER_RESEND for a person). The assumption it rests on, that a 404 now means Prisma never received the request, is not promised by v27: the operator answers for it. Still open: the automatic resend, only after Prisma answers PRISMA-PREGUNTAS 14 (idempotency), 17b and 17d, and it would need the failure kind stored durably and accepted_at written atomically with the 201. Until then a stuck forced reversal is polled, then COMPENSATION_FAILED, and a person uses the action or handles it by hand. Before go-live (the Prisma answer)
D-138 Load and fault campaign, finding F1 (2026-11-16) Closed (2026-11-16): the duplicate check of the callback inbox scanned and locked the whole table. JdbcInboundNotifications.FIND_EARLIER compared the CHAR(64) body_hash and the VARCHAR(20) type with the NVARCHAR parameters the JDBC driver sends, which converted the column and turned the seek of ix_inbound_notification_body_hash into a scan under an exclusive table lock (30,689 logical reads against 3; at 50 checkouts on a 37k row inbox 9.4 payments/s and a BINs p95 of 2.1 s). Now the statement casts its parameters to the column types (CAST(:hash AS CHAR(64)), CAST(:type AS VARCHAR(20)); a Types.VARCHAR bind does not help, the driver still sends NVARCHAR); the URL flag sendStringParametersAsUnicode is untouched. The index already existed, no migration. The other statements that compare a string parameter with a CHAR/VARCHAR column are administration screens or filters on small tables behind a numeric key, not hot paths. (InboxDuplicateCheckPlanIT.) The retention gap F1 pointed at (nothing purged inbound_notification and wire_log) is closed by D-139. Closed (D-139)
D-139 Data retention and the review of the hot queries' indexes (2026-11-16); closes the retention gap of D-138 Closed (2026-11-16): the gateway purges what it keeps only to look at, and the queries a review proved scanning read pages, not tables. Retention (RetentionJob, RUNBOOK section 14): processed inbound_notification rows and every wire_log row older than gateway.retention.days (90, 7 to 3650, validated at start) are deleted off-peak (03:00 to 05:00 in America/Argentina/Buenos_Aires, gateway.retention.window-*), in batches of 200 (at most 500: a batch of 500 was seen to reach the ~5000-lock threshold of escalation to a table lock, attempts counted by SQL Server, so the default is 200), each its own short transaction on a connection of its own with LOCK_TIMEOUT (2 s at most), DEADLOCK_PRIORITY LOW and a timeout on every statement shorter than the lease (the purge is the victim, never the traffic; the session is restored or the connection discarded), a pause of 200 ms between batches, a cap of 500,000 rows PER WINDOW shared by every node and restart (kept in job_lease, counted in the transaction of each batch only while the lease is the writer's; about 5 KB of transaction log per deleted row measured, so also a log budget of about 2.5 GB, recovery model to be checked on production, RUNBOOK section 14), a stop at the end of the window, a watermark so rows that must stay are read once per run, and a lease (job_lease, database time, renewed per batch) so one node of several works. The safety check of a row is a CASE of EXISTS, so SQL Server judges it row by row through seeks (payment, intention by Prisma id, compensation task, reversal): 50 logical reads for every inbox row deleted that belongs to a payment, 33 for a wire log row (the first form, one OR of the same tests, read 1,145 per row, and a column-to-column join did not use the filtered index on intention.prisma_intention_id, which is now named in the statement), measured by RetentionLinkedRowsPlanIT on 50,000 payments with 100,000 tasks and 20,000 reversals. Never purged: payment, intention, the snapshots, wallet_charge, reversal, reversal_resend, compensation_task, admin_audit, admin_user and the configuration. Product decision (the user): inbox rows a person must read (ABANDONED, UNCORRELATED, CHECKOUT_MISMATCH, FOREIGN_INTENTION, WRONG_STATE, UNUSABLE_NOTIFICATION, UNUSABLE_RESULT, UNUSABLE_BINS, REVERSAL_UNKNOWN, LATE_AFTER_REFUND) are never purged until an ADMIN marks them reviewed (reviewed_at, reviewed_by, review_comment in V3; console screen "Notificaciones a revisar" and GET /admin/api/v1/inbox/review, POST /admin/api/v1/inbox/{id}/review with a required comment, CSRF and audit; the dashboard counts the unreviewed); only a reviewed row older than the retention is purged. A callback written to the wire log before its intention existed is protected through wire_log.prisma_intention_id (V3); reversal notifications that name no intention end in UNCORRELATED/REVERSAL_UNKNOWN, so the review gate protects them (no link through prisma_payment_id: it repeats and is not indexed). A row of either table stays while its payment (by payment_id, or by the Prisma intention id the body names) is not over (RetentionRules), has a compensation task or a reversal open or being resent, or has a task that gave up whose money no other reversal returned. Off in local and test, on by default everywhere else; no metric (the application exposes none), one summary line per run, RETENTION_RUN_FAILED at ERROR. Late duplicates (AC-10): safe, no dedup table needed. The purge removes the inbox's memory of a first delivery (body_hash), so a callback that arrives again is processed as a first one; what makes it harmless is the state of the payment, intention, charge and reversal, which are never purged: a purchase notification is DUPLICATE by the wallet payment id, a BINs callback NOT_LIVE, a second charge finds its charge and its one reversal chain, an annulment or refund notification finds its reversal COMPLETED/FAILED and schedules no second refund. RetentionLateDuplicateIT purges the real rows and redelivers every callback of an approved sale, a late approval that was annulled, a refused annulment followed by a refund and a second charge, and asserts that payment, intention, charges, reversals, tasks, snapshots and the terminal's numbers are exactly what they were (the reformatted-bytes case already had ac10_). Indexes (V4, apart from the cheap DDL of V3 because a Flyway file holds its locks until it ends: the builds block the writers of their table, so V4 is applied in the off-peak window before the other nodes are restarted, RUNBOOK section 14; the migration's comments have the query, the reads before and after and the write cost of each): ix_inbound_notification_processed for the purge (13,149 reads per batch, 4 after), ix_inbound_notification_claim (type, received_at) filtered to the waiting rows for the claim of the inbox lanes (with 3,000 unclassifiable UNKNOWN rows and 20,000 notifications waiting: 9,204, 70,500 and 45,633 reads, 11, 3 and 4 after; the claim polls every half second), and ix_intention_checkout_state (checkout_id, state) for the live intention asked at every trxpago (678 reads on 150,000 intentions, 13 after), and the filtered ix_inbound_notification_review for the review list and the dashboard count. Indexes that code names in a hint must not be dropped (ix_inbound_notification_body_hash, ix_inbound_notification_unprocessed, ix_inbound_notification_review, ux_intention_prisma_id; RetentionIndexIT). Fixed in the code with no index: the console's trail of a payment (an OR over the inbox read 2,883,615 pages, 1.5 s; two seeks, 21 reads) and the dashboard's count of waiting callbacks (a scan of the whole inbox, 45,214 reads; the index named in the statement, 17). Measured and found fine: the compensation claim and backlog with 100,000 finished tasks, the orphan wait reaper, the dashboard's payments by day and authorizer calls, the console search by id, checkout, merchant or without a filter, the wire log of a payment, the charge lookups by payment and by intention (the reversal lookups were not measured: that table was empty in the seed). HotQueriesPlanIT, RetentionPlanIT, RetentionConcurrencyIT (300,000 rows purged at full speed in 12 s while four threads stored callbacks: no failure, max 295 ms, no lock escalation counted by SQL Server) keep them so. Load run (tools/load-test, 25 concurrent checkouts, 87,000 old rows purged during it, warm gateway): BINs callback p95 14 ms, p99 28 ms, no 5xx, approved-flow success 1.0, all invariants PASS, purge 51 s. The first runs found a real defect: after the purge changed the statistics SQL Server flipped the plan of the duplicate check of the inbox to walk ix_inbound_notification_prisma_payment (17,734 reads per call, one hot key range queueing every callback: BINs p95 496 ms, p99 2.9 s), so FIND_EARLIER now names ix_inbound_notification_body_hash. Still open, small: (a) callbacks of type UNKNOWN (nothing claims them) never get processed_at, so the purge, which takes processed rows only, never deletes them; (b) the console search by a state that no payment, or very few, has scans payment (3,078 reads at 150,000 payments: the optimizer walks the primary key backwards whatever the parameter type, and a (state, id) index did not change the plan) and so does a search by a day that is not recent (3,100): they need a rewrite or a hint, not an index; (c) the guard that stops the console renaming a checkout with payments not over reads 6,003 pages on a checkout of 1,500 payments (a rare write of an administrator); (d) admin_audit, bins_snapshot, complete_snapshot and the finished compensation tasks still have no retention (D-S5-5); (f) the check of a row and its delete are not atomic under READ COMMITTED: a payment that reopens between them loses the log evidence of a row older than the retention, never money (evidence only, documented, not worth range locks on the payment tables); (e) the SQL Server of the development machine is Express: indexes are built offline and the database is capped at 10 GB; the edition of production decides whether a later migration may use ONLINE = ON. Residuals split on 2026-11-16: (a) D-140, (b) D-141, (c) D-142, (d) D-143, (e) D-144, (f) D-145, and the reversal lookups that were not measured D-146. This entry stays closed. Closed
D-140 D-139 residual (a), 2026-11-16 Callbacks of type UNKNOWN (nothing claims them) never get processed_at, so the retention, which takes processed rows only, never deletes them (RetentionRules says so). They grow for ever. Decide the rule: mark them processed with a terminal outcome after a grace period, or purge them by age explicitly; an unclassified callback may be one a person wants to see, so mind the review gate. Hardening
D-141 D-139 residual (b), 2026-11-16 The console search by a payment state that no payment (or very few) has scans payment (3,078 reads at 150,000 payments: the optimizer walks the primary key backwards whatever the parameter type, and a (state, id) index did not change the plan), and so does a search by a day that is not recent (3,100 reads). It needs a rewrite or a hint, not an index. Hardening
D-142 D-139 residual (c), 2026-11-16 The guard that stops the console renaming a checkout that has payments not over reads 6,003 pages on a checkout of 1,500 payments. It is a rare write of an administrator, so it is cheap to leave; rewrite it if checkouts with many payments appear. (The indexes that code names in a hint are a different matter: RetentionIndexIT fails the build if one is dropped.) Hardening
D-143 D-139 residual (d), D-S5-5, 2026-11-16 admin_audit, bins_snapshot, complete_snapshot and the finished compensation tasks have no retention. The snapshots and the tasks are evidence for reversals, so the rule per table (age, and what must stay while a payment or a reversal is open) is a product decision first; measure their growth on production before writing it. Human decision, then hardening
D-144 D-139 residual (e) and deploy notes, 2026-11-16 The edition and the recovery model of the production SQL Server are not known to the repository. The edition decides whether a later index migration may use ONLINE = ON (the development machine is Express: offline builds, 10 GB cap); the recovery model decides what the nightly purge does to the log (about 5 KB of log per deleted row, 2.5 GB at the cap of 500,000 rows; in FULL the log is kept until a log backup runs). Before the first night: check SELECT name, recovery_model_desc FROM sys.databases, the free space of the log drive and the log backups (RUNBOOK section 14), lower max-rows-per-run if the disk needs it, and apply V4 in the off-peak window. Procedure delivered 2026-11-17 (go-live checklist): db/ops/check-gateway-database.sql reports the edition, the recovery model and the backups, and RUNBOOK 15.3 and 15.4 say what to do with each; this stays open until it is run on the production server. Before go-live (operations check)
D-145 D-139 residual (f), 2026-11-16 The safety check of a row and its delete are not atomic under READ COMMITTED: a payment that reopens between them loses the log evidence of a row older than the retention, never money. Accepted and documented; range locks on the payment tables are not worth it. Reopen only if the evidence of an aged row ever has to be guaranteed. Accepted (documented)
D-146 D-139 (not measured), 2026-11-16 The reversal lookups (by payment, by intention, by Prisma id) were not measured by the review of the hot queries: the reversal table was empty in the seed. Add them to HotQueriesPlanIT with a seeded table and check the plans. Hardening
D-147 D-14 (go-live checklist, 2026-11-17) Expand/contract migrations for rolling upgrades. Production is one node and a restart is a stop and a start, so there is no rolling upgrade today and nothing here needs it. The rule that every migration is backward compatible with the previous jar holds for V2 to V4 (RUNBOOK sections 5 and 14), is checked by review only, and is not codified or tested: no CI check applies the newest migration and runs the previous version's tests against it. Do it when a second node is added (the two-node test branch is the natural place), together with the question of which node migrates first (RUNBOOK 15.2). A second node
D-148 D-14 (go-live checklist, 2026-11-17) Rehearsal on the central server of what was proven only on Linux and by reading. CI proves the packaged jar under prod on Linux with a throwaway certificate; nothing here ran on the Windows server: the NSSM commands of RUNBOOK 2, 2c and 15.2 (AppParameters with the new JVM flags, AppEnvironmentExtra and nssm reset for the migration login), icacls on the config and on dumps, the housekeeping schtasks quoting (the PowerShell command was run on a scratch folder, the schtasks line was not), SQL Server's own certificate in the JVM trust store, the real edition (the Express 10 GB limit and the offline V4 builds), and the heap and working set with -Xmx512m (re-run the soak of tools/load-test with the flags of 2c if the server is tight). Also the first real run of release.yml (D-24). Before go-live, on the server
D-149 go-live checklist (2026-11-17) The console's unit tests are not in the CI gate, because they are flaky under load. In three full local runs of npm test (Vitest, 56 files, 679 tests, on a machine that was also running other builds) a different test failed each time (CockpitFlows, CockpitPage, PlansPage: a findByRole or a 5 s timeout), and every one of them passes when its file is run alone; none touches code of this change. CI therefore runs npm ci, npm run lint, npm run build and npm run scan:dist (what the release needs), not npm test. Find the load sensitivity (fixed 1 s findBy timeouts under parallel workers, an async effect that does not settle) or cap the workers, then add npm test to the step. Before the gate is trusted for console changes