Skip to content
OpenFreytProtocol

Roadmap

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

Status: Proposed protocol delivery sequence
Objective: Deliver a rigorously specified, TMS-independent private exchange for discovery, tendering, commitment and execution handover with independently verifiable interoperability.

Foundation gate — Assurance before production code

Section titled “Foundation gate — Assurance before production code”

No production broker or SDK implementation begins until the following exist:

  • accepted quality charter;
  • requirement and invariant registries;
  • glossary;
  • lifecycle state machines;
  • layered authorization matrix and bilateral policy model;
  • organization verification and connector-registration model;
  • OAuth/OIDC and event-security profiles;
  • threat model and abuse cases;
  • JSON Schema and OpenAPI validation pipeline;
  • conformance-test skeleton;
  • compatibility policy;
  • release-evidence format;
  • tracked ADRs for normative architecture decisions.

Phase 1 — Normative core specification

Section titled “Phase 1 — Normative core specification”

Scope

Section titled “Scope”

Specify:

  • OrganizationReference;
  • PartnerRelationship;
  • CapacityOffer;
  • LoadRequest;
  • MatchProposal;
  • MatchDecision;
  • TransportTender and counterproposals;
  • TransportCommitment;
  • ExecutionHandover and HandoverAcknowledgement;
  • common identifiers, timestamps, units and external references;
  • lifecycle transitions;
  • authorization and disclosure rules;
  • errors, idempotency and concurrency;
  • CloudEvents envelope and event names.

Deliverables

Section titled “Deliverables”
  • requirement IDs and traceability graph;
  • normative JSON Schemas;
  • OpenAPI 3.1 contract;
  • state-transition tables;
  • valid and invalid examples;
  • initial formal lifecycle model;
  • executable schema and transition checks.

Exit criteria

Section titled “Exit criteria”
  • every normative clause maps to a requirement and test;
  • an independent engineer can validate examples without Freyt code;
  • illegal transitions and unauthorized visibility have executable negative tests;
  • no public contract exposes Freyt-internal types.

Phase 2 — Conformance suite and reference model

Section titled “Phase 2 — Conformance suite and reference model”

Scope

Section titled “Scope”
  • pure deterministic reference model;
  • provider conformance profile;
  • consumer conformance profile;
  • broker conformance profile;
  • property-based command sequence generation;
  • model-based expected-state comparison;
  • compatibility diff tooling;
  • mutation testing for critical rules.

Exit criteria

Section titled “Exit criteria”
  • conformance tests run without importing an implementation;
  • randomized sequences are reproducible by seed;
  • all lifecycle and authorization invariants are covered;
  • no unexplained mutation survives in critical protocol logic.

Phase 3 — Smallest end-to-end implementation

Section titled “Phase 3 — Smallest end-to-end implementation”

Scope

Section titled “Scope”
  • relationship activation;
  • one-off capacity offer;
  • one-off load request;
  • deterministic match proposal;
  • explicit accept/reject;
  • withdrawal and expiry;
  • immutable decision history;
  • reference broker HTTP API;
  • Freyt reference client;
  • independent simulator or second client.

Exit criteria

Section titled “Exit criteria”
  • two organizations complete an exchange using only public contracts;
  • unauthorized parties cannot discover resources;
  • retries cannot create duplicate resources or decisions;
  • stale decisions are rejected;
  • no commitment exists without the configured acceptance policy;
  • both clients pass the same black-box suite.

Phase 4 — Events, execution handover and recovery

Section titled “Phase 4 — Events, execution handover and recovery”

Scope

Section titled “Scope”
  • CloudEvents publication;
  • authenticated and replay-resistant webhook or message-channel delivery profile;
  • ExecutionHandover, HandoverAcknowledgement, ExecutionReference, ExecutionUpdate and ExecutionOutcome;
  • source and destination external-reference mapping;
  • material amendments, cancellation and exception flows;
  • transactional outbox/inbox;
  • duplicate and out-of-order delivery handling;
  • connector capability negotiation and cursor-based reconciliation;
  • quarantine and dead-letter recovery;
  • restart recovery;
  • structured logs, traces and operational metrics.

Exit criteria

Section titled “Exit criteria”
  • commit/response timeouts are retry-safe;
  • duplicate and reordered events converge to correct state;
  • broker restart cannot lose accepted state;
  • duplicate handovers create or link exactly one destination record;
  • commercial commitment and destination import acknowledgement remain independently observable;
  • execution records remain linked without importing complete connected-system models;
  • missed delivery converges through reconciliation;
  • quarantine, dead letters and other failure modes are observable and actionable.

Phase 5 — Recurring capacity

Section titled “Phase 5 — Recurring capacity”

Scope

Section titled “Scope”
  • recurring offers and requests;
  • calendars and exceptions;
  • corridor profiles;
  • occurrence-specific withdrawal;
  • proposal generation across recurrence windows.

Exit criteria

Section titled “Exit criteria”
  • recurrence expansion is deterministic;
  • time-zone and daylight-saving boundaries are verified;
  • exceptions cannot resurrect withdrawn occurrences;
  • bounded generation prevents unbounded resource growth.

Phase 6 — Demand-led adapters

Section titled “Phase 6 — Demand-led adapters”

Build an adapter only for a confirmed participating system.

Potential adapters:

  • generic CSV import/export;
  • lightweight web portal;
  • participant-specific REST API;
  • established EDI or business-document formats;
  • execution-status or visibility feeds.

Exit criteria

Section titled “Exit criteria”
  • mappings preserve core semantics;
  • lossy mappings are documented;
  • invalid input is quarantined with actionable diagnostics;
  • adapter-specific fields do not leak into the canonical model;
  • conformance and organization-isolation tests pass.

Phase 7 — Stable protocol release

Section titled “Phase 7 — Stable protocol release”

Required evidence

Section titled “Required evidence”
  • complete requirements traceability;
  • formal invariant checks;
  • full mutation and property-test results;
  • independent-client interoperability;
  • backward-compatibility results;
  • migration and recovery rehearsal;
  • current threat model;
  • security assessment with no unresolved critical/high finding;
  • sustained load and failure-injection results;
  • signed schemas, artifacts and SBOM;
  • archived release evidence.

Deferred capabilities

Section titled “Deferred capabilities”

These require separate requirements and architecture decisions:

  • public marketplace discovery;
  • bidding and price discovery;
  • payments, escrow and claims;
  • automatic legal contracting;
  • autonomous award;
  • multi-leg and cross-dock optimization;
  • decentralized brokers;
  • federated trust infrastructure;
  • machine-learned matching;
  • reputation scoring;
  • commercial network analytics.

Immediate next actions

Section titled “Immediate next actions”
  1. Establish repository license and governance.
  2. Create requirements/requirements.yaml and requirements/invariants.yaml.
  3. Freeze the first glossary and lifecycle state machines.
  4. Write the authorization matrix and threat model.
  5. Create valid and invalid examples for the five core exchange resources.
  6. Implement schema, traceability and compatibility checks in CI.
  7. Build the reference model and conformance harness before the broker.