bijux-dag-core 0.4.1

Deterministic DAG kernel for graph parsing, validation, canonicalization, planning, and identity.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

# `bijux-dag-core` Architecture

`bijux-dag-core` is the pure graph kernel for Bijux DAG. It converts authored
graph data into validated, canonical, planner-ready structures without reading
runtime state or performing external effects.

## Processing Pipeline

```mermaid
flowchart LR
    source["Serialized graph"]
    parse["Strict parsing"]
    resolve["Input and reference resolution"]
    validate["Semantic validation"]
    canonical["Canonical graph"]
    identity["Graph and node identity"]
    plan["Planner lowering"]

    source --> parse --> resolve --> validate --> canonical
    canonical --> identity
    canonical --> plan
```

Each operation receives all required data from the caller. Runtime scheduling,
artifact layout, process execution, clocks, and environment discovery happen
in downstream crates.

The pipeline is intentionally one-way. Runtime observations cannot flow back
into canonicalization or identity without making the same authored graph mean
different things on different machines.

## Source Boundaries

| Area | Responsibility |
| --- | --- |
| `graph` | model, inputs, nodes, edges, resources, composition, expansion, topology |
| `pipeline` | strict parsing, reference resolution, and validation entrypoints |
| `analysis` | identity inputs, effects, trigger rules, and semantic analysis |
| `planner` | deterministic lowering into `ExecutionPlan` |
| `build` | builders, compile wrappers, lint, dry-run, and simulation helpers |
| `contracts` | typed invariant and compatibility evaluations |
| `lib.rs` | stable, prelude, compatibility, and experimental exports |

Domain logic belongs in these modules. The crate root curates access; it must
not become a second implementation of parsing, validation, or planning.

## Purity Rules

Core may deserialize, normalize Unicode, use deterministic collections, hash
canonical bytes, validate graph semantics, and lower a graph into a plan. It
must not access files, environment variables, processes, terminals, network,
wall-clock time, random execution identity, artifacts, or cache state.

The `Graph` model represents requested semantics, not observations about a
specific machine or run.

## Dependency Direction

`bijux-dag-runtime`, `bijux-dag-app`, `bijux-dag-testkit`, and `bijux-dev` may
depend on this crate. Core must not import them. `bijux-dag-artifacts` is a
sibling authority for retained evidence; graph validity and identity cannot
depend on a run directory.

```mermaid
flowchart TB
    core["bijux-dag-core<br/>graph and planning truth"]
    runtime["bijux-dag-runtime"]
    app["bijux-dag-app"]
    testkit["bijux-dag-testkit"]
    dev["bijux-dev"]
    artifacts["bijux-dag-artifacts<br/>retained evidence truth"]

    runtime --> core
    app --> core
    testkit -. development use .-> core
    dev -. verification use .-> core
    runtime --> artifacts
    app --> artifacts
```

The absence of an arrow from core to any other workspace package is a purity
constraint, not merely a preferred layering style.

## Extension Decisions

- Add authored graph data to the graph domain and define serialization rules.
- Add deterministic diagnostics for invalid input identified before planning.
- Add planner fields only when execution requires the lowered fact.
- Pass runtime-only values to runtime rather than adding them to `Graph`.
- Keep compatibility-sensitive entrypoints in `stable`.
- Put research contracts behind `experimental-public-api`.

## Verification

Deterministic, round-trip, canonicalization, validation, and planner contracts
protect these boundaries. Broad kernel changes should run:

```bash
cargo test --locked -p bijux-dag-core
```