Skip to content

Public Imports

The root package is the primary execution facade:

from bijux_canon_runtime import FlowManifest, RunMode, execute_flow

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.