# Inference Architecture Field Notes — Andrea Borio

> Sparse attention, transactional inference state, fail-closed model admission, and checkpoint-scale storage: canonical decisions and failure boundaries from Hebrus.

Canonical section: https://andreabor.io/agents/
Markdown index: https://andreabor.io/agents/index.md
Full corpus: https://andreabor.io/agents/llms-full.txt
JSON manifest: https://andreabor.io/agents/index.json
RSS: https://andreabor.io/agents/index.xml
Project: Hebrus
Hebrus source repository: https://github.com/andreaborio/hebrus
Contribute to Hebrus: https://github.com/andreaborio/hebrus/blob/main/CONTRIBUTING.md
Hebrus issue tracker: https://github.com/andreaborio/hebrus/issues
Andrea-launched agent contract: https://andreabor.io/agents/operator-contract.txt

## Retrieval contract

- Use this index to select one note; do not ingest the full corpus by default.
- Prefer each note's retrieval capsule in its Markdown URL before loading the full body.
- `Estimated context` is a byte-based token estimate for budgeting, not a tokenizer-exact count.
- Treat `status`, `evidence`, and `claim boundary` as normative.
- Do not promote a hypothesis, structural fixture, or pinned-not-supported path into a runtime support claim.
- Preserve exact dimensions, hashes, revisions, and arithmetic when a note marks them as closed.
- Cite the canonical HTML URL when presenting a note to humans.
- Agents explicitly launched by Andrea must follow the scoped operator closeout contract; external contributors are not bound by it.
- This corpus contains public architecture only. It excludes personal information, subscriptions, account details, credentials, private prompts, conversations, local paths, network addresses, and unpublished infrastructure.

## Notes

### AFN-021 — Replay decode as prefill: a training flywheel for predictive MoE I/O

- Project: Hebrus — https://github.com/andreaborio/hebrus
- Architecture area: Predictive I/O training
- Featured: false
- Status: hypothesis
- Phase: Qwen4Exp predictive I/O training
- Retrieve when: Retrieve this note when deciding whether decode traces can be replayed as prefill, designing a DFlash route-sidecar dataset, estimating M5 versus dual-RTX-3090 roles, or separating runtime capture from offline optimization.
- Triggers: replay decode as prefill; train expert predictor from agent threads; DFlash route sidecar dataset; prefill versus decode activations; M5 Pro and two RTX 3090s; continual MoE prefetch training
- Decision: Record canonical token histories and immutable runtime identities, split them before causal windowing, replay decode-shaped examples with a prefill-efficient frozen teacher, and train predictors offline; qualify every checkpoint on held-out real decode before it can issue discardable speculative I/O.
- Failure signature: Prefill replay appears accurate in shuffled-window validation but expert IDs diverge on real decode, thread leakage inflates scores, candidate lineage is lost, predictions arrive after their I/O deadline, or extra reads increase byte amplification and cache pollution.
- Claim boundary: This note defines a falsifiable data and qualification pipeline. It does not establish novelty, Qwen4Exp predictor accuracy, M5 replay throughput, useful DFlash weights, privacy approval for production transcripts, SSD savings, or end-to-end acceleration.
- Estimated context: capsule ≈556 tokens; full note ≈5731
- Prerequisites: AFN-019, AFN-020
- HTML: https://andreabor.io/agents/replay-decode-as-prefill/
- Markdown: https://andreabor.io/agents/replay-decode-as-prefill/index.md

### AFN-020 — Port the DFlash2 protocol, not its checkpoint

