Module foundation 

Oxi Foundation v1 — provider profile parsing and Keychain-backed secrets.

Parses ~/.oxi/foundation/v1/profiles.json (or the path rooted at $OXI_FOUNDATION_HOME for tests and deployment overrides) according to the schema in doc/spec/oxi-foundation-v1.md §2. Profiles are non-secret by construction: any field that could carry a secret is a parse-level rejection.

The SecretResolver trait lives at this CLI boundary and is never named from oxibrain-core / oxibrain-store / oxibrain-index (see ARCHITECTURE §15.7, ADR-007). Tests use InMemorySecretResolver; production uses OsKeychainResolver when the CLI is built with --features os-keychain.

Resolution ladder for an extraction role (Task 3 §3):

1. OXIBRAIN_LLM_PROVIDER (CLI/env override) — wins outright.
2. Foundation profile for the requested role whose declared capabilities satisfy the configured extraction mechanism, and whose Keychain secret resolves. A missing/unavailable secret reports why that profile cannot run and falls through to (3) without sending extraction elsewhere.
3. Existing ANTHROPIC_* / OPENAI_* compatibility environment.
4. Local GGUF (C2 — no API key required).

Structs

DeclaredCapabilities

Capabilities the profile’s remote model declares (§2.5 lists which ExtractMechanism flags it advertises). Profiles whose declared set does not satisfy the configured mechanism are rejected before any Keychain lookup happens.

FoundationProfiles

The full profiles.json document (§2.1).

InMemorySecretResolver

Deterministic in-memory SecretResolver for tests and the local-dev default. Constructed from a (service, account) -> secret map or, when no map is provided, refuses every lookup so missing-secret behaviour is exercised by tests rather than masked.

ProviderProfile

A single Foundation profile (§2.1, §2.2). Parsed strictly: extra fields that look like secrets cause the whole file to be rejected (§2.5).

ResolvedProfiles

A parsed and validated FoundationProfiles ready for role resolution.

SecretLocator

A Keychain locator for the profile’s secret. The shape is fixed by §2.4: {service, account}. The host’s SecretResolver turns this into a secret at runtime; the locator itself is safe to share.

Enums

FoundationError

Why a profiles.json was rejected at the parse boundary. The host must report one of these — never silently fall through to a different provider.

ProfileRole

The four roles a profile can declare (§2.3). Strongly typed so call sites compose against an enum, not a raw string.

ProviderKind

Map a Foundation profile’s provider field to the host’s adapter catalogue. Foundation v1 deliberately does not name “anthropic” or “openai” in the spec; the host picks the adapter that can honour the declared mechanism. Unknown provider kinds are a FoundationError::InvalidShape so a typo never silently maps to the wrong adapter.

Constants

ALLOWED_ROLES

The set of legal role strings (§2.3). The host rejects profiles that list any role outside this set, so a typo never silently disables a profile.

SCHEMA_VERSION

The only schema_version this host accepts. Any other value rejects the whole profiles.json at parse time — the host does not silently coerce.

SECRET_FIELD_NAMES

Field names whose presence in profiles.json is a parse-level rejection (§2.5). The locator is the only credential surface; anything that smells like an inline secret is a hard fail.

Traits

SecretResolver

Resolves a Keychain locator to a secret. Production implementations read the OS Keychain; tests use an in-memory map. The trait is never named from oxibrain-core / oxibrain-store / oxibrain-index; only the CLI adapter boundary calls into it (ARCHITECTURE §15.7).

Functions

default_secret_resolver

Construct the production-default SecretResolver for the current build.

foundation_home

Resolve the Foundation home directory.

load_profiles

Load profiles.json from the standard location and validate it strictly.