Bijux Core¶

bijux-core is the release and verification workspace for the bijux command runtime and the local-first bijux-dag toolchain.

Both products make operational authority visible. bijux resolves a command to one owner and preserves streams and exit semantics. bijux-dag turns a graph into a validated plan, executes it through an explicit backend, and retains the evidence needed to inspect, compare, or replay the result.

The same repository carries private verification surfaces that test release claims against code, schemas, fixtures, and generated evidence. Those maintainer tools validate the products; they are not hidden product APIs.

Two executables, two result models. bijux resolves one command and preserves process semantics. bijux-dag executes one graph and retains an integrity-bearing run record. Repository and maintainer material governs ownership and proof around those products.

Repository

Package boundaries, dependency direction, compatibility, release policy, and shared ownership.

CLI

Command semantics, routing, plugins, configuration, state, REPL behavior, and Python distribution.

DAG

Graph admission, planning, scheduling, backends, retained evidence, cache, comparison, and replay.

Maintainer

Toolchains, repository gates, evidence production, security checks, automation, release, and incident response.

Open the repository handbook Open the CLI handbook Open the DAG handbook Open the maintainer handbook

Released Product Boundary¶

Surface	Delivery	What you can rely on today
`bijux`	Rust crate, PyPI distribution, release bundles	the visible `bijux --help` runtime, including apps, plugins, layered config, REPL, diagnostics, history, and memory
`bijux-dag`	Rust crates and release bundles	the visible `bijux-dag --help` local DAG surface for validate, plan, run, replay, inspect, compare, cache, and verify workflows
maintainer tooling	repository-internal only	contributor and release workflows, not end-user product API

bijux-dag is intentionally honest about its current boundary. The stable lane is local-first. Experimental, simulated, and maintainer-only routes exist in the repository, but they are not presented here as the default product story.

Operational Model¶

flowchart LR
    intent["operator intent"]
    admission["parse · validate · resolve policy"]
    work["owned execution boundary"]
    result["process result or retained run"]
    integrity["diagnose · verify · compare"]
    decision["bounded decision"]

    intent --> admission --> work --> result --> integrity --> decision
    admission -->|"unsupported or unsafe"| refuse["refuse before effects"]
    integrity -->|"missing or inconsistent"| quarantine["preserve and investigate"]

Admission prevents unsupported work from becoming effects. Integrity checks prevent an incomplete or corrupted result from becoming trusted evidence. The CLI and DAG runtimes implement different versions of that lifecycle, while the maintainer control plane applies the same discipline to tests, documentation, packages, and releases.

Two Execution Paths¶

flowchart TB
    operator["operator or automation"]

    subgraph cli_path["Command runtime"]
        cli_input["CLI, REPL, or Python launcher"]
        cli_route["normalize config and resolve route"]
        cli_run["built-in, mounted app, or plugin execution"]
        cli_result["stdout · stderr · exit status"]
    end

    subgraph dag_path["Workflow runtime"]
        dag_input["graph source"]
        dag_plan["validate, canonicalize, and plan"]
        dag_run["backend execution"]
        dag_result["run directory · traces · artifacts · identity"]
    end

    operator --> cli_input --> cli_route --> cli_run --> cli_result
    operator --> dag_input --> dag_plan --> dag_run --> dag_result

The paths deliberately end differently. A CLI command returns process-facing streams and status. A DAG run also leaves an integrity-bearing record because replay, comparison, and post-run verification depend on durable evidence.

Trust Properties¶

Property	What the repository preserves	Where to verify it
owned command routing	aliases normalize to canonical routes; delegated processes retain native streams and exit status	CLI execution model
explicit configuration	layered values can be traced to their source and secret-like fields are redacted by default	CLI configuration guide
deterministic graph meaning	canonical graph and plan identities are separate from runtime and artifact identity	DAG reproducibility model
failure evidence	failed, skipped, blocked, cancelled, cached, and successful work remain distinguishable	DAG failure recovery
honest isolation	enforced checks are separated from host, container, scheduler, and cluster assumptions	Execution security
release traceability	publication boundaries and required evidence are machine-readable and contract-tested	Repository release operations

Choose By Responsibility¶

If you want to...	Open this handbook
run `bijux`, mount apps, work with plugins, or debug runtime behavior	CLI Handbook
author DAGs, run them locally, inspect artifacts, or replay a run	DAG Handbook
understand what the repository publishes, how crates divide work, or how release boundaries are enforced	Repository Handbook
work on repository gates, release proof, or documentation and automation pipelines	Maintainer Handbook

First Operational Journeys¶

To automate bijux, begin with the CLI surface, then use the configuration guide and diagnostics guide.
To execute a real graph, follow the first-run tutorial, then read the run evidence layout.
To diagnose a failed run, preserve it and follow observability and diagnostics before attempting recovery.
To evaluate a release or repository change, start with testing and validation and the maintainer gate map.

Evidence Strength¶

flowchart LR
    request["command or graph request"]
    contract["validated route, schema,<br/>graph, or policy"]
    execution["owned execution"]
    outcome["streams, status,<br/>state, or run directory"]
    verification["diagnostics, integrity,<br/>replay, or gate"]
    decision["bounded operational decision"]

    request --> contract --> execution --> outcome --> verification --> decision
    verification -->|"missing or inconsistent evidence"| refuse["refuse or narrow the claim"]

Outcome	Trust it for	Do not infer
successful `bijux` result	that one route completed under the observed state	that delegated code was isolated or all plugins are healthy
accepted DAG validation	that graph syntax and semantics passed the active contract	that any node executed
finalized run directory	that execution reached a retained terminal result	that files remain intact or domain output is correct
strict verification	that retained structural and integrity contracts pass	scientific, business, or workload correctness
replay or semantic comparison	the recorded identity and difference classification	equivalence outside the selected evidence and environment
green maintainer gate	the exact selected suite at the recorded revision	omitted platforms, external services, or broader release claims

Evidence becomes stronger only when the next authority is present. A process status establishes completion, retained state establishes what was recorded, integrity establishes whether that state is intact, and replay or comparison establishes only the equivalence claim encoded by its selected contract.

The v0.4.0 Release Notes define the current DAG release. Future Direction is non-binding direction; if it conflicts with the release boundary, the narrower shipped claim wins.