github.com/openfluke/welvet✅ engine

Why it exists

Loom’s flat poly/ package hit import-cycle and honesty walls (QAT morph, silent fallbacks, god-layer). Welvet is the rewrite: one feature per folder, storage-truth dtypes/quants, Dense as the shared MatVec microkernel, tests only in w2a, apps only in apps/.

What it is

An AI engine in Go: layers, 34 dtypes, 20 quant formats, and three backends (CPU tiled · Plan 9 SIMD · WebGPU). Version tracks a 100-point scorecard (today v1.1.1 · 100/100).

Rules
  1. No tests in engine packages          → w2a/
  2. No silent fallbacks                  → hard error
  3. No hardcoded float32                 → Tensor[T]
  4. No QAT                               → DType + Format = truth
  5. Train keeps storage truth            → in-dtype / re-Pack SGD, no retained f32 master
  6. One feature → one folder
  7. v1.0 = scorecard 100/100

Origin

Samuel Watson

Samuel Watson created OpenFluke after intensive T-ALL treatment (post-2018), from a simple frustration: AI tooling was heavy, opaque, and not portable enough to move models cleanly across operating systems or personal devices. Setting up GPU paths often meant large, brittle installs before experimentation could even begin.

That gap drove a long detour through cybersecurity, MBA, and psychology before returning through applied AI study - and finding that most paths still taught framework usage more than system construction. The result was a build journey across planetbridging into OpenFluke projects, from paragon and loom to Welvet.

The early breakthroughs were practical and hard-won: first dense nets in Go, then WebGPU proof points (for example iso-demo v0.1.0), then repeated cycles of speed, layers, 3D, tiling, SIMD, and bit-oriented model paths for personal intelligence.

Why "OpenFluke": open source values plus a life-saving fluke blood test that caught cancer early.
Why "Welvet": a name shaped in gaming sessions with family.

I wish this tool existed in 2018 to keep trying things in AI and asking "what if I try this?" - and maybe help deterministic medical deployment of AI models.

"Our duty, as soldiers, is to protect humanity. Whatever the cost." - Master Chief

package main

import (
	"fmt"

	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/dense"
)

func main() {
	l, err := dense.New(8, 4, core.ActivationReLU, core.DTypeFloat32)
	if err != nil {
		panic(err)
	}
	l.Exec.Backend = core.BackendCPUTiled

	x := core.NewTensor[float32](1, 8)
	for i := range x.Data {
		x.Data[i] = float32(i) * 0.1
	}
	pre, post, err := dense.Forward(l, x)
	if err != nil {
		panic(err)
	}
	fmt.Println("pre", len(pre.Data), "post", len(post.Data))
}

pre 4 post 4

cd welvet && go build ./...
cd w2a && go test ./tests/dense -v

✅ layout

Why it exists

Readers need a single map of what is engine vs harness vs app vs stub.

What it is

Top-level folders and their ownership. Engine packages never import w2a.

welvet/
  core weights quant simd webgpu tiling architecture fusedgpu
  layers/*          ← one folder per op (parallel = MoE + cameral)
  runtime/{forward,backward,training,step}
  systems/{dna,evolution,tween,tanhi,telemetry}
  lucy/             ← Score / Finalize / BuildLPD density (shared by hosts)
  model/{entity,hf,tokenizer,sampling,transformer}
  apps/{octo,flux2,mosstts}
  stub/*            ← designed surfaces, partial or empty
  w2a/              ← harness (separate module)
  tools/            ← eval / test tooling

Engine never imports apps. Lucy measuring is lucy/ (public). Lucy races (test41 / test48 / test50) live in the AAI tree and replace this module — see §68 cameral + AAI. w2a owns every timed matrix, including Test49 (all 23 train modes on origin-only cubes).

package main

import (
	"fmt"
	"os"
)

func main() {
	// Mental model only — list engine roots you depend on:
	roots := []string{
		"core", "weights", "quant", "simd", "webgpu", "tiling",
		"architecture", "fusedgpu", "layers", "runtime", "systems", "lucy", "model",
	}
	for _, r := range roots {
		fmt.Println("import github.com/openfluke/welvet/" + r + "/…")
	}
	_ = os.Getenv // apps/stub/w2a are separate concerns
}

import github.com/openfluke/welvet/core/…
import github.com/openfluke/welvet/weights/…
import github.com/openfluke/welvet/quant/…
import github.com/openfluke/welvet/simd/…
import github.com/openfluke/welvet/webgpu/…
import github.com/openfluke/welvet/tiling/…
import github.com/openfluke/welvet/architecture/…
import github.com/openfluke/welvet/fusedgpu/…
import github.com/openfluke/welvet/layers/…
import github.com/openfluke/welvet/runtime/…
import github.com/openfluke/welvet/systems/…
import github.com/openfluke/welvet/lucy/…
import github.com/openfluke/welvet/model/…

github.com/openfluke/welvet/core✅

Why it exists

Every polymorphic path needs one place for DType, LayerType, Activation, Backend, Tensor[T], and slim Layer metadata — without QAT morph defaults.

What it is

34 storage dtypes, Numeric generics, Tensor[T], ExecConfig (BackendCPUTiled | BackendSIMD | BackendWebGPU), Activate/ActivateDeriv, and converters for f16/bf16/fp8/fp4.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/core"
)

func main() {
	t := core.NewTensor[float32](2, 4)
	t.Data[0] = -1
	t.Data[0] = core.Activate(t.Data[0], core.ActivationReLU) // 0

	cfg := core.ExecConfig{
		Backend:   core.BackendSIMD,
		MultiCore: true,
		TileSize:  32,
	}
	fmt.Println(cfg.Backend.String(), core.ParseDType("bfloat16"), t.Len())
}

simd bfloat16 8

github.com/openfluke/welvet/weights✅

Why it exists

Unquantized matrices still need a typed store that streams MatVec and SGD without forcing a float32 master or Morph-as-training.

What it is

Store holds DType + Format + Native/Packed bytes. New[T], MatVec, MatVecT, DecodeRow, SelectWire (F32/F64/I8), ApplySGD. FormatNone: update in native lanes (float32 payload is the only f32 buffer; float64 uses native ALU; other dtypes decode→update→re-encode). Packed: unpack→update→re-Pack then drop scratch. RetainsF32Master() is true only for FormatNone+float32. Dense and composite projs share this store.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/quant"
	"github.com/openfluke/welvet/weights"
)

func main() {
	s, err := weights.New[float32](2, 2, []float32{1, 0, 0, 1}, core.DTypeFloat32, quant.FormatNone)
	if err != nil {
		panic(err)
	}
	y := make([]float32, 2)
	if err := weights.MatVec(s, []float32{3, 4}, y); err != nil {
		panic(err)
	}
	fmt.Println(y) // ≈ [3, 4]
}

[3 4]

github.com/openfluke/welvet/quant✅

Why it exists

Inference, storage, and train need classic Q-packs, k-quants, IQ, Ternary/Binary, and Affine without a separate QAT mode or retained f32 master. Format is storage truth.

What it is

Pack / Unpack / MatVec / MatVecT for FormatNone…AffinePacked. Dense SIMD once-projects codes into Int8QS + scales (EnsureQ* / EnsureK/IQ/AffineSIMDCache) — no full-matrix F32 inflate for k/IQ/Affine. SGD on packed stores: short-lived unpack scratch → update → re-Pack; Packed stays truth.

Families: classic Q8/Q4/Q5 · K-quants · IQ · TernaryPacked/BinaryPacked · AffinePacked.

Honesty: fused Dense SIMD for all 20 quants (group DotKRow / DotIQRow / DotAffineRow + classic Q*/BitNet). Peak dedicated k/IQ Plan 9 .s remains scorecard §12.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/quant"
)

func main() {
	w := []float32{0.1, -0.2, 0.3, 0.4, -0.5, 0.6, 0.05, -0.15}
	b, err := quant.Pack(quant.FormatQ4_0, w, 2, 4)
	if err != nil {
		panic(err)
	}
	y := make([]float32, 2)
	if err := quant.MatVec(b, []float32{1, 1, 1, 1}, y); err != nil {
		panic(err)
	}
	fmt.Println("rows", b.Rows, "cols", b.Cols, "y", y)
}

rows 2 cols 4 y [0.6857143 -1.4901161e-08]

github.com/openfluke/welvet/simd✅

Why it exists

CPU peak needs hand-written AVX2/NEON without a silent Go fallback that pretends SIMD ran.

What it is

amd64/arm64 .s kernels: DotTile, DotI8/U8, DotQ4_0, Saxpy, BitNet helpers, packed f16/bf16/fp8/fp4 dots; amd64 AVX2 DotTileF64 (WireF64); Go fused DotKRow / DotIQRow / DotAffineRow for k/IQ/Affine. SimdEnabled() false → BackendSIMD hard-errors.

v1.0.3: Dense FormatNone forward finished the remaining Plan 9 wires — DotTileF64 (amd64), BF16 convert, expand-once → DotTile. Backward still uses saxpy/DecodeRow paths. Universal sizes (any in/out/batch).

Arm still runs every FormatNone dtype through the right Dense strategy; the f64 wire is scalar until a NEON DotTileF64 lands. Hot traffic (f32 / i8) already has NEON.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/simd"
)

func main() {
	if !simd.SimdEnabled() {
		fmt.Println("SIMD not available on this arch — BackendSIMD must hard-error")
		return
	}
	acc := simd.DotTile([]float32{1, 2, 3, 4}, []float32{1, 1, 1, 1}, 0, 4, 0)
	fmt.Println(acc)
}

10

github.com/openfluke/welvet/webgpu✅

Why it exists

GPU paths must bind a real adapter. Host “fake GPU” was banned so suites cannot stamp WebGPU done when ALU ran on CPU.

What it is

DenseGEMV family (incl. quant/I8/resident), DenseGEMVT/DenseDW, RMSNorm, LayerNorm fwd, Softmax family, SwiGLUFuse. Available()/InitError() gate use.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/webgpu"
)

func main() {
	if !webgpu.Available() {
		fmt.Println("no adapter:", webgpu.InitError())
		return
	}
	y := make([]float32, 2)
	err := webgpu.DenseGEMV(
		[]float32{1, 0, 0, 1},
		[]float32{1.5, 2.5},
		y, 1, 2, 2,
	)
	fmt.Println(y, err, webgpu.AdapterName())
}

