Skip to content

Latest commit

 

History

History
203 lines (177 loc) · 15.7 KB

platform-support.md

File metadata and controls

203 lines (177 loc) · 15.7 KB

Platform support

This matrix separates source compilation, release packaging, installer or wrapper mapping, and native acceptance. One does not prove the next.

Evidence vocabulary

Layer What it proves
Source contract The inspected implementation and tests express the named invariant. It may be compiled or inspected for another target without running there.
Workflow configuration Automation is configured to request the named target/check. It does not prove that a run started or passed.
Cross-compiled artifact A host produced bytes for another target. It does not prove that the target OS loaded or exercised them.
Native acceptance The exact identified archive passed the named checks on the matching OS and architecture, with a retained receipt.

The filesystem hardening described below is source-contract evidence in this documentation tranche. The immutable v0.7.8 GitHub release resolves to f065b13462f9eaf27e0443f8911f021575b7c409; its 19 assets were verified after all six native-release rows and release attestations passed in workflow 33952398697. That does not validate the npm wrapper installation path. In the exact 2026-09-05 registry snapshot, the 0.7.4 candidate failed on all six targets, npm latest remains 0.6.0, and no exact npm 0.7.8 acceptance receipt is claimed.

Current matrix

Target Release build host and mode GitHub release workflow Primary npm wrapper Shell installer Configured native acceptance / current evidence
macOS Apple Silicon (aarch64-apple-darwin) macos-latest is currently an arm64 host; native-architecture build Archive + SBOM published and attested Mapped Mapped v0.7.8 release-native acceptance passed on macos-15 ARM64; npm 0.7.4 acceptance failed; no npm 0.7.8 receipt
macOS Intel (x86_64-apple-darwin) Cross-target build on the current arm64 macos-latest host Archive + SBOM published and attested Mapped Mapped v0.7.8 release-native acceptance passed on macos-15-intel X64; npm 0.7.4 acceptance failed; no npm 0.7.8 receipt
Linux ARM64 GNU (aarch64-unknown-linux-gnu) Cross-compiled with gcc-aarch64-linux-gnu on x64 Ubuntu 22.04 Archive + SBOM published and attested; GLIBC symbol ceiling enforced Mapped Mapped v0.7.8 release-native acceptance passed on ubuntu-22.04-arm ARM64; npm 0.7.4 acceptance failed; no npm 0.7.8 receipt
Linux x64 GNU (x86_64-unknown-linux-gnu) Native-architecture build on x64 Ubuntu 22.04 Archive + SBOM published and attested; GLIBC symbol ceiling enforced Mapped Mapped v0.7.8 release-native acceptance passed on ubuntu-22.04 X64; npm 0.7.4 acceptance failed; no npm 0.7.8 receipt
Windows x64 MSVC (x86_64-pc-windows-msvc) Native-architecture build on x64 windows-latest ZIP + SBOM published and attested Mapped Mapped by install.ps1 v0.7.8 release-native acceptance passed on windows-latest X64; npm 0.7.4 acceptance failed; no npm 0.7.8 receipt
Windows ARM64 MSVC (aarch64-pc-windows-msvc) Native-architecture build on arm64 windows-11-vs2026-arm ZIP + SBOM published and attested Mapped Mapped by install.ps1 v0.7.8 release-native acceptance passed on windows-11-vs2026-arm ARM64; npm 0.7.4 acceptance failed; no npm 0.7.8 receipt

The current workflow defines six target archives, each containing phantom and phantom-mcp: four Unix .tar.gz files and two Windows .zip files. Both npm wrappers and the direct installers share that six-target lookup contract. The separate npm-candidate-acceptance.yml workflow is configured to exercise the exact tagged five-file npm tarballs from fresh caches on these same six native host classes before npm publication, then to repeat acceptance against the integrity-pinned public release-candidate packages before either latest tag changes. A workflow definition is not a receipt; retain all six successful jobs for each mode. No exact npm 0.7.8 receipt is claimed here. The native-acceptance matrix is configured to download each exact build artifact on its matching runner, reject extra or unsafe archive members, verify archive integrity through extraction, assert the runner OS and architecture, run both binaries' exact tagged --version, and complete the MCP stdio schema smoke. On those same six native filesystems, it also runs both npm wrappers' platform mapping, cache validation, rollback, lock, archive, process-failure, and closed-schema tests without downloading or publishing an npm package. It then runs the real direct installer from that exact local archive in an isolated home/profile, validates both installed binaries and the source receipt, injects a test-only failure immediately after candidate promotion, and verifies that the sentinel-bearing accepted tree is restored with no sibling transaction residue. It then corrupts the checksum sidecar and proves that a pre-transaction integrity failure also preserves the accepted tree. Windows acceptance suppresses persistent user-PATH mutation on the CI account; it does not claim shell-profile acceptance. Attestation cannot begin until all six jobs succeed. The exact v0.7.8 tag workflow passed this release native matrix, completed release attestations, and created the immutable 19-asset GitHub release; retain workflow 33952398697 as the exact execution receipt. That receipt does not prove npm-wrapper installation: exact npm 0.7.4 acceptance failed independently and no exact npm 0.7.8 receipt is claimed.

