12. Configuration

Settings: one immutable generation

lychd.toml is the global Settings document under the Codex. Its only top-level sections are server, orchestration, and extensions. Settings is the sole BaseSettings model; nested strict BaseModel sections reject unknown and obsolete fields. The public Python entry is lychd.config.settings, not its internal section modules.

Source precedence is fixed:

explicit construction → environment → lychd.toml → Pydantic file secrets → model defaults

Environment names use the root SECTION__FIELD grammar. There is no dotenv source and nested sections do not load separate environment, TOML, or secret sources. Loading is read-only: it does not create Codex files, repair input, generate credentials, or mutate the environment. SettingsSnapshot captures a validated serialized generation; each preview/apply phase materializes and revalidates its own copy rather than retaining mutable nested models.

Every accepted field must have one real consumer. Current Settings exposes server.port, but the native listener host is fixed by runtime policy rather than TOML. Obsolete server.host, server.reload, server.keep_alive, and server.web.url inputs are rejected and do not appear in generated configuration; launcher flags or environment cannot smuggle them back as Codex intent.

[extensions] selects permitted built-in and Crypt packages; it neither selects an application nor creates a runtime. A future application selector requires its own accepted Spellweaver schema and may resolve only one registered exact profile revision, such as one of the mutually exclusive Reach deployment profiles. For each application and Habitat partition, that immutable selection binds one authority epoch, one Discord edge epoch, one active Phylactery, one Gateway/delivery credential owner, and the exact per-host role set. Unknown mixtures and boolean authority switches such as trusted, use_vps, local_db, or tether fail before Bind. The selected profile contributes no raw units: one immutable generation resolves its exact Composition/Pattern revisions and registered service roles into the ApplicationDeploymentManifest@1, then revalidates global ports, routes, secrets, mounts, migrations, dependencies, and resource policy before Bind. Settings owns the fixed runs and rites physical queues and their concurrency; routing can name only those queues. Global port claims and Rune port claims are arbitrated before any unit is written.

Changing profile or authority location is a typed Evolution effect, not Settings reload. It must quiesce admission, settle or preserve external-effect identities, fence the old epochs, revoke old routes and credential owners, transactionally restore an admitted partition when authority moves, and activate the new generation last. An old or simultaneous generation fails closed.

Gateway placement follows the same exact-profile law. Home and Remote are reference placements of one separate Gateway Host role, not applications, Extension Domains, or free configuration literals. A selected deployment profile either omits that role or binds its exact per-host manifest, Veil routes, optional Tether generation, backend identity, service Principals, edge secrets, firewall and management boundaries, and recovery contract. Loose fields such as gateway=true, rpi, vps, or an arbitrary proxy target cannot assemble a partial edge.

Presentation configuration obeys the same typed-source law when it is admitted. In particular, a future Altar palette may enter only through an explicitly owned validated Settings field or another Covenant-owned typed source with declared precedence; it is never an unmodelled TOML table, raw CSS file, selector, or extension side channel. Frontend owns the finite semantic colour roles and accessibility rules, while Configuration owns loading, validation, attribution, and immutable generation. Current Settings contains no palette field and changing the accepted root shape requires an implementation and State update.

A future Spellweaver configuration-to-casting selector follows the same root-shape law. Local TOML may select exact already-registered Scroll, Spell implementation, AgentSpec/Posture, and Context projection revisions plus bounded policy, with the Agent references resolved only through an exact placement; the portable Scroll remains canonical JSON. Configuration never names Python imports, BaseNodes, graph edges, callables, prompts, source bytes, credentials, or live handles, and it cannot turn schema registration into executable activation. No such Settings section or Rune branch is delivered.

Runes: location, provenance, semantics

A Rune is one validated top-level TOML instance in the Codex runes/ tree, not a runtime object or generated unit. Each concrete RuneConfig supplies one safe path_fragment; direct Python subclassing forms one anchor ancestry, and relative_path is computed from it. A fragment is one segment matching ^[a-z0-9](?:[a-z0-9_-]{0,48}[a-z0-9])?$. Distinct registered schemas cannot own the same exact anchor; nested anchors remain distinct and express declared class ancestry. Nested non-Rune Pydantic value objects may contribute shared validated structure without joining or branching that anchor ancestry. The delivered QuadletConfig is embedded under the quadlet field of Soulstone and Phoenix Runes and shares only the minimum OCI image invariant; it supplies neither a Rune path nor raw unit, lifecycle, mount, network, secret, or command authority. Generic sample generation renders required embedded values as typed TOML inline tables; maintained hand-authored examples may use the equivalent named table form such as [quadlet]. Branch classes are namespaces and cannot own TOML files; only leaf schemas may have one or more instances. A file's path supplies its identity and source_file provenance. Duplicate identity, files in branch anchors, arrays-of-tables instance encoding, unsafe fragments, and schema violations abort discovery.

