Private Exchange Profile

Generated from specification/private-exchange-profile.md. Edit the canonical source file, not this page.

Status: Pre-alpha normative design
Applies to: brokers, portals, transport management system connectors and conformance tooling

This profile extends the Partner Capacity Exchange from discovery into tendering, bilateral commitment and operational handover between heterogeneous systems.

1. Scope and system boundaries

The exchange coordinates mutually accepted logistics partners. It is authoritative for:

• organization and connector registrations;
• partner relationships and bilateral policy;
• published capacity and demand;
• proposals, tenders and decisions;
• commitments and handover acknowledgement;
• shared lifecycle events and audit history.

A connected system remains authoritative for its local customers, orders, shipments, routes, vehicles, drivers, invoices, planning state and execution records.

The protocol MUST NOT transfer a vendor-native object as its canonical representation. It MUST transfer a bounded, vendor-neutral execution package. Each system creates or links its own local record and records that link as a namespaced external reference.

2. Exchange products

2.1 CapacityOffer

A declaration of available vehicle movement or residual capacity. It supports discovery and reservation but is not an assignment.

2.2 LoadRequest

A declaration of freight requiring compatible capacity. It contains only the information permitted for its disclosure phase.

2.3 MatchProposal

An explainable, non-binding compatibility result. It MUST identify evaluated, satisfied, failed and unevaluated constraints. It MUST NOT itself reserve capacity or create an execution obligation.

2.4 TransportTender

A request for a partner to execute a specified movement. A tender freezes the decision-relevant terms presented to the recipient and references the originating proposal or bilateral workflow where applicable.

Minimum information includes:

• issuer and intended executing organization;
• expiry and decision policy;
• movement scope: full transport, route leg, collection or delivery;
• coarse or exact operational details according to disclosure policy;
• capacity, cargo and equipment requirements;
• commercial terms or a stable external terms reference;
• amendment and cancellation policy;
• source external references.

A counterproposal creates a new immutable tender revision linked to the preceding revision. It MUST NOT silently modify terms already presented for decision.

2.5 TransportCommitment

Immutable proof that all decisions required by the tender policy were accepted before expiry or valid withdrawal. It records:

• the accepted tender revision;
• required decisions and actors;
• accepted-at timestamps;
• a deterministic digest of the accepted decision-relevant payload;
• the bilateral policy version in force;
• the resulting capacity reservation or consumption.

A commitment is not itself proof that the executing system imported the work.

2.6 ExecutionHandover

The disclosure-controlled operational package required for the executing organization to create or link its local work record.

Minimum structure:

id:
resourceVersion:
commitmentId:
sourceOrganizationId:
executingOrganizationId:
externalReferences: []
movement:
  type: full-transport | route-leg | collection | delivery
  stops:
    - sequence:
      function: pickup | delivery | waypoint
      location:
      timeWindow:
      references: []
      instructions:
      contact:
cargo:
  description:
  packages: []
  grossWeight:
  volume:
  loadingMetres:
  palletSpaces:
  temperatureRange:
  dangerousGoods:
  handlingRequirements: []
equipment:
  bodyType:
  capabilities: []
documents: []
commercialTermsReference:
disclosurePolicy:
lifecyclePolicy:
acceptedSnapshotHash:

Exact addresses, contacts, customer identity, documents, price and sensitive cargo details MUST be released only when the relationship and resource disclosure policies permit them.

2.7 HandoverAcknowledgement

The executing connector records one of:

• imported: a local execution record was created;
• linked: an existing local execution record was linked;
• rejected: the package could not be accepted, with a stable reason code;
• quarantined: automatic import was unsafe and requires authorized review.

An acknowledgement includes destination external references. Duplicate handover delivery MUST resolve to the same local record and acknowledgement.

2.8 ExecutionUpdate and ExecutionOutcome

Execution updates communicate shared milestones and exceptions without replacing the local system’s detailed state. Supported baseline milestones are:

assigned
at-pickup
picked-up
in-transit
delayed
at-delivery
delivered
failed
cancelled
disputed

Corrections append or supersede prior updates. They never erase accepted decisions or historical evidence.

3. Lifecycle

capacity/load publication
  -> match proposal
  -> tender draft
  -> tender issued
  -> viewed
  -> accepted | rejected | expired | withdrawn | countered
  -> commitment created
  -> handover offered
  -> imported | linked | rejected | quarantined
  -> assigned
  -> execution updates
  -> completed | cancelled | failed | disputed
  -> corrected outcome when necessary

Commercial acceptance and technical handover acknowledgement MUST remain separate.

An amendment after commitment MUST:

1. identify the commitment and prior revision;
2. state changed fields and reason;
3. preserve the previously accepted snapshot;
4. require renewed acceptance when a decision-relevant term changes;
5. leave the existing commitment effective until policy defines replacement or cancellation.

Cancellation MUST be an explicit command and event. Deleting a resource does not cancel an operational commitment.

4. Authentication profile

4.1 Machine clients

Connectors use OAuth 2.0 Client Credentials. Production deployments SHOULD authenticate clients with private_key_jwt or mutual TLS rather than a long-lived shared secret.

An access token MUST contain or resolve to:

• issuer;
• subject identifying the connector;
• exact broker API audience;
• issued-at and expiry;
• unique token identifier;
• client identifier;
• owning organization identifier;
• granted scopes.

The broker MUST bind a connector registration to exactly one organization in one environment. Payload fields cannot override that binding. The broker SHOULD derive resource ownership from authenticated context.

Credentials and signing keys MUST support rotation, revocation and environment separation. Machine clients SHOULD use short-lived access tokens.

