phoenixflight 0.1.8

PhoenixFlight: governance-aware runtime for dynamic agent and workload membership.

PhoenixFlight

Dynamic Membership Runtime for Governed Agent and Workload Handoff

PhoenixFlight is a local dynamic membership runtime for registering, discovering, assigning, handing off, retiring, and auditing agents, services, tools, and workload packets. It is based on Dynamic Membership Architecture, a framework for systems where computational participants dynamically join, leave, migrate, fail, recover, and retire while preserving execution continuity.

PhoenixFlight complements Docker and Kubernetes by adding a governance-aware membership contract for agentic and distributed runtime participation. It is a local MVP runtime backed by research-grade architecture.

[!IMPORTANT] Technical Specification: Read the Technical Blueprint for an in-depth structural and mathematical specification of the Dynamic Membership Architecture (DMA) implementation.

---

Product Mental Model

PhoenixFile  →  .pflight bundle  →  governed runtime execution  →  assignment  →  handoff  →  audit

Stage	What happens
PhoenixFile	Declare participants, policies, capabilities, and governance contracts
.pflight bundle	Package + cryptographically verify the application for portable deployment
Governed runtime	Initialize the local runtime; register agents as members
Assignment	Policy-route a FlightPacket to the best-match member by trust + capability
Handoff	Migrate context from one member to another, preserving full lineage
Audit	Every event — register, assign, handoff, retire — written to JSONL audit trail

---

60-Second Quickstart

Get started with PhoenixFlight immediately via PyPI:

# 1. Install PhoenixFlight
pip install phoenixflight

# 2. Scaffold a new governed application
phoenix new my-app
cd my-app

# 3. Initialize local runtime
phoenix init

# 4. Validate the declarative app descriptor
phoenix validate -f PhoenixFile

# 5. Register the agent
phoenix member register agents/my-app-agent.yaml

# 6. Create a workload packet
phoenix packet create my-app

# 7. Auto-assign the packet based on capability and trust policy
phoenix assign packet-001 --to my-app-agent

# 8. Check your runtime status
phoenix status

# 9. Build a portable, signed .pflight bundle
phoenix build -f PhoenixFile

Scaffold a new app

phoenix new my-app

Inspect local runtime state at any time

phoenix status

`phoenix status` is the fastest way to inspect your local runtime: it prints a one-screen summary of initialization state, member counts, packet counts, and the most recent audit event. It exits 0 whether or not the runtime has been initialized, so it is safe to run at any point in the workflow. Use `phoenix --no-color status` in CI or when piping output to a file.

### Shell Completion

PhoenixFlight can generate completion scripts for bash, zsh, and fish:

```bash
phoenix completion bash > ~/.phoenix-completion.bash && source ~/.phoenix-completion.bash  # bash
phoenix completion zsh  > ~/.zsh/completions/_phoenix                                      # zsh
phoenix completion fish > ~/.config/fish/completions/phoenix.fish                          # fish

Both phoenix and pf are covered by each generated script. Full install instructions are in docs/INSTALL.md.

See docs/INSTALL.md for pipx, pip, Homebrew, and container install paths. See docs/CHANGELOG.md for version history and docs/RELEASE.md for the release runbook.

---

Watch PhoenixFlight register governed members, assign a FlightPacket, perform a handoff, write an audit trail, and build a verified .pflight bundle.

Full walkthrough video available in the v0.1.0-mvp release assets.

---

What PhoenixFlight Is

PhoenixFlight is a local governance-aware runtime that implements Dynamic Membership Architecture for real workloads and agents. It provides:

• A declarative application descriptor — PhoenixFile — describing participants, governance policies, and runtime contracts
• A portable unit of work — FlightPacket — that carries identity, capabilities, context, and audit history
• A packaged distribution format — .pflight bundle — for portable, cryptographically-verified deployment
• A CLI and REST API for the full membership lifecycle
• A policy engine for trust-scored, capability-routed assignment and handoff
• An audit trail capturing every membership event in structured JSONL

---

Why It Exists

Modern distributed and agentic systems assume static participants. When an agent crashes, a service migrates, or a workload is handed off between providers, most frameworks lose context, history, and governance continuity.

Dynamic Membership Architecture formalizes the contract for systems where membership is the variable, not the exception. PhoenixFlight is the reference implementation of that contract.

PhoenixFlight does not claim to replace Docker or Kubernetes. Correct framing:

PhoenixFlight adds governance-aware membership semantics — registration, trust, assignment, handoff, retirement, and audit — to complement the infrastructure scheduling and container packaging layers provided by Docker and Kubernetes.

---

Core Runtime Lifecycle

Register → Discover → Assign → Handoff → Retire → Audit

Step	What happens
Register	An agent or service joins the runtime with identity, capabilities, trust score, and namespace
Discover	The runtime finds eligible members matching required capabilities and trust thresholds
Assign	A FlightPacket is assigned to a member using policy-governed, trust-weighted capability routing
Handoff	A packet migrates from one member to another, preserving context, history, and ownership
Retire	A member gracefully drains its assignments and exits the runtime with an audit trail
Audit	Every event — registration, assignment, handoff, retirement, denial — is written to the audit log

---

PhoenixFile

PhoenixFile is the canonical declarative application descriptor for a governed participant group. It replaces nothing — it is the native PhoenixFlight contract.

apiVersion: phoenixflight.io/v1alpha1
kind: PhoenixApp
metadata:
  name: customer-validation-app
  namespace: tenant-a
  version: 0.1.0

runtime:
  language: python
  entrypoint: src/app.py

controlPlane:
  auth:
    provider: local
  policies:
    - policies/can-register.yaml
    - policies/can-assign.yaml
    - policies/can-handoff.yaml
  audit:
    sink: local
    format: jsonl
  assignment:
    strategy: trust-weighted-capability-routing
  governance:
    minimumTrustScore: 0.85

dataPlane:
  agents:
    - agents/governance-agent.yaml
    - agents/metadata-agent.yaml
  packets:
    - packets/customer-validation.packet.yaml
  handoffContracts:
    - contracts/customer-context-handoff.yaml

membership:
  discovery:
    mode: capability
  migration:
    enabled: true
  retirement:
    drainTimeoutSeconds: 30

Full spec: docs/PHOENIXFILE.md

---

FlightPacket

A FlightPacket is a portable unit of work. It carries:

• Workload identity and namespace
• Required capability constraints
• Context payload (checkpoint state)
• Policy tags (e.g., PII, GDPR)
• Ownership history (full handoff chain)
• Audit lineage

Packets are created from YAML manifests, assigned to members via trust-weighted routing, handed off between members preserving context, and audited at every transition.

---

.pflight Bundle

A .pflight bundle is a portable, signed runtime archive:

customer-validation-app-0.1.0.pflight (ZIP)
├── PhoenixFile
├── manifest.json
├── validation-report.json
├── hashes.json              ← SHA-256 for all files
├── agents/
├── packets/
├── policies/
└── contracts/

Build, inspect, verify, and unpack:

python3 -m src.phoenix_cli build -f examples/customer-validation/PhoenixFile
python3 -m src.phoenix_cli bundle inspect dist/customer-validation-app-0.1.0.pflight
python3 -m src.phoenix_cli bundle verify  dist/customer-validation-app-0.1.0.pflight
python3 -m src.phoenix_cli bundle unpack  dist/customer-validation-app-0.1.0.pflight --to ./unpacked

Full spec: docs/BUNDLE_FORMAT.md

---

Local Runtime State

PhoenixFlight stores all runtime state under .phoenixflight/:

.phoenixflight/
├── members.json      ← registered member registry
├── packets.json      ← active flight packets
├── audit.jsonl       ← structured audit log
└── imports/          ← local bundle registry

Initialize:

python3 -m src.phoenix_cli init

---

CLI Quickstart

Prerequisites

git clone https://github.com/KinshukON/DynamicMembershipArchitecture.git
cd DynamicMembershipArchitecture
pip install -e .

Full Local Demo

# 1. Initialize local runtime state
phoenix init

# 2. Validate a PhoenixFile
phoenix validate -f examples/customer-validation/PhoenixFile

# 3. Register members (agents)
phoenix member register examples/customer-validation/agents/governance-agent.yaml
phoenix member register examples/customer-validation/agents/metadata-agent.yaml

# 4. List members
phoenix member list

# 5. Create a flight packet
phoenix packet create customer-validation

# 6. List packets
phoenix packet list

# 7. Assign packet to a member (auto policy-checked)
phoenix assign packet-001 --to governance-agent

# 8. Inspect a packet
phoenix inspect packet-001

# 9. Handoff to another member
phoenix handoff packet-001 --from governance-agent --to metadata-agent

# 10. Retire a member
phoenix retire governance-agent

# 11. View audit log
phoenix audit

# 12. Build a portable .pflight bundle
phoenix build -f examples/customer-validation/PhoenixFile

# 13. Inspect the bundle
phoenix bundle inspect dist/customer-validation-app-0.1.0.pflight

# 14. Cryptographically verify bundle integrity
phoenix bundle verify dist/customer-validation-app-0.1.0.pflight

# 15. Unpack a bundle
phoenix bundle unpack dist/customer-validation-app-0.1.0.pflight --to ./unpacked

# 16. Emit a Dockerfile from PhoenixFile
phoenix emit dockerfile -f examples/customer-validation/PhoenixFile

# 17. Worker lifecycle
phoenix worker start     --id worker-01
phoenix worker heartbeat --id worker-01
phoenix worker retire    --id worker-01

# 18. Local registry
phoenix registry add     dist/customer-validation-app-0.1.0.pflight
phoenix registry list
phoenix registry inspect customer-validation-app

Developer fallback (no install required)

If you do not run pip install -e ., use the direct module invocation:

PYTHONPATH=src python3 -m src.phoenix_cli init
PYTHONPATH=src python3 -m src.phoenix_cli version

Full reference: docs/CLI_REFERENCE.md

---

API Quickstart

Start the API server:

python3 src/server.py --port 8000

Open http://localhost:8000 in your browser for the runtime console and dashboard.

REST API reference: docs/API.md

---

Enterprise Readiness

Capability	Status
PhoenixFile declarative descriptor	✅ Implemented
Dynamic member registry	✅ Implemented
Trust-weighted capability assignment	✅ Implemented
Policy-governed handoff	✅ Implemented
Graceful member retirement	✅ Implemented
Portable .pflight bundle (SHA-256 verified)	✅ Implemented
Bundle verification (strict integrity check)	✅ Implemented
Dockerfile emitter from PhoenixFile	✅ Implemented
Structured audit trail (JSONL)	✅ Implemented
SIEM audit export	✅ Implemented
Runtime worker lifecycle	✅ Implemented
Auth dev mode / JWT enforcement mode	✅ Implemented
Namespace isolation	✅ Implemented
Local bundle registry	✅ Implemented
Production JWT + OIDC	🔲 Roadmap
Multi-node distributed registry	🔲 Roadmap
Kubernetes operator	🔲 Roadmap

Full assessment: docs/ENTERPRISE_READINESS.md

---

Research Foundation

PhoenixFlight implements Dynamic Membership Architecture (DMA) — a formal framework for systems where participants dynamically join, leave, migrate, fail, recover, and retire while preserving execution continuity.

The DMA framework covers three major paradigms:

1. Phoenix-style virtual nodes — consistent hashing across a dynamic membership ring
2. Kubernetes-style constraint scheduling — capacity-scored workload placement
3. Agentic AI registries — capability-based routing with reliability scoring

The research demonstrates that all three paradigms instantiate the same six primitives: Identity, Discovery, Assignment, Migration, Retirement, Governance.

Running the Research Simulator

python3 src/main.py
python3 src/main.py --steps 120 --initial-resources 8 --imbalance-threshold 0.10 --seed 101

Research Materials

• paper/ — Technical paper (PDF and DOCX)
• figures/ — Architecture diagrams
• docs/technical_blueprint.md — Formal mathematical specification
• docs/ARCHITECTURE.md — Internal design specification

---

Current Limitations

• Local-only runtime: PhoenixFlight currently runs on a single machine. Distributed multi-node registry is on the roadmap.
• No production auth by default: PHOENIX_AUTH_MODE=dev is the default. Set PHOENIX_AUTH_MODE=jwt with PHOENIX_JWT_SECRET for JWT enforcement.
• Worker executes mock tasks only: The runtime worker uses safe non-shell handlers. Real task execution is not implemented.
• No container image registry: The Dockerfile emitter generates a file for review; image push requires Docker to be installed and run separately.
• SQLite state: Runtime state is stored in SQLite (phoenixflight.db) for local persistence. No distributed store.

---

Roadmap

• Production JWT/OIDC auth integration
• Multi-node distributed registry with leader election
• Kubernetes operator (Dockerfile.operator)
• LangGraph and LangChain adapter (in progress — src/langgraph_adapter.py)
• Live migration with checkpoint transfer
• Verifiable audit log (hash chain / Merkle)
• Helm chart for Kubernetes deployment

See docs/ROADMAP.md for details.

---

DOI Records

PhoenixFlight is connected to two related but distinct archival records:

Artifact	Type	DOI
Dynamic Membership Architecture paper	Publication / manuscript	https://doi.org/10.5281/zenodo.20693483
PhoenixFlight runtime	Software artifact / GitHub release archive	https://doi.org/10.5281/zenodo.20778458

The publication DOI refers to the Dynamic Membership Architecture research manuscript.
The software DOI refers to the runnable PhoenixFlight implementation and GitHub release archive.

---

Citation / DOI / ORCID / Author

Please cite the v1.0.0 Zenodo publication as:

Dutta, K. (2026). Dynamic Membership Architecture: From the Phoenix Computing Model to Cloud-Native and Agentic AI Runtime Systems (v1.0.0). Zenodo. https://doi.org/10.5281/zenodo.20693483

@misc{dutta2026dynamicmembershiparchitecture,
  author       = {Dutta, Kinshuk},
  title        = {Dynamic Membership Architecture: From the Phoenix Computing Model to Cloud-Native and Agentic AI Runtime Systems},
  year         = {2026},
  publisher    = {Zenodo},
  version      = {v1.0.0},
  doi          = {10.5281/zenodo.20693483},
  url          = {https://doi.org/10.5281/zenodo.20693483}
}

DOIs

• Version DOI (v1.0.0): https://doi.org/10.5281/zenodo.20693483
• Concept DOI (all versions): https://doi.org/10.5281/zenodo.20693482

Links

• Zenodo v1.0.0: https://doi.org/10.5281/zenodo.20693483
• Zenodo all-versions: https://doi.org/10.5281/zenodo.20693482
• GitHub release v1.0.0: https://github.com/KinshukON/DynamicMembershipArchitecture/releases/tag/v1.0.0
• Author ORCID: https://orcid.org/0009-0002-6039-549X
• Author website: https://kinshukdutta.ai
• Live site: https://phoenixflight.app

---

Provenance

PhoenixFlight and the Dynamic Membership Architecture implementation are originated and authored by Kinshuk Dutta.

Passive provenance marker: PF-DMA-KD-ORIGIN-2026-PHOENIXFLIGHT