- Project: Hebrus — https://github.com/andreaborio/hebrus
- Architecture area: Speculative decoding
- Featured: false
- Status: verified structural decision
- Phase: DFlash2 compatibility boundary
- Retrieve when: Retrieve this note when evaluating whether a DFlash2 checkpoint can accelerate a different target model, especially when the model names look related or both implementations expose a DFlash2DraftModel.
- Triggers: reuse DFlash2 weights on another model; DFlash2 for Qwen4Exp; GLM DFlash2 checkpoint compatibility; port speculative decoding to a new target; candidate path accepted prefix replay; target hidden capture contract
- Decision: Treat a released DFlash2 checkpoint as target-specific weights, while porting only its explicit proposal, candidate-path, verification, rollback, and dataset contracts to a newly trained target-specific adapter.
- Failure signature: A foreign checkpoint loads because tensor names or architecture labels happen to match, yet hidden widths, target-layer captures, vocabulary rows, selector projections, or cache rollback semantics differ; output may remain plausible while acceptance and routing evidence are invalid.
- Claim boundary: This decision establishes a compatibility boundary and a reusable integration protocol. It does not establish trained Qwen4Exp draft weights, acceptance length, quality parity, SSD savings, Metal performance, or end-to-end Hebrus support.
- Estimated context: capsule ≈487 tokens; full note ≈2020
- Prerequisites: AFN-010, AFN-019
- HTML: https://andreabor.io/agents/port-dflash2-protocol-not-checkpoint/
- Markdown: https://andreabor.io/agents/port-dflash2-protocol-not-checkpoint/index.md

### AFN-019 — Hide SSD misses before the router knows they exist

- Project: Hebrus — https://github.com/andreaborio/hebrus
- Architecture area: Storage scheduling
- Featured: false
- Status: hypothesis
- Phase: 8–11 performance architecture
- Retrieve when: Retrieve this note when implementing Qwen4Exp expert or PLE SSD streaming, combining ExpertMajor v2 with DFlash, designing route prediction, or deciding whether I/O latency can be overlapped with Metal compute.
- Triggers: hide SSD expert latency behind compute; DFlash with ExpertMajor v2; predict MoE routes before the native router; PLE and expert I/O priority; adaptive speculative block size for an offloaded MoE; Metal I/O wavefront scheduler
- Decision: Treat SSD-heavy Qwen4Exp inference as a deadline-scheduled wavefront and test three lookahead tiers—exact PLE requests, pre-attention expert prediction, and DFlash route prediction—while keeping the native router and transactional target state authoritative.
- Failure signature: The runtime reports cache hits or high SSD throughput while token latency still contains layer-by-layer wait bubbles, speculative expert reads starve PLE or exact misses, rejected DFlash suffixes amplify bytes per accepted token, or a predictor silently becomes the execution router.
- Claim boundary: This note does not establish expert-predictor accuracy, an M5 SSD bandwidth figure, a winning DFlash block size, an ExpertMajor codec, end-to-end acceleration, quality parity, or Qwen4Exp runtime support. Every mechanism remains gated by physical traces and exact target-state tests.
- Estimated context: capsule ≈546 tokens; full note ≈5556
- Prerequisites: AFN-002, AFN-003, AFN-010
- HTML: https://andreabor.io/agents/hide-ssd-misses-before-router/
- Markdown: https://andreabor.io/agents/hide-ssd-misses-before-router/index.md

### AFN-016 — A sparse mask is not sparse attention

- Project: Hebrus — https://github.com/andreaborio/hebrus
- Architecture area: Sparse attention
- Featured: true
- Status: verified checkpoint
- Phase: 6 architecture
- Retrieve when: You are implementing sparse or selected attention and need to distinguish mathematically sparse visibility from bounded memory traffic and compute.
- Triggers: top-k mask still runs dense attention; selected keys but quadratic memory; prove physically sparse QSA; compact K/V gather and online softmax
- Decision: Define sparse attention by physical work: keep compact logical IDs, resolve only selected cache slots, gather only selected K/V rows, and run online softmax over the compact row.
- Failure signature: Telemetry reports a small selected set while memory, dispatches, or kernel time still grow like dense attention because the selected IDs only modify a mask around a generic backend.
- Claim boundary: Hebrus c3759b5 proves the model-free F32 host and Metal sparse-QSA path through the frozen 262,144-token boundary; it does not register a production profile, family dispatch, artifact codec, full-checkpoint logits claim, or runtime support.
- Estimated context: capsule ≈413 tokens; full note ≈817
- Prerequisites: AFN-011
- HTML: https://andreabor.io/agents/sparse-mask-is-not-sparse-attention/
- Markdown: https://andreabor.io/agents/sparse-mask-is-not-sparse-attention/index.md

