Interface contracts and versioning

Narrow versioned contract between core and Logistics

A small interface spec defining the only data and calls crossing the boundary

Depends on: ARCH-0001

Contract spec documents (both sides)

Matching documents in the Logistics folder and the core docs; changes require both

Depends on: ARCH-0001

Contract: identity and keys

Business identity card, public key, signature verification service

Depends on: ARCH-0001, CONN-0012

Contract: inventory (INV)

Query product, stock location, receive goods event

Depends on: ARCH-0001, INV-0001

Contract: pricing (PRC)

Read price lists and tax rules; return computed prices

Depends on: ARCH-0001, CONN-0100

Contract: delivery (DLV)

Delivery order to job and job status back to order

Depends on: ARCH-0001, DLV-0002

Contract: waybill and handshake (CONN)

Waybill document, signature handshake, receiving event

Depends on: ARCH-0001, CONN-0050

Contract: bookkeeping (BK)

Posting events for freight income, costs, receivables

Depends on: ARCH-0001, BK-0034

Contract: licensing flags (LIC)

Package id and pricing-class flags in the licence token

Depends on: ARCH-0001

Contract: backup and export (DATA)

Hooks for including Logistics backups in encrypted backup bundles

Depends on: ARCH-0001

Contract: notifications and tasks (TASK)

Reminder events from Logistics to core task list

Depends on: ARCH-0001

Contract data formats (versioned JSON/CBOR schemas)

Machine-readable schemas with version numbers and test vectors

Depends on: ARCH-0001, ARCH-0016

Contract version negotiation handshake

On start, both sides announce supported contract versions and pick the highest common one

Depends on: ARCH-0001, ARCH-0016

Contract backward compatibility policy

Minor versions only add optional fields; breaking change requires a major version and a deprecation window

Depends on: ARCH-0001

Contract deprecation schedule

Documented support window for old contract versions

Depends on: ARCH-0001

Contract idempotency keys

Every cross-boundary event carries an idempotency key so retries are safe

Depends on: ARCH-0001

Contract error model

Standard error codes and retry hints

Depends on: ARCH-0001

Contract size and rate limits

Bound payload sizes and event rates across the boundary

Depends on: ARCH-0001

Contract capability flags

Feature discovery by capability bits instead of version guessing

Depends on: ARCH-0001

Contract transport abstraction

Same contract over in-process queue, local socket or file drop

Depends on: ARCH-0001

Contract test vectors

Shared golden examples used by both sides

Depends on: ARCH-0001

Contract tests (consumer and provider)

Automated tests proving each side honours the contract

Depends on: ARCH-0001, ARCH-0036

Contract test in CI for both sides

Release blocked if contract tests fail

Depends on: ARCH-0001

Compatibility matrix (core x Logistics x contract)

Table of tested version pairs with status

Depends on: ARCH-0001, ARCH-0028

Compatibility matrix published with each release

Matrix included in release notes

Depends on: ARCH-0001

Schema registry file in repo

Single folder holding all contract schemas

Depends on: ARCH-0001