Skip to content
Agent OS
AOS-PROD-004 Normative foundation

Backup, Migration, and User Recovery

Backup, Migration, and User Recovery: scope, decisions, requirements, evidence, risks, and traceability for the Agent OS programme.

Edit on GitHub →

Backup, Migration, and User Recovery

This specification defines a user-facing capability in terms of entities, actions, history, consent, recovery, accessibility, and provider contracts.

Table of Contents

Purpose and Scope

Area: Product System.

This specification defines a user-facing capability in terms of entities, actions, history, consent, recovery, accessibility, and provider contracts.

This document owns the semantics implied by Backup, Migration, and User Recovery. It does not assert that every described subsystem already exists. It defines the target model, constraints, evidence needed to trust an implementation, and the boundary with adjacent documents.

Normative Position

  1. Define ROM/firmware handoff, verified stages, measurements, anti-rollback, A/B or equivalent atomic update, recovery, and user-visible failure states.
  2. Separate device keys, release keys, recovery authority, and development unlock policy.
  3. Updates include kernel, services, drivers, firmware metadata, schemas, and migrations as an atomic compatibility set.

Operating Model

The operating model is contract-first and evidence-driven. A component declares its authority, resources, lifecycle, error model, cancellation and timeout behavior, observability, version, and compatibility promise. Backends are replaceable only when the same conformance suite passes and no forbidden platform type leaks into portable layers.

Implementation proceeds through a reference model or mock, deterministic QEMU evidence where relevant, documentation-first physical hardware, and quality-hardware evidence. Pixel 9 adapters remain quarantined according to ADR-0004.

Requirements

  • R01. Define ROM/firmware handoff, verified stages, measurements, anti-rollback, A/B or equivalent atomic update, recovery, and user-visible failure states.
  • R02. Separate device keys, release keys, recovery authority, and development unlock policy.
  • R03. Updates include kernel, services, drivers, firmware metadata, schemas, and migrations as an atomic compatibility set.
  • R04. Specify normal, partial, denied, timeout, cancellation, restart, upgrade, and permanent-failure behavior.
  • R05. Expose structured diagnostics without leaking secrets or vendor-specific implementation details.
  • R06. Link material unknowns to a claim and, when testable, an experiment with an owner and gate.
  • R07. Update affected documentation and task data when evidence changes the model.

Failure and Degradation

Degradation must be explicit rather than accidental. The system reports capability absence, reduced quality, unavailable provider, stale data, or unsafe condition through typed states. It must not silently fall back to broader authority, unrestricted legacy execution, unverified firmware, lossy data migration, or irreversible agent action.

Recovery defines what state is retained, reconstructed, re-enrolled, compensated, or intentionally discarded. Unsupported hardware or providers are rejected at binding time where possible.

Evidence and Acceptance

  • Power-cut update tests.
  • Rollback/freeze attack tests.
  • Reproducible recovery from corrupted slots and migrations.
  • Evidence records target identity, hardware revision, firmware, source commit, toolchain, configuration, seed, timestamps, artifacts, expected result, actual result, and reviewer.
  • Acceptance requires the referenced tasks to meet their own criteria; prose completion is not implementation completion.

Implementation Obligations

Task Obligation Priority Gate/Milestone Verification
AOS-PLAT-052 Implement recovery environment and service tools P0 M8 unbootable system, corrupt metadata, failed update, lost credential and malicious recovery media scenarios
AOS-PROD-031 Implement encrypted peer/cloud sync v0 P1 M8 partition/reorder/duplicate/corrupt/revoked-device/quota/key-rotation and metadata-privacy tests
AOS-PROD-060 Run full device migration and restore drill P0 M8 EXP-062 clean target, partial provider failure, unknown schema, corrupt bundle and lost source scenarios
AOS-PROD-061 Implement encrypted backup bundle and verified restore P0 M8 corrupt/truncate/wrong key/unknown schema/dedup/privacy/large data and scheduled drill tests
AOS-CAM-021 Implement DNG/portable RAW export and provenance P1 M5 validate with independent readers and compare decoded raw/metadata round trip
AOS-CELL-040 Model and evaluate eSIM lifecycle and partner requirements P1 M9 EXP-043 tabletop and available evaluation path; lost device, transfer, rollback and malicious profile scenarios
AOS-SEC-041 Threat-model and validate recovery environment P0 M8 stolen device, malicious media, rollback, data extraction, factory reset and failed-key scenarios

Risks and Open Questions

  • A partially updated system can be unrecoverable.
  • Vendor firmware rollback rules may conflict with project recovery.
  • Development unlock paths can weaken production guarantees.
  • Open-question rule: an unanswered high-impact question becomes a claim/experiment record and cannot be hidden in meeting notes.
  • Stop rule: work stops or changes track when legal rights, recovery, debug access, safety, or the required evidence path is unavailable.

Related Documents

Planning Reference Anchors

Backup Bundle

AOS-PROD-031 — Implement encrypted peer/cloud sync v0; AOS-PROD-061 — Implement encrypted backup bundle and verified restore; AOS-CAM-021 — Implement DNG/portable RAW export and provenance

Data Classes

AOS-CELL-040 — Model and evaluate eSIM lifecycle and partner requirements

Failure And Rollback

AOS-PLAT-052 — Implement recovery environment and service tools; AOS-SEC-041 — Threat-model and validate recovery environment

Migration Flow

AOS-PROD-060 — Run full device migration and restore drill