### AFN-017 — Top-k chooses the set; time chooses the order

- Project: Hebrus — https://github.com/andreaborio/hebrus
- Architecture area: Determinism
- Featured: false
- Status: verified checkpoint
- Phase: 6 architecture
- Retrieve when: You have a top-k selector whose mathematical result is a set, but downstream cache gathers and floating reductions require one canonical sequence.
- Triggers: top-k membership versus output order; sparse row differs below budget; heap order changes floating attention; deterministic selected ID sequence
- Decision: Use deterministic score order only to choose the top-k set, then emit the chosen groups in ascending logical position before expansion and tail append.
- Failure signature: The correct groups are selected but appear in rank order, so below-budget sparse rows differ from dense rows and finite-precision attention changes with heap or parallel-reduction details.
- Claim boundary: Hebrus c3759b5 proves the ordering rule for the model-free host and Metal QSA path, including dense parity, equal-score ties, full-raw/incremental identity, and long boundaries; it does not qualify a production profile or full-checkpoint inference.
- Estimated context: capsule ≈412 tokens; full note ≈705
- Prerequisites: AFN-011
- HTML: https://andreabor.io/agents/top-k-set-time-order/
- Markdown: https://andreabor.io/agents/top-k-set-time-order/index.md

### AFN-018 — A hole in cache history is not padding

- Project: Hebrus — https://github.com/andreaborio/hebrus
- Architecture area: Cache semantics
- Featured: false
- Status: verified checkpoint
- Phase: 6 architecture
- Retrieve when: You are grouping cached tokens by logical position and need to distinguish legal left padding or eviction from an internal gap that would silently drop attention history.
- Triggers: hole inside KV cache history; left padding versus missing token; group adjacent physical cache cells; sparse attention silently drops history
- Decision: Model each visible sequence as one contiguous logical-position run: permit an arbitrary first position for left padding, require every append to advance by one, and reject internal holes before sparse planning.
- Failure signature: A removed or stale middle token leaves earlier live tokens that belong to neither a complete group nor the final tail, so sparse attention silently forgets valid history.
- Claim boundary: Hebrus c3759b5 verifies the contiguous-run and transactional lifecycle contract in the model-free QSA cache and Metal selection path; it does not expose long QSA state through a production profile, artifact codec, or runtime-support admission.
- Estimated context: capsule ≈419 tokens; full note ≈691
- Prerequisites: AFN-010, AFN-011
- HTML: https://andreabor.io/agents/cache-hole-is-not-padding/
- Markdown: https://andreabor.io/agents/cache-hole-is-not-padding/index.md

### AFN-015 — A phase handoff needs a decision delta

- Project: Hebrus — https://github.com/andreaborio/hebrus
- Architecture area: Implementation boundary
- Featured: false
- Status: verified checkpoint
- Phase: agent operations
- Retrieve when: You are closing an implementation phase or architecture checkpoint and need to preserve reusable reasoning without publishing progress logs or unverified claims.
- Triggers: phase handoff missing reusable decisions; agent repeats settled architecture research; publish technical choice after implementation; closeout checklist for autonomous agent
- Decision: Require Andrea-launched agents to perform a decision-delta review before closing each verified phase, publishing reusable evidence-bound choices or explicitly recording that no new note is warranted.
- Failure signature: A later agent repeats a settled investigation, reintroduces a rejected shortcut, or learns an invariant only by reconstructing an old diff because the prior handoff recorded tests but not the reusable decision.
- Claim boundary: This operator workflow does not bind external contributors, make incomplete work publishable, or replace repository source, tests, accepted decisions, support contracts, and QA gates.
- Estimated context: capsule ≈410 tokens; full note ≈686
- Prerequisites: AFN-009
- HTML: https://andreabor.io/agents/phase-handoff-needs-decision-delta/
- Markdown: https://andreabor.io/agents/phase-handoff-needs-decision-delta/index.md

### AFN-014 — Do not call a contract vector an upstream capture

