bijux-canon-runtime

bijux-canon-runtime is the package that decides whether and how a flow runs, what gets recorded about that run, and how a later replay should be judged. It is the authority layer for execution, replay, runtime persistence, and non-determinism governance.

If you need to understand plan versus run modes, replay acceptance, trace capture, execution-store behavior, or non-determinism policy enforcement, start here.

What This Package Takes And Produces

• takes: validated flow manifests or resolved execution plans plus explicit execution policy
• produces: flow run results, replayable traces, persisted run records, and contract failures when execution violates policy
• guarantees: runtime mode selection stays explicit, replay semantics are checked, and persisted outputs remain tied to one governed run id
• does not do: define agent behavior, own ingest or retrieval policy, or infer missing determinism from ambient state

Minimal Example

from bijux_canon_runtime import execute_flow

result = execute_flow(manifest=my_manifest)
print(result.resolved_flow.manifest.flow_id)
print(result.trace is not None)
print(result.run_id)

Expected shape:

• result.resolved_flow is always present
• result.trace is present for non-plan execution
• result.run_id is set once the runtime registers a persisted run

Package continuity

• compatibility packages: bijux-canon, agentic-flows
• preserved import roots: bijux_canon, agentic_flows
• preserved commands: bijux-canon, agentic-flows
• alias expectation: the preserved names above should resolve to the same runtime API and command behavior as bijux-canon-runtime
• family-root alias handbook: bijux-canon alias handbook
• canonical migration guide: Migration guidance
• retired repository target: https://github.com/bijux/agentic-flows (see Repository consolidation notes)

What this package owns

• flow execution authority
• replay and acceptability semantics
• trace capture, runtime persistence, and execution-store behavior
• package-local CLI and API boundaries

What this package does not own

• agent composition policy
• ingest or index domain ownership
• repository tooling and release support

Source map

• src/bijux_canon_runtime/model for durable runtime models
• src/bijux_canon_runtime/runtime for execution engines and lifecycle logic
• src/bijux_canon_runtime/application for orchestration and replay coordination
• src/bijux_canon_runtime/observability for trace capture, analysis, and storage support
• src/bijux_canon_runtime/interfaces and src/bijux_canon_runtime/api for boundaries
• tests and examples for executable expectations and teaching material

Read this next

• Package guide
• Ownership boundary
• Architecture overview
• Interface contracts
• Release and versioning
• Compatibility packages
• Changelog

Primary entrypoint

• console script: bijux-canon-runtime

Release Readiness

• release line prepared for publish: 0.3.9
• release date: 2026-07-04
• package changelog: CHANGELOG.md

Changelog

All notable changes to bijux-canon-runtime are documented here.

Historical release entries below preserve the wording that shipped with the tagged release, including legacy distribution naming where applicable.

[0.3.9] - 2026-07-04

Changed

• Runtime release metadata now advertises the numbered handbook route and the synchronized 0.3.9 publish line.
• Internal canon dependency floors now accept the 0.3.9.dev0 package family during coordinated local release validation.

Fixed

• Generated docs badges and README release-readiness guidance now resolve to the canonical runtime handbook route instead of the stale short path.

[0.3.8] - 2026-06-28

Changed

• Runtime examples and README guidance now describe governed execution inputs, outputs, and publish readiness for the 0.3.8 line.
• Runtime compatibility documentation now names preserved distribution, import, and command aliases as parity surfaces that must keep resolving to the same runtime behavior.
• Flow execution models and CLI configuration handling now align more strictly with manifest-driven runtime contracts.
• Runtime continuity guidance now treats both agentic-flows and bijux-canon as real compatibility aliases that resolve to the same runtime execution surface.

Fixed

• Default execution settings are now valid by construction.
• Internal canon dependency floors now require the synchronized 0.3.8 package line instead of the stale 0.3.7 floor.

[0.3.7] - 2026-04-21

Changed

• Updated package README link text to readable markdown hyperlinks and aligned handbook navigation targets with canonical bijux-canon routes.

[0.3.6] - 2026-04-20

Changed

• Finalized the 0.3.6 package release entry and aligned release-readiness notes in the package README.

