Pact Runtime

Turn payout policies into proof-carrying, replay-safe ledger workflows.

Comment

Inspiration

Marketplace payout rules rarely live in one place. The policy describes what should happen, while API handlers, scheduled jobs, retry logic, database code, and ledger scripts each implement part of it.

When those representations drift, engineers cannot easily answer two basic questions:

  • Did this payout follow the exact policy a human approved?
  • Could a retry or race condition settle the same agreement twice?

I built Pact Runtime to make that chain inspectable. It connects an approved payout policy to deterministic runtime artifacts, bounded verification evidence, and the ledger transaction that ultimately changed the recorded balance.

What it does

Pact Runtime turns payout policy into a workflow that can be reviewed, verified, executed, and traced from the original clause to the final ledger postings.

The current version supports one explicit workflow family: a marketplace milestone with funding, delivery, acceptance, a seller and platform split, an exact refund deadline, disputes, replay protection, and competing settlement commands.

The product follows Define → Break → Prove:

  • Define: GPT-5.6 converts policy prose into a structured, source-linked candidate. Missing, unsupported, or contradictory terms appear as visible blockers. A human reviews the normalized rules and approves one immutable candidate hash.

  • Break: A bounded verifier explores the compiled states and transitions, checks invariants, and records minimized counterexamples when it finds an unsafe path.

  • Prove: Each approved clause can be traced through its transition, money effect, generated Numscript, artifact manifest, verification report, and final Formance Ledger postings.

The signature demonstration is the Terminal Race. A buyer release and a scheduled refund attempt to finalize the same agreement concurrently through the ordinary runtime and worker paths.

PostgreSQL allows one command to reserve the terminal outcome. The competing command is rejected with STALE_AGREEMENT_VERSION, and the winning operation produces a single terminal transaction in Formance Ledger. Across 100 isolated races, the recorded tests observed zero double settlements.

Pact Runtime does not hold funds or replace a payment provider. It governs when a supported ledger effect is authorized and refuses to activate or execute artifacts whose evidence, hashes, or stored bytes no longer match.

How I built it

Pact Runtime is a TypeScript and Node.js monorepo organized around shared execution contracts.

One canonicalizer defines the exact bytes used for structured-data hashes. Money uses native bigint internally and canonical minor-unit strings at JSON boundaries, keeping floating-point arithmetic out of monetary paths.

The compiler generates transition tables, event schemas, static Numscript programs, verifier input, traceability records, and a manifest binding the generated files together. Compilation is isolated from timestamps, randomness, locale, and unstable iteration order. A clean-process test confirms that the same approved candidate produces byte-identical artifacts.

A Fastify API coordinates commands through PostgreSQL. Agreement locks, expected versions, actor bindings, trusted time, and stable event identities determine whether a transition may proceed. A separate scheduler captures deadline work from a trusted clock. A separate worker owns the only write-capable Formance Ledger client.

PostgreSQL and Formance Ledger do not share a transaction, so accepted operations are delivered through a durable outbox. Retries preserve the same event, operation, idempotency key, Ledger reference, and expected postings.

After delivery, Pact Runtime compares the returned postings with the approved effect. Missing, malformed, or mismatched evidence is quarantined rather than treated as success.

The Next.js and React interface reads hashes, balances, decisions, verification results, and postings from stored backend records. The public showcase is read-only. Signed, workspace-bound presenter controls operate on isolated demo runs without exposing Ledger credentials in the browser.

How I used Codex

I used Codex throughout implementation, testing, integration, and adversarial review.

I divided the project into narrow workstreams separated by frozen schemas, canonical bytes, and database contracts. Each Codex session received a bounded goal, an owned package boundary, and named acceptance scenarios. I integrated changes only after the relevant build, lint, deterministic-test, and real-service checks passed.

The build record contains 86 focused Codex implementation sessions. Independent reviews found problems that materially changed the system, including compilation from stale approvals, unsafe lock ordering, report and artifact substitution, and an unsigned presenter cookie that could reach privileged actions.

