Configuration Surface¶
Runtime behavior is declared by a flow manifest, a verification policy, an execution mode, and persistence settings. The manifest and policy are JSON; the CLI does not infer missing governance from ambient defaults.
Effective workspace configuration¶
A local Runtime workspace has one versioned layout. Its manifest binds the effective configuration identity, layout identity, optional locked embedding model, CAS, DuckDB execution and durable-job authority, legacy job-import path, persistent index root, locks, staging, process state, VEX records, operations, backups, and the ordered workspace-migration ledger. Runtime-owned state must remain below the workspace root. A locked model directory may be external so one verified local cache can serve multiple isolated workspaces.
runtime.duckdb is the live authority for job lifecycle rows and their CAS
request/result identities. jobs.sqlite remains in compatible layouts only so
older job rows can be validated and imported idempotently; workers never append
new state there.
Initialize or validate the layout before admitting documents:
# Offline lexical profile: no model or network/cache access.
bijux-canon-runtime init --workspace /srv/bijux-canon/research
# Local dense and hybrid profiles: bind a verified materialized model.
bijux-canon-runtime init \
--workspace /srv/bijux-canon/research \
--model /srv/bijux-models/local-minilm-384/<locked-revision>
Add --json for a stable machine-readable result. A compatible repeat reports
unchanged without rewriting state. A partial workspace, incompatible version
or configuration, configured but missing/corrupt model, external state override, unsafe path,
or unwritable activation is refused with a typed code and remediation. A known
older layout is preflighted, backed up, and migrated with manifest-last
activation; the result names the ordered migration and rollback identity. Init
never downloads a model and never silently repairs, downgrades, or replaces
unrecognized state.
The canonical environment names begin with BIJUX_CANON_RUNTIME_. In
particular, WORKING_ROOT, DB_PATH, EMBEDDING_MODEL_PATH, and
RETRIEVAL_INDEX_PATH participate in the recorded effective configuration.
BIJUX_CANON_RUNTIME_RETRIEVAL_POLICY_ID selects one Index-owned versioned
hybrid policy and also participates in that identity. Unknown policy IDs are
refused during composition rather than interpreted as ambient parameters.
Explicit --workspace and --model init arguments take precedence over their
environment counterparts; other configured fields remain part of the exact
workspace identity.
Each executable surface resolves this configuration once. Composition, readiness, execution context, retrieval and agent adapters, inspection, and configured backup construction consume that same immutable object; adapters do not re-read environment paths during a run. Consequently, changing an environment variable after admission cannot redirect retrieval, CAS, DuckDB, jobs, model, index, or backup state for the admitted execution. A configured backup derives its database, CAS, and default backup generation root from the same workspace layout.
Readiness is capability- and profile-specific. Query it explicitly:
bijux-canon-runtime v2 ready --operation ingest --profile offline-lexical
bijux-canon-runtime v2 ready --operation retrieve --profile offline-lexical
bijux-canon-runtime v2 ready --operation research --profile local-hybrid-ann
initialized and ingest validate the workspace, exact DuckDB schema, CAS,
and write authority. For offline-lexical, index, retrieval, answer, and
research readiness do not require a model or active dense generation; each
supplied corpus or lexical artifact is verified before queueing. Dense and
hybrid readiness additionally requires the locked local model and active
generation. Submission preflight then validates archive backends, model lock,
and vector dimension. The HTTP equivalent is
GET /api/v2/ready?operation=<name>&profile=<profile>.
Inspect the complete effective product without opening environment files or state databases by hand:
The canonical JSON result, the human rendering, public Python
discover_runtime_capabilities() call, and
GET /api/v2/capabilities expose the same configuration identity and winning
source for every field, workspace/model/active-generation identities, exact
installed canonical distribution versions, operation set, parser dispositions,
accepted provider identifiers, and readiness for all seven public
capabilities. Credential values are never resolved into the report; only the
configured environment-variable reference and a boolean availability verdict
are exposed.
The current installed reasoning adapter accepts exactly credential-free and
local-recorded. Both are local and require no credential. A configured
online credential reference is configuration/readiness evidence only; it does
not manufacture an online adapter or add an identifier to the supported
provider list.
Flow manifest¶
A v1 manifest owns the identifiers and boundaries that must survive planning and replay:
| Surface | Required declarations |
|---|---|
| Identity | flow_id, tenant_id, flow_state |
| Determinism | determinism_level, replay mode and acceptability, entropy budget, optional non-determinism intent |
| Replay | minimum claim overlap and maximum contradiction delta |
| Dataset | identifier, tenant, version, hash, state, storage URI, and deprecation permission |
| Topology | agents and agent:dependency edges |
| Authority | retrieval contracts and verification gates |
Unknown top-level keys are rejected. The loader fixes spec_version to v1
and requires an explicit determinism level; default is not accepted. Dataset
tenant and flow tenant must agree, agents must be unique, and dependencies must
form a reachable directed acyclic graph.
The checked-in minimal example is
packages/bijux-canon-runtime/examples/boring/flow.json.
Verification policy¶
Live execution and replay require a policy JSON document. It declares the verification level, failure mode, randomness tolerance, arbitration rule and quorum, required evidence, maximum rule cost, rules, and the rule identifiers that cause failure or escalation. The policy fingerprint is persisted with the trace and compared during replay.
Execution modes¶
| Mode | Behavior | Persistence |
|---|---|---|
plan |
resolve and validate the execution plan without running it | none |
dry-run |
exercise the dry-run executor and produce a trace | DuckDB required |
live |
invoke runtime integrations, verify, and finalize | DuckDB and policy required |
observe |
verify a supplied observed run | Python API; store, policy, and observed run required |
unsafe |
execute through the live path with an explicit warning event | Python API requires store and policy |
The supported CLI surface is:
bijux-canon-runtime run MANIFEST --policy POLICY --db-path RUNS.duckdb
bijux-canon-runtime replay MANIFEST --policy POLICY \
--run-id RUN_ID --tenant-id TENANT --db-path RUNS.duckdb
bijux-canon-runtime inspect run RUN_ID --tenant-id TENANT --db-path RUNS.duckdb
All three accept --json; run and replay accept --strict-determinism.
Planning, dry-run, diff, failure explanation, and database validation are also
implemented as CLI commands but hidden from top-level help. unsafe-run is
present in the parser but cannot currently supply the verification policy that
runtime validation requires; do not depend on that CLI path.
Python configuration and environment¶
ExecutionConfig additionally accepts artifact and execution stores, an
ExecutionBudget, observers, an observed run, parent and child flow IDs, a
resume run ID, verification and non-determinism policies, and strictness.
Executable modes use a write store; resumed execution also needs a read store.
Set BIJUX_CANON_RUNTIME_STRICT=1 to force strict determinism. The legacy
AGENTIC_FLOWS_STRICT=1 name is also recognized. Strict environment mode
rejects dry-run and unsafe execution. The legacy AGENTIC_FLOWS_DB_PATH is
still recognized at lower precedence than the canonical database setting.