An Anchor is an owned directory territory. A Fragment is its safe local path segment. An Instance is one leaf TOML document. Provenance follows an instance at runtime but is not a TOML field. Validated instances are frozen: resolvers may derive effective state but may not alter Codex intent.

Filesystem ancestry names type, not semantic defaults. Named leaf profile instances supply family-specific defaults; a capability-bearing Rune references profiles and applies local overlays. Resolvers combine profile, runtime/family defaults, local overlay, then request-time override. Presets such as a llama.cpp router .ini are typed, readable references: they tune their runtime but cannot change port arbitration, coven exclusivity, or host ownership. Upstream precedence is CLI arguments > model-specific preset section > global [*] section; a generated CLI override that deliberately shadows a preset value must remain visible to the operator.

The accepted general-service Rune shape uses first-class [[capabilities]] entries. Each entry references one registered semantic interface and exact immutable profile, declares its permitted operations and invocation mode, and pins the runtime driver/dialect, conformance evidence, resource envelope, and containment profile required to make that instance honest. Definitions are provider-owned registry contributions; a Rune selects them and supplies instance-local endpoint, secret reference, lifecycle, and explicit overlay values. It cannot redefine their schemas, licenses, or proved limits inline.

Current source delivers only [[models]]: models behind one Rune instance with closed families, modalities, tool/streaming support, context size, and generation overlays. Those blocks remain v1 compatibility sugar for exact admitted model-interface projections; non-model services never invent a model_id or generation overlay merely to become loadable. Neither form encodes multiple Rune instances.

For the current v1 path, capability synthesis begins with text input and output. Field precedence is Rune hint, then live probe or adapter-discovered runtime fact, then runtime profile default. An explicit modality hint replaces discovered and default modalities; when omitted, probed modalities may enrich the runtime base. In v2, open facts are profile-specific and a live probe may establish readiness but never invent an interface, operation, language, format, dialect, or permission. Dispatcher (22) may verify a declared capability only by downgrading it.

Extension activation and application selection

Selected extension registration shims add RuneConfig types to context.runes; the loader is given that explicit schema list and never scans packages. A Configurable extension registers its schema through this contract, then separately registers any runtime definition or adapter in its own domain store. Importing a package does not register it; registering a schema does not create a service. Extensions cannot introduce custom loaders, source precedence, parsers, or type= dispatch. Extensions (05) owns compatibility tiers.

The complete preauthorization Rune generation is validated before durable reconciliation. Duplicate slugs fail deterministically, and an incoming Rune cannot replace a row whose durable owner is not codex:rune. Only after those checks may one transaction refresh Rune-owned rows, retain their usage and operator-enabled state, mark absent Rune-owned policies unavailable, and publish newly admitted policies.

Realization and the writable Codex

init and init --dry-run derive the same LifecyclePlan. The real command rejects UID 0, inscribes missing anchors and inactive leaf samples, and must round-trip a generated Settings TOML through fresh validation. Marked samples are ignored until their marker is removed. bind first uses one immutable Settings/extension/Rune generation to compile declarations, then revalidates the foundation, secret presence, generations, and receipts under the lifecycle lock immediately before mutation. A content-identical reconciliation is a no-op; an indeterminate mutation keeps recovery evidence. Layout (13) owns path creation, locks, receipts, and filesystem attestation; Security (09) owns trusted executables and permissions.

The assembly pipeline is: load and validate Settings; assemble selected schemas; discover and validate Rune instances; enforce identity, domain policy, and ports; then project only exact Scribe-owned units. Downstream registries consume that generation and must not reopen the Rune filesystem.

A sanctioned live Codex writer is designed separately from current sample writing. It must stage a typed request, validate the complete staged tree as bind would, atomically rename only after that validation, and use an explicit reload signal. It has no ambient authority from Smith or Altar. Core promotion needs live HitL; a narrower preauthorization must be expressly lawful. No hot reload is delivered. State of Work records this path as Designed.

Secrets, privacy, autonomy, and projections

Codex stores only secret references (including *_secret), never values. Resolution occurs at the consumer from an explicit value, *_FILE, or declared mounted Podman secret; missing, empty, or unsafe sources fail closed. Bind preflight requires the Codex secret file to be Magus-owned with group and other permissions closed. Generated units use file form and scope mounts to the unit that needs them. Filesystem permissions do not isolate code within that unit.

Codex also sets the privacy/egress baseline (thresholds, anonymization requirement, destination and purpose eligibility, non-declassifiable categories, transformer/verifier profile, receipt lifetime, revision) and autonomy baseline. The Policy Ward rejects adaptive Phylactery state that is more permissive than Codex. Absent explicit authorization, effects require HitL or are denied; confidence does not authorize core promotion, migrations, destructive deletion, secret changes, egress broadening, host authority, excessive spending, or cross-identity memory sharing.

Vessel configuration is the source of truth. A future Tomb envelope is derived, secret-free, and cannot alter queues, network, mounts, privacy, autonomy, approval, or authority. Tomb receives no Codex mount. Security (09) owns credentials and isolation; the Tomb delivery boundary remains Designed.