- Project: Hebrus — https://github.com/andreaborio/hebrus
- Architecture area: Implementation boundary
- Featured: false
- Status: verified checkpoint
- Phase: 5
- Retrieve when: You are generating golden vectors from a framework that does not expose every cache image, token choice, tie policy, or synthetic control needed by the native test.
- Triggers: golden fixture generated by code under test; upstream framework does not expose cache state; per-array oracle provenance; synthetic control mislabeled as upstream
- Decision: Record provenance per fixture array and reserve the upstream-capture label for values actually emitted by pinned upstream code; label synthetic identities and state images as contract controls.
- Failure signature: A generated file mixes upstream outputs and locally invented controls under one trusted label, allowing the implementation to validate its own assumption as external truth.
- Claim boundary: These tiny graph vectors prove primitive and transition semantics only; they do not contain checkpoint weights, full-layer intermediates, quantization error, or final model logits.
- Estimated context: capsule ≈366 tokens; full note ≈717
- Prerequisites: AFN-008
- HTML: https://andreabor.io/agents/label-contract-control-vectors/
- Markdown: https://andreabor.io/agents/label-contract-control-vectors/index.md

### AFN-013 — Correctness code can exist without becoming a product feature

- Project: Hebrus — https://github.com/andreaborio/hebrus
- Architecture area: Implementation boundary
- Featured: false
- Status: verified checkpoint
- Phase: 5
- Retrieve when: You need realistic integration and hardware tests for a new backend or model family without accidentally advertising, auto-selecting, or accepting it in production.
- Triggers: test backend accidentally exposed in production; compiled code mistaken for supported feature; staged model-family rollout; fail-closed product registration
- Decision: Link the reviewed correctness implementation behind an unreachable test seam, while keeping product admission fail-closed until artifact, memory, quality, and performance gates qualify an execution route.
- Failure signature: A test-only kernel is linked, generic dispatch discovers it, and users can reach an unqualified artifact or backend because compiled code was mistaken for a support contract.
- Claim boundary: Phase 5 proves tiny model-free host and physical-Metal semantics only; real checkpoint parity, codec choice, SSD streaming, memory fit, throughput, server, downloader, and release support remain disabled.
- Estimated context: capsule ≈394 tokens; full note ≈660
- Prerequisites: AFN-004, AFN-008
- HTML: https://andreabor.io/agents/correctness-code-can-stay-unreachable/
- Markdown: https://andreabor.io/agents/correctness-code-can-stay-unreachable/index.md

### AFN-012 — An ubatch is not a sequence boundary

- Project: Hebrus — https://github.com/andreaborio/hebrus
- Architecture area: Implementation boundary
- Featured: false
- Status: verified checkpoint
- Phase: 5
- Retrieve when: You are chunking a stateful convolution, hash-derived embedding, or recurrent prefill path and need batching changes to preserve exact sequence semantics.
- Triggers: prefill chunk size changes logits; dilated convolution state across batches; sequence state leaks between batch rows; EOS changes n-gram embedding history
- Decision: Own PLE history and dilated-convolution state by logical sequence, carrying it across ubatches and updating it in the frozen EOS order.
- Failure signature: Changing prefill chunk size changes row hashes or logits, the first token after a boundary sees zeroed history, or one sequence consumes another sequence's convolution tail.
- Claim boundary: This proves model-free PLE state transitions with resident synthetic rows; it does not qualify the 320M-row production codec, page cache, SSD reads, or I/O overlap.
- Estimated context: capsule ≈373 tokens; full note ≈655
- Prerequisites: AFN-003, AFN-008
- HTML: https://andreabor.io/agents/ubatch-is-not-sequence-boundary/
- Markdown: https://andreabor.io/agents/ubatch-is-not-sequence-boundary/index.md

### AFN-011 — A reference algorithm needs an expiry condition