[0.3.5] - 2026-04-19

Changed

• Runtime schema-hash packaging and stability-test guidance now reference canonical API paths under apis/bijux-canon-runtime/v1.
• Package contract docs and shared handbook links now resolve canonical runtime handbook routes without numbered slug targets.

[0.3.4] - 2026-04-11

Fixed

• Runtime release metadata now falls back to 0.3.4 when tag metadata is not available during local validation.
• Internal canon package dependency floors now require the synchronized 0.3.4 package line.
• Package README badge links now follow the shared badge catalog and point to the exact GHCR package pages used for published runtime bundles.

[0.3.2] - 2026-04-10

Fixed

• Runtime release metadata now falls back to 0.3.2 when tag metadata is not available during local validation.
• Internal canon package dependency floors now require the synchronized 0.3.2 package line.

[0.3.0] - 2026-04-05

Added

• Package-local documentation now explains execution authority, replay semantics, operator boundaries, API contract testing, and example datasets in clearer human-facing language.
• Runtime now has focused package tests for command mapping, execution persistence, canonical package-version lookup, and identifier exports.

Changed

• The package was realigned under the canonical bijux-canon-runtime identity, with runtime models, contracts, ontology, observability, interfaces, and API surfaces renamed around durable ownership.
• Execution orchestration was decomposed into smaller modules for flow preparation, step execution, run recording, replay analysis, policy handling, and persistence support.
• Runtime command handling, RunMode ownership, and non-determinism lifecycle plumbing were consolidated into clearer runtime-facing modules.
• Planner behavior now uses normalized dependency ordering and canonical package version discovery for runtime metadata.
• Flow preparation, execution recording, replay analysis, tool-event recording, verification arbitration, and persistence support were split into smaller modules so runtime behavior is easier to reason about and maintain.
• PyPI metadata, search keywords, and project URLs now make the canonical runtime package easier to discover from package indexes and Bijux-owned docs.
• The package README now uses PyPI-safe badge and link targets, and it points legacy agentic-flows users to the canonical migration path and retired repository guidance.
• Package-local PyPI publication guidance is now checked in and shipped with the source distribution so runtime release expectations stay durable.
• Source distributions now publish package-local ignore rules instead of a generic repo-level .gitignore.

Fixed

• Duplicate dependency declarations are now rejected during planning.
• Runtime metadata and tests now align with canonical package names and the bijux-cli 0.3.3 line.
• Root package quality gates were repaired after the refactor series.
• Replay and storage typing, readiness responses, and verification-policy override handling were tightened during the runtime refactor series.
• Release artifacts now ship the repository LICENSE file so downstream consumers receive the license text with the published package.

[0.1.0] – 2025-01-21

Added

• Core runtime
  • Deterministic execution lifecycle with planning, execution, and finalization phases.
  • Execution modes: plan, dry-run, live, observe, and unsafe.
  • Strict determinism guardrails with explicit seed and environment fingerprints.
• Non-determinism governance
  • Declared non-determinism intent model and policy validation.
  • Entropy budgeting with enforcement, exhaustion semantics, and replay analysis.
  • Determinism profiles with structured replay metadata.
• Replay and audit
  • Replay modes (strict/bounded/observational) and acceptability classifications.
  • Trace diffing, replay envelopes, and deterministic replay validation.
  • Observability capture for events, artifacts, evidence, and entropy usage.
• Persistence
  • DuckDB execution store with schema contract enforcement and migrations.
  • Execution schema, replay envelopes, checkpoints, and trace storage.
• CLI + API surface
  • CLI commands for planning, running, replaying, inspecting, and diffing runs.
  • OpenAPI schema for the HTTP surface with schema hash stability checks.
• Policies and verification
  • Verification policy and arbitration plumbing for reasoning and evidence checks.
  • Failure taxonomy with deterministic error classes.
• Docs and examples
  • Determinism/non-determinism contract docs and storage model guidance.
  • Examples for deterministic and replay behavior.
• Quality gates
  • Makefile orchestration for tests, linting, docs, API checks, SBOM, and citation outputs.