OpenFreytProtocol Context

Generated from CONTEXT.md. Edit the canonical source file, not this page.

Status: Authoritative project context, pre-alpha

1. Purpose

OpenFreytProtocol enables logistics organizations that trust each other to discover capacity and demand, tender transport work, create explicit commitments and transfer execution between heterogeneous transport management systems.

The initial product profile is a closed private exchange. It allows accepted partners to publish constrained supply and demand, discover compatible opportunities, negotiate versioned tenders, record authorized commitments, transfer a bounded execution package and share execution outcomes.

Freyt is the first reference client, not the mandatory source of truth. Other TMS products, brokers, integration platforms and lightweight portals participate through the same public contract.

2. Problem boundary

Transport organizations frequently have:

• empty return movements;
• partially used vehicles;
• recurring lanes with unused capacity;
• transport demand a trusted partner could execute;
• fragmented partner-capacity information;
• incompatible TMS data models;
• no neutral, low-friction exchange contract.

Public freight exchanges solve a different problem. They typically optimize broad market discovery and spot transactions. OpenFreytProtocol focuses on controlled collaboration between known organizations, with explicit authorization and limited information disclosure.

3. Protocol thesis

A dependable partner exchange requires:

1. bilateral partner acceptance;
2. explicit data-sharing scopes;
3. minimal disclosure before commitment;
4. precise capacity and demand semantics;
5. deterministic, explainable compatibility;
6. explicit acceptance and withdrawal;
7. idempotent commands and ordered resource history;
8. implementation-independent conformance tests.

The protocol standardizes the exchange boundary. It does not replace the planning, pricing, external legal contracting or local execution responsibilities of participating systems. The exchange is authoritative for shared relationships, tenders, commitments, handover state and audit history; each connected system remains authoritative for its local operational records.

4. Actors

• Capacity provider: publishes available vehicle or trip capacity.
• Capacity requester: publishes demand for transport capacity.
• Partner administrator: establishes relationships, permissions and disclosure policy.
• Planner: evaluates proposals and tenders, records decisions and reviews amendments or exceptions.
• Executing partner: accepts committed work and acknowledges creation or linkage of its local execution record.
• Reference broker: authorizes discovery, maintains exchange state, records commitments, coordinates handover and emits events.
• TMS connector: maps a participant’s internal model to the public protocol, preserves references, quarantines unsafe mappings and reconciles after downtime.
• Reference client: Freyt is the first rich implementation without privileged protocol semantics.

An organization may perform more than one role.

5. Initial use cases

5.1 Empty return capacity

A provider publishes that a vehicle can carry a compatible load on or near a return corridor within a bounded time window.

5.2 Residual capacity

A planned movement has available weight, volume, pallet-space or loading-metre capacity that can be offered to accepted partners.

5.3 Load request

A partner publishes demand using coarse pickup and delivery areas, time windows, capacity requirements and operational constraints.

5.4 Recurring corridor

Partners describe repeating supply or demand on known corridors without exposing their complete planning data.

5.5 Match decision

The broker or an authorized participant proposes a compatible offer/request pair. The involved organizations explicitly accept, reject or allow the proposal to expire.

5.6 Tender and commitment

A selected partner receives a versioned transport tender. Required authorized decisions over an immutable revision create a commitment. Counterproposals and material amendments preserve prior terms and require the decisions defined by bilateral policy.

5.7 Execution handover

After commitment, the source transfers the minimum authorized stops, time windows, cargo facts, constraints, references and instructions needed to execute the movement. The destination acknowledges whether it imported, linked, rejected or quarantined the package. Both systems retain their local records.

6. Included scope

• organization references;
• bilateral partner relationships;
• scoped visibility and permissions;
• capacity offers and load requests;
• geographic areas and time windows;
• vehicle, equipment and capacity constraints;
• explainable match proposals;
• versioned transport tenders and counterproposals;
• immutable commitments and accepted-payload digests;
• bounded execution handovers and destination acknowledgements;
• amendments, cancellation, exceptions and execution updates;
• organization, connector and bilateral trust policy;
• idempotent commands and optimistic concurrency;
• lifecycle events and reconciliation;
• immutable decision history;
• execution references and outcome status;
• public examples and conformance tests;
• a reference broker and independent clients.

7. Explicit non-goals

• public anonymous freight marketplace;
• mandatory use of one TMS;
• auctions or dynamic price discovery;
• escrow, payments, clearing or claims;
• automatic legal contract formation;
• autonomous award without authorized confirmation;
• complete order, shipment, vehicle or customer synchronization;
• full route optimization;
• multi-leg orchestration in the first profile;
• universal logistics ontology;
• mandatory dataspace or federation infrastructure;
• dependency on proprietary, inaccessible or insufficiently mature protocols.

