Oneiric

Explainable component resolution, lifecycle management, and remote delivery for Python 3.14+ runtimes

Oneiric is a standalone resolver and runtime foundation. Register adapters, services, tasks, events, workflows, and actions; explain selection decisions; manage lifecycle transitions; and hydrate capabilities from remote manifests.

Quick Links

• Capabilities
• Domains and built-ins
• Quick start
• Configuration
• CLI map
• Documentation

Quality checks

Use Crackerjack for the repository quality gate; the commands are documented below in Development.

Capabilities

• Resolution: deterministic selection by explicit configuration, stack, priority, and registration order, with explainable and shadowed candidates.
• Lifecycle: activation, health checks, binding, cleanup, rollback, and safe provider swaps through LifecycleManager.
• Runtime orchestration: watchers, remote refresh, workflow checkpoints, event dispatch, pause/drain supervision, and optional scheduler callbacks.
• Remote delivery: YAML/JSON manifests with optional digest and signature verification, canonical packaging, and per-domain registration.
• Operations: structured logging, runtime health and telemetry snapshots, notification routing, plugin discovery, and secrets-cache management.

Domains and built-ins

The resolver exposes six registered domains. Each domain uses the same selection and lifecycle model, while domain-specific bridges provide the execution behavior.

Built-in action keys include compression.encode, compression.hash, compression.stream, workflow.audit, workflow.orchestrate, workflow.notify, workflow.retry, http.fetch, event.dispatch, and debug.console. Use oneiric --demo list --domain action to inspect the complete registry.

Runtime and operations

• Watchers reload selections using watchfiles or polling; serverless profiles can disable remote refresh and watchers.
• RuntimeOrchestrator coordinates remote sync, event dispatch, workflow execution, checkpoints, notifications, and the optional scheduler HTTP server for Cloud Tasks callbacks.
• DomainActivityStore records pause/drain state, while the supervisor keeps inactive components from accepting work.
• Runtime health, telemetry, lifecycle, activity, and workflow checkpoint artifacts are written beneath the configured cache directory.
• oneiric health, status, activity, remote-status, and supervisor-info expose operator-facing state.

Configuration

load_settings() layers project and user configuration for the selected project_name. From lowest to highest precedence, it checks:

1. Code defaults
2. settings/<project_name>.yaml or .yml at the project root
3. settings/local.yaml at the project root
4. ${XDG_CONFIG_HOME:-~/.config}/<project_name>/config.yaml
5. ${XDG_CONFIG_HOME:-~/.config}/<project_name>/local.yaml
6. Environment overrides in the form <PROJECT_NAME>_<SETTING>__<FIELD>

For example, a project using project_name="oneiric" checks ~/.config/oneiric/config.yaml and ~/.config/oneiric/local.yaml when XDG_CONFIG_HOME is not set. Set XDG_CONFIG_HOME to relocate the user configuration root. Missing layered files are ignored. Project paths are normally anchored at the installed package/project root; an explicit project_root= can be supplied when embedding Oneiric elsewhere.

An explicit path= argument to load_settings() or the corresponding <PROJECT_NAME>_CONFIG environment variable is applied last and takes precedence over all layered files. The CLI exposes the same override through --config.

Quick start

For repository development:

uv sync --group dev
uv run oneiric --demo list --domain adapter
uv run oneiric --demo list --domain action
uv run oneiric --demo explain demo --domain adapter
uv run oneiric --demo health --probe --json

Inspect runtime plans without starting the long-running loop:

uv run oneiric --demo orchestrate --print-dag --inspect-json
uv run oneiric --demo orchestrate --events --inspect-json
uv run oneiric workflow plan --workflow <workflow-key> --json

Run a manifest sync, event, workflow, or action explicitly:

uv run oneiric remote-sync --manifest docs/sample_remote_manifest.yaml
uv run oneiric event emit demo.event --payload '{"source":"cli"}' --json
uv run oneiric workflow run <workflow-key> --context '{"request_id":"demo"}' --json
uv run oneiric action-invoke compression.encode --payload '{"text":"hello"}' --json

Start the orchestrator when a long-running process is required:

