φ PhiOS

Optical vs. Electrical Transport Advisor (R1)

Research contract and limitations. Try python -m phios.optical_path_r1 --sizes 64,4096,65536,1048576 for deterministic synthetic link-budget estimates. This never probes hardware, changes routing, or provides physical authority.

Local-first, authority-aware computing for human + computational collaboration.

Sovereign. Coherent. Local. Free.

PhiOS is an open-source operator shell, verification spine, governed application platform, memory/ledger system, and constrained agent runtime built around one rule:

Capability is not authority.

The project is under active development and should be treated as alpha software.

ΦVine Windows-binary advisory review (Rung 8)

The App Platform can now review a local, untrusted ΦVine handoff JSON with phi-app review-phivine phivine-handoff.json. It validates the record and displays its candidate artifact fingerprint, requested access and unresolved security gates, but always returns HELD (exit 3). It never imports a Windows program, installs Wine, changes the app registry, grants permission or launches a Windows binary. This input is separate from PhiOS's public GitHub repository profiler. See the Rung 8 advisory review contract.

The Python package release is separate from the Linux OS effort. The Linux target is an unpublished x86_64 UEFI Arch-based Wayfire/PhiShell development preview. The exact normal candidate passed VM live/installed boot, persistent data, matched OS recovery and one restricted Linux proof effect. A separate QA image passed bounded signed-package update/interruption tests. The desktop candidate also passed virtual network/audio, manual PAM screen locking and session cleanup, with all nine aggregate jobs green. Physical hardware, the actual final signed transition, source/license delivery and public release remain open; Secure Boot is unsupported. See the OS release contract, exact evidence and release handoff.

Φ Sovereignty by Design (first executable rung)

The Φ Sovereignty Contract makes user exit, data portability, offline operation, and independently auditable claims explicit design requirements. The PhiShell Sovereignty Center is a user-facing, UNVERIFIED status and self-assessment panel, not a machine audit.

A standalone Python 3.11+ utility can pack, verify, and restore an operator-selected local directory in ordinary ZIP + SHA-256 format without running PhiOS:

python scripts/sovereignty_exit_v01.py pack --source my-data --output backup.zip
python scripts/sovereignty_exit_v01.py verify --bundle backup.zip
python scripts/sovereignty_exit_v01.py unpack --bundle backup.zip --output restored-data

Archives are unencrypted. This tool is not yet a complete PhiOS app-state export. See scope and exit tests.

R2 (scoped, still PARTIAL): An explicitly approved ZIP of a verified phi-state backup can be checked and extracted using only Python standard library and the two standalone exit scripts on a non-Phi machine. It includes just the existing backup's supported canonical memory, Curiosity and audit files, not a full PhiShell/GitPorch/browser/model ecosystem export, OS offline proof or recovered authority. See R2 portability and exclusions.

Public website browser smoke gate

The public PhiOS website can be used and tested without installing anything locally. The PhiOS Site GitHub Actions workflow builds the Vite frontend and runs real headless Chromium smoke tests on a temporary GitHub-hosted runner before Pages deployment. The checks cover rendered content, navigation, the architecture controls, CRT mode, the public project-status payload and a small-screen viewport. Failure traces are saved in the CI run. See the browser smoke contract.

A separate post-deployment public Pages browser check now waits for project-status.json at the real GitHub Pages address to report the exact shipped commit, then tests rendered public navigation in Chromium. This can mark an already deployed release red and produce failure evidence, but it cannot automatically undo a Pages deployment. See production smoke contract.

Both checks are online website testing, not offline recovery of your PC, Python operator runtime, or Linux PhiOS OS.

What PhiOS is

PhiOS is designed for systems that can observe, reason, retrieve, plan, and act without quietly collapsing those abilities into permission.

The recurring pattern is:

request
  ↓
explicit authority
  ↓
bounded capability
  ↓
typed evidence
  ↓
narrow receipt
  ↓
revalidation before consequential action

A tool existing does not mean it may be used. A memory being retrievable does not mean it is current. A verifier finding a problem does not mean it may repair it. A recovered identity does not inherit old authority merely because continuity was demonstrated.

Current surfaces

Surface	Current line	Role
Shell / MCP	active	operator interface, workflows, resources, prompts, capability surfaces
Spine	v0.24	authority-aware observation, verification, evidence, and receipts
App Platform	v0.58	governed repo profiling, intake, toolchain/runtime execution, install, launch, update, rollback, cleanup, and release lineage
PhiReflex	v0.10	provider-neutral fast advisory layer with authenticated bounded routing influence
Governed Memory	active	canonical local memory, derived semantic index, read admissibility, temporal horizon
Reality Ledger	active	append-only evidence plus bounded read-only analytics
Covenant Runtime	CR-01 + recovery v0.1	zero-authority identity, topology, transition, continuity, and recovery contracts
Core reasoning	v0.8	geometric reduction, relational fields, dynamic state, routing, replanning, adoption, action binding, execution handoff

Architectural laws

PhiOS encodes distinctions that automation stacks often blur:

capability
!=
authority

observation
!=
truth

retrievable
!=
currently admissible

authentication
!=
authorization

detection
!=
authorized remediation

same topology
!=
same identity

recovered state
!=
recovered authority

installed
!=
runnable

update authority
!=
rollback authority

derived evidence
!=
source evidence

These are implementation constraints, not slogans pasted over ordinary automation.

Architecture

human / client / local agent
          │
          ▼
    Shell / MCP boundary
          │
          ├───────────────┐
          ▼               ▼
       Spine         App Platform
          │               │
          ▼               ▼
   Reality Gate      governed plans
          │               │
          ├──────┬────────┘
          ▼      ▼
      Memory   Covenant
          │      │
          └──┬───┘
             ▼
      Mandala contracts
             │
             ▼
       explicit authority
             │
             ▼
    governed action / handoff
             │
             ▼
        typed receipts
             │
             ▼
       Reality Ledger

PhiReflex can contribute bounded routing influence, but it does not receive action or execution authority.

What works today

Spine v0.24

The Spine supports bounded local evidence and verification across files, screen regions, network interfaces, TCP listeners, loopback HTTP, JSON structure/scalars, repeated observations, cadence, temporal envelopes, and numeric transitions.

A result such as:

"port 11434 is listening"

does not become:

"Ollama is healthy"

unless the broader claim is separately observed and verified.

Current contract: Spine v0.24 numeric-transition verification.

App Platform v0.58

The App Platform provides a governed lifecycle from public repository profiling and source intake through exact-commit acquisition, reviewed build planning, digest-bound toolchain capsule matching, verified capsule acquisition, toolchain attestation, network-denied sandbox planning, an explicit single-build OCI runtime boundary, a concrete rootless Podman adapter, request-bound backend qualification/selection, and a selected-backend execution gate, dependency staging, offline build, artifact installation, visible/persistent launch, app cataloging, side-by-side update, separately authorized rollback, cleanup recovery, release discovery, human review, execution lineage, package lineage, and release-install proposal gating.

Important boundaries include:

public repository != redistribution authority
registered        != installed
installed         != launch authority
release observed  != release selected
candidate selected != update authorized
successful build  != install authority
install           != update authority
update            != rollback authority

Current contract: App Platform v0.58 repository profiler.

v0.58 classifies a bounded public GitHub repository against the current PhiOS path and returns either SUPPORTED_AFTER_OPERATOR_APPROVAL or one exact primary blocker. The assessment remains advisory and grants no acquisition, build, install, or launch authority.

PhiReflex v0.10

PhiReflex is a provider-neutral fast advisory layer. It began as shadow-only evaluation and now supports a narrowly governed live routing-influence path with authenticated grants, trust lifecycle, provider manifests, use limits, root pinning, adapter attestation, one-use activation nonces, offline checkpoint verification, and conflict-only replication snapshots.

Even when live:

routing_influence_authority = true
action_authority            = false
execution_authority         = false

Current contract: PhiReflex v0.10 root pinning and attestation.

Governed memory and evidence horizon

Canonical memory belongs to PhiOS. Vector search is a replaceable derived index.

The hardened memory path separates:

record exists canonically
from
record may enter active context now

Stale memory can remain auditable while direct context admission expires. Re-entry requires the configured temporal/reconsolidation path rather than timestamp laundering.

See: Governed memory and Memory Evidence Horizon v0.1.

Input and output API keys

PhiOS includes a bounded API-key boundary for both directions:

• inbound keys authenticate a configured caller/audience without turning possession into action authority;
• outbound keys are resolved ephemerally from an external secret source and can be leased to adapters without writing the raw credential into normal receipts.

A network adapter still has to declare and pass the normal effect and authority boundaries.

See API Key Boundary v0.1.

Covenant identity and recovery

Covenant CR-01 defines zero-authority identity/topology/transition contracts.

The recovery extension adds invariant-bound identity continuity across topology changes, exact epoch chaining, exact recovery-state continuity, and mandatory downstream authority revalidation.

same machine != same identity
same identity != restored authority

See: Covenant Runtime CR-01 and Identity Continuity and Recovery v0.1.

Research hardening

The current hardening line adds explicit contracts for:

• authority projection and no-mint memory reads;
• control-plane isolation;
• environmental effect classification;
• observation frontiers;
• transformation lineage and exactness;
• evidence-path independence and disagreement;
• verifier/governance escalation;
• dynamic-state decay and termination;
• memory evidence horizons and reconsolidation;
• inbound/outbound API-key handling;
• invariant-bound identity recovery.

See ENTER THE FIELD → PhiOS research hardening.

GitPorch HomeNode native connection (R1-H6)

PhiOS now includes a read-only, explicitly invoked native HomeNode client for GitPorch's authenticated TLS capability gateway. It's a small standard-library Python adapter, not a LAN server, Git remote, automated deployment, or browser token bridge.

phi-homenode status --mode offline
phi-homenode status --mode public
# Only after operator-controlled certificate pin and secret files are configured:
phi-homenode preflight
phi-homenode status --mode local

