Ambiguous transmission
A timeout or response-path loss can follow a durable remote effect. FaultLedger records uncertainty instead of assuming failure.
Work / Engineering case study
FaultLedger
A deterministic .NET laboratory for studying failure modes in distributed financial-style transaction orchestration.
Open SourceLaboratoryReview Required
01 / Project overview
Make distributed transaction failure boundaries inspectable.
FaultLedger is described in its public repository as a deterministic .NET laboratory for distributed financial-style transaction orchestration. It studies how exact money, explicit transfer states, provider uncertainty, durable identities, and delivery boundaries behave under failure.
The project is synthetic and laboratory-scoped. It is not a real payment processor, bank, wallet, card processor, or production financial platform. It does not move real money.
02 / Engineering problem
A timeout does not prove that a remote effect did not happen.
Distributed financial-style workflows can fail between local persistence, provider transmission, provider acceptance, callback receipt, and downstream delivery. A missing response can therefore be ambiguous rather than a safe invitation to submit again.
FaultLedger makes those boundaries explicit so that retry, reconciliation, callback, and delivery behavior can be inspected as durable state transitions.
03 / Correctness model
Correctness is a set of durable facts and guarded transitions.
Exact money handling with explicit currency and precision rules
Explicit transfer states, including ambiguous and unknown outcomes
Durable idempotency backed by PostgreSQL invariants
Reconciliation and duplicate-safe callback processing
Transactional inbox and outbox boundaries
Duplicate-safe consumption and recoverable delivery semantics
The repository describes PostgreSQL as the durable correctness boundary for transfers, fingerprints, inbox, outbox, and audit history. Process-local locks and caches are not treated as the source of truth.
04 / Failure boundaries
Unknown is an explicit outcome with a conservative next step.
Durable before acknowledgement
Authenticated callbacks are bounded, persisted, and processed with duplicate and stale evidence handling.
At least once
Publication can be redelivered with the same event identity. FaultLedger does not claim exactly-once distributed delivery.
05 / Architecture
A small modular monolith with explicit external boundaries.
The public repository describes an API, application, domain, and infrastructure split. Infrastructure adapts PostgreSQL, HTTP, a synthetic provider, a simulated consumer, inbox/outbox delivery, and audit history.
There is no real provider rail, Redis, broker, event-sourcing framework, wallet, or real ledger in the stated project scope.
- 01APIValidated local HTTP boundaries for transfer and callback flows
- 02ApplicationOrchestration, contracts, diagnostics, and reconciliation
- 03DomainExact money and guarded transfer state transitions
- 04InfrastructurePostgreSQL, synthetic provider, inbox, outbox, and audit history
06 / Why UNKNOWN matters
Do not turn uncertainty into an accidental duplicate.
When a provider response is missing, Unknown preserves the fact that local code cannot prove whether the remote side accepted the operation. FaultLedger documents a conservative DoNotRepost path and routes ambiguity to lookup-based reconciliation.
That boundary is the point of the laboratory: a retry policy must respect what the system knows, what it does not know, and which evidence is durable.
07 / Delivery semantics
Durable identities make retries inspectable.
Idempotency keys map to immutable request fingerprints. Callback event IDs, inbox records, outbox messages, and simulated consumer receipts provide durable identities for duplicate-safe processing.
Outbox publication is documented as at least once. A remote effect may commit before the local publication mark does, so redelivery uses the same event identity. This is a laboratory model, not an exactly-once guarantee.
08 / Evidence and inspection
Read the repository with its evidence boundaries intact.
The public repository is the available external evidence for this case study.
- Exact Money and guarded Transfer transitions
- Idempotency, reconciliation, callback, dispatcher, and instrumentation tests
- PostgreSQL and Testcontainers scenarios documented as Docker-dependent evidence
- Synthetic provider and Toxiproxy failure scenarios
Documentation review required: README.md describes an implemented application and test evidence, while SECURITY.md and CONTRIBUTING.md still describe a governance-only repository with no application. Until that drift is resolved in the public repository, this case study does not present the implementation as fully verified or production-ready.
Docker-dependent PostgreSQL, Testcontainers, restart, outbox, consumer, and Toxiproxy scenarios are documented as blocked or environment-dependent in the repository evidence.
Inspect FaultLedger on GitHub (external)Next step