Settlement proof

settlement-proof

Verify state, not an actor's success message. Treat this as a read-only airlock for payment outcome claims.

Enforce the safety boundary

• Query only read APIs or operator-provided snapshots.
• Never repair, retry, capture, refund, reverse, reconcile, or post ledger entries.
• Halt on the first mismatch and report it.
• Mark missing or pending evidence UNVERIFIABLE; never infer agreement.
• Keep credentials and customer data out of snapshots and packets.
• Label synthetic inputs and outputs as synthetic.

Run an included synthetic fixture

Execute from the skill directory:

node scripts/verify-fixture.mjs fixtures/settled

Use any included fixture directory or its scenario.json file. Interpret exits as:

• 0: PROVED
• 1: MISMATCH; stop the enclosing workflow
• 2: UNVERIFIABLE or invalid input; do not claim success

Do not continue to a mutation step after exit 1 or 2 unless a human starts a separate, explicitly authorized workflow.

Map the contract onto real systems

1. State the exact claim: paymentId, terminal outcome, integer amountMinor, and currency.
2. Identify the authoritative processor, ledger, idempotency store, reconciliation result, and compensating-action log for the same tenant and environment.
3. Obtain least-privilege read access. Refuse to use a mutation-capable tool when a read-only alternative is required by policy.
4. Read all systems within one logical observation window. Record observedAt and stable correlation identifiers.
5. Normalize the reads into the shape used by fixtures/*/scenario.json with synthetic: false.
6. Store the snapshot in a protected local temporary path without secrets, PANs, bank details, names, emails, or raw provider payloads.
7. Run node scripts/verify-fixture.mjs <snapshot-path>.
8. Return the complete evidence packet and its exit meaning. On MISMATCH, name the halt location and leave later checks as NOT_EVALUATED.
9. Retain or remove the snapshot only under the operator's privacy, evidence, and audit policy.

Map adapters to this minimum contract:

{
  "synthetic": false,
  "observedAt": "2026-07-13T12:00:00.000Z",
  "claim": {
    "paymentId": "opaque-payment-id",
    "outcome": "SETTLED",
    "amountMinor": 10000,
    "currency": "USD"
  },
  "systems": {
    "processor": {
      "paymentId": "opaque-payment-id",
      "processorTransactionId": "opaque-processor-id",
      "outcome": "SETTLED",
      "amountMinor": 10000,
      "currency": "USD"
    },
    "ledger": {
      "entries": [
        {
          "entryId": "opaque-entry-id",
          "paymentId": "opaque-payment-id",
          "account": "processor_clearing",
          "kind": "SETTLEMENT",
          "status": "POSTED",
          "amountSignedMinor": -10000,
          "currency": "USD"
        }
      ]
    },
    "idempotency": {
      "key": "opaque-idempotency-key",
      "attempts": 1,
      "appliedEffects": 1,
      "duplicatesSuppressed": 0,
      "lastResult": "APPLIED"
    },
    "reconciliation": {
      "jobRunId": "opaque-job-id",
      "result": "MATCHED",
      "paymentId": "opaque-payment-id",
      "outcome": "SETTLED",
      "amountMinor": 10000,
      "currency": "USD"
    },
    "compensatingActions": []
  }
}

Supply a complete balanced ledger entry set; the single entry above demonstrates field names only and would correctly produce MISMATCH.

Report precisely

• Say PROVED only when every v1 check passes.
• Say MISMATCH when observed state contradicts the claim, and quote halted.at plus halted.reason.
• Say UNVERIFIABLE when evidence is absent, incomplete, pending, or malformed, and quote unverifiableReasons.
• Describe compensating actions only as observed state. Do not recommend or execute one as part of verification.
• Keep the limitations in README's WHAT IT DOES NOT PROVE section attached to high-stakes interpretations.