Partner Capacity Exchange design research

Generated from docs/research/partner-capacity-exchange-design.md. Edit the canonical source file, not this page.

Status: Curated design input; ADRs and the normative specification take precedence.

1. Network model

A closed partner network is the preferred initial operating model.

Organizations establish bilateral relationships before discovering each other’s capacity or demand. This provides a practical basis for authorization, commercial trust and controlled data disclosure without turning the protocol into a public freight marketplace.

The network can later support groups or communities, but group visibility must resolve to explicit organization-level authorization.

2. Initial exchange opportunities

The strongest initial patterns are:

• empty return capacity;
• residual weight, volume, pallet-space or loading-metre capacity;
• recurring lanes;
• corridor-compatible load requests;
• vehicle- and time-window-compatible partner handoff.

These patterns can be represented without synchronizing a participant’s complete planning or order domain.

3. Exchange lifecycle

Partner relationship requested
  → relationship accepted
    → capacity offer / load request published
      → compatible opportunity discovered
        → non-binding proposal created
          → authorized decisions recorded
            → accepted exchange linked to execution
              → completed / cancelled / disputed outcome

Withdrawal, expiry, rejection and cancellation are first-class outcomes. They are not exceptional database deletions.

4. Disclosure stages

Before an active relationship

Share only organization-discovery information needed to request a relationship.

Active relationship, before a proposal

Depending on policy, share coarse regions, time windows, vehicle/body type, available or required capacity and operational constraints.

Open proposal

Share enough compatibility and rationale data to make an informed decision. Exact addresses, customers, pricing and sensitive goods information remain policy-controlled.

Accepted proposal

Release the operational details explicitly allowed by the relationship and decision policy. Participants retain their own authoritative order and trip records.

5. Matching

Initial matching should be deterministic and explainable. A proposal records which checks passed, failed or were not evaluated.

Potential checks:

• relationship authorization;
• resource availability and expiry;
• area/corridor overlap;
• pickup and delivery windows;
• vehicle/body compatibility;
• capacity dimensions;
• equipment and handling requirements;
• goods restrictions;
• maximum detour or participant policy.

A matcher abstains when required data is missing or ambiguous. It never converts uncertainty into an operational commitment.

6. Marketplace risks and protocol controls

Risk	Protocol control
Unauthorized commercial visibility	Bilateral relationships, scopes and hidden-resource responses
Stale capacity	Expiry, version checks and withdrawal commands
Double commitment	Explicit lifecycle, optimistic concurrency and idempotency
Race between acceptance and withdrawal	Atomic command handling and formal state invariants
Duplicate integration messages	Idempotency keys and event IDs
Out-of-order updates	Monotonic resource versions
Excessive disclosure	Field-level disclosure phases
Lock-in	Public schemas, conformance tests and independent client
Semantic drift	Versioned definitions and compatibility checks
Adapter corruption	Quarantine, diagnostics and mapping tests

7. Central broker versus federation

A central reference broker is appropriate for the first implementation because it simplifies consistency, onboarding, authorization and observability.

The public protocol prevents the broker from becoming a permanent proprietary boundary. Later federation remains possible if real operational requirements justify the additional identity, discovery, consistency and governance complexity.

Federation should not be implemented pre-emptively.

8. Commercial boundary

The core protocol does not standardize:

• pricing strategy or market-price formation;
• payment or escrow;
• liability allocation;
• claims;
• external legal contract terms;
• partner reputation scores.

A tender may disclose a price or stable commercial-terms reference when bilateral policy permits it. These fields record the terms presented for a protocol decision; they do not define payment behavior or claim that the protocol commitment replaces an external legal transport contract. A match proposal remains non-binding.

9. Interoperability conclusion

The protocol should own only its exchange-specific semantics and build on mature internet primitives. Existing TMS or document formats belong behind adapters. An external concept is promoted into the core only after multiple independent participants demonstrate the same need and conformance tests can define its behaviour.

10. Discovery and execution transfer are separate

A private marketplace needs two connected but distinct loops:

1. discovery compares capacity and demand and produces non-binding proposals;
2. tendering freezes proposed terms, records required decisions and creates an immutable commitment;
3. execution handover releases the minimum operational package and waits for destination acknowledgement;
4. execution updates and outcomes close the shared loop.

A connected system’s internal ride, order, shipment or route is not portable. The transferable object is a bounded movement with stops, time windows, cargo facts, equipment constraints, references and disclosure-controlled instructions. The source and executing systems create or retain their own local records.

11. Multi-system trust

Trust has three independent dimensions:

• organizational trust: the participant has a verified broker identity and accepted exchange terms;
• technical trust: each connector is registered, organization-bound, versioned, revocable and conformant;
• bilateral trust: an active relationship permits specific products, actions, fields and lifecycle behavior.

An access token proves a technical caller identity. It does not by itself grant partner visibility. Authorization also evaluates relationship policy, resource visibility, disclosure phase, actor role and lifecycle state.

12. Handover reliability

Commercial acceptance and technical import are different facts. A tender may be accepted while the destination connector is offline or rejects an unsafe mapping. The protocol therefore needs a handover acknowledgement with imported, linked, rejected and quarantined outcomes.

At-least-once event delivery requires durable inbox and outbox state, idempotency, external-reference mapping and reconciliation from authoritative resource versions. Duplicate handovers must resolve to one destination record. Missed or reordered events must not regress state.

13. Connector boundary

A connector maps between a local model and canonical exchange resources. It preserves source and destination references, validates before publishing, quarantines ambiguity instead of inventing data, exposes health and mapping failures, and reconciles after downtime.

Direct writes to an application’s internal database are unsuitable unless that application explicitly exposes the database interface as a supported integration contract. Product-specific APIs, files, messages and schemas remain adapter concerns and do not change the canonical protocol.