webgpu probe goos=linux goarch=amd64 WELVET_WGPU_BACKEND=""
  adapter high-perf: name="NVIDIA GeForce GTX 1650 SUPER" vendor="NVIDIA" arch="" driver="610.57.04" backend=vulkan type=discrete-gpu | maxBuf=1099511627776 maxSSBO=2147483644 maxSSBO/stage=524288 maxBindGroups=8 maxComputeWG=65535 maxInvoc/WG=1024
  → selected high-perf
  adapter low-power: name="Intel(R) UHD Graphics 630 (CML GT2)" vendor="Intel open-source Mesa driver" arch="" driver="Mesa 26.1.8" backend=vulkan type=integrated-gpu | maxBuf=2147483647 maxSSBO=2147483644 maxSSBO/stage=103 maxBindGroups=8 maxComputeWG=65535 maxInvoc/WG=1024
  adapter force-fallback: name="llvmpipe (LLVM 22.1.8, 256 bits)" vendor="llvmpipe" arch="" driver="Mesa 26.1.8 (LLVM 22.1.8)" backend=vulkan type=cpu | maxBuf=2147483647 maxSSBO=134217728 maxSSBO/stage=48 maxBindGroups=8 maxComputeWG=65535 maxInvoc/WG=1024
  adapter default: name="NVIDIA GeForce GTX 1650 SUPER" vendor="NVIDIA" arch="" driver="610.57.04" backend=vulkan type=discrete-gpu | maxBuf=1099511627776 maxSSBO=2147483644 maxSSBO/stage=524288 maxBindGroups=8 maxComputeWG=65535 maxInvoc/WG=1024
  try RequestDevice inflated: maxBuf=2147483648 maxSSBO=1073741824 maxSSBO/stage=524288 maxBindGroups=8 maxComputeWG=65535 maxInvoc/WG=1024
RESULT: OK via=inflated adapter="NVIDIA GeForce GTX 1650 SUPER" backend=vulkan maxSSBO=2147483644 maxBuf=1099511627776
[1.5 2.5] <nil> NVIDIA GeForce GTX 1650 SUPER

github.com/openfluke/welvet/tiling✅

Why it exists

MatVec throughput depends on tile size and when to go multi-core vs GPU workgroups. Centralizing caps keeps Dense and friends consistent.

What it is

DefaultCPUTile, DefaultGPUWG, CPUTile, PreferMultiCore, GPUWorkgroupsX.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/tiling"
)

func main() {
	tile := tiling.CPUTile(0) // default 32
	mc := tiling.PreferMultiCore(8, 256, tile)
	wg := tiling.GPUWorkgroupsX(1024, 0)
	fmt.Println(tile, mc, wg)
}

32 true 16

github.com/openfluke/welvet/architecture✅

Why it exists

Networks are spatial (Depth×Rows×Cols×LayersPerCell), not only linear stacks. Topology lives here; compute lives in layer packages.

What it is

Grid/Cell/Coord, NewGrid, BindOp, HopOrder, SetRemoteLink/ResolveHop. VolumetricNetwork is an alias for Grid.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/architecture"
	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/dense"
)

func main() {
	g := architecture.NewGrid(1, 1, 2, 1) // depth, rows, cols, layersPerCell
	l, _ := dense.New(4, 4, core.ActivationLinear, core.DTypeFloat32)
	if err := dense.Place(g, 0, 0, 0, 0, l); err != nil {
		panic(err)
	}
	_ = g.SetRemoteLink(0, 0, 1, 0, 0, 0, 0, 0) // spatial feedback hop
	fmt.Println("cells", len(g.HopOrder()))
}

cells 2

github.com/openfluke/welvet/fusedgpu✅

Why it exists

Token-by-token host round-trips kill decode. A fused engine keeps weights and scratch resident for Q4_0 and BinaryG128 hybrid paths.

What it is

Engine from Spec (AppendTokens/Reset/Close); HybridEngine (PrefillSample/DecodeSample/DecodeChunk). Specs come from model/transformer export.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/fusedgpu"
	"github.com/openfluke/welvet/model/transformer"
)

func main() {
	m, err := transformer.LoadEntity("model.entity")
	if err != nil {
		fmt.Println("need an ENTITY file:", err)
		return
	}
	spec, err := m.ExportFusedGPUSpec()
	if err != nil {
		panic(err)
	}
	eng, err := fusedgpu.NewFromSpec(spec)
	if err != nil {
		panic(err)
	}
	defer eng.Close()
	logits, err := eng.AppendTokens([]uint32{1, 2, 3})
	fmt.Println(len(logits), err)
}

need an ENTITY file: open model.entity: no such file or directory

github.com/openfluke/welvet/layers/dense✅

Why it exists

Most FLOPs are W@x. One Dense stack owns FormatNone×34 and all quants × three backends so every composite proj shares one correctness surface — including native in-dtype SGD.

What it is

New / NewConfigured[T], Forward/Backward (dispatch on Exec.Backend), Place, ApplyGradSGD (→ weights.ApplySGD on the store). SIMD forward (v1.0.3): dtype switch by MatVec strategy — DotTile / DotI8 / lowp packed / expand-once→DotTile / WireF64+DotTileF64; fused Dot* for classic Q*, k/IQ, AffinePacked. Composites (MHA, SwiGLU, CNN im2col, RNN/LSTM/Mamba, residual·sequential·parallel) reuse Dense children via syncProjExec. BackwardSIMD still DecodeRow/saxpy (not the new expand wires).

forwardSIMDByWire (strategy groups)

Before → after (µs/op, Go Δ)

Full Go/C++/Rust columns: before wins Go 2 / C++ 31 / Rust 1; after Go 24 / C++ 9 / Rust 1. Highlight Go speedups (before→after):

C++ still owns int8/narrow, uint8, bf16/fp8. float32 DotTile remains Go’s race (929.5 vs C++ 1162 / Rust 1335). uint8 affine is a known Go follow-up.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/dense"
	"github.com/openfluke/welvet/quant"
)

func main() {
	init := make([]float32, 4*8)
	l, err := dense.NewConfigured(8, 4, core.ActivationReLU, core.DTypeFloat32, quant.FormatNone, init)
	if err != nil {
		panic(err)
	}
	l.Exec.Backend = core.BackendCPUTiled
	x := core.NewTensor[float32](1, 8)
	pre, post, err := dense.Forward(l, x)
	if err != nil {
		panic(err)
	}
	gIn, gW, err := dense.Backward(l, post, x, pre)
	_ = dense.ApplyGradSGD(l, gW, 1e-3)
	fmt.Println(len(gIn.Data), len(gW.Data))
}

8 32

github.com/openfluke/welvet/layers/mha✅

Why it exists

Transformers need multi-head attention with masks, RoPE/ALiBi, GQA/MQA, and cross-attn — without forking MatVec for every projection.

What it is

Q/K/V/O are Dense children. Presets: DecoderCausal, EncoderBidirectional, CrossAttention, … Attn/RoPE ALU is host today; on-device attn shaders are still open.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/mha"
)

func main() {
	l, err := mha.New(mha.DecoderCausal(32, 4, 4))
	if err != nil {
		panic(err)
	}
	x := core.NewTensor[float32](1, 8, 32) // [batch, seq, dim]
	pre, post, err := mha.Forward(l, x)
	fmt.Println(pre != nil, len(post.Data), err)
}

true 256 <nil>

github.com/openfluke/welvet/layers/swiglu✅

Why it exists

Modern decoder FFNs are SiLU(gate)⊙up → down. Projections must share Dense’s quant/backend matrix.

What it is

Gate/Up/Down Dense children; DefaultFFN(dModel); WebGPU SiLU⊙ fuse on forward.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/swiglu"
)

func main() {
	l, err := swiglu.New(swiglu.DefaultFFN(64))
	if err != nil {
		panic(err)
	}
	x := core.NewTensor[float32](1, 64)
	_, post, err := swiglu.Forward(l, x)
	fmt.Println(len(post.Data), err)
}

64 <nil>

github.com/openfluke/welvet/layers/rmsnorm✅

Why it exists

Llama-style blocks normalize by RMS, not mean+var. Needs native fwd/bwd and WebGPU shaders.

What it is

Per-token RMS + γ on weights.Store; WebGPU fwd+bwd; SIMD DotTile stats + host scale.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/rmsnorm"
	"github.com/openfluke/welvet/quant"
)

func main() {
	gamma := []float32{1, 1, 1, 1}
	l, err := rmsnorm.NewConfigured(rmsnorm.Config{Dim: 4}, core.DTypeFloat32, quant.FormatNone, gamma)
	if err != nil {
		panic(err)
	}
	x := core.NewTensor[float32](1, 4)
	_, y, err := rmsnorm.Forward(l, x)
	fmt.Println(y.Data, err)
}

[0 0 0 0] <nil>

github.com/openfluke/welvet/layers/layernorm✅

Why it exists

Classic mean+var normalization with γ/β — still required for many HF architectures.

What it is

WebGPU forward; backward host today. Same dtype×quant axes as other weighted layers.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/layernorm"
)

func main() {
	l, err := layernorm.New(layernorm.Config{Dim: 8})
	if err != nil {
		panic(err)
	}
	x := core.NewTensor[float32](1, 8)
	_, y, err := layernorm.Forward(l, x)
	fmt.Println(len(y.Data), err)
}

8 <nil>

github.com/openfluke/welvet/layers/embedding✅

Why it exists

Token IDs must gather rows from a table — not a Dense MatVec — with scatter grads on backward.

What it is

Config{VocabSize, EmbeddingDim, SeqLen}; table on weights.Store; host gather on SIMD/WebGPU today.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/embedding"
)

func main() {
	l, err := embedding.New(embedding.Config{VocabSize: 32, EmbeddingDim: 16, SeqLen: 4})
	if err != nil {
		panic(err)
	}
	ids := core.NewTensor[float32](1, 4)
	ids.Data[0], ids.Data[1] = 3, 7
	_, y, err := embedding.Forward(l, ids)
	fmt.Println(y.Shape, err)
}

[1 4 16] <nil>

github.com/openfluke/welvet/layers/softmax✅

Why it exists

Classification heads and attention need stable softmax variants, including sparse/Gumbel/Entmax for research paths.

What it is

Weightless layer; KindStandard/Temperature/Grid/Hierarchical/Gumbel/Masked/Sparse/… WebGPU covers std family; exotic kinds hard-error on GPU (no silent host).

package main

import (
	"fmt"

	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/softmax"
)

