Metadata-Version: 2.4
Name: bijux-canon-runtime
Version: 0.3.6
Summary: Governed runtime execution, replay policy, and auditable non-determinism for the bijux-canon package family from Bijux.
Project-URL: Homepage, https://bijux.io/bijux-canon/bijux-canon-runtime/
Project-URL: Website, https://bijux.io/
Project-URL: Documentation, https://bijux.io/bijux-canon/bijux-canon-runtime/
Project-URL: Repository, https://github.com/bijux/bijux-canon
Project-URL: Issues, https://github.com/bijux/bijux-canon/issues
Project-URL: Changelog, https://github.com/bijux/bijux-canon/blob/main/packages/bijux-canon-runtime/CHANGELOG.md
Project-URL: Security, https://github.com/bijux/bijux-canon/blob/main/SECURITY.md
Project-URL: Funding, https://github.com/sponsors/bijux
Project-URL: PackageMap, https://bijux.io/bijux-canon/01-bijux-canon/foundation/package-map/
Project-URL: CompatibilityGuide, https://bijux.io/bijux-canon/08-compat-packages/migration/migration-guidance/
Author-email: Bijan Mousavi <bijan@bijux.io>
Maintainer-email: Bijan Mousavi <bijan@bijux.io>
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agents,audit,bijux,bijux-canon,bijux.io,contract-first,execution,governance,non-determinism,replay,reproducibility,workflow-runtime
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: <4,>=3.11
Requires-Dist: bijux-canon-agent<0.4.0,>=0.3.4
Requires-Dist: bijux-canon-index<0.4.0,>=0.3.4
Requires-Dist: bijux-canon-ingest<0.4.0,>=0.3.4
Requires-Dist: bijux-canon-reason<0.4.0,>=0.3.4
Requires-Dist: bijux-cli<0.4.0,>=0.3.4
Requires-Dist: duckdb<2.0.0,>=1.1.3
Requires-Dist: pydantic<3.0.0,>=2.0.2
Provides-Extra: api
Requires-Dist: fastapi<1.0,>=0.128; extra == 'api'
Requires-Dist: starlette<2.0,>=0.46; extra == 'api'
Requires-Dist: uvicorn<1.0,>=0.32; extra == 'api'
Provides-Extra: dev
Requires-Dist: bandit<2.0,>=1.7.10; extra == 'dev'
Requires-Dist: build<2.0,>=1.0.3; extra == 'dev'
Requires-Dist: codespell<3.0,>=2.3.0; extra == 'dev'
Requires-Dist: deptry<1.0,>=0.10.0; extra == 'dev'
Requires-Dist: fastapi<1.0,>=0.128; extra == 'dev'
Requires-Dist: httpx<1.0,>=0.27.0; extra == 'dev'
Requires-Dist: hypothesis-jsonschema<1.0,>=0.23.0; extra == 'dev'
Requires-Dist: hypothesis<7.0,>=6.103.0; extra == 'dev'
Requires-Dist: interrogate<2.0,>=1.7.0; extra == 'dev'
Requires-Dist: mkdocs-material<10.0,>=9.5.39; extra == 'dev'
Requires-Dist: mkdocs<2.0,>=1.6.1; extra == 'dev'
Requires-Dist: mypy<2.0,>=1.11.2; extra == 'dev'
Requires-Dist: pexpect<5.0,>=4.8.0; extra == 'dev'
Requires-Dist: pip-audit<3.0,>=2.7.3; extra == 'dev'
Requires-Dist: pydocstyle<7.0,>=6.2.1; extra == 'dev'
Requires-Dist: pyfakefs>=5.9.0; extra == 'dev'
Requires-Dist: pytest-asyncio<2.0,>=1.0.0; extra == 'dev'
Requires-Dist: pytest-benchmark<6.0,>=4.0.0; extra == 'dev'
Requires-Dist: pytest-cov<8.0,>=6.2.1; extra == 'dev'
Requires-Dist: pytest-mock<4.0,>=3.14.1; extra == 'dev'
Requires-Dist: pytest-rerunfailures<17.0,>=13.0; extra == 'dev'
Requires-Dist: pytest-timeout<3.0,>=2.4.0; extra == 'dev'
Requires-Dist: pytest<10.0,>=9.0.3; extra == 'dev'
Requires-Dist: pyyaml<7.0,>=6.0; extra == 'dev'
Requires-Dist: radon>=6.0.0; extra == 'dev'
Requires-Dist: ruff<1.0,>=0.6.8; extra == 'dev'
Requires-Dist: starlette<2.0,>=0.46; extra == 'dev'
Requires-Dist: types-colorama<1.0,>=0.0.14; extra == 'dev'
Requires-Dist: types-orjson<4.0,>=3.6.0; extra == 'dev'
Requires-Dist: types-pexpect<5.0,>=4.9.0; extra == 'dev'
Requires-Dist: types-psutil<8.0,>=6.0.0; extra == 'dev'
Requires-Dist: types-pyyaml<7.0,>=6.0.12; extra == 'dev'
Requires-Dist: typing-extensions<5.0,>=4.5.0; extra == 'dev'
Requires-Dist: vulture<3.0,>=2.7; extra == 'dev'
Description-Content-Type: text/markdown

