Module foundation 

Oxi Foundation v1 host primitives for oxicode.

Reads the versioned contract under ~/.oxi/foundation/v1/. The contract is the only interface across the host boundary: oxicode does not import from oxibrain or oxios directly.

Layout

~/.oxi/foundation/v1/
├── foundation.json
├── profiles.json
├── packages.lock
└── packages/<sha256>/

Override the root with $OXI_FOUNDATION_HOME. The contract is documented in docs/superpowers/specs/2026-08-17-oxi-foundation-contract.md.

Modules

• compatibility — typed foundation.json parsing + schema / host-version negotiation.
• profiles — typed profiles.json parsing, role resolution, and the pure resolve_profile decision function.
• packages — typed packages.lock parsing, digest verification, and capability mapping to oxicode’s existing policy.
• credentials — Keychain-backed credential resolver (see credentials.rs).
• compat_import — one-time legacy compatibility import (gated by OXICODE_FOUNDATION_MIGRATION=1).
• fixtures — helpers that load the shared cross-host JSON fixtures from tests/fixtures/oxi-foundation/v1/.

All errors are re-typeset through FoundationError; the Display/Debug impls never expose a secret value.

• brain — BrainMemoryBackend, the only durable-memory authority under the Foundation host. Talks to oxibrain over a Unix-domain socket; surfaces degraded state on connection failure.

Modules

brain

Brain (oxibrain) memory backend.

brain_control

oxibrain daemon lifecycle control — bring a brain·down daemon back.

compat_import

One-time legacy compatibility import.

compatibility

foundation.json parsing and host-version negotiation.

credentials

Keychain-backed credential resolver + legacy one-time importer.

files

Filenames the contract requires at the foundation root.

fixtures

Shared cross-host fixture loader.

migrate

Migration primitives: legacy memory → Brain (oxibrain).

packages

packages.lock parsing, digest verification, and capability mapping.

profiles

profiles.json parsing and role resolution.

Structs

FoundationSnapshot

In-memory snapshot of the foundation installation. Cheap to clone — all fields are Arc-friendly.

Enums

CredentialSource

Source of the resolved provider/model. Used in logs and diagnostics.

FoundationError

Error type for every foundation operation. Carries no secrets.

Constants

FOUNDATION_ROOT_SUFFIX

Canonical subdirectory name under the host’s $HOME (or $OXI_FOUNDATION_HOME).

Functions

discover

Full filesystem discovery — parses foundation.json, profiles.json, and packages.lock (when present). Returns a typed snapshot or a typed error. All reads are best-effort for the lockfile: the foundation is usable without installed packages.

fetch_oxicode_home

Resolve the oxicode home directory through the unified Oxi home layout ($OXICODE_HOME, else <oxi_home>/oxicode, else ~/.oxi/oxicode). The Foundation host is independent: OXICODE_HOME/OXI_HOME only affect oxicode-local paths (legacy memory, migration checkpoints, etc.) and do not change the Foundation root.

foundation_present

true when the foundation installation is present and looks well-formed enough to attempt parsing. Reads only metadata; does not validate schemas.

foundation_root

Resolve the foundation root. Honors $OXI_FOUNDATION_HOME; falls back to $HOME/.oxi/foundation/v1. Never reads secrets from this path.