func main() {
	l, err := softmax.New(softmax.Config{Dim: 4, Kind: softmax.KindStandard})
	if err != nil {
		panic(err)
	}
	x := core.NewTensor[float32](1, 4)
	copy(x.Data, []float32{2, 1, 0.1, -1})
	_, y, err := softmax.Forward(l, x)
	fmt.Println(y.Data, err)
}

[0.6380664 0.23473153 0.09543471 0.031767454] <nil>

github.com/openfluke/welvet/layers/sequential✅

Why it exists

Some cells need an ordered Dense chain without burning grid hops.

What it is

Dense→Dense compose, or mixed Ops via NewFromOps (Dense, SwiGLU, RMSNorm, LayerNorm). Parallel as a child is parallel.ResidualGraft / a Sandwich — Sequential cannot import parallel.

NewFromOps walks mixed children (Dense, SwiGLU, RMSNorm, LayerNorm) through the same fwd/bwd as a Dense chain. Parallel is not a Sequential child (import cycle) — wrap F with parallel.ResidualGraft or put Parallel in a Sandwich. w2a covers mixed Sequential cells; this is on the v1.0 board, not a leftover “open.”

package main

import (
	"fmt"

	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/sequential"
)

func main() {
	l, err := sequential.New(sequential.Config{Dim: 16, Depth: 3})
	if err != nil {
		panic(err)
	}
	x := core.NewTensor[float32](1, 16)
	_, y, err := sequential.Forward(l, x)
	fmt.Println(len(y.Data), err)
}

16 <nil>

github.com/openfluke/welvet/layers/residual✅

Why it exists

Skip connections stabilize deep stacks: y = F(x) + x with correct skip grads.

What it is

F is Dense Dim→Dim, or mixed Ops via NewFromOps (Dense, SwiGLU, RMSNorm, LayerNorm). Parallel as F is parallel.ResidualGraft (y = F(x)+x) — Residual cannot import parallel.

NewFromOps builds F over mixed Ops. Parallel as F is parallel.ResidualGraft → y = F(x)+x. Skip grads still land on F and the identity path. Nested mixed Residual is on the v1.0 board.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/residual"
)

func main() {
	l, err := residual.New(residual.Config{Dim: 16, Depth: 2})
	if err != nil {
		panic(err)
	}
	x := core.NewTensor[float32](1, 16)
	_, y, err := residual.Forward(l, x)
	fmt.Println(len(y.Data), err)
}

16 <nil>

github.com/openfluke/welvet/layers/cnn2✅

Why it exists

Conv nets must sit on the same dtype×quant×backend matrix as Dense. im2col → Dense GEMV is the intentional first cut.

What it is

cnn1/cnn2/cnn3: host im2col then Proj Dense. Full timed matrices. Tiled conv shaders still ⬜.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/cnn2"
)

func main() {
	l, err := cnn2.New(cnn2.Config{
		InChannels: 1, Filters: 4, Height: 8, Width: 8, Kernel: 3, Stride: 1,
	})
	if err != nil {
		panic(err)
	}
	x := core.NewTensor[float32](1, 1, 8, 8)
	_, y, err := cnn2.Forward(l, x)
	fmt.Println(y.Shape, err)
}

[1 4 6 6] <nil>

github.com/openfluke/welvet/layers/lstm✅

Why it exists

Sequence models before transformers still need vanilla RNN and LSTM with BPTT on the shared MatVec stack.

What it is

IH/HH (and LSTM gates) via Dense; recurrence ALU host; device required for WebGPU path.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/lstm"
	"github.com/openfluke/welvet/layers/rnn"
)

func main() {
	r, _ := rnn.New(rnn.Config{InputSize: 8, HiddenSize: 16, SeqLen: 4})
	l, _ := lstm.New(lstm.Config{InputSize: 8, HiddenSize: 16, SeqLen: 4})
	x := core.NewTensor[float32](1, 4, 8)
	_, yr, _ := rnn.Forward(r, x)
	_, yl, _ := lstm.Forward(l, x)
	fmt.Println(len(yr.Data), len(yl.Data))
}

64 64

github.com/openfluke/welvet/layers/seqmix✅

Why it exists

Attention, SSM, linear attn, and conv mixers must not be accidental forks of mha. Naming the contract keeps packages honest.

What it is

KindAttention | KindSSM | KindLinearAttn | KindConvMix and Contract{Kind,DModel,MaxT}. No compute here.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/layers/seqmix"
)

func main() {
	c := seqmix.Contract{Kind: seqmix.KindAttention, DModel: 64, MaxT: 2048}
	fmt.Println(c.Kind.String()) // attention
}

attention

github.com/openfluke/welvet/layers/gdn✅

Why it exists

Linear attention / decode-first mixers (Gated DeltaNet) need a first-class package under KindLinearAttn.

What it is

Exec CPU/SIMD/WebGPU; ForwardDecode; truncated BPTT. Timed matrix is Float32-primary: PermutationOK is f32 × FormatNone/BinaryPacked × CPU/SIMD/WebGPU; other cells GAP (declared), not FAIL.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/layers/gdn"
)

func main() {
	l, err := gdn.New(gdn.Config{
		HiddenSize: 64, NumKeyHeads: 4, NumValueHeads: 4,
		KeyHeadDim: 16, ValueHeadDim: 16, ConvKernel: 4,
	})
	if err != nil {
		fmt.Println("config rejected:", err)
		return
	}
	l.Reset()
	x := make([]float32, 64)
	y := make([]float32, 64)
	fmt.Println(l.ForwardDecode(x, y))
}

<nil>

github.com/openfluke/welvet/layers/mamba✅

Why it exists

SSM mixers (KindSSM) are not MHA clones — they need their own selective-scan path.

What it is

InProj → softplus(Δ) scan → OutProj. Full timed matrix + train grids (scan ALU host).

package main

import (
	"fmt"

	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/mamba"
)

func main() {
	l, err := mamba.New(mamba.Config{DModel: 32, DState: 16, Expand: 2, SeqLen: 8})
	if err != nil {
		fmt.Println(err)
		return
	}
	x := core.NewTensor[float32](1, 8, 32)
	_, y, err := mamba.Forward(l, x)
	fmt.Println(y != nil, err)
}

true <nil>

github.com/openfluke/welvet/layers/convt1✅

Why it exists

Generators and U-Nets need transposed convolution as a peer of CNN, on the same Dense proj surface.

What it is

Scatter upsample + Dense Proj. Full timed matrix + train grids (tiled transpose shaders still §12).

package main

import (
	"fmt"

	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/convt1"
)

func main() {
	l, err := convt1.New(convt1.Config{InChannels: 4, Filters: 2, SeqLen: 8, Kernel: 3, Stride: 2})
	if err != nil {
		panic(err)
	}
	x := core.NewTensor[float32](1, 4, 8)
	_, y, err := convt1.Forward(l, x)
	fmt.Println(y.Shape, err)
}

[1 2 17] <nil>

github.com/openfluke/welvet/layers/kmeans✅

Why it exists

Soft clustering as a differentiable layer lets topology experiments sit inside the same train loop.

What it is

Centers on Dense (K×FeatureDim); soft assignment outputs. Full timed matrix + train grids.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/kmeans"
)

func main() {
	l, err := kmeans.New(kmeans.Config{NumClusters: 4, FeatureDim: 8})
	if err != nil {
		panic(err)
	}
	x := core.NewTensor[float32](1, 8)
	_, y, err := kmeans.Forward(l, x)
	fmt.Println(y.Shape, err)
}

[1 4] <nil>

github.com/openfluke/welvet/layers/parallel✅

Why it exists

Mixture-of-experts and multi-path cells need concat/add/avg/filter combines. Cameral graphs need sibling hemispheres that share input, merge outputs, and optionally train under distinct modes.

What it is

Parallel branches + Stack sandwiches. Hemispheres / Bicameral / Sandwich build nested multi-cameral nets. SetBranchModes + TrainStackMSE let each hemi use a different TrainMode (all 29 named updates — BP, Tween, Split, FastProxy, Sparse, Step*, Mesh*, …).

input x
   │
   ▼
 Dense stem
   │
   ├──────────┐
   ▼          ▼
 Hemi L     Hemi R     ← own Dense weights
 StepBP     TweenChain ← BranchModes
   │          │
   └──── add ─┘
         │
         ▼
    Dense head → ŷ → MSE

Cameral API (v1.0)

• Hemispheres / HemispheresFrom — n twins (Dense or mixed Ops), merged by add/avg/concat/filter
• Bicameral / Sandwich / BicameralFrom — stem → Parallel → head Stack
• SetBranchModes(...) — stamp per-hemi TrainMode
• TrainStackMSE — forward → MSE → per-branch update (honours BranchModes)
• ResidualGraft — skip around a Parallel F without Residual importing this package
• WriteCameralFile / LoadCameral — cameral .entity (in model/entity)
• CamSyncConfig / SetCamSync / SyncNow — soft/hard inter-cameral weight blend + cross-layer same-shape pairs → §70

Uniform Bi/Tri/Quad can train via Grid training.Step (one mode for the net). Mix jobs need the Stack path so each cameral actually uses its own mode.

Why hemispheres exist, and how AAI Lucy benches use them: §68. Inter-cameral weight sync (crazy cross-mesh same-shape blends): §70. All 29 named updates and their equations: §67.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/parallel"
	"github.com/openfluke/welvet/quant"
)

func main() {
	// Dense stem → 2 hemispheres (add) → Dense head
	s, err := parallel.Bicameral(8, 16, 1, core.ActivationLeakyReLU,
		core.DTypeFloat32, quant.FormatNone)
	if err != nil {
		panic(err)
	}
	// Mix: left hemi StepBP, right hemi StepTweenChain
	hemi := s.Children[1].(*parallel.Layer)
	hemi.SetBranchModes(parallel.ModeStepBP, parallel.ModeStepTweenChain)

	x := core.NewTensor[float32](1, 8)
	t := core.NewTensor[float32](1, 1)
	t.Data[0] = 0.5
	loss, err := parallel.TrainStackMSE(s, x, t, parallel.ModeStepBP, 0.01)
	fmt.Println("loss", loss, "err", err)
}

loss 0 err <nil>

github.com/openfluke/welvet/layers/metacognition✅

Why it exists

Observed layers can apply heuristic stability rules (gate/scale/reset) without dtype morph/QAT.

What it is

Wraps Dense + DefaultStabilityRules(); Stats exposed. Full timed matrix + train grids.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/metacognition"
)

func main() {
	l, err := metacognition.New(metacognition.Config{
		Dim: 16, Rules: metacognition.DefaultStabilityRules(),
	})
	if err != nil {
		panic(err)
	}
	x := core.NewTensor[float32](1, 16)
	_, y, err := metacognition.Forward(l, x)
	fmt.Println(len(y.Data), err)
}