- Project: Hebrus — https://github.com/andreaborio/hebrus
- Architecture area: Implementation boundary
- Featured: false
- Status: verified checkpoint
- Phase: 5
- Retrieve when: You need a simple reference path to unlock graph bring-up without allowing its memory complexity or semantics to leak into advertised long-context support.
- Triggers: reference attention becomes production path; quadratic long-context allocation; dense versus sparse parity plan; boundary test at first unsupported context
- Decision: Use dense QSA only as a bounded correctness oracle through 2,051 visible keys and reject larger contexts until the native sparse algorithm is independently qualified.
- Failure signature: A small-context reference implementation passes tests and is accidentally reused at production context, creating quadratic allocation, hangs, OOM, or a false support claim.
- Claim boundary: The dense oracle establishes small-context QSA semantics only; it does not implement sparse selection, long-state lifecycle, 100K context, or production memory behavior.
- Estimated context: capsule ≈342 tokens; full note ≈572
- Prerequisites: AFN-001, AFN-008
- HTML: https://andreabor.io/agents/dense-reference-needs-expiry/
- Markdown: https://andreabor.io/agents/dense-reference-needs-expiry/index.md

### AFN-010 — One bank flip is enough: make the whole inference chunk transactional

- Project: Hebrus — https://github.com/andreaborio/hebrus
- Architecture area: Transactional state
- Featured: true
- Status: verified checkpoint
- Phase: 5
- Retrieve when: You are implementing stateful inference, speculative work, or a multi-stage accelerator graph where one request can fail after mutating recurrent state, KV/index caches, routing state, or logits.
- Triggers: failed inference corrupts the next request; partial KV or recurrent-state commit; transactional GPU graph publication; chunk and token execution diverge
- Decision: Execute a complete token chunk against a private state bank and publish every persistent owner with one bank-index flip only after all host and Metal stages succeed.
- Failure signature: A failed token leaves the frontier unchanged but advances one cache, convolution row, route, or logits buffer, so the next request starts from a state no valid execution produced.
- Claim boundary: This proves transactional behavior for the Phase 5 model-free resident graph; it does not prove full-checkpoint logits, production codecs, SSD execution, memory fit, or product support.
- Estimated context: capsule ≈374 tokens; full note ≈655
- Prerequisites: AFN-001, AFN-008
- HTML: https://andreabor.io/agents/whole-chunk-transaction/
- Markdown: https://andreabor.io/agents/whole-chunk-transaction/index.md

### AFN-009 — The recovery packet: enough context to continue, not enough to drown

- Project: Hebrus — https://github.com/andreaborio/hebrus
- Architecture area: Implementation boundary
- Featured: false
- Status: verified checkpoint
- Phase: agent operations
- Retrieve when: You need to hand a long-running coding project to a new agent, recover after context compaction, or choose the smallest trustworthy document that can answer one implementation question.
- Triggers: agent handoff after long implementation; context compaction recovery; project knowledge consumes too many tokens; multiple agents repeat settled research
- Decision: Publish architectural knowledge in selector, recovery-capsule, full-note, and source-evidence tiers instead of handing every agent the whole project transcript.
- Failure signature: A new agent rereads the repository or conversation, repeats settled research, reopens rejected decisions, or mistakes an old status summary for current authority.
- Claim boundary: This structure reduces retrieval cost and repeated work; it cannot guarantee that an agent selects the right note or that the underlying technical decision is correct.
- Estimated context: capsule ≈352 tokens; full note ≈1391
- Prerequisites: none
- HTML: https://andreabor.io/agents/recovery-packets-for-autonomous-agents/
- Markdown: https://andreabor.io/agents/recovery-packets-for-autonomous-agents/index.md

### AFN-008 — Close the text pipeline before asking the model

- Project: Hebrus — https://github.com/andreaborio/hebrus
- Architecture area: Implementation boundary
- Featured: false
- Status: verified checkpoint
- Phase: 4
- Retrieve when: You are sequencing a new model-family integration and need a test hierarchy that isolates text-pipeline failures before checkpoint-backed graph parity.
- Triggers: full-model mismatch has too many possible owners; tokenizer or template fixture design; mutation-testing a model contract
- Decision: Make tokenizer and chat behavior independently executable and mutation-tested before using full-model output as the debugging oracle.
- Failure signature: One differing model response leaves tokenizer, template, graph, state, quantization, kernel, and sampler defects equally plausible.
- Claim boundary: These model-free gates do not contain checkpoint weights or prove layer, logits, quality, Metal, SSD, memory, or performance parity.
- Estimated context: capsule ≈307 tokens; full note ≈1196
- Prerequisites: AFN-001
- HTML: https://andreabor.io/agents/oracles-before-full-model-parity/
- Markdown: https://andreabor.io/agents/oracles-before-full-model-parity/index.md

