Metadata-Version: 2.4
Name: bijux-canon-runtime
Version: 0.3.9
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/06-bijux-canon-runtime/
Project-URL: Website, https://bijux.io/
Project-URL: Documentation, https://bijux.io/bijux-canon/06-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.9.dev0
Requires-Dist: bijux-canon-index<0.4.0,>=0.3.9.dev0
Requires-Dist: bijux-canon-ingest<0.4.0,>=0.3.9.dev0
Requires-Dist: bijux-canon-reason<0.4.0,>=0.3.9.dev0
Requires-Dist: bijux-cli<0.4.0,>=0.3.6
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,>=1.3.1; 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: httpx2<3.0,>=2.5.0; 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<3.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,>=1.3.1; 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

<!-- bijux-canon-badges:generated:start -->
[![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?branch=main)](https://github.com/bijux/bijux-canon/actions/workflows/verify.yml?query=branch%3Amain)
[![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](https://img.shields.io/pypi/v/bijux-canon?label=bijux--canon&logo=pypi)](https://pypi.org/project/bijux-canon/)
[![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](https://img.shields.io/badge/bijux--canon-ghcr-181717?logo=github)](https://github.com/bijux/bijux-canon/pkgs/container/bijux-canon%2Fbijux-canon)
[![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/06-bijux-canon-runtime/)
[![bijux-canon-agent docs](https://img.shields.io/badge/docs-agent-2563EB?logo=materialformkdocs&logoColor=white)](https://bijux.io/bijux-canon/05-bijux-canon-agent/)
[![bijux-canon-ingest docs](https://img.shields.io/badge/docs-ingest-2563EB?logo=materialformkdocs&logoColor=white)](https://bijux.io/bijux-canon/02-bijux-canon-ingest/)
[![bijux-canon-reason docs](https://img.shields.io/badge/docs-reason-2563EB?logo=materialformkdocs&logoColor=white)](https://bijux.io/bijux-canon/04-bijux-canon-reason/)
[![bijux-canon-index docs](https://img.shields.io/badge/docs-index-2563EB?logo=materialformkdocs&logoColor=white)](https://bijux.io/bijux-canon/03-bijux-canon-index/)
<!-- bijux-canon-badges:generated:end -->

`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

```python
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`](https://pypi.org/project/bijux-canon/), [`agentic-flows`](https://pypi.org/project/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](https://bijux.io/bijux-canon/08-compat-packages/catalog/bijux-canon/)
- canonical migration guide: [Migration guidance](https://bijux.io/bijux-canon/08-compat-packages/migration/migration-guidance/)
- retired repository target: [https://github.com/bijux/agentic-flows](https://github.com/bijux/agentic-flows) (see [Repository consolidation notes](https://bijux.io/bijux-canon/08-compat-packages/migration/repository-consolidation/))

## 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/06-bijux-canon-runtime/)
- [Ownership boundary](https://bijux.io/bijux-canon/06-bijux-canon-runtime/foundation/ownership-boundary/)
- [Architecture overview](https://bijux.io/bijux-canon/06-bijux-canon-runtime/architecture/)
- [Interface contracts](https://bijux.io/bijux-canon/06-bijux-canon-runtime/interfaces/)
- [Release and versioning](https://bijux.io/bijux-canon/06-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

- release line prepared for publish: `0.3.9`
- release date: `2026-07-04`
- package changelog: [`CHANGELOG.md`](CHANGELOG.md)
# Changelog  
<a id="top"></a>  

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.

<a id="v0-3-0"></a>  
## [0.3.0] - 2026-04-05  

<!-- release-v0-3-0 start -->
### 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.
<!-- release-v0-3-0 end -->  

---  

<!-- release start -->  

<a id="v0-1-0"></a>  
## [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.


<!-- release end -->