16 <nil>

github.com/openfluke/welvet/runtime/forward✅

Why it exists

A grid of heterogeneous ops needs one walker that dispatches by concrete type and fails loudly on unknowns.

What it is

Forward[T](grid, input) → Result tape; Cell[T] for single-cell dispatch. Covers Dense…Residual + extended wired ops.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/architecture"
	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/dense"
	"github.com/openfluke/welvet/runtime/forward"
)

func main() {
	g := architecture.NewGrid(1, 1, 1, 1)
	l, _ := dense.New(8, 8, core.ActivationLinear, core.DTypeFloat32)
	_ = dense.Place(g, 0, 0, 0, 0, l)
	res, err := forward.Forward(g, core.NewTensor[float32](1, 8))
	fmt.Println(res != nil, err)
}

true <nil>

github.com/openfluke/welvet/runtime/backward✅

Why it exists

Training needs a reverse tape over the same ops forward used — no separate graph framework.

What it is

Backward[T](fwdResult, gradOut) walks the tape and returns per-op weight grads.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/architecture"
	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/dense"
	"github.com/openfluke/welvet/runtime/backward"
	"github.com/openfluke/welvet/runtime/forward"
)

func main() {
	g := architecture.NewGrid(1, 1, 1, 1)
	l, _ := dense.New(4, 4, core.ActivationLinear, core.DTypeFloat32)
	_ = dense.Place(g, 0, 0, 0, 0, l)
	fwd, _ := forward.Forward(g, core.NewTensor[float32](1, 4))
	bwd, err := backward.Backward(fwd, core.NewTensor[float32](1, 4))
	fmt.Println(bwd != nil, err)
}

true <nil>

github.com/openfluke/welvet/runtime/training✅

Why it exists

Suites and small nets need MSE+SGD and tween hooks without inventing an external trainer or a retained float32 master beside storage.

What it is

MSE/MSEGrad, SGD, Step, ApplyTween/StepTween, StepMesh. Layer-agnostic ApplyGradSGD dispatch (Dense…Mamba/GDN/…). FormatNone: in-dtype ApplySGD; packed: unpack→update→re-Pack. No QAT dual path — storage dtype/format is truth after every step. Sandwich credit (Split / FastProxy / Sparse / …) lives in layers/parallel TrainMode — see §67.

Grid training.Step is MSE + backprop on a volumetric tape. Cameral Mix and the 29 named credit updates use parallel.TrainStackMSE (and Mesh* schedulers) so hemispheres can disagree. Equations, rival metric (hard Acc vs StepBP), and Lucy Score honesty: §67.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/architecture"
	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/dense"
	"github.com/openfluke/welvet/runtime/forward"
	"github.com/openfluke/welvet/runtime/training"
)

func main() {
	g := architecture.NewGrid(1, 1, 1, 1)
	l, _ := dense.New(4, 4, core.ActivationLinear, core.DTypeFloat32)
	_ = dense.Place(g, 0, 0, 0, 0, l)
	fwd, _ := forward.Forward(g, core.NewTensor[float32](1, 4))
	loss, err := training.Step(fwd, core.NewTensor[float32](1, 4), 1e-2)
	fmt.Println(loss, err)
}

0 <nil>

github.com/openfluke/welvet/runtime/step✅

Why it exists

Spatial feedback (remote links) needs a discrete-time mesh where every cell updates from a double buffer — different from a decoder wavefront. Cross-numeric train also needs the same mesh with weight DType ⊥ activation Tensor[T].

What it is

State[T], StepForward/StepBackward/StepApplyTween / StepMesh across the grid for all wired Ops × dtype × quant × CPU/SIMD. W2A Cross-Numeric Train: polyops.AllKinds() × weight dtype × act host (smoke ~21×7×5 ≈ 735; full ~21×34×15 ≈ 10.7k) — asserts no retained f32 master after StepMesh. Stack Step* is a different clock: IsLineStep / TrainLine (1D pipe) — see §67.

Two clocks named Step

This package is the volumetric mesh: every grid cell hops from a double buffer. MeshBP / MeshTween / MeshTweenChain call it.

Stack Step* (IsLineStep) is a 1D systolic pipe on a Sandwich — not this mesh. One sample enters child 0 per TrainStackMSE tick; every in-flight sample advances one layer; the output/train event is the sample that entered depth ticks ago. Fill ticks do not update. Serve stays a full ForwardStack. Mesh* still needs a Grid. Named updates: §67.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/architecture"
	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/dense"
	"github.com/openfluke/welvet/runtime/step"
)

func main() {
	g := architecture.NewGrid(1, 1, 1, 1)
	l, _ := dense.New(4, 4, core.ActivationLinear, core.DTypeFloat32)
	_ = dense.Place(g, 0, 0, 0, 0, l)
	st := step.New[float32](g)
	_, err := step.StepForward(g, st, false)
	fmt.Println(err)
}

<nil>

github.com/openfluke/welvet/systems/dna✅

Why it exists

Quant and train must be measurable as topology/weight fingerprints — DNA detects logic shifts.

What it is

ExtractDNA, CompareNetworks, CosineSimilarity, FlattenOp / CollectStores across dtype×quant.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/architecture"
	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/dense"
	"github.com/openfluke/welvet/systems/dna"
)

func main() {
	g := architecture.NewGrid(1, 1, 1, 1)
	l, _ := dense.New(4, 4, core.ActivationLinear, core.DTypeFloat32)
	_ = dense.Place(g, 0, 0, 0, 0, l)
	a := dna.ExtractDNA(g)
	fmt.Println(dna.CompareNetworks(a, a))
}

{1 map[0,0,0,0:1] []}

github.com/openfluke/welvet/systems/evolution✅

Why it exists

Topology search and weight crossover need first-class splice + NEAT on CPU-resident grids.

What it is

SpliceDNA, NEATMutate, NewNEATPopulation, CloneGrid — dtype/quant preserved via SetFromF32.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/architecture"
	"github.com/openfluke/welvet/systems/evolution"
)

func main() {
	a, b := architecture.NewGrid(1, 1, 1, 1), architecture.NewGrid(1, 1, 1, 1)
	child, err := evolution.SpliceDNA(a, b, evolution.DefaultSpliceConfig())
	if err != nil {
		fmt.Println(err)
		return
	}
	_, err = evolution.NEATMutate(child, evolution.DefaultNEATConfig(16))
	fmt.Println(err)
}

<nil>

github.com/openfluke/welvet/systems/tween✅

Why it exists

Target propagation (chain-rule or Hebbian layerwise gaps) is an alternative credit-assignment path. Not the same package as TrainMode Tween / TweenChain on a Sandwich (those are layers/parallel — §67).

What it is

NewState, Forward, BackwardChainRule / BackwardLayerwise, ApplyGaps; SIMD DotTile/Saxpy budgets.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/architecture"
	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/systems/tween"
)

func main() {
	g := architecture.NewGrid(1, 1, 1, 1)
	st := tween.NewState[float32](g, tween.DefaultConfig())
	_, err := tween.Forward(g, st, core.NewTensor[float32](1, 4))
	fmt.Println(err)
}

forward: no op at {0 0 0 0} (type Dense)

github.com/openfluke/welvet/systems/tanhi✅

Why it exists

Training visualization must never block the engine — best-effort UDP JSON-lines to a HUD.

What it is

TANHI = Tensor Activation Network Holographic Interface. Sparse non-blocking JSON-line UDP events for per-layer forward/backward HUD visualization (timing, dtypes, shapes, routing links, parallel branches/combine). v1.1.1: grid BP, cameral stack/parallel train (all mode families), step mesh; ConfigureGrid, SetTanhi, topology bridge. ConfigFromGrid, Emit/EmitSweep, DefaultUDPPort (17481). SoulGlitch-style consumers.

package main

import (
	"github.com/openfluke/welvet/architecture"
	"github.com/openfluke/welvet/systems/tanhi"
)

func main() {
	g := architecture.NewGrid(1, 1, 1, 1)
	cfg := tanhi.ConfigFromGrid(g)
	tanhi.EmitSweep(cfg, "epoch-0") // non-blocking best-effort
}

(no output)

github.com/openfluke/welvet/systems/telemetry✅

Why it exists

Static structural blueprints (sizes, op kinds) differ from live TANHI events.

What it is

ExtractNetworkBlueprint, ExtractLayerTelemetry for introspection/UIs.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/architecture"
	"github.com/openfluke/welvet/systems/telemetry"
)

func main() {
	g := architecture.NewGrid(1, 1, 1, 1)
	bp := telemetry.ExtractNetworkBlueprint(g, "demo")
	fmt.Printf("%+v\n", bp)
}

{ID:demo TotalLayers:1 TotalParams:0 Layers:[{Z:0 Y:0 X:0 L:0 Type:Dense Activation:ReLU Parameters:0 InputShape:[] OutputShape:[] Branches:[] CombineMode:}]}

github.com/openfluke/welvet/model/entity✅

Why it exists

HF safetensors are awkward for native topology + packed weights. ENTITY is the Welvet checkpoint.

What it is

Open/Inspect/IsEntity, LoadBlob/LoadQuantBlob, PackFromHF/ImportFromHF, WriteTransformerFile, SerializeNetwork, WriteCameralFile / LoadCameral (sandwich Stack + TrainMode).

package main

import (
	"fmt"

	"github.com/openfluke/welvet/model/entity"
)

func main() {
	info, err := entity.Inspect("model.entity")
	if err != nil {
		fmt.Println(err)
		return
	}
	ef, err := entity.Open("model.entity")
	if err != nil {
		panic(err)
	}
	defer ef.Close()
	fmt.Println(info, ef.HasTokenizerBlob())
}

open model.entity: no such file or directory

github.com/openfluke/welvet/model/hf✅

Why it exists

Import starts with probing HF/MLX layouts before packing ENTITY.

What it is

InspectSnapshot, DetectArchitecture, safetensors/MLX loaders, Qwen3.5 hybrid helpers.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/model/hf"
)

func main() {
	info, err := hf.InspectSnapshot("/path/to/hf-snapshot")
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(info)
}

hf: config.json: stat /path/to/hf-snapshot/config.json: no such file or directory

github.com/openfluke/welvet/model/tokenizer✅

Why it exists

Generate needs encode/decode of HF tokenizer.json without pulling Python.

What it is

LoadTokenizer, Encode/Decode, LoadForEntity.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/model/tokenizer"
)

