Project: ship a payment feed with executable contract gates

Last updated: 6 Oct 20265 min read

project

Turn one payment-feed contract into negative-fixture tests, candidate-specific release evidence and a rollback-safe serving pointer.

Write a concrete contract

Define payment ID, revision, customer reference, currency, amount in minor units and effective timestamp. Specify the unique grain as payment ID plus revision and state whether a reversal may carry a negative amount. Name two consumer totals that must reconcile. Add field ownership and contract version. The compiler should emit structural and row checks from this one declaration.

Prove tests are wired

Load 470 valid payments and create separate negative fixtures for a null ID, duplicate ID plus revision, unsupported currency, invalid amount and missing timestamp. Each fixture must fail the intended rule; passing valid data alone is not evidence. Record which rules run in the warehouse, which run in a validation job and which remain unimplemented. An unimplemented blocking rule stops the release.

Construct candidate evidence

Build a candidate table without replacing the current pointer. Run key checks, amount totals, null and range checks, and one dependent dashboard query against that candidate. Attach the candidate generation, contract version, runner revision and input positions to the report. Insert a late correction, rerun the checks and prove that the totals change only once. Idempotent loading is necessary but does not replace result reconciliation.

Exercise failure and exception paths

Plant one duplicate that blocks publication. Keep the previous generation serving. Separately plant a waivable country-mix rule failure and approve a narrow, time-limited exception with owner and interval. Show that the exception does not suppress the duplicate failure. Expire it and prove that the same rule can no longer be waived. Retain both failed reports.

Publish and hand over

Repair the duplicate, rerun the full candidate suite and advance the pointer atomically. Query the consumer endpoint and match its generation to the passing report. Submit the contract, generated-rule map, negative-fixture matrix, failure and success reports, exception record, pointer trace, totals and rollback drill. A dashboard that looks correct without a candidate-bound proof does not pass this project.

Implementation

payments = [
    ("pay-47", 1, 2375), ("pay-48", 1, 6400),
    ("pay-49", 1, -125),
]

def payment_gate(records):
    identities = [(payment_id, revision) for payment_id, revision, _ in records]
    if len(identities) != len(set(identities)):
        return {"passed": False, "reason": "duplicate_identity"}
    return {"passed": True, "net_cents": sum(cents for _, _, cents in records)}

assert payment_gate(payments) == {"passed": True, "net_cents": 8650}
assert payment_gate(payments + [("pay-47", 1, 2375)])["reason"] == "duplicate_identity"

Performance and operating cost

The reference duplicate check uses O(N) expected time and O(N) key space for N payments. Full production checks also scan changed data, join reference sets and run consumer queries; record those bytes and elapsed times separately. A candidate and last-good generation require temporary storage, but allow a failed batch to be rejected without interrupting readers.

Common Mistakes

Do not generate tests from a different contract version than the candidate expects.
Do not suppress a blocking duplicate with a warning exception.
Do not advance the public pointer before the exact candidate passes.