# bijux-canon-runtime


[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)](https://pypi.org/project/bijux-canon-runtime/)
[![Typing: typed](https://img.shields.io/badge/typing-typed%20(PEP%20561)-0A7BBB)](https://pypi.org/project/bijux-canon-runtime/)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-0F766E)](https://github.com/bijux/bijux-canon/blob/main/LICENSE)
[![CI Status](https://github.com/bijux/bijux-canon/actions/workflows/verify.yml/badge.svg)](https://github.com/bijux/bijux-canon/actions/workflows/verify.yml)
[![GitHub Repository](https://img.shields.io/badge/github-bijux%2Fbijux--canon-181717?logo=github)](https://github.com/bijux/bijux-canon)

[![bijux-canon-runtime](https://img.shields.io/pypi/v/bijux-canon-runtime?label=runtime&logo=pypi)](https://pypi.org/project/bijux-canon-runtime/)
[![bijux-canon-agent](https://img.shields.io/pypi/v/bijux-canon-agent?label=agent&logo=pypi)](https://pypi.org/project/bijux-canon-agent/)
[![bijux-canon-ingest](https://img.shields.io/pypi/v/bijux-canon-ingest?label=ingest&logo=pypi)](https://pypi.org/project/bijux-canon-ingest/)
[![bijux-canon-reason](https://img.shields.io/pypi/v/bijux-canon-reason?label=reason&logo=pypi)](https://pypi.org/project/bijux-canon-reason/)
[![bijux-canon-index](https://img.shields.io/pypi/v/bijux-canon-index?label=index&logo=pypi)](https://pypi.org/project/bijux-canon-index/)
[![agentic-flows](https://img.shields.io/pypi/v/agentic-flows?label=agentic--flows&logo=pypi)](https://pypi.org/project/agentic-flows/)
[![bijux-agent](https://img.shields.io/pypi/v/bijux-agent?label=bijux--agent&logo=pypi)](https://pypi.org/project/bijux-agent/)
[![bijux-rag](https://img.shields.io/pypi/v/bijux-rag?label=bijux--rag&logo=pypi)](https://pypi.org/project/bijux-rag/)
[![bijux-rar](https://img.shields.io/pypi/v/bijux-rar?label=bijux--rar&logo=pypi)](https://pypi.org/project/bijux-rar/)
[![bijux-vex](https://img.shields.io/pypi/v/bijux-vex?label=bijux--vex&logo=pypi)](https://pypi.org/project/bijux-vex/)

[![bijux-canon-runtime](https://img.shields.io/badge/runtime-ghcr-181717?logo=github)](https://github.com/bijux/bijux-canon/pkgs/container/bijux-canon%2Fbijux-canon-runtime)
[![bijux-canon-agent](https://img.shields.io/badge/agent-ghcr-181717?logo=github)](https://github.com/bijux/bijux-canon/pkgs/container/bijux-canon%2Fbijux-canon-agent)
[![bijux-canon-ingest](https://img.shields.io/badge/ingest-ghcr-181717?logo=github)](https://github.com/bijux/bijux-canon/pkgs/container/bijux-canon%2Fbijux-canon-ingest)
[![bijux-canon-reason](https://img.shields.io/badge/reason-ghcr-181717?logo=github)](https://github.com/bijux/bijux-canon/pkgs/container/bijux-canon%2Fbijux-canon-reason)
[![bijux-canon-index](https://img.shields.io/badge/index-ghcr-181717?logo=github)](https://github.com/bijux/bijux-canon/pkgs/container/bijux-canon%2Fbijux-canon-index)
[![agentic-flows](https://img.shields.io/badge/agentic--flows-ghcr-181717?logo=github)](https://github.com/bijux/bijux-canon/pkgs/container/bijux-canon%2Fagentic-flows)
[![bijux-agent](https://img.shields.io/badge/bijux--agent-ghcr-181717?logo=github)](https://github.com/bijux/bijux-canon/pkgs/container/bijux-canon%2Fbijux-agent)
[![bijux-rag](https://img.shields.io/badge/bijux--rag-ghcr-181717?logo=github)](https://github.com/bijux/bijux-canon/pkgs/container/bijux-canon%2Fbijux-rag)
[![bijux-rar](https://img.shields.io/badge/bijux--rar-ghcr-181717?logo=github)](https://github.com/bijux/bijux-canon/pkgs/container/bijux-canon%2Fbijux-rar)
[![bijux-vex](https://img.shields.io/badge/bijux--vex-ghcr-181717?logo=github)](https://github.com/bijux/bijux-canon/pkgs/container/bijux-canon%2Fbijux-vex)

[![bijux-canon-runtime docs](https://img.shields.io/badge/docs-runtime-2563EB?logo=materialformkdocs&logoColor=white)](https://bijux.io/bijux-canon/bijux-canon-runtime/)
[![bijux-canon-agent docs](https://img.shields.io/badge/docs-agent-2563EB?logo=materialformkdocs&logoColor=white)](https://bijux.io/bijux-canon/bijux-canon-agent/)
[![bijux-canon-ingest docs](https://img.shields.io/badge/docs-ingest-2563EB?logo=materialformkdocs&logoColor=white)](https://bijux.io/bijux-canon/bijux-canon-ingest/)
[![bijux-canon-reason docs](https://img.shields.io/badge/docs-reason-2563EB?logo=materialformkdocs&logoColor=white)](https://bijux.io/bijux-canon/bijux-canon-reason/)
[![bijux-canon-index docs](https://img.shields.io/badge/docs-index-2563EB?logo=materialformkdocs&logoColor=white)](https://bijux.io/bijux-canon/bijux-canon-index/)


`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.

## Legacy continuity

- compatibility package: [`agentic-flows`](https://pypi.org/project/agentic-flows/)
- legacy import root: `agentic_flows`
- legacy command: `agentic-flows`
- canonical migration guide: <https://bijux.io/bijux-canon/08-compat-packages/migration/migration-guidance/>
- retired repository target: <https://github.com/bijux/agentic-flows>

## 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`](https://github.com/bijux/bijux-canon/tree/main/packages/bijux-canon-runtime/src/bijux_canon_runtime/model) for durable runtime models
- [`src/bijux_canon_runtime/runtime`](https://github.com/bijux/bijux-canon/tree/main/packages/bijux-canon-runtime/src/bijux_canon_runtime/runtime) for execution engines and lifecycle logic
- [`src/bijux_canon_runtime/application`](https://github.com/bijux/bijux-canon/tree/main/packages/bijux-canon-runtime/src/bijux_canon_runtime/application) for orchestration and replay coordination
- [`src/bijux_canon_runtime/observability`](https://github.com/bijux/bijux-canon/tree/main/packages/bijux-canon-runtime/src/bijux_canon_runtime/observability) for trace capture, analysis, and storage support
- [`src/bijux_canon_runtime/interfaces`](https://github.com/bijux/bijux-canon/tree/main/packages/bijux-canon-runtime/src/bijux_canon_runtime/interfaces) and [`src/bijux_canon_runtime/api`](https://github.com/bijux/bijux-canon/tree/main/packages/bijux-canon-runtime/src/bijux_canon_runtime/api) for boundaries
- [`tests`](https://github.com/bijux/bijux-canon/tree/main/packages/bijux-canon-runtime/tests) and [`examples`](https://github.com/bijux/bijux-canon/tree/main/packages/bijux-canon-runtime/examples) for executable expectations and teaching material

## Read this next

- [Package guide](https://bijux.io/bijux-canon/bijux-canon-runtime/)
- [Ownership boundary](https://bijux.io/bijux-canon/bijux-canon-runtime/foundation/ownership-boundary/)
- [Architecture overview](https://bijux.io/bijux-canon/bijux-canon-runtime/architecture/)
- [Interface contracts](https://bijux.io/bijux-canon/bijux-canon-runtime/interfaces/)
- [Release and versioning](https://bijux.io/bijux-canon/bijux-canon-runtime/operations/release-and-versioning/)
- [Compatibility packages](https://bijux.io/bijux-canon/08-compat-packages/)
- [Changelog](https://github.com/bijux/bijux-canon/blob/main/packages/bijux-canon-runtime/CHANGELOG.md)

## Primary entrypoint

- console script: `bijux-canon-runtime`

## Release Readiness

- upcoming release line: `0.3.6`
- package changelog: [`CHANGELOG.md`](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.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.