func main() {
	tok, err := tokenizer.LoadTokenizer("tokenizer.json")
	if err != nil {
		fmt.Println(err)
		return
	}
	ids := tok.Encode("hello welvet", true)
	fmt.Println(ids, tok.Decode(ids, true))
}

failed to read tokenizer file: open tokenizer.json: no such file or directory

github.com/openfluke/welvet/model/sampling✅

Why it exists

Logits → token ID needs ArgMax, TopK+temperature, penalties, and chat hygiene in one place.

What it is

ArgMax, SampleTopK, ApplyRepetitionPenalty, BanIDs, SanitizeChatReply.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/model/sampling"
)

func main() {
	logits := []float32{0.1, 2.4, 0.3, -1}
	fmt.Println(sampling.ArgMax(logits))
	fmt.Println(sampling.SampleTopK(logits, 2, 0.8, true))
}

1
1

github.com/openfluke/welvet/model/transformer✅

Why it exists

ENTITY packs must run as Llama-style decoders with KV cache, profiles (SIMD/WebGPU/fused), and chat templates.

What it is

LoadEntity → Model; Generate; ApplyExec profiles; ExportFusedGPUSpec / hybrid sync.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/model/tokenizer"
	"github.com/openfluke/welvet/model/transformer"
)

func main() {
	m, err := transformer.LoadEntity("model.entity")
	if err != nil {
		fmt.Println(err)
		return
	}
	tok, err := tokenizer.LoadTokenizer("tokenizer.json")
	if err != nil {
		panic(err)
	}
	if err := m.ApplyExec(transformer.ProfileSIMDMultiCore()); err != nil {
		panic(err)
	}
	text, _, err := m.Generate(
		tok.Encode, tok.Decode, nil,
		"You are helpful.", "Say hi.",
		transformer.GenOptions{MaxTokens: 32, Silent: true},
	)
	fmt.Println(text, err)
}

open model.entity: no such file or directory

github.com/openfluke/welvet/apps/…🚧

Why it exists

Products must not pollute engine packages. Octo is the model shell; flux2/mosstts are domain apps. Lucy races (AAI test41 / test48 / test50) are benches, not Welvet packages.

What it is

octo (own module): download/convert/chat, see §44. flux2: MMDiT image. mosstts: Speak/SpeakToFile pipeline. AAI sandwiches race TrainMode on toys — see §68. Off the v1.0 engine board.

The engine never imports apps. AAI is a separate Lucy harness that replaces github.com/openfluke/welvet. It is how we talk about cameral Mix and credit modes with numbers (hard Acc, SoftAcc, Score) instead of slogans. Public API stays in layers/parallel + lucy.

package main

import "fmt"

func main() {
	fmt.Println("Apps import the engine — the engine never imports apps.")
	fmt.Println("  cd apps/octo && go run .")
	fmt.Println("  cd apps/flux2 && go run .")
	fmt.Println("  cd apps/mosstts && go run .")
}

Apps import the engine — the engine never imports apps.
  cd apps/octo && go run .
  cd apps/flux2 && go run .
  cd apps/mosstts && go run .

cd apps/octo && go run .   # when module wired

github.com/openfluke/welvet/apps/octo✅ runs

Why it exists

A model is only useful with a shell around it: pull weights from Hugging Face, convert them to a Welvet .entity, then chat, serve, or benchmark. Octo is that shell, kept in its own module so the engine never depends on an app.

What it is

Subcommands cover the whole loop: hub download/ensure repos, convert pack to a single .entity, interactive run/serve/chat, plus image and speech menus. Its bench harness sweeps every quant format across a CPU Plan 9 SIMD fused profile and a WebGPU fused profile.

Bench: SmolLM2-135M-Instruct across quant formats

template smol2-135m-fuse · linux/amd64 · NVIDIA GTX 1650 SUPER · 3m17s · 80 runs (76 ok, 4 skipped: "none" has no fused kernel). Throughput is total tokens/s on the first prompt; entity is on-disk size.

21 quant formats run end to end; the table shows a representative slice. Full report: apps/octo/dist/octo-run-v0.76.txt.

Sample replies

Q8_0  / gpu   I'm a helpful assistant. I'm here to help you with your inquiries.
Q4_0  / gpu   I'm ready to help. What can I help you with?
Q6_K  / gpu   2 + 2 is 4.
Q6_K  / simd  I'm a helpful assistant.
IQ2_XXS/gpu   ,))hidAPAAPAAPAAPAAPA...   (sub-2-bit degrades)

package main

import "fmt"

func main() {
	fmt.Println("Octo is its own module — the engine never imports it.")
	fmt.Println("  cd apps/octo && go run .")
	fmt.Println("  download -> convert -> .entity -> chat / serve / bench")
}

Octo is its own module — the engine never imports it.
  cd apps/octo && go run .
  download -> convert -> .entity -> chat / serve / bench

cd apps/octo && go run .

github.com/openfluke/welvet/stub/seed🚧

Why it exists

Ship topology recipes (layer seeds → He-init) without weight blobs.

What it is

SeedFrom/From, RNG, InitStoreHe, Dense/MHA/SwiGLU/CNN infinite manifests.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/stub/seed"
)

func main() {
	s := seed.From("demo-net", 0)
	rng := seed.New(s)
	fmt.Println(rng.NormFloat64())
}

0.4118750632366808

github.com/openfluke/welvet/stub/serialization🚧

Why it exists

Volumetric grids need JSON/ENTITY persist beyond transformer packs.

What it is

SerializeEntity/LoadEntity, SerializeGrid/GridFromSpec — native FormatNone bytes; packed via wire.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/architecture"
	"github.com/openfluke/welvet/stub/serialization"
)

func main() {
	g := architecture.NewGrid(1, 1, 1, 1)
	raw, err := serialization.SerializeGrid(g)
	fmt.Println(len(raw), err)
}

101 <nil>

github.com/openfluke/welvet/stub/memory🚧

Why it exists

HF→ENTITY and GPU upload need footprint accounting and optional history charts.

What it is

FromGrid, Footprint, InitScavenger, ReleaseTransient; WELVET_MEMORY_HISTORY=1.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/architecture"
	"github.com/openfluke/welvet/stub/memory"
)

func main() {
	g := architecture.NewGrid(1, 1, 1, 1)
	fp := memory.FromGrid(g)
	fmt.Printf("%+v\n", fp)
}

{HostWeightsMB:0 GPUWeightsMB:0 GPUKVMB:0}

github.com/openfluke/welvet/stub/donate🚧

Why it exists

LAN donors should accept framed JSON jobs without embedding HTTP in the engine.

What it is

u32-LE + JSON frames; ServeTCP/Dial; model_push vs local_lm. v0 workers echo.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/stub/donate"
)

func main() {
	fmt.Println("default port", donate.DefaultPort)
	// ln, err := donate.ServeTCP(donate.ServerOptions{Addr: ":17001", Mode: donate.ServerLocalLM})
}

default port 17001

github.com/openfluke/welvet/stub/fountain🚧

Why it exists

Recover specialist weight blobs over lossy links via LT fountain codes, then ensemble.

What it is

NewLTEncoder/Decoder, RecoverWeightBlobs, Neural/DenseFactory helpers.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/stub/fountain"
)

func main() {
	src := [][]byte{make([]byte, 64), make([]byte, 64), make([]byte, 64)}
	enc, err := fountain.NewLTEncoder(src, 42)
	fmt.Printf("%T %v\n", enc, err)
}

*fountain.LTEncoder <nil>

github.com/openfluke/welvet/stub/hardware🚧

Why it exists

Dispatchers and UIs need a portable host audit (OS/CPU/RAM/GPU).

What it is

Audit() → SystemAudit with linux /proc or platform fallbacks.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/stub/hardware"
)

func main() {
	a := hardware.Audit()
	fmt.Printf("%+v\n", a.CPU)
	fmt.Println(hardware.Description())
}

{Model:Intel(R) Core(TM) i5-10400 CPU @ 2.90GHz Logical:12 GOMAXPROCS:12}
OS: linux | CPU: Intel(R) Core(TM) i5-10400 CPU @ 2.90GHz (12) | RAM: 31.12 GB | GPU: Unknown GPU (0.0 GB)

github.com/openfluke/welvet/stub/accel⬜

Why it exists

Vendor accelerators (Intel NPU, Qualcomm QNN, Apple Metal) will plug beside WebGPU — not replace it.

What it is

Package is doc.go only today (⬜). No symbols yet; reserved for plugin loader design.

package main

// import "github.com/openfluke/welvet/stub/accel"
// No exported API yet — see package doc.go for intent.

func main() {}

(no output)

github.com/openfluke/welvet/stub/clustering🚧

Why it exists

Offline clustering helpers on tensors without inventing a second math stack.

What it is

KMeansCluster, HierarchicalGroup, distance/silhouette helpers.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/stub/clustering"
)

func main() {
	pts := []*core.Tensor[float32]{
		core.NewTensor[float32](2),
		core.NewTensor[float32](2),
	}
	pts[0].Data[0], pts[0].Data[1] = 0, 0
	pts[1].Data[0], pts[1].Data[1] = 1, 1
	cent, assign := clustering.KMeansCluster(pts, 2, 10, false)
	fmt.Println(len(cent), assign)
}

2 [0 1]

github.com/openfluke/welvet/stub/ensemble🚧

Why it exists

Combine multiple model votes and find complementary specialists.

What it is

MajorityVote, FindComplementaryMatches, PerformanceSimilarity.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/stub/ensemble"
)

func main() {
	votes := [][]int{{0, 1, 1}, {0, 0, 1}, {0, 1, 0}}
	fmt.Println(ensemble.MajorityVote(votes))
}

[0 1 1]

github.com/openfluke/welvet/stub/evaluation🚧

Why it exists

Benchmark grids through runtime/forward with deviation metrics.

What it is

EvaluateNetwork, MultiNetworkEvaluation, DeviationMetrics.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/architecture"
	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/stub/evaluation"
)

func main() {
	g := architecture.NewGrid(1, 1, 1, 1)
	in := []*core.Tensor[float32]{core.NewTensor[float32](1, 4)}
	rep, err := evaluation.EvaluateNetwork(g, in, []float64{0, 0, 0, 0})
	fmt.Println(rep, err)
}

<nil> evaluation: length mismatch inputs=1 expected=4

github.com/openfluke/welvet/stub/grafting🚧

Why it exists

Merge grids into Parallel/Residual structures for topology experiments.

What it is