Public and Offline do not probe a network. Local uses a verified, SHA-256-pinned certificate and bearer token from private files for one GET /v1/capabilities. Any failure selects OFFLINE without claiming local services work, or silently contacting public GitHub. Nothing starts automatically, and no connection confers install, execution, Git push or identity authority. Do not place tokens in PhiOS Pages, EnterTheField.org or browser JavaScript.

See R1-H6 HomeNode trust and operation.

Quick start

Requirements

• Python 3.11+
• psutil>=5.9.0
• mcp>=1.26,<2

Clone and install:

git clone https://github.com/MichaelWave369/PhiOS.git
cd PhiOS
python -m pip install -e .

Development install:

python -m pip install -e ".[dev]"

Optional components:

python -m pip install -e ".[screen]"
python -m pip install -e ".[ocr]"
python -m pip install -e ".[memory-vector]"
python -m pip install -e ".[ledger-reports]"
python -m pip install -e ".[reflex-jev]"
python -m pip install -e ".[reflex-authority]"

Some execution paths are Linux-specific. Bubblewrap isolation and Wayland-visible desktop execution require the corresponding Linux environment and tools.

Main entry points:

phi --help
phi-spine --help
phi-app --help
phi-reflex --help
phi-memory --help
phi-ledger --help
phi-mcp

Initialize governed memory in its disabled state:

phi-memory init-config
phi-memory status

API-key example

Do not commit real API keys.

An outbound provider key can be supplied through the runtime environment and registered by reference:

from phios.spine import OutboundApiKeySpec, PhiOSSpine

spine = PhiOSSpine(
    state_root="./state",
    allowed_permissions=(),
    task_id="example",
)

spine.api_keys.register_outbound(
    OutboundApiKeySpec(
        key_id="provider-output",
        provider="provider",
        environment_variable="PROVIDER_API_KEY",
    )
)

lease = spine.api_keys.lease_outbound(
    key_id="provider-output",
    provider="provider",
)
headers = lease.authorization_headers()

The lease can produce a Bearer header or a configured X-API-Key-style header. The credential itself is deliberately excluded from ordinary lease receipts and metadata.

Repository map

phios/
├─ core/           governed reasoning and execution handoff
├─ shell/          operator shell
├─ mcp/            MCP interface
├─ spine/          authority-aware runtime
├─ apps/           governed app lifecycle
├─ mandala/        typed contracts and receipts
├─ memory/         canonical memory + derived retrieval
├─ ledger_reports/ read-only analytics projection
├─ reflex/         bounded advisory/routing layer
├─ covenant/       identity/topology/recovery contracts
├─ soma/           bounded perception/evidence
└─ reality/        Reality Gate verification

docs/              current contracts, architecture, history
tests/             regression and contract tests
scripts/           development and policy helpers

Development gates

CI enforces:

ruff check phios/
mypy phios/ --ignore-missing-imports
pytest -q
bash scripts/policy_no_telemetry_runtime.sh

Special lanes also exercise the governed-memory vector backend and the isolated DuckDB/Ledger path.

New contracts should normally include deterministic serialization/hashing where appropriate, strict parsing, explicit authority fields, tamper tests, and failure-path tests.

Documentation

Start here:

• Documentation index
• Living specification
• Architecture blueprint
• Version and contract history
• Research hardening
• Contributing
• Changelog

The old root-level README_SPINE_V*.md and README_APP_PLATFORM_V*.md overview snapshots have been retired from the working tree. Their narrower technical contracts remain under docs/, and the original overview files remain available through Git history.

When documents disagree, prefer:

1. code on main;
2. current tests and CI-enforced contracts;
3. the latest component contract;
4. this README;
5. historical material.

License

PhiOS project-owned code and documentation are released under the MIT License unless otherwise noted.

See LICENSE, PHI_COMMONS.md, THIRD_PARTY_NOTICES.md, and MODEL_LICENSES.md.

Direction

PhiOS is trying to make powerful local computation easier to use without allowing capability, inference, convenience, or recovery to silently become authority.

Sovereign. Coherent. Local. Free.

Φ PhiARK Knowledge Vault: read-only PhiOS integration probe (R0.6)

The PhiShell app library includes an advisory PhiARK Knowledge Vault tile, explicitly not bundled / not installed. PhiOS can independently inspect a configured local PhiARK data folder without requiring cloud AI or repository access:

phi-app phiark-status --data-root /absolute/path/to/PhiARKVault
phi-app phiark-status --data-root /absolute/path/to/PhiARKVault --verify-kiwix
phi-app phiark-status --data-root /absolute/path/to/PhiARKVault --probe-loopback

The default probe accesses only local files, verifies SHA-256 stored document bytes, and never launches the PhiARK Node server or Kiwix. The optional Kiwix check reads archive files to recheck their stored checksums; the optional network probe contacts 127.0.0.1:3691 only, and is not proof of process identity. There are no authority grants, installs or bootable images. See the R0.6 governance contract and PhiOS #321.