Codex also helped turn integrity and concurrency concerns into executable tests instead of leaving them as design claims. I retained control over decisions that changed authority or product scope, including the supported workflow, approval boundary, trusted-time model, money representation, worker-only Ledger access, and the rule that no model participates after approval.

The complete methodology and session record are documented in BUILD_LOG.md.

How I used GPT-5.6

GPT-5.6 operates at one narrow pre-approval boundary. It interprets policy prose into normalized terms, visible blockers, and evidence linked to the original text. Its response is treated as untrusted data.

GPT-5.6 cannot approve a policy, activate a workflow, authorize a transition, generate or submit a Ledger transaction, or change a balance.

A human approves one exact candidate hash. From that point forward, compilation, verification, activation, authorization, scheduling, retries, and Ledger delivery follow deterministic software paths with no further model calls.

I evaluated this boundary with a 27-call corpus. Twenty-six calls completed structurally, but the evaluation also found policies where the model missed a required blocker or returned an incorrect issue code. Those observed failures shaped the architecture: model interpretation assists human review, but it never becomes runtime authority.

Challenges I ran into

Producing stable artifacts

Deterministic business logic was not enough by itself. Object ordering, time representation, money encoding, file order, and cross-process behavior all had to produce identical bytes. Pact Runtime addresses this through one canonical representation and clean-process artifact comparison.

Maintaining one authorized result across two durable systems

A PostgreSQL commit cannot atomically include a remote Formance Ledger commit. Durable outbox delivery, stable operation identities, Ledger idempotency, posting comparison, and quarantine work together to recover without creating a second financial intent.

Handling trusted deadlines and concurrency

A public caller cannot control authorization-relevant time. The scheduler records trusted effective time and submits deadline actions through the same versioned coordinator as public commands, so competing outcomes are resolved by the real runtime rather than a demonstration shortcut.

Reporting verification honestly

The verifier explores a finite declared model. Reports preserve the explored bounds, states, transitions, invariant results, and counterexamples instead of turning a bounded result into a universal correctness claim.

Accomplishments that I'm proud of

The recorded release completed 439 fast tests and 124 integration tests against real PostgreSQL and the pinned Formance Ledger.

The checks cover:

  • Deterministic compilation across clean processes
  • 1,000 generated scheduler and runtime sequences
  • Worker crash recovery
  • Uncertain Ledger delivery
  • Replay behavior
  • Migration upgrades
  • Artifact and evidence tampering

The project also includes an unsafe policy fixture that the verifier refuses to activate after finding a minimized four-event path that violates two invariants.

In the successful workflow, the interface connects the approved source clause to the generated program, verification result, terminal transaction, and exact balance evidence.

The completed product provides one working path from human-readable policy through approval, deterministic compilation, bounded verification, concurrent runtime execution, durable Ledger delivery, and persisted evidence.

What I learned

The most important design question in an AI-assisted money system is where model authority stops.

GPT-5.6 is useful for extracting and organizing intent, while approval, authorization, compilation, and money movement require independently enforceable boundaries.

Determinism has to begin at the representation layer. Adding hashes later would not resolve disagreements about bytes, ordering, money, time, or identity.

Exactly-once behavior is an end-to-end protocol rather than a database flag. It depends on preserving the relationship between the command, agreement version, operation, outbox record, Ledger idempotency key, transaction reference, and returned postings.

Codex work was easiest to validate when tasks were narrow and acceptance criteria were executable. Independent review sessions were especially useful when asked to disprove a completed claim.

What's next for Pact Runtime

The next step is to add workflow families one at a time, each with an explicit schema, compiler templates, invariants, and acceptance suite. The marketplace milestone will remain the reference workflow and regression fixture.

Planned extensions include:

  • SDKs
  • Webhook delivery
  • Stronger tenant and credential isolation
  • Production observability
  • Broader verification models
  • Regulated payment or custody integrations
  • An external security review

Built With

Share this project:

Updates