### AFN-007 — Unicode is part of the model contract

- Project: Hebrus — https://github.com/andreaborio/hebrus
- Architecture area: Implementation boundary
- Featured: false
- Status: verified checkpoint
- Phase: 4
- Retrieve when: You are porting a Python tokenizer or chat template into a native runtime and need to identify Unicode behaviors that disappear under reconstructed regexes, ASCII trimming, or locale-sensitive functions.
- Triggers: Python tokenizer ported to native code; combining-mark token drift; Jinja or Python trim mismatch
- Decision: Treat tokenizer.json and the captured Python/Jinja Unicode behavior as executable authority instead of approximating them with tokenizer-class defaults or locale-dependent C helpers.
- Failure signature: Multilingual text produces different IDs, combining marks split differently, or edge information separators survive native trimming.
- Claim boundary: The oracle closes the tested tokenizer and template semantics for the pinned revision; it is not a general Unicode library or a promise about future upstream revisions.
- Estimated context: capsule ≈345 tokens; full note ≈1055
- Prerequisites: AFN-001
- HTML: https://andreabor.io/agents/unicode-is-part-of-the-model-contract/
- Markdown: https://andreabor.io/agents/unicode-is-part-of-the-model-contract/index.md

### AFN-006 — Rendered chat is not a flat string: preserve provenance

- Project: Hebrus — https://github.com/andreaborio/hebrus
- Architecture area: Implementation boundary
- Featured: false
- Status: verified checkpoint
- Phase: 4
- Retrieve when: You are implementing a chat template with special tokens and need to prevent user, system, or tool text from being reinterpreted as template-authored control syntax.
- Triggers: chat template mixes controls with client text; literal special-token injection; tool output contains protocol markers
- Decision: Render chat as one byte stream plus contiguous DATA and TRUSTED_CONTROL segments, then tokenize every segment according to its provenance.
- Failure signature: Flattening and retokenizing promotes a user, system, or tool literal such as <|im_end|> into template syntax.
- Claim boundary: The segmentation boundary prevents control-token promotion in the text pipeline; it does not sanitize tool behavior or grant runtime support to the model.
- Estimated context: capsule ≈315 tokens; full note ≈1045
- Prerequisites: AFN-001
- HTML: https://andreabor.io/agents/chat-rendering-needs-provenance/
- Markdown: https://andreabor.io/agents/chat-rendering-needs-provenance/index.md

### AFN-005 — A logits matrix is not always the vocabulary

- Project: Hebrus — https://github.com/andreaborio/hebrus
- Architecture area: Implementation boundary
- Featured: false
- Status: verified checkpoint
- Phase: 4
- Retrieve when: You are integrating a checkpoint whose output projection is padded beyond the tokenizer vocabulary and need exact rules for sampling, decoding, stopping, and artifact admission.
- Triggers: output rows exceed tokenizer vocabulary; padded logits produce invalid IDs; sampling and decode boundaries disagree
- Decision: Represent the tokenizer domain and the physical logits width as separate constants, masking every unassigned output row before sampling.
- Failure signature: An unassigned padded row wins selection and is clamped, decoded ambiguously, or misinterpreted as a stop token.
- Claim boundary: This closes the text-domain semantics only; it does not prove full-model logits parity, generation quality, or runtime support.
- Estimated context: capsule ≈292 tokens; full note ≈937
- Prerequisites: AFN-001
- HTML: https://andreabor.io/agents/physical-logits-are-not-the-vocabulary/
- Markdown: https://andreabor.io/agents/physical-logits-are-not-the-vocabulary/index.md

### AFN-001 — Porting Qwen3.8-Flash-Next to Hebrus: evidence before execution

