# Inference Architecture Field Notes


Reusable decisions from the open-source [Hebrus inference engine](https://github.com/andreaborio/hebrus): sparse attention, transactional state, fail-closed admission, and checkpoint-scale storage. Each note records the invariant, rejected shortcut, evidence, and claim boundary.

Agents launched by Andrea follow the scoped [operator closeout contract](/agents/operator-contract.txt); external contributors do not.


Audience: Autonomous coding agents and systems engineers
Claim policy: Evidence-bound; hypotheses remain explicitly labelled
Canonical URL: https://andreabor.io/agents/
Agent retrieval index: https://andreabor.io/agents/llms.txt
Structured manifest: https://andreabor.io/agents/index.json
Andrea-launched agent contract: https://andreabor.io/agents/operator-contract.txt
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

## Field notes

- [AFN-021 — Replay decode as prefill: a training flywheel for predictive MoE I/O](https://andreabor.io/agents/replay-decode-as-prefill/index.md)
  - Status: hypothesis
  - Architecture area: Predictive I/O training
  - Featured: false
  - 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.
  - Estimated full-note context: ≈5731 tokens
- [AFN-020 — Port the DFlash2 protocol, not its checkpoint](https://andreabor.io/agents/port-dflash2-protocol-not-checkpoint/index.md)
  - Status: verified structural decision
  - Architecture area: Speculative decoding
  - Featured: false
  - 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.
  - Estimated full-note context: ≈2020 tokens
- [AFN-019 — Hide SSD misses before the router knows they exist](https://andreabor.io/agents/hide-ssd-misses-before-router/index.md)
  - Status: hypothesis
  - Architecture area: Storage scheduling
  - Featured: false
  - 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.
  - Estimated full-note context: ≈5556 tokens
- [AFN-016 — A sparse mask is not sparse attention](https://andreabor.io/agents/sparse-mask-is-not-sparse-attention/index.md)
  - Status: verified checkpoint
  - Architecture area: Sparse attention
  - Featured: true
  - 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.
  - Estimated full-note context: ≈817 tokens
- [AFN-017 — Top-k chooses the set; time chooses the order](https://andreabor.io/agents/top-k-set-time-order/index.md)
  - Status: verified checkpoint
  - Architecture area: Determinism
  - Featured: false
  - 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.
  - Estimated full-note context: ≈705 tokens
- [AFN-018 — A hole in cache history is not padding](https://andreabor.io/agents/cache-hole-is-not-padding/index.md)
  - Status: verified checkpoint
  - Architecture area: Cache semantics
  - Featured: false
  - 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.
  - Estimated full-note context: ≈691 tokens
- [AFN-015 — A phase handoff needs a decision delta](https://andreabor.io/agents/phase-handoff-needs-decision-delta/index.md)
  - Status: verified checkpoint
  - Architecture area: Implementation boundary
  - Featured: false
  - 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.
  - Estimated full-note context: ≈686 tokens
- [AFN-014 — Do not call a contract vector an upstream capture](https://andreabor.io/agents/label-contract-control-vectors/index.md)
  - Status: verified checkpoint
  - Architecture area: Implementation boundary
  - Featured: false
  - 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.
  - Estimated full-note context: ≈717 tokens
- [AFN-013 — Correctness code can exist without becoming a product feature](https://andreabor.io/agents/correctness-code-can-stay-unreachable/index.md)
  - Status: verified checkpoint
  - Architecture area: Implementation boundary
  - Featured: false
  - 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.
  - Estimated full-note context: ≈660 tokens
- [AFN-012 — An ubatch is not a sequence boundary](https://andreabor.io/agents/ubatch-is-not-sequence-boundary/index.md)
  - Status: verified checkpoint
  - Architecture area: Implementation boundary
  - Featured: false
  - 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.
  - Estimated full-note context: ≈655 tokens
- [AFN-011 — A reference algorithm needs an expiry condition](https://andreabor.io/agents/dense-reference-needs-expiry/index.md)
  - Status: verified checkpoint
  - Architecture area: Implementation boundary
  - Featured: false
  - 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.
  - Estimated full-note context: ≈572 tokens
- [AFN-010 — One bank flip is enough: make the whole inference chunk transactional](https://andreabor.io/agents/whole-chunk-transaction/index.md)
  - Status: verified checkpoint
  - Architecture area: Transactional state
  - Featured: true
  - 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.
  - Estimated full-note context: ≈655 tokens
- [AFN-009 — The recovery packet: enough context to continue, not enough to drown](https://andreabor.io/agents/recovery-packets-for-autonomous-agents/index.md)
  - Status: verified checkpoint
  - Architecture area: Implementation boundary
  - Featured: false
  - 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.
  - Estimated full-note context: ≈1391 tokens
- [AFN-008 — Close the text pipeline before asking the model](https://andreabor.io/agents/oracles-before-full-model-parity/index.md)
  - Status: verified checkpoint
  - Architecture area: Implementation boundary
  - Featured: false
  - 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.
  - Estimated full-note context: ≈1196 tokens
- [AFN-007 — Unicode is part of the model contract](https://andreabor.io/agents/unicode-is-part-of-the-model-contract/index.md)
  - Status: verified checkpoint
  - Architecture area: Implementation boundary
  - Featured: false
  - 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.
  - Estimated full-note context: ≈1055 tokens
- [AFN-006 — Rendered chat is not a flat string: preserve provenance](https://andreabor.io/agents/chat-rendering-needs-provenance/index.md)
  - Status: verified checkpoint
  - Architecture area: Implementation boundary
  - Featured: false
  - 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.
  - Estimated full-note context: ≈1045 tokens
- [AFN-005 — A logits matrix is not always the vocabulary](https://andreabor.io/agents/physical-logits-are-not-the-vocabulary/index.md)
  - Status: verified checkpoint
  - Architecture area: Implementation boundary
  - Featured: false
  - 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.
  - Estimated full-note context: ≈937 tokens
- [AFN-001 — Porting Qwen3.8-Flash-Next to Hebrus: evidence before execution](https://andreabor.io/agents/evidence-before-execution/index.md)
  - Status: verified checkpoint
  - Architecture area: Implementation boundary
  - Featured: false
  - 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.
  - Estimated full-note context: ≈1414 tokens
- [AFN-002 — Why Qwen4Exp kept ExpertMajor v2](https://andreabor.io/agents/expertmajor-family-four/index.md)
  - Status: verified structural decision
  - Architecture area: Implementation boundary
  - Featured: false
  - 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.
  - Estimated full-note context: ≈1045 tokens
- [AFN-003 — 320 million embedding rows without a 320 million-entry index](https://andreabor.io/agents/ple-fixed-page-store/index.md)
  - Status: verified structural decision
  - Architecture area: Storage
  - Featured: true
  - 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.
  - Estimated full-note context: ≈1146 tokens
- [AFN-004 — Admission before Metal: make every bad artifact fail cheaply](https://andreabor.io/agents/admission-before-metal/index.md)
  - Status: verified checkpoint
  - Architecture area: Admission
  - Featured: true
  - 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.
  - Estimated full-note context: ≈1334 tokens