GraftGrids, ResidualGraft, GraftToGrid — Dense branches in v0.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/architecture"
	"github.com/openfluke/welvet/layers/parallel"
	"github.com/openfluke/welvet/stub/grafting"
)

func main() {
	a, b := architecture.NewGrid(1, 1, 1, 1), architecture.NewGrid(1, 1, 1, 1)
	out, err := grafting.GraftGrids([]*architecture.Grid{a, b}, parallel.CombineConcat)
	fmt.Println(out != nil, err)
}

false grafting: no valid branches

github.com/openfluke/welvet/stub/grouping🚧

Why it exists

Detect layer archetypes from safetensor-style names before mounting.

What it is

GroupRelatedTensors, DetectMHA/DetectSwiGLU/DetectRMSNorm → ArchetypeHint.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/stub/grouping"
)

func main() {
	tensors := []grouping.DetectedTensor{
		{Name: "model.layers.0.self_attn.q_proj.weight"},
		{Name: "model.layers.0.self_attn.k_proj.weight"},
		{Name: "model.layers.0.self_attn.v_proj.weight"},
		{Name: "model.layers.0.self_attn.o_proj.weight"},
	}
	ok, hint := grouping.DetectMHA("block0", tensors, 64, 4)
	fmt.Println(ok, hint)
}

true {MultiHeadAttention 64 4}

github.com/openfluke/welvet/stub/introspection🚧

Why it exists

UIs and FFI need to list Grid methods without hardcoding every export.

What it is

GetMethods, GetMethodsJSON, GetMethodSignature.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/architecture"
	"github.com/openfluke/welvet/stub/introspection"
)

func main() {
	g := architecture.NewGrid(1, 1, 1, 1)
	methods, err := introspection.GetMethods(g)
	fmt.Println(len(methods), err)
}

9 <nil>

github.com/openfluke/welvet/stub/observer🚧

Why it exists

Attach forward/backward observers for debugging without coupling to tanhi UDP.

What it is

Observer interface; ConsoleObserver / HTTPObserver / BufferObserver; ComputeLayerStats.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/stub/observer"
)

func main() {
	var obs observer.Observer = &observer.ConsoleObserver{}
	fmt.Printf("%T\n", obs)
}

*observer.ConsoleObserver

github.com/openfluke/welvet/stub/pipeline🚧

Why it exists

Decoder wavefront stats helpers — not a full Lucy-style pipeline runner yet.

What it is

PipelineForwardStats, TokenTimelineSummary.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/stub/pipeline"
)

func main() {
	var s pipeline.PipelineForwardStats
	fmt.Printf("%+v\n", s)
}

{PipelineTicks:0 SubLayerOps:0 MaxActiveJobs:0 MaxBlockSpread:0 MaxDistinctBlocks:0 MaxPendingTokens:0 StallFallback:false TokenDoneTick:[]}

github.com/openfluke/welvet/stub/templates🚧

Why it exists

Chat prompts must match model families (ChatML, Llama3, BitNet) without app-specific string glue.

What it is

Template.BuildPrompt; presets ChatML, Llama3, BitNetInstruction, MicrosoftBitNetChat.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/stub/templates"
)

func main() {
	p := templates.ChatML.BuildPrompt(nil, "You are helpful.", "Say hi")
	fmt.Println(p)
}

<|im_start|>system
You are helpful.
<|im_start|>user
Say hi
<|im_start|>assistant

github.com/openfluke/welvet/stub/universal🚧

Why it exists

Probe unknown safetensor geometry and mount placeholder grids until full weight import lands.

What it is

LoadUniversal / LoadUniversalDetailed, ProbeDeepGeometry, MountGeometrically.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/stub/universal"
)

func main() {
	g, err := universal.LoadUniversal("/path/to/snapshot")
	fmt.Println(g != nil, err)
}

false universal: "/path/to/snapshot": open /path/to/snapshot: no such file or directory

github.com/openfluke/w2a✅ harness

Why it exists

Engine packages must stay free of tests. w2a owns timed 34×20×3 matrices, gap census, honesty stamps, and the train-mode permutation smoke (Test49). See §63 for a live full-suite run.

What it is

