Crate vyre_primitives 

vyre-primitives — compositional primitives for vyre.

Shape (mirrors Linux kernel fs/ / mm/ / net/ — subsystem directories under one crate, feature-gated for consumers):

vyre-primitives/
  src/
    lib.rs                  # subsystem table (this file)
    markers.rs              # unit-struct marker types, always on
    text/                   # feature = "text"
      mod.rs
      char_class.rs
      utf8_validate.rs
      line_index.rs
    matching/               # feature = "matching"
      mod.rs
      bracket_match.rs
    bitset/                 # feature = "bitset"
    fixpoint/               # feature = "fixpoint"
    graph/                  # feature = "graph"     (CSR + BFS + SCC + motif + toposort)
    hash/                   # feature = "hash"
    label/                  # feature = "label"
    math/                   # feature = "math"
    nn/                     # feature = "nn"
    parsing/                # feature = "parsing"
    predicate/              # feature = "predicate"
    reduce/                 # feature = "reduce"

Two kinds of primitive live here:

1. Marker types (markers, always on, zero deps) — unit structs the reference interpreter and backend emitters dispatch on.

2. Tier 2.5 substrate (per-domain feature flags) — shared fn(...) -> Program primitives reused by ≥ 2 Tier-3 dialects. Each domain is one folder + one feature flag. Tier 3 crates depend on vyre-primitives and enable only the domains they need.

The path IS the interface. Subsystem mod.rs exposes sub-modules, not a flat namespace — callers write vyre_primitives::text::char_class::char_class(...) so the LEGO chain is visible at every call site.

See docs/primitives-tier.md and docs/lego-block-rule.md for the tier rule, admission criteria, and Gate 1 enforcement.

Modules

bitset

Bitset primitives — and/or/not/xor/popcount/any/ contains over packed u32 bitsets. The NodeSet / ValueSet representation every graph primitive consumes. Tier 2.5 bitset primitives — and/or/not/xor/popcount/ any/contains over packed u32 bitsets. These are the LEGO blocks every higher-level graph/taint composition reaches for when combining two NodeSets.

cat

Categorical primitives (P-PRIM-16/17/18). Yoneda embedding, adjoint-pair detection, Kan extension over finite categories. Consumed by the optimizer’s functorial_pass_composition substrate. Categorical primitives (P-PRIM-16/17/18).

decode

Decode primitives. Tier 2.5 decode primitives.

dnnf

d-DNNF (decomposable / deterministic NNF) compiler primitive (P-PRIM-6). Host-side CNF → d-DNNF via Shannon decomposition, linear-time model counting on the result. Used by knowledge_compile_pass_precondition to turn pass-precondition formulae into linear-cost evaluators. Decomposable-NNF (d-DNNF) compiler primitive (P-PRIM-6).

effects

Effects-typed pipeline primitives (P-1.0-V1.x). Pure-data substrate: EffectRow bitmask, Handler over a row, handler_apply discharges effects, handler_compose builds a joint handler. Reference for the foundation effects-typed lower pipeline (V1.3). Effects-typed pipeline primitives (P-1.0-V1.x).

fixpoint

Deterministic fixpoint primitive (ping-pong with convergence flag). Composes csr_forward_traverse + bitset OR into the transitive-closure driver every stdlib taint rule needs. Tier 2.5 fixpoint primitives — driver-free convergence loops for bitset transfer functions.

geom

