Local Runtime State
The local developer runtime maintains a lightweight state cache under the .phoenixflight/ directory. State directories are auto-generated on initialization:
State Files Structure
- 📁
.phoenixflight/- Core root directory (git ignored) - 📄
registry.json- Active & retired members index - 📄
packets.json- Managed Flight Packet records - 📄
assignments.json- Map of active task allocations - 📄
audit.jsonl- Sequential event streaming log - 📁
imports/- Workspace templates retrieved from Hub
Scheduling Engine
PhoenixFlight incorporates a **trust-weighted capability routing scheduler**. When scheduling a workload, the engine discovers healthy matching resources and scores them using resource reliability and current load:
Assignments partition workloads only to healthy active participants, safeguarding namespaces from resource leaking.
Graceful Retirement & Eviction
When an agent fails or is retired (e.g. CLI retire command), the runtime transition is executed safely:
Retirement Flow
1. Member status changes to RETIRED.
2. All active packet assignments mapped to the member are evicted.
3. Evicted packet states revert back to PENDING for automatic rescheduling.
4. Load metrics are reset and audited in the event logs.
Portable Runtime Bundles (.pflight)
The PhoenixFlight compiler builds portable, immutable .pflight bundles from a declarative PhoenixFile. Unlike Dockerfiles which compile process container configurations, a .pflight bundle compiles logical workload and governance state contracts.
Bundle Features
- Self-contained: Copies all referenced agents, policies, packets, and contracts.
- Verifiable: Generates cryptographic SHA-256 integrity hashes for all packaged files.
- Governance-aware: Includes build manifests and namespace validation reports.
Compile and Inspect Command:
python3 -m src.phoenix_cli bundle inspect dist/customer-validation-app-0.1.0.pflight