Idempotency as a contract
The reference proof is documented to retry payment.capture.v1, then force a conflicting reuse of its idempotency key.
Engineering backend correctness for decisions under uncertainty.
Signal is a reusable, protocol-governed decision-processing platform for events, evidence, assessment, decisions, learning, memory, replay, and audit. It makes dangerous operations explicit and inspectable without presenting the project as a client result.
The problem
When a timeout does not tell you whether the operation happened.
State-changing systems must distinguish a new operation from a retry, a duplicate event, a conflicting identifier, and a replayed request. Without explicit records, a caller may not know whether to retry, reconcile, or stop.
Signal’s repository describes a model where Queries, Mutations, and Events have stable names, schemas, idempotency metadata, replay information, subscriber dedupe, and audit evidence. Those are architectural mechanisms to inspect—not a blanket claim that every distributed failure is solved.
Architecture
Protocol first, execution explicit, evidence visible.
The public README identifies three kernel packages: @signal/protocol for shared contracts, @signal/runtime for dispatch and execution mechanics, and @signal/ports for dependency-inversion boundaries.
Verified architecture model
CallerMutation or event
ProtocolNames, envelopes, schemas
RuntimeDispatch, idempotency, replay, audit
PortsDependency boundaries
Domain operationBusiness behavior and validation
EvidenceAudit, outbox, emitted events
The diagram follows the repository’s stated separation: protocol defines the shared language, runtime executes operations, ports expose capability boundaries, and domain packages provide decision intelligence. Persistence and external side effects remain system-specific boundaries rather than an automatic exactly-once guarantee.
Replay-aware operations
Replay metadata and subscriber dedupe are named behaviors in the documented runtime model, while delivery guarantees remain bounded.
Auditable evidence
The reference proof describes redacted audit and outbox evidence, making accepted and recorded behavior reviewable.
Domain-agnostic kernel
Decision packages sit outside the kernel, so runtime mechanics and domain intelligence remain separate concerns.
Reference walkthrough
A payment capture proof, as documented by the project.
The repository instructs developers to run pnpm proof:reference. The sequence below reflects the README’s stated proof scope; it is not presented as an execution performed during this portfolio build.
- 01
Submit payment.capture.v1 with an idempotency key.
- 02
Retry the same operation and observe replay handling.
- 03
Force conflicting reuse of the operation identifier.
- 04
Inspect redacted audit and outbox evidence.
- 05
Check subscriber dedupe and run certification.
Evidence and limits
What the public artifact supports.
| Behavior | Supporting source | Status | Limitation |
|---|---|---|---|
| Stable operation contracts | README: protocol, runtime, and ports packages | Documented | This page does not independently certify every contract. |
| Duplicate mutation handling | README reference proof: payment.capture.v1 with the same idempotency key | Documented | Execution was not run in this portfolio build. |
| Conflict detection | README reference proof: forced idempotency conflict | Documented | The exact response is not reproduced here. |
| Audit and outbox evidence | README reference proof: redacted audit and outbox evidence | Documented | Retention and storage guarantees need deeper source review. |
| Subscriber deduplication | README reference proof: subscriber dedupe check | Documented | External delivery guarantees remain outside this artifact. |
This case study does not claim exactly-once external execution, tamper-proof audit records, complete replay prevention, or production adoption. Those properties depend on persistence, transaction boundaries, external side effects, retention, and deployment assumptions that require deeper inspection than the public README alone provides.