ADR-0002: Private exchange and execution handover
Generated from
docs/adr/0002-private-exchange-execution-handover.md. Edit the canonical source file, not this page.
Status: Accepted
Date: 1 September 2026
This ADR expands the first protocol profile from capacity discovery into a complete private exchange between heterogeneous transport management systems. It supplements ADR-0001 and does not turn OpenFreytProtocol into a universal transport model.
D015 — Separate discovery from execution transfer
Section titled “D015 — Separate discovery from execution transfer”Capacity discovery, load discovery and match proposals remain independent from transport tendering and execution handover. A match may lead to a tender, but a match is neither an operational assignment nor a legal commitment.
D016 — Transfer a bounded execution package
Section titled “D016 — Transfer a bounded execution package”The protocol transfers a vendor-neutral execution package containing only the stops, time windows, cargo facts, constraints, references, instructions and disclosure-controlled contact details needed to perform an accepted movement. It does not copy a source system’s internal ride, order, shipment, route or planning object.
The source and executing systems retain their own local records. The exchange links those records through the protocol resource identifier and namespaced external references.
D017 — Distinguish agreement from technical handover
Section titled “D017 — Distinguish agreement from technical handover”Commercial acceptance and technical import acknowledgement are separate state transitions. An accepted tender creates an immutable commitment; it is not operationally handed over until the executing system acknowledges that it created or linked the corresponding local record.
D018 — Trust is organizational, technical and bilateral
Section titled “D018 — Trust is organizational, technical and bilateral”An access token alone is not sufficient trust. The private exchange requires:
- a verified organization identity;
- a registered connector or interactive client bound to that organization;
- an active bilateral partner relationship;
- granted API scopes and relationship policy;
- resource-specific visibility and disclosure policy;
- actor authorization for the requested lifecycle transition.
Machine clients use the protocol security profile. Interactive users authenticate through OpenID Connect. Internal TMS session tokens are not portable exchange credentials.
D019 — The exchange is a coordination control plane
Section titled “D019 — The exchange is a coordination control plane”The exchange is authoritative for partner relationships, exchanged resources, decisions, commitments, handover state and the shared audit journal. Connected systems remain authoritative for their local commercial, planning and execution records.
Connectors translate between local models and canonical protocol resources, preserve references, process messages idempotently, quarantine unsafe mappings and reconcile after missed delivery or downtime.
D020 — Profiles keep the canonical contract bounded
Section titled “D020 — Profiles keep the canonical contract bounded”The protocol is organized into composable profiles:
- core identity, relationship, concurrency and error behavior;
- discovery for capacity, demand and matching;
- tendering and immutable commitment;
- execution handover, amendment, cancellation and operational updates;
- security and connector conformance.
An implementation advertises the versions and optional capabilities it supports. Unsupported optional capabilities must fail explicitly rather than being silently ignored.