# vyre-primitives
Compositional primitives for vyre: the Tier-2.5 LEGO substrate that
sits between Tier-2 hardware intrinsics (`vyre-intrinsics`) and Tier-3
domain libraries (`vyre-libs`). Every domain library reuses primitives
from this crate; consumers compose primitives without touching
`vyre-driver-*` directly.
## What this crate is
The crate is feature-gated per domain so a consumer that wants only
bitset operations does not pay for the matching DFA, the d-DNNF
compiler, or the cryptographic hash family. Each domain is a feature
flag; a crate-level marker type lives at
`vyre-primitives::<domain>::*` and submits one
`OperationRegistration::primitive(...)` so the canonical operation registry
enumerates every primitive linked into the current binary.
The crate intentionally has zero concrete backend dependencies. It
depends only on `vyre-foundation` + `vyre-spec`.
The boundary is enforced by `scripts/check_architectural_invariants.sh`
and `OWNERSHIP.md`.
## Domain layout
Mirrors the Linux kernel `fs/` / `mm/` / `net/` shape: each domain is
its own subdirectory under `src/`, gated behind a Cargo feature flag.
| `bitset` | `bitset/` | bitset_and / or / xor / not / popcount / contains |
| `reduce` | `reduce/` | reduce_sum / max / min / count / scatter / segment |
| `text` | `text/` | char_class / line_index / utf8_validate |
| `matching` | `matching/` | dfa_compile, classifier_emit, region builder |
| `math` | `math/` | linalg primitives, sparse_recovery, interval algebra |
| `nn` | `nn/` | activation, attention scaffolding (composed in libs) |
| `hash` | `hash/` | perfect_hash, blake3_round |
| `parsing` | `parsing/` | bracket_match, ast_walk_preorder |
| `graph` | `graph/` | csr_*, motif, reachable, union_find, exploded |
| `bitset` `+ reduce` | derived | scan_*, prefix_*, four_russians readiness |
| `label` | `label/` | resolve_family, label_program |
| `predicate` | `predicate/` | size_argument_of and friends (predicate substrate) |
| `fixpoint` | `fixpoint/` | persistent_fixpoint, level_wave |
| `dnnf` | `dnnf/` | host-side d-DNNF compiler + model counter (P-PRIM-6) |
| `inventory-registry`| (gate) | Enables `inventory::submit!` registration system |
`all-lego` enables every Tier-2.5 domain; `default` enables the small
core (`bitset`, `reduce`, `inventory-registry`).
## Architecture decisions
- **Marker types only at the public surface.** Each primitive is a
unit struct that implements the relevant trait
(`ReferenceEvaluator`, `BackendEmitter`, etc.). The implementations
live in `vyre-reference` (CPU oracle) and the per-backend crate.
- **No GPU code in this crate.** Every primitive's GPU lowering lives
in the concrete driver crate that owns the target. The marker type
does not import shader strings: the
`check_no_string_wgsl.sh` gate is non-negotiable.
- **Promotion path.** A composition that lives in `vyre-libs` is
promoted to a primitive here only after ≥3 distinct callers and an
explicit architectural review. The `LEGO_PRIMITIVES.md` audit tracks
candidates.
- **Per-domain test directories.** Every domain ships positive,
negative, adversarial, cross-call, and proptest fixtures; see
`tests/<domain>_*.rs`.
## Where to look
- `src/lib.rs`: feature-gate table and the public domain list.
- `src/markers.rs`: the always-on marker registry types.
- `tests/`: per-domain adversarial corpora.
- `docs/OWNERSHIP.md`: workspace boundary definition.
- `docs/generated/OP_SCHEMA.json`: canonical operation tiers, signatures,
fixtures, backend evidence, and composition chains.
## Conformance
Every primitive ships a CPU reference (in `vyre-reference`) byte
identical to the GPU output. The conformance runner
(`vyre-conform`) walks the registered primitive table and asserts
parity across backends; drift is publish-blocking.
## Crate contract
This section is generated by `python3 scripts/crate_readmes.py --write` from
the crate manifest, release train, ownership registry, and crate-guide metadata.
### Purpose
Own reusable Tier 2.5 program builders shared by higher-level libraries and runtimes.
### Boundaries
The `primitive-library` owner maintains this `primitives` crate at `vyre-primitives`.
Its allowed internal production dependencies are: `vyre-foundation`, `vyre-spec`.
Any other normal or build dependency requires an ownership-registry change.
### Minimal real example
Run the checked-in behavior from `vyre-primitives/examples/dominator_tree_e2e.rs`:
```console
CARGO_BUILD_JOBS=1 ./cargo_full run -p vyre-primitives --example dominator_tree_e2e --features cpu-parity,graph
```
### Features
- Manifest features: `all-lego`, `bitset`, `cat`, `cpu-parity`, `decode`, `default`, `dnnf`, `effects`, `fixpoint`, `geom`, `gpu`, `graph`, `hash`, `inventory-registry`, `label`, `matching`, `math`, `nfa`, `nn`, `opt`, `parsing`, `predicate`, `reduce`, `text`, `topology`, `types`, `visual`, `vyre-foundation`, `zx`
- Default feature members: None
### Errors and unsupported behavior
Invalid dimensions, overflow, unsupported contracts, and malformed program inputs are rejected while the program is built or validated.
### Testing
Use [`docs/testing/vyre-primitives.md`](../docs/testing/vyre-primitives.md) for exact commands, Cargo targets, hardware
requirements, evidence outputs, expected skips, and failure semantics.
### Release status
`vyre-primitives@0.7.2` is a publishable crate on the current Vyre release train. Publication still requires the release evidence and user-approval gates.
### Ownership
`docs/CRATE_OWNERSHIP.toml` is authoritative for this crate's responsibility
and allowed internal edges. Regenerate `docs/CRATE_GRAPH.md` and
`docs/OWNERSHIP.md` after changing that registry.
### License
Licensed under either of
- Apache License, Version 2.0, or
- MIT license
at your option. See the workspace `LICENSE-APACHE` and `LICENSE-MIT` files.