ADR-0001: Foundational protocol decisions

Generated from docs/adr/0001-foundational-protocol-decisions.md. Edit the canonical source file, not this page.

Status: Accepted
Date: 31 August 2026

This tracked architecture decision record contains the foundational decisions that govern OpenFreytProtocol. Research is informative and cannot override accepted ADRs. The ignored root DECISIONS.md may serve as a local workflow projection, but this ADR is the durable source.

D001 — Closed partner network first

The first protocol profile supports a closed private exchange. Organizations exchange data only through explicitly accepted partner relationships. ADR-0002 extends the capacity-discovery foundation with tendering, commitment and execution handover.

D002 — Narrow initial use cases

Start discovery with recurring lanes, empty return capacity, residual capacity and compatible load requests. Public spot-market discovery, auctions, multi-leg optimization and automation of external legal contracts remain deferred. ADR-0002 adds operational tenders and protocol commitments without claiming that a protocol commitment replaces a legal transport contract.

D003 — Neutral reference broker

Use a logically neutral central reference broker for the first implementation. Freyt may implement or host it and acts as the first reference client, but every participant uses the same public protocol and no operation is exclusive to Freyt.

D004 — Small project-owned canonical contract

Define a narrow public JSON contract around partner relationships, capacity offers, load requests, match proposals, match decisions and execution handoff. Do not adopt a broad external logistics model as the canonical domain.

Use:

• JSON Schema 2020-12 for payload semantics;
• OpenAPI 3.1 for synchronous HTTP operations;
• CloudEvents for asynchronous event envelopes;
• OAuth 2.0 and, where required, OpenID Connect for identity and authorization;
• publicly available ISO, UN and IETF standards for primitive values.

D005 — External formats remain adapters

Existing business-document, EDI, visibility and TMS formats may be supported by adapters when a concrete participant needs them. They do not define the canonical model and are not a condition for participation.

D006 — Avoid inaccessible or immature dependencies

The protocol must not depend on closed specifications, membership-only contracts, difficult-to-consult documentation or insufficiently mature infrastructure. Any new external dependency requires an ADR with accessibility, maturity, licensing, tooling and exit-risk evidence.

D007 — No mandatory federated infrastructure

The first profile does not require a dataspace connector, federation platform or external certification framework. Purpose limitation, organization identity, explicit authorization and data sovereignty are implemented directly using mature internet standards. Federation can be evaluated later without changing core exchange semantics.

D008 — Minimum disclosure

Before the configured match phase, share only the corridor, time window, vehicle, capacity and compatibility information needed for discovery. Customer names, exact addresses, prices and commercially sensitive execution details remain protected according to bilateral policy.

D009 — Explicit commitment

A proposal is non-binding. A match becomes an operational commitment only through explicit authorized acceptance according to the bilateral decision policy. The protocol does not automatically form legal contracts, settle payments or award work without confirmation.

D010 — Immutable lifecycle history

Resources evolve through versioned transitions. Accepted decisions cannot be silently rewritten. Corrections append or supersede records and retain the reason, actor, timestamp and prior relationship.

D011 — Implementation-independent conformance

The specification and conformance suite define behaviour; the reference implementation does not. Stable releases require a reference broker, the Freyt client and at least one independently implemented client or simulator to pass the same black-box suite.

D012 — Assurance-driven development

Production implementation begins only after requirements, invariants, lifecycle models, authorization rules, threats and conformance checks exist. Critical protocol claims require traceable executable evidence. TDD, property-based testing, mutation testing, formal lifecycle modeling, real-boundary integration testing and resilience testing are required according to QUALITY-STRATEGY.md.

D013 — Open governance

Publish specifications, schemas, examples and conformance tooling under a permissive license. Manage normative changes through tracked ADRs or RFCs, immutable schema versions and compatibility checks. Prefer additive evolution within a major version.

Open point: Confirm the legal entity or community structure that owns releases, trademarks and governance rights.

D014 — Documentation is generated from protocol sources

The static documentation website is part of the protocol repository. Every development and production build validates canonical content and regenerates documentation pages, structured-artifact reference pages, downloadable artifacts and machine-readable indexes from the same source revision. Generated pages are never edited as independent sources.

Use an open-source static toolchain. Publishing to a public hosting target remains a separate operational decision.