Existing commercial agreements, prices, liability terms and execution contracts remain outside the core protocol.

8. Architecture direction

8.1 Neutral reference broker

The first implementation uses a central broker for consistent authorization, matching, lifecycle management, idempotency and event publication.

The broker is neutral at its public boundary:

• no Freyt-internal types or database identifiers;
• no privileged Freyt operation;
• all participants use the published contract;
• an independent broker implementation remains possible;
• clients can be validated without access to Freyt source code.

8.2 Small canonical model

The protocol defines only concepts required for partner capacity exchange:

• OrganizationReference;
• PartnerRelationship;
• CapacityOffer;
• LoadRequest;
• MatchProposal;
• MatchDecision;
• ExecutionReference;
• ExecutionOutcome.

Complete transport orders, route plans, customer records and invoices remain external references or adapter concerns.

8.3 Normative layers

• JSON Schema 2020-12 defines shared payload semantics.
• OpenAPI 3.1 defines synchronous HTTP behaviour.
• CloudEvents defines asynchronous event envelopes.
• State-machine specifications define legal transitions.
• Examples and conformance tests define observable compatibility.

8.4 Adapter boundary

Existing enterprise or sector formats may be supported when a real participant requires them. Adapters map at the edge and cannot silently redefine core semantics. Every lossy mapping must be documented.

9. Trust and data sharing

• Relationships require explicit acceptance.
• Offers and requests are not globally visible by default.
• Authorization is evaluated for every command, read and event delivery.
• Visibility can be limited to named partners or relationship-defined groups.
• Exact addresses, customer identities, pricing and sensitive goods details may remain hidden until the configured disclosure phase.
• Participants control publication, withdrawal and future availability.
• Historical decisions remain auditable after withdrawal or termination.
• Logs contain correlation identifiers but avoid sensitive payloads.
• Organization data must never leak through reads, errors, search, metrics, events or caches.

10. Matching principles

The first matcher is deterministic and explainable. Compatibility can consider:

• active partner authorization;
• origin and destination area overlap;
• pickup and delivery windows;
• direction and acceptable detour;
• vehicle and body type;
• weight, volume, pallet and loading-metre capacity;
• equipment and handling requirements;
• goods restrictions;
• participant policy constraints.

Every proposal includes structured reason codes and the observed resource versions. Ambiguous or incompatible cases abstain. A proposed match does not disclose protected data or create a commitment.

11. Reliability principles

• Commands are idempotent.
• Concurrent updates use explicit resource versions.
• Event delivery is at least once.
• Consumers deduplicate events and reject state regression.
• Accepted decisions are append-only.
• Broker restarts cannot lose committed state.
• Expired or withdrawn resources cannot be accepted.
• Failure responses are stable, typed and correlated.
• Every state transition is reconstructable from durable history.

12. Interoperability principles

• Public contracts are implementation-neutral.
• Primitive values use mature public standards.
• Extensions are namespaced and cannot change core behaviour.
• Breaking semantic changes require a major version.
• Every supported version has immutable schemas.
• Compatibility is proven through black-box conformance tests.
• Stable releases require at least one independently implemented client.

13. Success criteria

The protocol succeeds when:

• two independent organizations can integrate without sharing a TMS;
• a participant can publish capacity or demand with minimal disclosure;
• only authorized partners can discover it;
• a proposal can be explained and explicitly decided;
• retries and concurrent actions cannot create duplicate or contradictory commitments;
• accepted matches can be linked to each participant’s execution records;
• independent implementations pass the same conformance suite;
• errors and recovery paths are operationally diagnosable.

14. Open questions

• Which organization-identifier strategy is sufficiently open and practical?
• What is the smallest useful vehicle/body taxonomy?
• Which geographic area representations belong in the first profile?
• Which party or foundation owns protocol governance and trademarks?
• Which disclosure policies are required before and after acceptance?
• Does commitment require one acceptance, bilateral acceptance or configurable policy?
• How are cancellations and execution disputes represented?
• Which first non-Freyt client proves independence?
• Which adapter is justified by the first participating systems?
• What retention periods apply to exchange and audit data?

15. Current direction

Build a small, open and rigorously verified Partner Capacity Exchange protocol. Prioritize one complete interoperable exchange over broad semantic coverage. Expand only when concrete partner use cases and conformance evidence justify the change.