uv run oneiric start \
  --manifest docs/sample_remote_manifest.yaml \
  --refresh-interval 120 \
  --no-http
uv run oneiric process-status
uv run oneiric health --probe --json
uv run oneiric stop

Serverless profile

The serverless profile is intended for deployments such as Cloud Run. It can be selected through the environment or CLI and combined with explicit remote/HTTP settings:

uv run oneiric manifest pack \
  --input docs/sample_remote_manifest.yaml \
  --output build/serverless_manifest.json

ONEIRIC_PROFILE=serverless uv run oneiric supervisor-info
ONEIRIC_PROFILE=serverless uv run oneiric health --probe --json
ONEIRIC_PROFILE=serverless uv run oneiric start --no-remote --no-http

Deployment details are in docs/deployment/CLOUD_RUN_BUILD.md.

CLI map

The installed console script is oneiric. Use oneiric --help for the complete command surface; uv run oneiric is the repository-local form.

• Inspect: list, status, explain, health, plugins, and supervisor-info expose registrations, resolution decisions, lifecycle state, and runtime health.
• Manage lifecycle: swap, pause, drain, start, stop, and process-status control providers and the background orchestrator.
• Run work: event emit, workflow plan, workflow run, workflow enqueue, and action-invoke exercise runtime capabilities.
• Deliver manifests: remote-sync, remote-status, and manifest pack handle remote inputs and cached synchronization state.
• Operate integrations: plugins, secrets, shell, and load-test provide discovery, secret-cache operations, interactive administration, and runtime load testing.

Bodai Integration

When installed alongside the Bodai ecosystem, Oneiric supplies the shared resolver, lifecycle manager, and adapter catalog used by the other Bodai components. The standalone install is identical — Bodai does not impose special-case overrides on Oneiric's domain model; consumers wire the same load_settings() and adapter registries they would in any other Python application.

Observability and state

Oneiric uses structured logging and writes runtime artifacts below the configured cache_dir (the default setting is .oneiric_cache). The runtime surface includes:

• runtime_health.json for watcher, remote, supervisor, and orchestrator state
• runtime_telemetry.json for event and workflow execution summaries
• lifecycle_status.json for provider lifecycle snapshots
• domain_activity.sqlite for pause/drain state
• workflow_checkpoints.sqlite for resumable workflow execution when enabled

See docs/OBSERVABILITY_GUIDE.md for logging, telemetry, and artifact-handling details. workflow.notify routes messages through the configured messaging adapter when notification delivery is enabled.

Remote manifests

Remote manifests can describe adapters, services, tasks, events, workflows, and actions. Oneiric can load them from local paths or supported URIs, validate optional signatures and digests, register their domains, and refresh them on a schedule.

uv run oneiric manifest pack \
  --input docs/sample_remote_manifest.yaml \
  --output build/manifest.json
uv run oneiric remote-sync --manifest docs/sample_remote_manifest.yaml
uv run oneiric remote-status

See docs/REMOTE_MANIFEST_SCHEMA.md and docs/SIGNATURE_VERIFICATION.md for the manifest and verification contracts.

Documentation

• Documentation index — navigation through architecture, operations, examples, and reference material.
• CLI reference — command options and operator flows.
• Package map — module layout and extension points.
• Custom adapters — registration and resolver extension patterns.
• XDG configuration — configuration layers and interactive settings inspection.
• Observability guide — logging and runtime artifacts.
• Deployment guides and runbooks — Cloud Run, systemd, maintenance, and troubleshooting.

Development

# Fast repository checks
python -m crackerjack run --fast

# Comprehensive checks
python -m crackerjack run --comp

# Full quality run, including tests
python -m crackerjack run --run-tests

Run the repository-local gate after changing runtime, adapter, action, or CLI behavior. Add or update tests and documentation with the same change.

Contributing

1. Review the relevant architecture and operator documentation.
2. Run python -m crackerjack run --run-tests before opening a PR.
3. Add or update tests for runtime features, adapters, actions, or CLI flows.
4. Update the README or linked documentation when the operator surface changes.

License and support

• License: BSD-3-Clause (see LICENSE).
• Issues: https://github.com/lesleslie/oneiric/issues
• Docs: Start with docs/README.md.