GitHub's current hosted-runner reference maps windows-latest to x64 and macos-latest to arm64. GNU/Linux release builds use the explicit ubuntu-22.04 x64 image rather than a moving ubuntu-latest label. The workflow's Windows ARM64 jobs use the literal windows-11-vs2026-arm label. Runner labels and images can change, so the run log and image metadata are the source of truth for a particular release. A native-architecture compilation host is not native acceptance on its own. The separate matrix is configured to execute the exact resulting archive; only a retained successful run establishes that evidence for a particular candidate.

GNU/Linux compatibility baseline

The oldest GNU/Linux userspace targeted by the release workflow is Ubuntu 22.04, whose baseline GNU C Library is GLIBC 2.35. After building each x64 and ARM64 GNU target, the workflow reads the ELF version requirements of both phantom and phantom-mcp and fails if the highest numeric requirement exceeds GLIBC_2.35. It also fails closed when it cannot read numeric GLIBC evidence or encounters an unknown GLIBC requirement.

This is a deterministic symbol-version ceiling, not a claim that every Linux distribution with GLIBC 2.35 is compatible. The GLIBC build gate itself does not test the packaged archive, ARM64 execution, the kernel, loader, native credential store, proxy, or MCP behavior. It does not constitute native runtime acceptance. The separate native matrix is configured to cover exact-archive execution and MCP schema initialization on Linux x64 and ARM64, but its source definition is not a successful candidate receipt and it does not cover the remaining operating-system integrations below.

Feature-specific boundaries

Feature macOS Linux Windows
Core CLI, vault, proxy, MCP source Implemented Implemented Implemented
Native credential store Keychain integration Kernel keyutils by default; explicit trusted-terminal migration to persistent desktop Secret Service; encrypted-file fallback for CI/headless use Credential Manager integration
Provider-grant design source and value-free metadata Present Present Present
Provider issuance/enrollment/renewal/revocation Hard-denied before credential/network access in 0.7.8 Hard-denied before credential/network access in 0.7.8 Hard-denied before credential/network access in 0.7.8
Workspace inspect/propose/request Implemented Implemented Inspect/propose only
Durable workspace apply Descriptor-relative Unix implementation Descriptor-relative Unix implementation Fails closed
Durable broker replay foundation Unix implementation Unix implementation Fails closed
Production confined engineering runtime Unavailable Unavailable Unavailable

Governed filesystem mutation

Contract Current source evidence Acceptance boundary
Retained root/parent identity Project and explicitly authorized global config writers resolve targets from retained directory capabilities; Unix rename-and-decoy tests preserve the replacement decoy The exact native-release receipt does not exercise this filesystem contract
Symlink and reparse denial No-follow traversal rejects symlink/reparse ancestors and leaf targets; Windows implementation has source-contract checks Windows tests in source are not a native Windows run
Hard-link denial Sensitive anchored files must be regular and have one link before read/effect Platform filesystem behavior still needs exact native acceptance
Exact compare-and-swap Before-images bind stable file identity and bytes; same-content replacement identities are rejected Covers cooperating Phantom operations, not arbitrary same-user writers
Init review admission Before vault provisioning, init retains the reviewed project root and exact dotenv/config leaf identity, bytes, and permissions; after locking it revalidates root and leaf snapshots before mutation Source and deterministic decoy-test evidence, not a native credential-store run
Vault/project lock order Vault/application authority is resolved before the project lock; stable root identity and exact config are revalidated afterward Source and concurrency-test evidence, not native scheduler or credential-store acceptance
Effect status CommittedVerifiedButDurabilityUncertain is committed and exactly verified, with a value-free warning/receipt and no rollback or retry; CommittedButUncertain is Partial when verification or durability remains unresolved Partial outcomes require operator reconciliation and are not safe blind retries
Windows permissions before bytes New private files/directories establish and verify a protected current-user DACL before content; replacements preserve and verify the reviewed exact DACL, inheritance state, and read-only state before bytes Source-contract tests only; protected native Windows CI acceptance remains pending
Created-parent rollback Identity-bound receipts remove only exact, empty transaction-created directories after descendant handles are dropped Unknown creation state without a receipt remains explicitly unresolved

