Restore authority reconciliation¶
A verified, schema-compatible backup proves that bytes were preserved. It does not prove that the authority recorded in those bytes is still usable. A backup taken before an approval token was spent still holds a nonce store with no claim for that token. A snapshot taken before a revocation still records the grant as active. openmed.agent.approvals.restore_reconciliation adds an explicit anti-replay boundary between restore and admission. It reconciles the restored generation against current, injected authority before any protected work resumes.
This slice owns reconciliation only. Backup format, encryption, integrity checks and identity services stay with their own components. The module reuses the existing approval token, nonce store, runtime revocation and workflow recovery contracts. It performs no network access.
Inputs¶
RestoredSnapshot is a content-free view of one restored generation:
snapshot_digest: opaque digest of the backup generation.recorded_epoch: recovery epoch recorded in the backup.approvals:RestoredApprovalrecords for tokens outstanding at backup time.RestoredApproval.from_token(token, clock_skew_seconds=...)keeps only the token digest, nonce digest and verifier retention bound, never the bearer token. Pass the live verifier's skew so the burn covers its full acceptance window.workflows:RestoredWorkflowentries holding a validated checkpoint lineage, or a sealedRetiredJournalRecord, plus theAuthorityBindingthe run recorded at preview. Useauthority=Noneonly for runs that use no runtime-revocable authority.
Everything in the snapshot is historical evidence. Nothing in it establishes current authority.
RestoreReconciler takes the authoritative current state as injected ports:
| Port | Contract |
|---|---|
nonce_store | The live ApprovalNonceStore shared with every verifier |
epochs | A RecoveryEpochStore with monotonic high water, never restored from the same backup |
authority | An AuthorityRuntime with the current status provider and independent generation store |
clock | Trusted integer Unix clock |
observe | Read-only effect status lookup by idempotency key for one restored tip |
InMemoryRecoveryEpochStore serves single-process use and tests. Production restores need a durable epoch store kept outside every backup. A store restored with the run state could rewind epochs.
Reconciliation order¶
reconcile(snapshot, observe=...) runs these steps in a fixed order:
- Open a recovery epoch. The new epoch is strictly above both the recorded epoch and the retained high water.
RecoveryEpochbinds the epoch, its predecessor, the snapshot digest and the time intoepoch_digest. If the store fails or rewinds, the call fails withrecovery_epoch_unavailableorepoch_not_monotonic, and nothing is admitted. - Burn pre-restore approvals. Each unexpired snapshot nonce is claimed in the live nonce store, using the same digest and retention bound as
ApprovalTokenVerifier. After this step the token raisesApprovalReplayError, even when the live store is the restored pre-consumption copy. The outcome ispre_restore_nonce_burned, orpre_restore_nonce_already_claimedwhen the authoritative store already held the claim. Expired approvals areapproval_expired. A store failure holds the approval withnonce_journal_unavailable. - Check current authority. A workflow that recorded a binding is checked at the
resumeboundary with fresh status, before any sink read. Revoked, expired, changed-generation, rolled-back and mismatched authority stay unusable even when the snapshot recorded an earlier active state. The outcome isfresh_review_required. An unavailable, stale or store-unavailable status, or a missing runtime, keeps the workflowheld. - Reconcile effects. The existing
recover_workflowplanner compares the restored lineage with live sink observations. Effects committed after the backup are reported as committed and are never repeated. Ambiguous or mismatched effects needreview_required. A failed or malformed lookup keeps the workflowheld. - Invalidate pre-restore approval receipts. A resumable plan whose pending retries need approval becomes
fresh_review_requiredwithpre_restore_approval_invalidated. The checkpoint receipt digest is kept ashistorical_approval_receipt_digest. It never authorizes a retry. Only plans without approval-gated retries returnresumewith idempotency keys. A missing or expired recorded receipt also needsfresh_review_required.
Completed, aborted and retired lineages skip authority and sink lookups, because they admit no further effect.
Epoch-bound approvals¶
Burning covers tokens the snapshot recorded. A token issued after the backup is not in the snapshot. To cover it, issue and verify every approval against epoch_action_digest(action_digest, epoch). A token signed for an earlier epoch then fails as an action mismatch and is consumed. Before admission, call require_current_epoch(epoch, epochs). It fails with stale_recovery_epoch after a later restore.
from openmed.agent.approvals import (
ApprovalReplayError,
ApprovalTokenSigner,
ApprovalTokenVerifier,
InMemoryApprovalNonceStore,
)
from openmed.agent.approvals.restore_reconciliation import (
InMemoryRecoveryEpochStore,
RestoredApproval,
RestoredSnapshot,
RestoreReconciler,
epoch_action_digest,
require_current_epoch,
)
key = b"synthetic-local-approval-key-32-bytes"
action = "sha256:" + "a" * 64
role = "role:org.example/clinical-reviewer@1.0.0"
signer = ApprovalTokenSigner(key, clock=lambda: 10)
token = signer.issue(action_digest=action, reviewer_role=role, expires_at=500)
# The live store was replaced by a pre-consumption backup copy.
restored_store = InMemoryApprovalNonceStore()
epochs = InMemoryRecoveryEpochStore()
snapshot = RestoredSnapshot(
snapshot_digest="sha256:" + "b" * 64,
recorded_epoch=0,
approvals=(RestoredApproval.from_token(token),),
workflows=(),
)
report = RestoreReconciler(restored_store, epochs, clock=lambda: 10).reconcile(
snapshot, observe=lambda checkpoint: ()
)
report.require_complete()
assert report.approvals[0].reason.value == "pre_restore_nonce_burned"
verifier = ApprovalTokenVerifier(key, restored_store, clock=lambda: 10)
try:
verifier.consume(token, action_digest=action, reviewer_role=role)
except ApprovalReplayError:
pass
else:
raise AssertionError("restored token must stay spent")
require_current_epoch(report.epoch, epochs)
bound = epoch_action_digest(action, report.epoch)
fresh = signer.issue(action_digest=bound, reviewer_role=role, expires_at=500)
verifier.consume(fresh, action_digest=bound, reviewer_role=role)
Admission and evidence¶
RestoreReconciliationReport.require_complete() raises restore_reconciliation_incomplete while any approval or workflow is held. Hosts must not admit restored work until a later run completes. Reconciliation is idempotent: rerunning it opens a newer epoch and never revives a burned nonce.
Restore never erases committed effects. Committed effects recorded in the snapshot stay in the outcome even when authority is denied or unavailable. Journals and sinks are only read. Restore also never claims that review was repeated. Its outcomes contain no approval-success code, and fresh_review_required means a new human review is still needed. A resumable plan still needs the normal read and dispatch checks at the next operation.
to_json() emits only the schema version, epoch record, controlled reason codes, counts, opaque action identifiers, idempotency keys and digests. It never includes bearer tokens, nonces, provider or store exception text, paths or source payloads. Keep these linkable digests under audit-data access controls.
This slice adds no autonomous clinical action, cloud fallback, identity service or backup format. It covers the Python contracts only; no matching Swift API is introduced.
Focused offline validation: