# Expert Foundry architecture decisions

Status: research implementation v0.1, 2026-09-05. Accepted means an implementation design decision, not production qualification. The site runs a synthetic CPU fixture and the actual MetaHarness router on synthetic calibration examples. Its JSON state exchange is a proposed LatentMesh application boundary, not LMS1 wire compatibility.

## ADR 001: Preserve the parent coordinate system

Decision: extract routed expert groups independently in every supported transformer layer, retaining embeddings, attention, normalization, mandatory shared experts, tokenizer assets and output head. Expert IDs are layer local. Remap expert tensor IDs and router rows together. Require at least the original top K experts and a uniform retained expert count for these HF schemas.

Alternatives rejected: serving one FFN expert as a language model; splicing equally sized tensors from unrelated parents; assuming frequently used experts are causally important. Dense models require a different extraction or distillation workflow.

Implemented: Qwen2 MoE, Qwen3 MoE and Mixtral individual/fused floating safetensors schemas. Unknown or packed quantized schemas stop explicitly. Structural test fixtures cover preserved shared tensors and remapping. This is not a promise that arbitrary current checkpoints reload in every inference engine.

Acceptance: keep-all tensor equivalence, complete backbone, original parent hashes, no source overwrite. Before model promotion, perform actual runtime keep-all logit equivalence.

## ADR 002: Separate request routing from token routing

Decision: reuse @metaharness/router 0.4.0 as the outer request router. Its calibration examples are immutable, dimension checked, finite, priced and versioned. The wrapper explicitly checks metBar and falls back to the full parent. A fallback does not inherit the rejected specialist's predicted quality or price. Internal token routing remains owned by the model runtime.

Alternatives rejected: selecting FFN weights with a request router; using upstream metBar=false as success; treating estimated quality as a per-request guarantee; allowing a model route to grant new permissions.

Implemented: pinned package, vendored MIT browser distribution, wrapper tests and microbenchmarks. Browser routing examples are synthetic and authorize no execution. Real checkpoint mixture receipts start disabled.

ruvLLM: verified MemoryAwareRouter and paging interfaces are documented. Native worker and exported checkpoint loader compatibility remain unverified. The initial baseline uses no cache-biased routing; it would change model behavior and needs separate quality measurement.

Acceptance: invalid vectors/costs rejected, parent fallback, unchanged tool scope, unseen mixed-domain route evaluation under a common cost envelope.

## ADR 003: Use typed state before raw latent transfer

Decision: exchange explicit state deltas, evidence references and manifest hashes. Never use raw model activations or cross-specialist KV reuse by default. Preserve M3 and M5X as clean negative evidence for the tested latent channels. Native parent expert separation does not depend on those experiments succeeding.

Implemented local protocol: expert-foundry/state-delta/v1. Canonical JSON SHA-256, 64 KiB state limit, 128 KiB envelope limit, base/result hashes, contiguous positive sequence, identity binding and replay rejection. Binding includes parent revision, mask hash, tokenizer hash, precision, positional settings, tenant and session. Hashes detect corruption; they are not authentication. State updates are serialized.

Integration boundary: LatentMesh Rust has CriticalState, SemanticDelta and SemanticEnvelope with an LMS1 wire encoding. Our JSON demo is not that wire format. Build a native bridge with cross-language golden vectors and authenticated transport before network use. Do not send model weights over constrained radio links. The in-process replay check is not durable distributed replay protection.

Alternatives rejected: undocumented tensor interchange, silently reusing KV after changing a specialist, claiming a smaller state message improves RF utility without wire/energy accounting.

Acceptance: wrong identity/base/hash, oversized payloads and replay fail. Network gate additionally needs signature verification, durable sequencing and loss/reorder testing. Causal latent research requires matched, valid mismatched and no-channel controls.

## ADR 004: Stream on CPU, evaluate on an explicit worker

Decision: use safetensors metadata and bounded range copying for exports. A single configurable copy buffer is 4 KiB to 64 MiB. GPU is unnecessary for copying existing weights. Model calibration and heldout generation are separate bounded jobs, useful on GPU for large parents.

Implemented: read-only source, staging directory, atomic output rename, no overwrite, tokenizer preservation, source/output hashing and full output schema reinspection. No pickle, custom remote code, automatic weight download or cloud rental. The hosted static application accepts config JSON only and never receives model weights.

Tradeoff: export integrity hashes scan the parent multiple times. This is deliberate provenance work and part of reported end-to-end time; raw copy throughput must not be substituted. Peak memory includes OS page cache and interpreter metadata beyond the configured copy buffer. The output is currently a single safetensors file, so enough disk space is required.

Core Memory / RVF: retain versioned evidence and human approval boundaries. Current upstream compatibility and federation contracts are recorded in integrations.md. No federation service, identity authority, memory database or RVF signer was provisioned. Do not make those claims based on local hash receipts.

Acceptance: buffer sweep with identical inputs/masks and hashing enabled; source unchanged; output valid; local paths and no remote-code execution. GPU launch requires named weights, storage, device, authorized budget and dataset.

## ADR 005: Optimize only behind an evidence gate

Decision: compare full parent, same-size random pruning and calibrated masks on identical sealed tasks. Add activation-frequency and coalition methods when supported. Separate synthetic/router/export timings from real generation results. Record raw task outcomes, seeds, versions, bytes, latency samples, actual peak device memory and energy only if measured.

Starting real-model gates: <=2 percentage points quality loss; >=30% peak device memory reduction; <=10% p95 latency regression; >=1,000 untouched tasks across five seeds; selected masks beat random and pass mixed-domain tasks; artifact hashes independently verified. These are proposed gates, not achieved results. The JavaScript predicate checks metrics only; it is not an authorization service.

Stopping rule: first run keep-all reload equivalence. Stop immediately on structural mismatch, invalid values or a security regression. Test 80% then 60% retention. Stop more aggressive pruning after two failed retention levels; retain the full parent. Small total weights do not imply fewer active FLOPs, lower fleet memory, or faster generation.

Evidence: local tests and synthetic fixtures qualify software behavior only. The NumPy fixture plants domain locality, uses oracle domain labels for its outer route, and has no transformer attention. One random-control seed slightly exceeds selected accuracy. We report that result rather than treating pruning as universally beneficial.

Acceptance: requirement-to-evidence receipt plus human review. Nothing synthetic may promote a real model. Keep the original model and receipts for rollback.