Native credential-store and ACL source are likewise not acceptance. In particular, the configured keyring crate features select macOS Keychain, Linux keyutils or Secret Service, and Windows Credential Manager. Linux keyutils entries are in-memory and do not survive a reboot. On a headed Linux desktop, phantom vault migrate-linux can copy and read-after-write verify the current project's entries in Secret Service before atomically selecting it. The command retains keyutils source entries, is safe to retry after a partial copy, refuses conflicting destination values, and requires an exact attached- terminal challenge before reading any secret value. A project that completed the migration fails closed when Secret Service is unavailable; it never silently treats the retained volatile copy as authoritative. CI, WSL, and headless systems should use the explicit encrypted-file vault instead. The migration writes a Secret Service corroboration sentinel for explicit recovery checks. An independent owner-only corroboration record under Phantom's configuration root prevents loss of only the data-root marker plus a reboot from silently selecting keyutils: one missing record fails closed without a Secret Service probe, while the explicit migration command can reconcile the prepared state. Normal unmarked/headless vault opens do not probe Secret Service because doing so can prompt or hang without a desktop session. Loss or deletion of all local Phantom state is not recoverable automatically; restore that state from a verified backup before accessing the vault.

Those source mappings, plus source-tested protected current-user DACL behavior, do not prove that an exact archive passed credential-store operations under a real user policy. That evidence still requires protected native CI against the exact candidate on each claimed platform.

Provider-grant support in source does not prove that a provider application is configured, consent completed, a credential accepted, renewal succeeded, or a customer workflow passed. Use throwaway provider accounts for authorized native acceptance and never place provider client secrets on the command line.

Install methods

  • The reviewed v0.7.8 source build checks out f065b13462f9eaf27e0443f8911f021575b7c409 and runs cargo build --release --locked --bin phantom --bin phantom-mcp. An unpinned crates.io install currently resolves the older 0.5.1 track.
  • The npm packages' latest tags currently resolve 0.6.0. Exact 0.7.4 wrappers exist only under release-candidate and failed the six-target npm acceptance gate; they are not the reviewed v0.7.8 GitHub release path.
  • scripts/install.sh supports macOS and GNU Linux targets. Native Windows uses scripts/install.ps1; both scripts verify bounded HTTPS downloads, strict sidecar checksums, archive shape, and binary identity before promotion.
  • The Homebrew formula publishes reviewed v0.7.8 as a separately managed distribution surface. The repository's release workflow does not automatically update a tap.

Configured and additional native acceptance

Before claiming a target as release-ready, test the exact archive and digest on that target:

  1. validate the archive has exactly the expected two regular files;
  2. verify the published checksum and exact --version output for both binaries;
  3. run install, upgrade, interruption, rollback, and cache-recovery paths;
  4. exercise the native credential store and encrypted-file fallback;
  5. run an authenticated loopback proxy request and MCP stdio initialization;
  6. exercise supported shells and editor setup; and
  7. record code-signing, notarization, or platform trust results separately.

The release workflow automates steps 1 and 2, a bounded portion of step 3 (fresh direct install, receipt validation, post-promotion rollback, and checksum-failure preservation), native-filesystem source tests for both npm wrappers, and MCP schema initialization from step 5 on all six native runners. Those wrapper tests do not prove installation of a packed or registry-hosted npm artifact; the separate npm candidate workflow owns that evidence. Upgrade, interruption, cache recovery, persistent PATH/shell behavior, credential stores, an authenticated proxy request, editors, and platform trust still require separately retained evidence. No repository-local source test or workflow definition is a substitute for a successful exact-candidate run and those additional receipts.

External benchmark

Phantom's Rama-derived engineering standard pins the upstream main snapshot 267e4790c899736e6f60d982c8a0932406d4079e, reviewed 2026-09-01. Rama's explicit stacks, modular crates, runnable examples, and tiered platform CI are benchmarks for improving Phantom's engineering evidence. Rama is not a dependency, and its platform tiers or features do not transfer to Phantom.