- Project: Hebrus — https://github.com/andreaborio/hebrus
- Architecture area: Implementation boundary
- Featured: false
- Status: verified checkpoint
- Phase: 0–3
- Retrieve when: You are adding a new model family to an inference runtime and need an order of operations that prevents a plausible but incorrect graph from becoming the de facto specification.
- Triggers: new model-family bring-up; uncertain checkpoint identity; graph work beginning before executable contracts
- Decision: Freeze the source identity and executable contracts before implementing model execution.
- Failure signature: Kernel debugging begins before the exact input contract is closed, so local fixes accumulate around a plausible but incorrect model.
- Claim boundary: The checkpoint is structurally admitted but remains pinned-not-supported; this note makes no throughput, quality, or runtime-support claim.
- Estimated context: capsule ≈292 tokens; full note ≈1414
- Prerequisites: none
- HTML: https://andreabor.io/agents/evidence-before-execution/
- Markdown: https://andreabor.io/agents/evidence-before-execution/index.md

### AFN-002 — Why Qwen4Exp kept ExpertMajor v2

- Project: Hebrus — https://github.com/andreaborio/hebrus
- Architecture area: Implementation boundary
- Featured: false
- Status: verified structural decision
- Phase: 2
- Retrieve when: You need to add a model with new expert geometry to an existing routed-expert container without conflating model family, storage format, and release-qualified codec.
- Triggers: new expert geometry in an existing container; logical row width does not divide codec block size; structural acceptance confused with codec qualification
- Decision: Extend ExpertMajor v2 with a distinct family-4 descriptor while keeping its wire format unchanged.
- Failure signature: A structurally plausible store parses even though one role cannot be represented by the declared block geometry, or a new family changes legacy output bytes.
- Claim boundary: MLX affine4 G64 proves the geometry only; no Qwen4Exp routed-expert codec is release-qualified by this decision.
- Estimated context: capsule ≈288 tokens; full note ≈1045
- Prerequisites: AFN-001
- HTML: https://andreabor.io/agents/expertmajor-family-four/
- Markdown: https://andreabor.io/agents/expertmajor-family-four/index.md

### AFN-003 — 320 million embedding rows without a 320 million-entry index

- Project: Hebrus — https://github.com/andreaborio/hebrus
- Architecture area: Storage
- Featured: true
- Status: verified structural decision
- Phase: 2
- Retrieve when: You are designing storage for hundreds of millions of fixed-width lookup rows and need bounded metadata, independent verification, and future SSD caching.
- Triggers: hundreds of millions of fixed-width rows; bounded SSD lookup metadata; TOCTOU-safe page verification
- Decision: Represent PLE as a fixed-page embedded extent with affine row location and one digest per page, never a per-row offset table.
- Failure signature: Metadata grows with row count, lazy mapping creates unbounded first-touch, or bytes are verified in one read and copied from another.
- Claim boundary: The wire structure is frozen; production row codec, rows per page, page stride, and cache policy remain unqualified.
- Estimated context: capsule ≈284 tokens; full note ≈1146
- Prerequisites: AFN-001
- HTML: https://andreabor.io/agents/ple-fixed-page-store/
- Markdown: https://andreabor.io/agents/ple-fixed-page-store/index.md

### AFN-004 — Admission before Metal: make every bad artifact fail cheaply

- Project: Hebrus — https://github.com/andreaborio/hebrus
- Architecture area: Admission
- Featured: true
- Status: verified checkpoint
- Phase: 3
- Retrieve when: You are integrating a complex artifact into a GPU runtime and need deterministic field-level failures before expensive allocation or opaque backend errors.
- Triggers: GPU loader fails too late; artifact ownership or extent ambiguity; need deterministic field-level rejection
- Decision: Complete exact artifact admission in a dedicated CPU-only path before registering Qwen4Exp execution.
- Failure signature: A malformed artifact reaches the backend and fails as an opaque missing-tensor, allocation, overlap, or device error.
- Claim boundary: The dedicated binary proves structural admission only and intentionally rejects generation; normal builds still register no Qwen4Exp physical runtime profile.
- Estimated context: capsule ≈291 tokens; full note ≈1334
- Prerequisites: AFN-001, AFN-002, AFN-003
- HTML: https://andreabor.io/agents/admission-before-metal/
- Markdown: https://andreabor.io/agents/admission-before-metal/index.md