Interactive go run . ([0] Run ALL). Suites under suites/*. StampBackendNote / AffinePackable prevent fake ✅. Test49: AllNamedTrainModes × 1³/2³/3³ × Parallel/Bicameral/poly, origin-only — included in [0].

package main

import "fmt"

func main() {
	fmt.Println("w2a is a separate module — engine packages never contain tests.")
	fmt.Println("")
	fmt.Println("  cd w2a")
	fmt.Println("  go run .                                      # interactive; [0] = ALL")
	fmt.Println("  go test ./tests/dense -v")
	fmt.Println("  go test ./tests/parallel -run Test49AllTrainModesCubes -count=1 -v")
}

w2a is a separate module — engine packages never contain tests.

  cd w2a
  go run .                                      # interactive; [0] = ALL
  go test ./tests/dense -v
  go test ./tests/parallel -run Test49AllTrainModesCubes -count=1 -v

cd w2a && go run .
cd w2a && go test ./tests/dense -v && go test ./tests/parallel -run Test49AllTrainModesCubes -count=1 -v

github.com/openfluke/w2a✅ 246k cells

Why it exists

Claims are cheap; a stamped matrix is not. This is the actual output of one full w2a [0] Run ALL so the book's ✅ marks are backed by numbers you can reproduce, not asserted.

What it is

Every timed layer sweeps its dtype × format × backend matrix; every suite runs its case checks. v1.0 board: 246,032 matrix cells, FAIL 0, RESULT PASS. GAP cells are declared skips (not silent fails).

What grew since the 228k board

• Test49 — 29 named TrainModes × 1³/2³/3³ × Parallel + Bicameral + poly kinds (origin-only). All cells OK.
• Cameral perm — Mix / BranchModes / credit on sandwiches (OK cells + declared GAP on exotic dtypes).
• Nested Sequential / Residual mixed children + ResidualGraft.
• Mesh* credit tokens on the named-mode list (stack family on a grid walk).

Do not quote this stamp as a Lucy race or “beats PyTorch.” It is surface coverage: every claimed path either runs or is stamped GAP. Lucy Acc vs Score lives in AAI test50 (§68).

Cross-numeric train

W2A Step includes Cross-Numeric Train (kinds × weight dtype × act host; full census ~10.7k under the train op). Storage truth checked after StepMesh — no retained f32 master for non-float32 FormatNone. Public Dense demotion + W×A showcase: down-the-dem (chapter 65).

package main

import "fmt"

func main() {
	cells := 246032
	fmt.Printf("w2a [0] ALL: %d cells  FAIL 0  RESULT PASS\n", cells)
	fmt.Println("GAP = declared skip (GDN non-f32, AffinePacked, …) — not a fail")
}

w2a [0] ALL: 246032 cells  FAIL 0  RESULT PASS
GAP = declared skip (GDN non-f32, AffinePacked, …) — not a fail

cd w2a && go run .   # [0] Run ALL; writes logs/suite.txt

v1.1.1

Why it exists

Version is earned from a weighted board, not marketing. v1.0 is 100/100 on the engine board. Minor/patch tags (v1.1.0, v1.1.1, …) pack features without a new board. Apps, stubs, and NPU sit off-board.

What it is

version = 0.{round(earned)} until 100 → v1.0. Scorecard today 100/100; this book tags v1.1.1. Training credit is §9 on the board (8 pts), not an afterthought.

v1.0 cut

• w2a [0] ALL — 246,032 cells, FAIL 0, RESULT PASS (§63)
• Training credit — StepBP, Tween*, Split, Alt, HeadProxy, FastProxy, Linear, Sparse, Step* pipe twins, Mesh* (§67)
• Cameral — Hemispheres, Mix BranchModes, Sandwich, ResidualGraft, cameral .entity (§68)
• CamSync — soft/hard inter-cameral + cross-layer same-shape weight blend (§70)
• Nested Sequential/Residual mixed children (Dense/SwiGLU/RMSNorm/LayerNorm)
• lucy — SoftAcc / Availability / Score + BuildLPD density (§66 · §69)
• v1.0.3 — Dense FormatNone SIMD forward: WireF64/DotTileF64, expand-once, BF16 convert; ~4.3× geo-mean on 34-dtype deep suite vs prior Go; Dense-backed projs inherit (§6 · §11)
• v1.1.1 — Cam adjusting fixed: CamSync on all layers (§70)
• v1.1.0 — CamSync + training_modes.md + Lucy Lean density + book §70 (§70 · §69)

package main

import "fmt"

func main() {
	earned := 100.0
	fmt.Println("v1.1.1")
	fmt.Printf("scorecard %.0f/100\n", earned)
}

v1.1.1
scorecard 100/100

github.com/openfluke/welvet/runtime/training✅

Why it exists

Weight storage dtype and activation Tensor[T] are independent axes. Proving train without a retained float32 master means sweeping W×A — not only matched float32 acts.

What it is

W2A Step Cross-Numeric Train: polyops.AllKinds() × FormatNone weight dtype × Go Numeric act host (smoke ~735; full ~10.7k) via StepMesh, then assert no retained f32 master. Public Dense volumetric showcase: down-the-dem — dtype demotion ladder, packed quants, and the full 34×15×3 perm matrix with charts/PDF.

down-the-dem — same 5-layer Dense stack on cubes 1³ / 2³ / 3³; only the number story changes:

• dtype — FormatNone demotion (wide → 1-bit), in-dtype SGD
• quant — packed formats; unpack → update → re-Pack
• perm — every weight dtype × every act host (1,530 cells on three grids)

Repo + report: github.com/openfluke/down-the-dem · PDF: report/down-the-dem.pdf in that repo. Honesty: runnable storage-truth train ≠ task accuracy or native low-precision GEMV ALU.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/architecture"
	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/dense"
	"github.com/openfluke/welvet/quant"
	"github.com/openfluke/welvet/runtime/training"
)

func main() {
	// Weight storage: int8 FormatNone. Activations/grads: Tensor[int8].
	g := architecture.NewGrid(1, 1, 1, 1)
	init := make([]float32, 4*4)
	for i := range init {
		init[i] = 0.1
	}
	l, err := dense.NewConfigured(4, 4, core.ActivationLinear, core.DTypeInt8, quant.FormatNone, init)
	if err != nil {
		panic(err)
	}
	if err := dense.Place(g, 0, 0, 0, 0, l); err != nil {
		panic(err)
	}
	x := core.NewTensor[int8](1, 4)
	y := core.NewTensor[int8](1, 4)
	for i := 0; i < 4; i++ {
		x.Data[i] = int8(i + 1)
		y.Data[i] = int8(i)
	}
	loss, _, err := training.StepMesh(g, x, y, 1, 0.05)
	fmt.Println(loss, err, l.Weights.RetainsF32Master())
}

1.5 <nil> false

github.com/openfluke/welvet/lucy✅

Why it exists

Adaptation benches (test41-w, tide, live_gpt) need one shared measuring math — SoftAcc, Availability, AdaptPct, Score — not three copies of the formulas.

What it is

Pure measuring package: SoftAcc / SoftAccProb, Window + Snapshot, Finalize. No datasets, no train loops. Sine scale 0.10; classification SoftAccProb scale 1.0. Density / synthetic-organism board is §69.

SoftAcc      = 100 × (1 − |pred−target| / scale)   clamped [0,100]
Availability = InferMs / (InferMs + TrainMs) × 100
Score        = Throughput × Availability × Acc / 10_000
Acc          = hard argmax % (AvgAccuracy) — the Acc pillar
AdaptPct     = mean SoftAcc in AdaptWindows after each switch

tide/metrics re-exports this package for existing tide callers. Engine tests for lucy live under w2a/tests/lucy.

AAI Lucy benches (private tree, replace → public Welvet): test41 native cam, test48 credit sweep, test50 23-mode FP32 race. Harness is not an engine package. Pulse math is this chapter. Density board: §69. Modes + equations: §67. Cameral sandwiches: §68.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/lucy"
)

func main() {
	a := lucy.SoftAccOne(0.72, 0.80) // sine scale 0.10
	p := lucy.SoftAccProb(0.91, 1.0) // class scale 1.0
	var snap lucy.Snapshot
	snap.AvgAccuracy = 80
	snap.SoftAcc = a
	snap.InferMs = 8
	snap.TrainMs = 2
	snap.Throughput = 12000
	lucy.Finalize(&snap, lucy.Options{AdaptWindows: 10})
	fmt.Printf("soft=%.1f class=%.1f avail=%.1f score=%.0f\n",
		a, p, snap.Availability, snap.Score)
}

soft=20.0 class=91.0 avail=80.0 score=7680

github.com/openfluke/welvet/layers/parallel✅ 29 modes

Why it exists

Backprop is one update, not the only one. Credit assignment (broadcast gap, head proxy, sparse duty clock) has to be a named axis you can race — not a comment in a notebook. Cameral Mix also needs one TrainMode per hemisphere on the same loss.

What it is

parallel.TrainMode: AllNamedTrainModes() = 29 (Inherit omitted). Stack-local Split/Alt plus Step* 1D pipe twins and Mesh* grid schedulers. TrainStackMSE / TrainStackCE honour BranchModes. Display names use Short() / ShortTrainMode. Rival metric is hard Acc vs StepBP; Lucy Score is Tput × Avail × Acc — do not mix those sentences.

Loss gap (MSE or CE)

MSE:  L = (1/d) ||ŷ − t||²     g_y = (2/d)(ŷ − t)
CE:   L = −mean log softmax(ŷ)_class     g_y = (p − t) / B

Head always sees g_y. Classification hosts call TrainStackCE so Acc can leave chance; MSE on a one-hot stays uniform. What each mode does with g_y is the whole story.

Families (29 named tokens)

AllCreditTrainModes() = 16 stack-local Split/Alt plus Step* credit twins (no Mesh). AllMeshCreditTrainModes() = 4 Mesh credit (no HeadProxy / Linear / LinearCache / HeadProxyAsync Mesh twins). AllStackLocalTrainModes() = 22 (no Inherit, no Mesh*). AllNamedTrainModes() = 29 — the Test49 / test50 set. IsLineStep() = 11 (StepBP, StepTween, StepTweenChain, StepTweenSplit, StepTweenAlt, plus the six Step* credit twins).

Tables and logs use Short() / ShortTrainMode (legend: [T]=Tween [S]=Split [FP]=FastProxy [L]=Linear [HP]=HeadProxy). Persistence and ParseTrainMode still use the full String() token. New Step* iota values were appended so old uint8 numbers stay stable.

Equations

Backprop (the rival)

head:   g_head = J_head^T g_y
hemi:   g_hemi = J_hemi^T g_head
stem:   g_stem = J_stem^T g_hemi
dW_i from local Backward(g_i, x_i)

SIMD GEMV. This is who FastProxy has to beat on hard Acc — not Lucy Score.

Tween — broadcast, half LR

g_i = P(g_y)     η ← η/2
dW_i = localBackward(g_i, x_i)

Blind to W^T sign. Sine Acc collapses. MeshTween is the volumetric scheduler of this family, not a secret FastProxy.

TweenSplit — even split

g_i = (1/N) P(g_y)

Still not J^T. Cheap Acc ceiling. Score can rise because the update is cheap (Avail), not because g is better.

TweenAlt — Split then Tween

Per sample, AltTimes times (default 1): Split from live g_y → re-forward → Tween from g_y′ (half LR). Extra forwards kill Avail → Score last.

HeadProxy

g_proxy = J_head^T g_y = W_head^T (g_y ⊙ act′(pre_head))
hidden i = 1…N−1:  g_i = 1/(N−1) P(g_proxy)
                   dW_i = g_i x_i^T     (no discarded W^T)

One real J_head^T. Hemispheres do not get J_hemi^T.

FastProxy

g_proxy = W_head^T g_y          ← skip act′
head dW still uses act′
hidden: same 1/(N−1) P(g_proxy) dW-only as HeadProxy

DFA with B := W_head^T, not a learned random B. On AAI test50 sine, FastProxy SoftAcc often sits above StepBP while both are at 100% hard Acc — that is the FastProxy vs BP sentence.

Linear

g_head↓  = g_y
g_hemi↓  = W_head^T g_y          (siblings share the vector)
g_stem↓  = Σ_hemi W_hemi^T g_hemi↓
then every leaf: g_i = (1/N) P(g_i↓),  dW_i = g_i x_i^T

Same O(N²) class as backprop. Score stays StepBP-class unless Acc is way up.

LinearCache — dead control

every 20 steps: full Linear walk, cache g_i↓
else: g_i ← g_i^cache · ||g_y||_live / ||g_y||_cache

Norm scaling cannot recover sign flips after a frequency switch. If this wins sine, the board is lying.

HeadProxyAsync

g_hidden^(T) = 1/(N−1) P(g_proxy^(T−1))
head computes g_proxy^(T) = W_head^T g_y^(T) for next step

First sample seeds live. Stale sign on XOR. Not EMA.

Sparse — duty clock

g_proxy = W_head^T g_y
dW_head = g_y x_head^T
k = t mod (N−1)
dW_k    = P(g_proxy) x_k^T
other leaves: dW = 0 this sample

Real FLOP cut → Avail 40–50% → Lucy Score explodes. That is a duty clock, not a smaller big-O than backprop and not a better chain rule. On test50 copy, Sparse often loses Acc vs StepBP while winning Score.

Step* — 1D systolic pipe

The Step prefix on a stack mode is a schedule, not a second leftover-forward pass and not Mesh*. IsLineStep → TrainLine / trainStackLine: one sample enters child 0 per tick; every in-flight sample advances one layer; the output (and the train event) is the sample that entered D ticks ago. Fill ticks do not update. Serve stays a full ForwardStack.

Same family update on the Sandwich whether Step or not — HeadProxy / Linear / FastProxy / Sparse / Async credit walk trainTweenSplitLeaves on both twins. Mesh* still requires a Grid (RequiresGrid). There is no Mesh HeadProxy / Linear / LinearCache / HeadProxyAsync.

Mesh*

MeshBP = volumetric training.Step. MeshTween = StepMesh. MeshTweenChain = StepTween. Mesh Split / Alt / FastProxy / Sparse credit the placed stack under a grid walk. On origin-only 1³/2³/3³ (rest IsDisabled) Mesh* usually matches the stack twin. Cube size is hop topology, not 27 sandwiches.

Where it is raced

• w2a Test49 — permutation smoke: 29 modes × 1³/2³/3³ × Parallel / Bicameral / poly kinds, origin-only. In [0] Run ALL. Not a Lucy race.
• AAI test48 — credit sweep (layers × dtypes × short jobs) with these equations.
• AAI test50 — FP32 Lucy race, all 29, cams 1–3, cubes 1–3. Copy: Split/Alt family +5 to +12 Acc vs StepBP. Sine: Acc ceiling; FastProxy SoftAcc is the knife. XOR: 4-point parking lot (75%). Sparse wins Score, not Acc.

Cameral why + sandwich stem→mid→head: §68. Measuring math: §66.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/layers/parallel"
)

func main() {
	named := parallel.AllNamedTrainModes()
	line := 0
	for _, m := range named {
		if m.IsLineStep() {
			line++
		}
	}
	fp, err := parallel.ParseTrainMode("stepfastproxy")
	fmt.Println("named", len(named), "linestep", line)
	fmt.Println("stepfastproxy", fp.Short(), err)
	fmt.Println(parallel.ShortTrainModeLegend)
}

named 31 linestep 11
stepfastproxy Step[T][S][FP] <nil>
[T]=Tween  [S]=Split  [FP]=FastProxy  [L]=Linear  [HP]=HeadProxy  [F]=Freeze  [Sh]=Shadow  [A]=Adv  [M]=Memory

github.com/openfluke/welvet/layers/parallel✅ cameral

Why it exists

A single Dense chain cannot host two independent weight copies that share an input, merge, and optionally train under different updates. That is the cameral graph: hemispheres, not screen-space sprites and not a second hidden size.

What it is

Hemispheres / Bicameral / Sandwich / Mix. Stem → Parallel mid → Dense head. SetBranchModes + TrainStackMSE. Lucy races in AAI (test41 / test48 / test50) import this API; measuring is lucy/; harness is not engine.

x  →  Dense stem  →  ┬→ Hemi 1 (own W, own TrainMode)
                     ├→ Hemi 2
                     └→ Hemi n     merge add|avg|concat|filter
                              → Dense head → ŷ
                              MSE → g_y → each branch’s update

Why cameral exists

Welvet already has Sequential (ordered compose) and Residual (skip). Neither is “two brains on one x.” A hemisphere is an independent sub-net with its own weights. Bi / Tri / Quad are n hemispheres plus a merge. Mix stamps a different TrainMode per hemi (SetBranchModes) so left can be StepBP while right is TweenChain — one loss on the merge. Grid training.Step applies one mode to the whole net; Mix needs TrainStackMSE or the BranchModes stamp is a lie.

The sandwich (stem → mid → head) is not extra depth for its own sake. Credit modes need a head Jacobian (or a W_head^T proxy). Without a head, FastProxy / HeadProxy have nothing to inject. Stem gets the down-going vector after hemispheres merge. That is why AAI Lucy jobs are sandwiches even when cameral count is 1 (mid is a single Dense, not Parallel).

API (engine, public)

• Hemispheres / HemispheresFrom — n twins; merge add/avg/concat/filter
• Bicameral / BicameralFrom / Sandwich — stem → Parallel → head Stack
• SetBranchModes / TrainStackMSE — Mix path
• ResidualGraft — y = F(x)+x when F is Parallel
• WriteCameralFile / LoadCameral — cameral .entity (in model/entity)
• CamSync — optional weight averaging across cams / layers → §70

Layer package chapter: §27. Named updates: §67. Weight sync across cams (and across mesh layouts when shapes match): §70.

AAI Lucy benches

AAI is a separate tree. It replaces github.com/openfluke/welvet (public chaosglue module). The engine does not import AAI. Lucy math is §66.

test50 copy: Split / Alt / MeshSplit family about +5 to +12 Acc over StepBP (~68–74%). Sine: Acc ceiling (many modes 100% including StepBP); FastProxy SoftAcc ~56–68 vs StepBP ~42–53. XOR: almost everyone at 75% (3 of 4 bits) — parking lot. Sparse wins Score, not Acc. Origin-only cubes: extra cells are disabled; 3³ is hop topology, not 27 copies.

w2a Test49 is the permutation smoke of those 29 modes (in [0] Run ALL), not a Lucy race. Do not quote Test49 as “we beat backprop.”

package main

import (
	"fmt"

	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/parallel"
	"github.com/openfluke/welvet/quant"
)

func main() {
	s, err := parallel.Bicameral(8, 16, 1, core.ActivationLeakyReLU,
		core.DTypeFloat32, quant.FormatNone)
	if err != nil {
		panic(err)
	}
	hemi := s.Children[1].(*parallel.Layer)
	hemi.SetBranchModes(parallel.ModeStepBP, parallel.ModeTweenSplitFastProxy)

	x := core.NewTensor[float32](1, 8)
	t := core.NewTensor[float32](1, 1)
	t.Data[0] = 0.5
	loss, err := parallel.TrainStackMSE(s, x, t, parallel.ModeStepBP, 0.01)
	fmt.Println("mix loss", loss, "err", err)
}

mix loss 0 err <nil>

github.com/openfluke/welvet/lucy✅ BuildLPD

Why it exists

A new host (char LM, MNIST, a layer sprint) should not copy tide's goldilocks math. The question is always the same: can the net run and train at the same time in a small box, then how far that live-fit condenses without becoming a trap. That ruler belongs in the engine.

What it is

lucy.BuildLPD ranks Samples for consciousness (Acc / Throughput / Availability keep vs learner peaks) then Lucy density (Q × shrink vs Acc-champ RAM). Gold / near / keep / trap bands, consciousness radar, and memory-density radar are computed here. Tide dash and Lucy PDF only draw the board.

WHY
  Industry ships dead calculators: INT8 inference, no on-device train.
  Synthetic organism = serve while learning, then shrink without falling
  into chance-Acc "tiny & fast" traps.

PILLARS (consciousness)
  Acc    = argmax %          (did it learn?)
  Thru   = outputs / second  (can it act while live?)
  Avail  = InferMs / busy    (can you still talk to it while it trains?)
  Score  = T × Avail × Acc / 10_000     live-fit
  SoftAcc is serve-confidence — not a pillar.

DENSITY (memory intelligence)
  Acc champ = RAM reference (best learner, not the Score champ)
  Learner   = RelAcc ≥ 70% of Acc champ   (traps do not set Thru/Avail peaks)
  Q         = geomean(RelAcc, RelThru, RelAvail)
  shrink    = AccChampRAM / thisRAM   (capped ×32)
  LPD       = Q × shrink    if RelAcc ≥ 70% else 0

BANDS
  gold  all 3 pillars ≥80% and RAM ≤20% of Acc champ
  near  Acc + (Thru or Avail) ≥80% at ≤50% RAM
  trap  RAM ≤20% and Acc keep <70%     (binary looking dense)
  Score/MiB is the trap metric — do not use it for goldilocks.

RADARS (for PDF / dash — math here, drawing in tide)
  Consciousness  = (RelAcc, RelThru, RelAvail)
  Memory density = (RelAcc, RelThru, RelAvail) × shrink   traps at origin

Why we measure this

The goal is not a better chatbot and not a paper for a faculty board. It is a synthetic organism: a net that owns time — continuous serve, continuous train, no turn-based halt, no phone-home. Lucy Score asks the thermodynamic question tide was built for: does SGD that blocks inference die, and do proxy / Split / Sparse paths keep the live loop while still learning?

Hard Acc is whether it learned. Availability is whether it still breathes. Throughput is how many actions it took while both were happening. Multiply them and you get live-fit. SoftAcc is how confident the serve looked — useful, not the Acc term.

Memory density asks the second question: once you have a learner, how far can dtype / quant / cameral width condense that live-fit versus the Acc champ's RAM without collapsing to chance Acc. A binary cell that is 30× smaller and 4× faster with 12% Acc is a trap (LPD = 0). An int8 that keeps ≥70% of Acc-champ Acc at a fifth the RAM is goldilocks.

Formulas

What tide still owns

Tide is the race: serve+train pulses, permute matrix, dashboard, Lucy PDF (including drawing the two radars). tide/report.BuildLPD pretty-prints cell IDs then calls lucy.BuildLPD. A new thing that only needs the ruler:

import "github.com/openfluke/welvet/lucy"
board := lucy.BuildLPD(samples)
_ = board.Top[0].Consciousness()  // Acc, Thru, Avail keep
_ = board.Top[0].MemoryDensity()  // same × shrink; traps at 0

Classification hosts should train with TrainStackCE so the Acc pillar can leave chance; MSE on a one-hot stays uniform. That is a loss gap in layers/parallel, not a Lucy formula.

Pulse math: §66. Train modes: §67.

package main

import (
	"fmt"

	"github.com/openfluke/welvet/lucy"
)

func main() {
	board := lucy.BuildLPD([]lucy.Sample{
		{ID: "f32", Mode: "sgd", Acc: 90, Thru: 200, Avail: 40, Score: 100, RAMKiB: 1000},
		{ID: "int8", Mode: "sgd", Acc: 82, Thru: 180, Avail: 38, Score: 85, RAMKiB: 180},
		{ID: "bin", Mode: "sgd", Acc: 12, Thru: 400, Avail: 50, Score: 40, RAMKiB: 40},
	})
	top := board.Top[0]
	fmt.Printf("lead=%s band=%s LPD=%.2f trap=%s\n",
		top.ID, top.Band, top.LPD, board.Trap[0].ID)
}

lead=int8 band=gold LPD=5.11 trap=bin

github.com/openfluke/welvet/layers/parallel✅ CamSync

Why it exists

Mix BranchModes and different inits let cams diverge on purpose. Sometimes you want them to share — gently (1% pull) or hard (full average) — within a Parallel, across Stack children, or even between same-shaped stores sitting on wildly different mesh layouts (1×2×1 ↔ 2×4×5). That is CamSync: couple weights without collapsing the graph into one Dense.

What it is

CamSyncConfig{Alpha, When, Groups, Cross}. BlendStores pulls every store in a clique toward the mean. Empty Groups = all cams; Cross wires SyncEndpoint pairs across layers/cams. Shape rule: Rows×Cols must match. Bidirectional today; one-way teacher→student not yet.

Parallel mid (n cams)                 Stack / mesh (any DxHxW)
  ┌─ cam0 W ─┐                          cell A 1×2×1     cell B 2×4×5
  │  cam1 W  │  Groups / all-cams       layer-1 Dense    cam3 layer-1 Dense
  │  cam2 W  │  α·mean blend     OR     [128×64]  ←──Cross──→  [128×64]
  └─ cam3 W ─┘                          (mesh size irrelevant — shape is)
         │
    SyncAfterSample | Step | Pulse | Manual SyncNow

Knobs

What works / what does not (yet)

• ✅ All cams together, selective groups, soft or hard α
• ✅ Cross-layer / cross-cam pairs inside one Stack
• ✅ “Same layer on a different mesh” when weight shapes match
• ✅ v1.1.1 — cam adjusting on all layer types (Dense, CNN, Parallel, Stack-resolved stores)
• ❌ One-directional (teacher → student) — pairs are mutual mean-blend
• ❌ Mismatched Rows×Cols — rejected or skipped
• ❌ Auto sync across two separate Stack instances — host calls weights.BlendStores on the two stores

API

• parallel.CamSyncConfig · DefaultCamSync() · SetCamSync on Layer or Stack
• SyncNow / Pulse / MaybeSync
• weights.BlendStores · weights.StoreCosine (diagnostics)

Cameral sandwiches: §68. Parallel package: §27. Host probe: ok/cam_sync (MNIST sample α×cams matrix).

package main

import (
	"fmt"

	"github.com/openfluke/welvet/core"
	"github.com/openfluke/welvet/layers/dense"
	"github.com/openfluke/welvet/layers/parallel"
	"github.com/openfluke/welvet/quant"
	"github.com/openfluke/welvet/stub/seed"
	"github.com/openfluke/welvet/weights"
)

func main() {
	s, err := parallel.Bicameral(8, 16, 1, core.ActivationLeakyReLU,
		core.DTypeFloat32, quant.FormatNone)
	if err != nil {
		panic(err)
	}
	hemi := s.Children[1].(*parallel.Layer)
	left := hemi.Branches[0].(*dense.Layer).Weights
	right := hemi.Branches[1].(*dense.Layer).Weights
	_ = seed.InitStoreHe(left, 16, seed.From("cam0"))
	_ = seed.InitStoreHe(right, 16, seed.From("cam1"))

	hemi.SetCamSync(parallel.CamSyncConfig{
		Enabled: true,
		Alpha:   1.0,
		When:    parallel.SyncManual,
	})
	before, _ := weights.StoreCosine(left, right)
	if err := hemi.SyncNow(); err != nil {
		panic(err)
	}
	after, _ := weights.StoreCosine(left, right)
	fmt.Printf("cosine before=%.4f after=%.4f\n", before, after)
}

cosine before=-0.0697 after=1.0000