Change providers

This 1.2.0-draft.3 contract defines the tested reference handover procedure included in the implementation candidate. No external certification is claimed. This module composes the existing authority, history, free, paid and archive contracts. It adds no new wire profile or transferable credential. The originator can use another provider or a direct origin-owned service under the same rules.

1. Supported procedure and invariants

The supported procedure is fresh-agreement handover. The origin appoints a distinct successor service and the participating agent accepts a fresh offer there. The original agreement, issuer, receipt, assent, reporting destination, paid evidence, access/use expiry and retention limits MUST retain their original identity and exact bytes. An operational database copy or evidence archive MUST NOT become an access grant at the successor. Transparent assignment of an existing agreement is not specified by this edition.

The successor MUST use a new service ID when the issuer changes, a distinct issuer/endpoint binding and newly provisioned scoped credentials. A newly authorised signing key has a new key ID and independently provisioned material. A provider cannot appoint a successor: only the origin’s current odexa-service.json grants the capability and scope. A service descriptor without the required external delegation gives an external provider no authority.

These requirements apply to the implementer claiming handover support:

ID	Requirement	Existing contract / evidence
HAND-1	Retain exact original evidence and independently acquired trust before withdrawing export authority	Explicit free/paid/storage/asset archive contracts; live import and historical retrieval tests
HAND-2	Publish and verify a distinct origin-appointed successor; do not copy operational grants	Closed service/delegation binding, store identity checks and staging test
HAND-3	Provision fresh scoped credentials and obtain fresh signed assent	Existing client registration, credential scope and agreement contract; live wrong-secret/old-assent/token tests
HAND-4	Withdraw predecessor access authority and reject outages/locally known rollback without fallback	Current-authority service/gateway/history contracts; origin and successor outage, rollback and restart tests
HAND-5	Preserve accepted use/retention/reporting terms; drain outstanding reporting under explicit limited authority or record the gap	Selected storage contract and limited-collector transition test
HAND-6	Keep paid rights/evidence separate; require any new quote and payer mandate explicitly	Paid contract and two-provider paid transition test
HAND-7	Distinguish retirement, known compromise and historical evidence	Live new-key signing test; retained-history and archive compromise tests

The authority document still uses delegation.schema.json; free/paid messages use their existing closed schemas. These are procedure requirements over those messages, not extra fields to inject into an accepted receipt. The real TLS transition fixtures exercise the cross-document semantics which a schema alone cannot establish.

2. Prepare and retain evidence

1. Inventory the predecessor’s accepted agreements, access/use windows, reporting endpoints, pending reports, retained assets and payment states. An inventory covers known local records; it MUST NOT be labelled a complete account of all external use.
2. Choose the matching ordinary/storage/asset free or paid archive profile. Export while the predecessor still has current export_evidence authority. Preserve original policy/authority/terms bytes and independently provisioned public reporter/payer identities. Bundle-carried keys cannot establish independent trust.
3. Verify and import into a separate inert EvidenceArchive, StorageEvidenceArchive, AssetEvidenceArchive or PaidEvidenceArchive, as appropriate. Preserve the exact archive bytes and import report. A missing dependency, failed import or unavailable authority prevents a claim that preservation is complete; it does not justify bypassing verification.
4. Keep the original operational store, gateway journal and authority history in their original namespaces. Never point the successor service at them, relabel their identity, or transfer a provider’s Basic secret, bearer token or payer mandate. Restrict and retain original credentials only as needed for the original service’s supported historical receipt and reporting operations.

The archive importer requires current exporter authority at import time, including its post-lock check. Complete necessary imports before full withdrawal. After withdrawal, archive.get(origin, bundle_id) retrieves previously imported bytes with authority_status:"historical_only" and reactivates_access:false. Its import_report is the earlier verification result, not a new current-authority or compromise check. A fresh import/verification MUST NOT be made to pass by rewinding the clock or presenting the old observation as current. Newly learned compromise must be reported when evidence is reviewed; a past import report cannot override it.

If an incident requires immediate withdrawal before export, withdraw access and retain the material already held. State the evidence gap. Do not reinstate a compromised provider merely to obtain a cleaner archive.

3. Appoint and provision the successor

Create a separate store with the successor’s exact origin, service_id, issuer. Configure the exact base_url, independent authority history and active signing key. Keep TLS validation enabled. Generate credentials outside published metadata and give each agent, gateway, administrator and optional payer/verifier only its intended origin/path scope and role. No protocol secret appears in the authority document or evidence bundle.

Publish an increasing origin authority revision containing the successor descriptor and explicit delegation. Preserve the policy lineage and increase its revision when its exact bytes change. Overlap with the predecessor is permitted only for explicitly intended capabilities; it is not an automatic fallback route. The origin, successor, gateway and participating client each obtain current authority through their trusted acquisition path.

A receipt and an archive are evidence, not tokens. The agent verifies the successor offer and its exact contexts, signs a fresh acceptance, and receives a new agreement ID. Old provider tokens, agreement IDs, signed assent, reporter keys or passwords cannot be reused to activate that agreement. The publisher switches its selected gateway configuration to the successor and gives that gateway a new journal path. It retains the predecessor journal separately for unresolved admissions and evidence; the reference deliberately refuses an in-place identity rewrite.

Provider transport MUST enforce credential scope before sending. The hostile test deliberately sends a synthetic wrong credential directly to the successor to demonstrate server rejection; that does not authorize a compliant client to disclose the predecessor’s real secret to another host.