4.2 Interactive users

Interactive users authenticate with OpenID Connect Authorization Code and PKCE. The resulting authorization context MUST identify the user, organization membership and permitted roles. High-impact actions such as commitment acceptance MAY require step-up authentication according to exchange policy.

A connected system’s internal session token MUST NOT be accepted as an exchange credential unless a specified token-exchange or federation profile validates issuer, audience, organization and actor semantics.

5. Authorization profile

Every protected operation evaluates:

1. token validity and audience;
2. active connector or user registration;
3. active organization;
4. resource ownership or participation;
5. active partner relationship;
6. client scope;
7. bilateral relationship policy;
8. resource visibility;
9. field disclosure phase;
10. actor role;
11. lifecycle preconditions;
12. current resource version and expiry.

API scopes describe what a client may call. Relationship policy describes what two organizations permit between each other. Resource visibility describes who may observe one resource. Passing one layer MUST NOT bypass another.

Recommended additional scopes are:

tenders:publish
tenders:read
tenders:decide
commitments:read
handovers:write
handovers:read
handovers:acknowledge
execution:update
connectors:manage

The exchange SHOULD conceal resource existence with 404 where 403 would disclose protected partner activity.

6. Organization, connector and bilateral trust

An organization registration contains a broker-scoped identifier, verified legal identity, status, administrators, accepted terms, security contacts and registered connectors. Legal identifiers are attributes; they do not replace the broker-scoped identifier.

A connector registration contains:

• immutable client identifier;
• owning organization;
• software product and adapter version;
• supported protocol profiles and versions;
• authentication and event-verification keys;
• permitted scopes;
• environment and callback endpoints;
• conformance status;
• health and revocation state.

A partner relationship policy SHOULD define:

• permitted exchange products and actions;
• geographic or business restrictions;
• visibility and disclosure stages;
• decision policy;
• onward-subcontracting permission;
• commercial-field visibility;
• update obligations;
• document permissions;
• amendment and cancellation rules;
• retention and dispute contacts;
• effective and expiry dates.

Suspension prevents new exchange activity. It MUST NOT erase history or prevent the minimum authorized processing required to finish, cancel or audit existing commitments.

7. Connector contract

A conformant connector MUST:

• map local records to canonical resources without inventing required values;
• preserve source and destination external references;
• bind all processing to its authenticated organization;
• validate payloads before publishing or importing;
• quarantine ambiguous or unsafe mappings;
• process commands and events idempotently;
• persist inbox, outbox and mapping state durably;
• recover from duplicate, reordered and missed delivery;
• reconcile authoritative resources from a cursor or version;
• expose health, lag, mapping failures and dead letters;
• redact sensitive values from logs.

A connector SHOULD maintain the exchange resource ID and version, local system and resource type, local ID, last imported/exported versions, synchronization state and last stable error code.

Direct writes to a connected system’s internal database are non-conformant unless that system explicitly documents the database interface as a supported integration contract.

8. Idempotency, consistency and recovery

State-changing commands MUST carry an idempotency key. Mutable-resource commands MUST assert the expected resource version. The implementation mechanism is not prescribed, but observable behavior MUST guarantee:

• no commitment without all required acceptances;
• no commitment after valid withdrawal or expiry;
• no double commitment of exclusive capacity;
• one idempotency key has one effect;
• duplicate handovers do not create duplicate local work;
• reordered events do not regress state;
• amendments cannot silently replace accepted terms.

Connectors SHOULD use a transactional outbox and durable inbox. Event delivery is at least once. Event notifications are not the only durable source: recipients MUST be able to retrieve and reconcile authoritative resources.

An accepted tender whose destination import fails remains committed but not handed over. The failure MUST be observable and recoverable; it MUST NOT be reported as successful execution transfer.

9. Event security

The event security mechanism will be fixed in the security specification before v0.1. It MUST provide:

• producer and destination authentication;
• payload integrity;
• covered event identifier and timestamp;
• replay resistance;
• key identification, rotation and revocation;
• retry, dead-letter inspection and authorized replay.

A conformant profile may use mutual TLS with OAuth-protected retrieval, HTTP Message Signatures, or signed event payloads only after one method and its canonicalization rules are selected normatively.

10. Capability and version negotiation

A connector capabilities endpoint MUST advertise:

• protocol and profile versions;
• supported resources and commands;
• supported event delivery modes;
• optional cargo, equipment and document capabilities;
• maximum payload and document limits;
• conformance profile identifier.

Unsupported mandatory capabilities fail with an explicit stable problem code. They are never silently discarded.

11. Operational requirements

A production exchange requires observable surfaces for:

• authentication and authorization denials;
• connector health and last successful exchange;
• event delivery attempts and dead letters;
• handovers awaiting acknowledgement;
• quarantined mappings;
• version conflicts;
• reconciliation progress;
• active commitments affected by organization, connector or relationship suspension.

Logs MUST avoid exact locations, customer identities, contact details, sensitive cargo and commercial terms unless an explicitly authorized diagnostic mode is active.

12. Conformance scenarios

The black-box conformance suite MUST cover at least:

• capacity and demand discovery within an active relationship;
• isolation from a non-partner organization;
• tender acceptance, rejection, counterproposal, expiry and withdrawal;
• commitment creation under each supported decision policy;
• handover import and destination acknowledgement;
• duplicate command, event and handover delivery;
• amendment requiring renewed acceptance;
• cancellation racing with acceptance or import;
• connector outage followed by reconciliation;
• relationship or credential suspension during active execution;
• quarantined mapping without invented data;
• bidirectional exchange between independently implemented clients.