Public Imports¶
The root package is the primary execution facade:
RunMode and execute_flow are resolved lazily, keeping manifest-only imports
lightweight. Calling execute_flow(manifest) without a configuration selects
live strict execution; use an explicit ExecutionConfig when planning,
observing, resuming, or binding governed stores and policies.
Facade And Authority Map¶
flowchart LR
consumer["runtime consumer"]
root["package root<br/>manifest + mode + execution"]
support["runtime facade<br/>result + mode + execution"]
model["model facade<br/>manifest, plan, trace, replay envelope"]
ontology["ontology facade<br/>IDs and semantic enums"]
verification["verification facade<br/>arbitration orchestration"]
api["api.v2<br/>application-service ASGI app"]
application["application internals"]
execution["executors + persistence"]
consumer --> root
consumer --> support
consumer --> model
consumer --> ontology
consumer --> verification
consumer --> api
root --> application --> execution
support --> application
api --> application
The root is the strongest general-purpose Python boundary. Model and ontology facades expose the durable records and vocabulary required to inspect a run. Application and execution modules implement the lifecycle and are not public extension points merely because repository tests import them.
Public Facades¶
| Need | Import surface |
|---|---|
| execution entrypoint | bijux_canon_runtime or bijux_canon_runtime.runtime |
| effective capability discovery | bijux_canon_runtime.discover_runtime_capabilities |
| execution result facade | bijux_canon_runtime.runtime |
| stable plan, trace, and replay models | bijux_canon_runtime.model |
| identifiers and semantic enums | bijux_canon_runtime.ontology |
| verification orchestration | bijux_canon_runtime.verification |
| implemented application-service HTTP schemas and ASGI app | bijux_canon_runtime.api.v2 |
| legacy compatibility HTTP schemas and partial ASGI app | bijux_canon_runtime.api.v1 |
from bijux_canon_runtime import (
RunMode,
discover_runtime_capabilities,
execute_flow,
)
from bijux_canon_runtime.application.execute_flow import ExecutionConfig
from bijux_canon_runtime.model import FlowManifest
from bijux_canon_runtime.ontology import DeterminismLevel
discover_runtime_capabilities() is the stable read-only facade for effective
configuration identities, sources, installed support, and readiness. It never
returns credential values. ExecutionConfig still has no package-root export;
the shown application import remains the operational path for legacy flow
execution configuration, and the application package is not a general
extension surface.
FlowManifest construction validates its dataclass shape. Execute through the
application boundary so contract validation, planning, determinism enforcement,
trace finalization, and persistence remain in the governed lifecycle.
Read Construction And Execution Separately¶
| Object or call | Establishes | Does not establish |
|---|---|---|
FlowManifest construction |
dataclass shape and local field invariants | resolvable datasets, admissible policy, or executable dependencies |
execute_flow in plan mode |
resolved immutable plan and execution contract | a run ID, event trace, artifacts, or side effects |
non-plan FlowRunResult |
governed result collections and optional persisted run identity | policy acceptance merely because execution completed |
ExecutionTrace |
finalized causal record | certifiability or replay equivalence |
ReplayEnvelope |
declared comparison inputs and acceptability | that required state was retained or a replay will pass |
Runtime deliberately separates completion, finalization, verification, certifiability, acceptance, persistence, resume, and replay. Consumer code should not collapse those states into a single success flag.
Model and API Boundaries¶
The stable model facade exports FlowManifest, ExecutionPlan,
ExecutionTrace, and ReplayEnvelope. The ontology facade owns typed IDs and
enums used across those models. bijux_canon_runtime.api.v2 exports the
implemented shared-application-service ASGI app and app factory. The separate
v1 facade retains legacy request and response schemas; its flow run and replay
routes return 501 Not Implemented.
Avoid importing lifecycle preparation helpers, concrete executors, DuckDB schema internals, or modules marked as internal. They implement the public facades and can change as long as the governed contracts remain intact.
Upgrade Evidence By Surface¶
| Used surface | Focused evidence |
|---|---|
root or runtime facade |
API inventory, plan-mode behavior, result semantics |
| model and ontology facades | construction, immutability, enum/ID snapshots, plan and replay identities |
| verification facade | required-gate, contradiction, arbitration, and refusal cases |
| CLI | option/exit/output contracts plus persisted store records where applicable |
| HTTP v2 | installed server, transport parity, bounded payload, OpenAPI pin/hash, and live workflow |
| HTTP v1 | legacy OpenAPI pin, probe behavior, and explicit run/replay 501 behavior |
| persisted execution | schema, causal ordering, manifest/policy/environment identity, resume and replay regression tests |
bijux_canon and agentic_flows forward the canonical package for compatibility.
New integrations should use bijux_canon_runtime; see
Compatibility Commitments for correspondence
and migration rules.