Reference system2026Public source

CargoMesh

A deterministic transaction compiler and durable runtime for container logistics.

I defined the transaction model, execution boundaries, verification states, and acceptance strategy for the reference system.

Role: System architect and independent builder
Capability proof: Shows contract-first platform design, deterministic domain modeling, durable workflow decisions, and fail-closed verification.
Technology: Python · Temporal · DCSA contracts · Playwright

Context

Container-logistics software sits between changing standards, carrier-specific interfaces, browser fallbacks, approvals, and business actions that may be difficult to reverse. The engineering problem is not simply moving JSON between systems. It is preserving the identity and intent of a transaction while the execution path, evidence source, and external interface can all change.

CargoMesh is a public reference system that explores this boundary. It compiles pinned DCSA contracts into deterministic Transaction IR, freezes an execution plan, runs approved work through durable orchestration, and records separately sourced evidence before assigning a verification state.

Problem

A successful request is not the same as a proven commercial outcome. A carrier call can time out after accepting work; a portal can drift; a retry can duplicate a booking; evidence can arrive late or contradict the execution receipt. Treating every completed adapter call as success would hide precisely the risks the system is meant to control.

The design therefore separates execution state from verification state. EXECUTED_UNVERIFIED means an action finished without sufficient independent proof. VERIFIED requires matching evidence. Conflicts become NEEDS_REVIEW; missing, stale, or insufficient evidence becomes HALTED. This narrower vocabulary is more useful than an optimistic green check because it tells an operator what is known, what remains uncertain, and when automation must stop.

What this case proves

Contract-first modeling can make replay and compatibility decisions deterministic.
Durable workflow state can preserve approval, retry, cancellation, and compensation across process boundaries.
Independent evidence can prevent execution receipts from becoming unsupported outcome claims.

Constraints

Constraints that shape the system

External logistics contracts evolve, but an accepted transaction must remain reproducible against the exact contract version used.
Retries and compensation can create real side effects, so execution state cannot be reconstructed from an in-memory request alone.
A successful adapter call is not sufficient proof that the intended business outcome occurred.

Key decisions

Choices, alternatives, and trade-offs

Compile before executing

Context: Pass-through payloads make later replay, migration, and policy decisions depend on changing external schemas.
Choice: Pin the source contract and compile it into a strict, immutable Transaction IR with canonical JSON and a digest.
Alternatives: Forward external JSON directly to adapters; Maintain informal field mappings inside each integration
Trade-off: The compiler adds up-front schema work, but it makes compatibility changes and execution identity explicit.

Inspect supporting evidence

Reuse a durable workflow runtime

Context: Approval waits, retries, cancellation, and reverse compensation outlive a single process request.
Choice: Use Temporal for durable orchestration and keep adapter effects behind explicit Activity boundaries.
Alternatives: Build a custom queue and state machine; Retry inside API request handlers
Trade-off: Temporal is an operational dependency, but it avoids inventing a less inspectable workflow engine.

Inspect supporting evidence

Architecture and failure behavior

Responsibility, input, output, and failure

01
Pinned contract
Freeze the accepted DCSA source and compatibility boundary.
Input
Versioned standard files
Output
Verified local contract source
Failure
Digest or compatibility mismatch fails before compilation.
02
Transaction compiler
Normalize business intent into deterministic Transaction IR.
Input
Pinned contract payload and tenant context
Output
Canonical IR, diagnostics, and digest
Failure
Unknown fields or invalid predicates are rejected explicitly.
03
Execution plan
Freeze dependencies, approval, retry, and compensation rules.
Input
Transaction IR and policy
Output
Immutable ordered plan
Failure
Denied or unresolved policy stops submission.
04
Durable runtime
Execute approved adapter operations with queryable state.
Input
Plan, signals, and adapter bindings
Output
Receipts and execution state
Failure
Retryable faults are bounded; ambiguous effects halt for verification.
05
Independent verification
Compare separately collected evidence with intended outcomes.
Input
Immutable receipts and bounded observations
Output
VERIFIED, NEEDS_REVIEW, or HALTED verdict
Failure
Missing, stale, or conflicting evidence never becomes VERIFIED.

Failure modes

How failure is detected, bounded, and escalated

Trigger	Detection and response	Side effects and human boundary	Assurance
The same idempotency key is reused for different business intent.	Tenant-scoped digest comparison detects the conflict. Reject the second submission instead of starting new work.	No adapter operation starts for a conflicting replay. The caller must resolve which intent is authoritative.	Verified
A portal recipe no longer matches the expected interface signature.	Origin, heading, label, and notice checks produce a drift signature. Stop the browser path rather than guessing a selector.	Recipes are read-only, checksum-pinned, and isolated per invocation. A reviewed adapter update is required before retrying.	Verified
An execution result is ambiguous after an external timeout.	The runtime records an unknown-effect state instead of assuming failure. Collect independent evidence before any retry or cancellation decision.	Effectful work does not automatically fall through to another route. Conflicting evidence becomes NEEDS_REVIEW.	Designed
Compensation fails after a later plan step fails.	The durable plan records the failed reverse action and current state. Halt with queryable failure detail rather than claim rollback succeeded.	Compensation order is frozen before execution. An operator reviews unresolved external state.	Designed

Project evidence

Evidence and its verification scope

Architecture

Pinned DCSA contracts and deterministic Transaction IRVerified scope

CargoMesh compiles pinned logistics contracts into versioned, digest-backed business transaction representations.

Reference implementation using the documented accepted transaction demonstrations.CargoMesh README — implemented surface

Durable workflow runtimeVerified scope

Execution paths model approval, retry, compensation, cancellation, and queryable state using Temporal rather than a custom workflow engine.

Local reference runtime; external production services remain outside the repository.CargoMesh README — durable runtime

Verification

Explicit verification statesVerified scope

The system distinguishes EXECUTED_UNVERIFIED, VERIFIED, NEEDS_REVIEW, and HALTED instead of treating execution as proof of outcome.

Deterministic reference reports and separately sourced evidence.CargoMesh README — verification boundary

Disclosure

External integration boundaryVerified scope

The repository explicitly distinguishes synthetic adapters and local control boundaries from real carrier, identity, payment, and cloud integrations.

Public repository disclosure.CargoMesh README — implementation disclosure

Honest status

Implemented, not claimed, and still required

Running status: Reference system
Data: Deterministic fixtures and explicitly synthetic transaction demonstrations.
External integrations: Synthetic API/browser adapters; real carrier, identity, payment, and cloud integrations remain external.
Revenue claim: No customer traffic or commercial revenue is claimed.
Source: Public source
Before production: Real adapter certification, hosted identity and secrets, deployment hardening, and independent operational review remain required.

Integration scope: Accepted demonstrations use synthetic API/browser adapters and a deliberately synthetic booking slice; real carrier, identity, payment, and cloud integrations remain external.

Reflection and next priorities

What worked

Separating execution from verification made the system's strongest claim precise: an action can finish without yet being proven.

What I would change

I would introduce the smallest accepted vertical slice earlier, then expand boards only when each one changes a concrete failure boundary.

Next priorities

Certify one real read-only adapter against the existing contract and drift tests.
Run the durable runtime in a hosted staging boundary with externalized secrets.
Add independent operational review before any effectful production integration.

Not worth doing yet: A broad adapter marketplace is not worth building before one real integration proves the certification and support model.

Hiring

Discuss a role using this evidence

Discuss a suitable role

Project

Discuss a focused adaptation

View source Discuss this project