Geometric / Clifford-algebra primitives (#8). Multivector products for equivariant NNs, physics simulation, robotics, 3D vision. Tier 2.5 geometric-algebra primitives (#8).

graph

Graph primitives (topological sort, reachability, CSR traversal, SCC decomposition, path reconstruction — the Tier 2.5 substrate that surgec’s stdlib rules compose against). Tier 2.5 graph primitives.

harness

Tier-2.5 primitive registry. See harness::OpEntry. Gated behind the inventory-registry feature so default builds stay dep-free; the conform harness + xtask enable the feature. Tier 2.5 LEGO primitive registry.

hash

Hash primitives (FNV-1a 32/64, CRC-32). Tier 2.5 hash primitives.

label

Label → NodeSet resolver — turn a TagFamily bitmask into a NodeSet bitset. Implements the @family lookup that surgec’s label surface surfaces. Tier 2.5 label → NodeSet resolver.

matching

Pattern-matching primitives. Tier 2.5 byte/text scan primitives (DFA, substring, filters).

math

Math primitives (dot, scan, reduce, broadcast). Tier 2.5 mathematical primitives.

nfa

NFA primitives — subgroup-cooperative simulator (G1 GPU perf). NFA primitives — subgroup-cooperative epsilon closure and step simulation.

nn

Neural-network primitives (attention and normalization sub-kernels). Tier 2.5 neural-network primitives.

opt

Optimization primitives (#9, #14, #46). Homotopy continuation, SOS, matroid intersection. Self: vyre’s megakernel scheduler. Tier 2.5 optimization primitives (#9, #14, #46).

parsing

Parsing primitives (optimizer and AST scan kernels). Tier 2.5 parsing primitives.

predicate

Frozen predicate primitives — the ~10 engine primitives (call_to, return_value_of, arg_of, size_argument_of, edge, in_function, in_file, in_package, literal_of, node_kind) that SURGE stdlib rules compose into every higher-level query. Frozen predicate primitives — the ~10 engine primitives listed in surgec’s vision as “the engine has ≈10 true primitives; everything else is SURGE stdlib.” Each is a thin wrapper that emits a vyre Program composing crate::graph + crate::bitset + crate::label primitives with a specific edge-kind mask, tag mask, or node-kind constant.

range

Domain-neutral byte-range primitive.

reduce

Reduction primitives — count/min/max/sum over bitsets and fixed-width ValueSets. Backs SURGE aggregates. Tier 2.5 reduction primitives — count/min/max/sum over bitsets and fixed-width u32 ValueSets.

serial_data

Wire-format envelope re-exported from vyre-foundation.

text

Text primitives. Tier 2.5 text primitives.

topology

Topological-data-analysis primitives (#15, #32). Vietoris-Rips filtration + simplicial complex operations. User: TDA, persistent landscape features, call-graph topological signatures. Tier 2.5 topological-data-analysis primitives (#15, #32).

types

Type-discipline primitives (P-PRIM-14, …). Substructural (linear/affine/relevant/unrestricted) checks the foundation validate pipeline consumes per buffer. Type-discipline primitives (P-PRIM-14, P-PRIM-15, …).

vfs

Virtual File System DMA primitives. Uses vyre_foundation::ir so it’s gated behind the same set of features that pull vyre-foundation in as an optional dep. Any of the domain features enables vfs. GPU-native virtual filesystem primitives.

visual

Visual pixel-map primitives. Shared packed-RGBA invocation skeletons reused by higher-level image-processing compositions. Packed-RGBA visual primitives.

zx

ZX-calculus rewrite primitives (P-PRIM-5). Spider fusion, identity removal, color change. Pure-CPU on a Vec + edge multiset; no FP, no IR-builder dep. ZX-calculus rewrite primitives (P-PRIM-5).

Structs

ArithAdd

Integer wrap-around addition primitive.

ArithMul

Integer wrap-around multiplication primitive.

BitwiseAnd

Bitwise AND primitive.

BitwiseOr

Bitwise OR primitive.

BitwiseXor

Bitwise XOR primitive.

Clz

Count-leading-zeros primitive.

CompareEq

Equality comparison primitive.

CompareLt

Less-than comparison primitive.

Gather

Workgroup-local gather primitive.

HashBlake3

BLAKE3 hashing primitive.

HashFnv1a

FNV-1a hashing primitive.

PatternMatchDfa

DFA-driven scan primitive.

PatternMatchLiteral

Literal-string scan primitive.

Popcount

Population-count primitive.

Reduce

Associative reduction primitive.

RegionId

Stable identifier for a workgroup-shared memory region.

Scan

Inclusive/exclusive prefix scan primitive.

Scatter

Scatter primitive.

ShiftLeft

Logical shift-left primitive.

ShiftRight

Logical shift-right primitive.

Shuffle

Workgroup-local shuffle primitive.

Enums

CombineOp

Associative reduction operator shared by scan/reduce primitives.