4. Withdraw access and finish existing duties

The origin publishes a higher authority revision withdrawing the predecessor’s access capabilities and selects the successor at its delivery boundary. The reference rejects new offers, tokens and admissions after the changed authority is observed. A cached body needs current admission too. An outage at the origin or selected successor produces denial; it does not select the predecessor, accept an archive, or turn a policy declaration into a token.

Remote publication and remote delivery are not globally atomic. The reference uses a bounded five-second authority observation and checks locally superseded snapshots. Already admitted/in-flight work follows its declared delivery boundary. An operator MUST NOT describe this as instantaneous revocation across all observers. Durable highest-observed history rejects a lower revision after restart; a fresh installation that has never seen a newer revision cannot detect that rollback solely from the old document. Retain its own history and provision current authority independently; resetting the history is not a migration step.

Existing reporting obligations remain tied to the accepted collector. Where an orderly transition is possible, keep a narrowly scoped predecessor delegation for receive_events and export_evidence, with zero access/use limits and payment_mode:"none", until the known reporting/retention/use tail is handled. The service descriptor may retain its key-use capabilities while its delegation permits only collection/export. Do not mutate a key’s pinned uses under the same key ID. This phase is limited continuing authority, not full withdrawal.

Drain exact signed outbox records and verify acknowledgements. Continuing storage preserves the original acquisition time, parent lineage, retention deadline and use expiry; changing providers MUST NOT restart any timer. A stored cessation report remains an authenticated client claim, not proof of physical erasure. Keep missing, late or unresolved reports visible. A successor collector MUST NOT silently accept a predecessor-bound event under its own agreement or rewrite the original reporting destination. Future offers may select a new destination using a newly published policy revision.

After the intended tail is complete, publish another increasing revision removing the old delegation and retiring its operation keys. If the predecessor becomes unavailable, keep unsent evidence locally and report the obligation as unresolved; do not fabricate acknowledgement. Emergency compromise may require immediate full withdrawal despite gaps. Exact retrieval/retry of an already committed receipt or intake may still return its original historical bytes; it does not create new authority or access.

5. Existing paid rights

A handover does not rewrite an existing paid agreement, erase its recorded payment, grant a refund, prove bank settlement or establish that a contractual obligation has ended. Original quote, accepted terms, payer mandate and signed verifier history remain with the original agreement. Preserved payment evidence is available for reconciliation; it is not a reusable spending instruction.

The operator must make the service treatment explicit before changing a customer’s paid access. Supported protocol choices are:

• Keep the original authorised service available for the agreed access window while the successor is prepared, then use fresh agreements for later access.
• Offer a separate free successor agreement when the originator elects to provide replacement access without another payment. This has payment:{required:false} and no payment call; it does not claim to transfer the old payment.
• Offer a new paid agreement with its own exact quote, fresh assent and separately authorised payer mandate. The old quote, mandate, client secret or provider confirmation MUST NOT activate it. The payer can decline; technical handover is not authorisation for an additional charge.

Odexa does not automate commercial credits, refunds or legal assignment in this profile. Any such arrangement needs its own explicit process. If original payment verification needs to continue during a planned access overlap, retain only the specifically required original verifier/access authority for that interval and describe the overlap accurately. Do not remove that verifier and then pretend the old access can still be authenticated. After full withdrawal the reference does not query a former verifier under its old appointment.

The paid transition fixture demonstrates original confirmed evidence remaining unchanged, a successor agreement initially pending, rejection of the predecessor’s payer secret and mandate, and access only after a new mandate and authenticated successor verification. Both verifiers are synthetic and read-only: the test neither charges twice nor proves a banking transaction occurred.

6. Key rotation and recovery

Publish the new key ID/material with the required role before using it. Observe that revision in durable history, configure the service to sign with the new key, and publish retirement of the old key at an increasing revision. Keep original receipts and historical authority bytes. New status statements use the new authorised key; exact receipt retries return the original bytes.

Retirement prevents new operations but does not by itself discredit a historically valid signature. Known compromise is different: the historical verifier rejects affected key material even when an older pinned document called it active. History prevents revoked material returning under a new key ID after removal/restart. Record the retirement/revocation times consistently and never overwrite old key material, validity or uses under an existing key ID.

Recover from an operational configuration error with a newly authorised configuration and increasing revision; do not replay a lower authority document, clear history or reactivate a retired/revoked key. An archive can support investigation, but cannot recover access by itself. If a removed service/key ID is reintroduced, the reference’s retained withdrawal pins reject it; use a genuinely new authorised identity.

7. Reproduce and assess the evidence

From the working source with its documented Python dependencies:

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=tests:. python3 -m unittest -v test_provider_handover

The six integration tests start an origin and two distinct provider HTTPS origins, validate certificates using an explicit temporary test CA, use separate SQLite stores and retain exact evidence. They cover fresh free/paid agreements, credential rejection and pre-send scoping, admission switch, staged lack of authority, current-origin/successor outages, durable rollback denial, key rotation, inert archives and selected-storage collection after access withdrawal. All keys/content/payment assertions are synthetic. No production website, account or origin is changed.

The focused handover results also include three historical compromise/retirement/restart checks. This procedure adds no wire schema or runtime envelope. Use the installed quickstart for the deployable CLI; test fixtures are reproducibility evidence. The combined technical checks are recorded in current validation, with release status and deployment limits in release status.