{"audience":"Autonomous coding agents and systems engineers","author":"Andrea Borio","canonical_url":"https://andreabor.io/agents/","kind":"agent-field-notes-index","notes":[{"architecture_area":"Predictive I/O training","canonical_url":"https://andreabor.io/agents/replay-decode-as-prefill/","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.","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.","estimated_tokens":{"full_note":5731,"method":"UTF-8 source bytes divided by four; approximate","retrieval_capsule":556},"evidence":"Public DFlash training methodology, published MoE expert-prediction and speculative-prefetch research, public Qwen4Exp geometry, and the AFN-019/AFN-020 architecture boundaries; no trained Qwen4Exp sidecar or M5 performance checkpoint yet","evidence_checkpoint":"DFlash arXiv:2602.06036v2; Pre-Attention Expert Prediction arXiv:2511.10676v1; SpecPrefetch arXiv:2607.24787v2; hypothesis only","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.","featured":false,"id":"AFN-021","invariant":"Replay may manufacture training examples, but it may not manufacture evidence about decode latency, cache state, proposal acceptance, SSD overlap, or exact runtime parity; the native router remains authoritative.","keywords":["prefill replay","decode traces","DFlash 2","Qwen4Exp","MoE routing","expert prefetch","route sidecar","SSD streaming","continual dataset","speculative decoding","RTX 3090","M5 Pro"],"markdown_url":"https://andreabor.io/agents/replay-decode-as-prefill/index.md","minimal_safe_implementation":"Capture a small authorized decode set, split by owner and thread before windowing, pin model/tokenizer/template identities, prove exact top-10 replay parity, persist compact labels, train the smallest shared sidecar, compare with history baselines, and shadow-test deadline-aware I/O on the target M5 runtime.","phase":"Qwen4Exp predictive I/O training","prerequisites":["AFN-019","AFN-020"],"project":{"contributing_url":"https://github.com/andreaborio/hebrus/blob/main/CONTRIBUTING.md","issues_url":"https://github.com/andreaborio/hebrus/issues","name":"Hebrus","repository_url":"https://github.com/andreaborio/hebrus"},"published":"2026-08-31","rejected_shortcut":"Train on randomly mixed prefill windows, persist every large activation, update weights inside inference, treat replay validation as decode evidence, replace the native router with predictions, or launch full DFlash training before a small route sidecar beats simple controls.","related_notes":["AFN-002","AFN-010","AFN-015"],"retrieval_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"],"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.","status":"hypothesis","summary":"A decode-shaped, prefill-executed data pipeline for training expert-prefetch predictors without putting optimization in the inference runtime.","supersedes":[],"title":"Replay decode as prefill: a training flywheel for predictive MoE I/O"},{"architecture_area":"Speculative decoding","canonical_url":"https://andreabor.io/agents/port-dflash2-protocol-not-checkpoint/","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.","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.","estimated_tokens":{"full_note":2020,"method":"UTF-8 source bytes divided by four; approximate","retrieval_capsule":487},"evidence":"Pinned public DFlash2 draft configurations for Qwen3.8-27B and GLM-5.3-Flash, the public z-lab/dflash implementation, and the public Qwen3.8-Flash-Next target configuration","evidence_checkpoint":"incoai/Qwen3.8-27B-DFlash2 dedf8df68adfb1afeaf7b7480c0a0243108177b4; incoai/GLM-5.3-Flash-DFlash2 bf582e4eacc1810f76656d1811693ff6c6737d2a; z-lab/dflash 07ebd93db9f472af339b644bb70221ad8428328a","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.","featured":false,"id":"AFN-020","invariant":"The target model remains the sole authority for token probabilities, acceptance, committed cache state, and native MoE routing; a draft or route sidecar may propose work but cannot redefine target semantics.","keywords":["DFlash 2","speculative decoding","checkpoint compatibility","Qwen4Exp","Qwen3.8-Flash-Next","GLM-5.3-Flash","hidden capture","candidate selector","accepted prefix","route sidecar","model contract"],"markdown_url":"https://andreabor.io/agents/port-dflash2-protocol-not-checkpoint/index.md","minimal_safe_implementation":"Pin both target and draft revisions, fail closed on every target-bound dimension, define a versioned hidden-capture and verifier trace, replay proposals against the native target, train new draft or sidecar weights, and promote only after greedy/sampling correctness plus target-hardware measurements.","phase":"DFlash2 compatibility boundary","prerequisites":["AFN-010","AFN-019"],"project":{"contributing_url":"https://github.com/andreaborio/hebrus/blob/main/CONTRIBUTING.md","issues_url":"https://github.com/andreaborio/hebrus/issues","name":"Hebrus","repository_url":"https://github.com/andreaborio/hebrus"},"published":"2026-08-31","rejected_shortcut":"Rename a GLM or dense-Qwen DFlash2 checkpoint, reshape or truncate incompatible tensors, assume a shared model_type means shared weights, or let predicted routes replace the native top-k router.","related_notes":["AFN-002","AFN-015"],"retrieval_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"],"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.","status":"verified structural decision","summary":"DFlash2 weights are bound to one target model, but proposal, candidate selection, verification, accepted-prefix replay, and route-sidecar contracts can be rebuilt for another target.","supersedes":[],"title":"Port the DFlash2 protocol, not its checkpoint"},{"architecture_area":"Storage scheduling","canonical_url":"https://andreabor.io/agents/hide-ssd-misses-before-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.","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.","estimated_tokens":{"full_note":5556,"method":"UTF-8 source bytes divided by four; approximate","retrieval_capsule":546},"evidence":"Public Qwen4Exp geometry, established Hebrus storage and transaction contracts, published expert-prefetch research, DFlash 2 design evidence, and documented Metal I/O capabilities; no Qwen4Exp M5 performance checkpoint yet","evidence_checkpoint":"Hebrus c3759b5 plus Qwen/Qwen3.8-Flash-Next revision de4b8e4d43b917e7706784d8bb445c9af86a3540; hypothesis only","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.","featured":false,"id":"AFN-019","invariant":"Prediction may change which bytes arrive early, but it must never change native top-10 routing, target arithmetic, token acceptance, committed sequence state, or the priority of exact critical reads.","keywords":["SSD streaming","ExpertMajor v2","Qwen4Exp","DFlash 2","speculative decoding","expert prefetch","route prediction","PLE","Metal I/O","MTLIOCommandQueue","mixture of experts","Apple Silicon","deadline scheduling","latency hiding"],"markdown_url":"https://andreabor.io/agents/hide-ssd-misses-before-router/index.md","minimal_safe_implementation":"Use generation-owned I/O tickets with deadlines and confidence, separate exact and speculative queues, reconcile predictions against the native router, stream ExpertMajor components through bounded buffers, publish only accepted target state, and measure timely recall, useful bytes, amplification, and exposed wait rather than hit rate alone.","phase":"8–11 performance architecture","prerequisites":["AFN-002","AFN-003","AFN-010"],"project":{"contributing_url":"https://github.com/andreaborio/hebrus/blob/main/CONTRIBUTING.md","issues_url":"https://github.com/andreaborio/hebrus/issues","name":"Hebrus","repository_url":"https://github.com/andreaborio/hebrus"},"published":"2026-08-31","rejected_shortcut":"Prefetch every plausible expert, fix DFlash at its largest block, wait for all selected records before starting compute, use one global I/O queue, or treat Metal I/O capability and paper speedups as evidence that the M5 path is profitable.","related_notes":["AFN-015","AFN-016"],"retrieval_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"],"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.","status":"hypothesis","summary":"A falsifiable pipeline hypothesis for SSD-heavy Qwen4Exp inference: exact PLE lookahead, predictive expert loading, DFlash route forecasts, component-level streaming, and deadline-aware scheduling.","supersedes":[],"title":"Hide SSD misses before the router knows they exist"},{"architecture_area":"Sparse attention","canonical_url":"https://andreabor.io/agents/sparse-mask-is-not-sparse-attention/","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.","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.","estimated_tokens":{"full_note":817,"method":"UTF-8 source bytes divided by four; approximate","retrieval_capsule":413},"evidence":"Pinned Transformers plus independent NumPy capture; host strict and ASan/UBSan lanes; actual-device Metal selection at 65,537, 100,000, and 262,144 visible tokens; compact gather and online attention; zero dense-mask byte accounting; private allocation, non-completion, and clean-completion gates","evidence_checkpoint":"Hebrus c3759b5","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.","featured":true,"id":"AFN-016","invariant":"For each query, allocation, K/V reads, score work, and softmax work scale with selected width plus candidate-group scoring, never with the full query-by-key rectangle.","keywords":["sparse attention","Qwen4Exp","QSA","Metal","online softmax","KV cache","memory complexity","Hebrus"],"markdown_url":"https://andreabor.io/agents/sparse-mask-is-not-sparse-attention/index.md","minimal_safe_implementation":"Carry selected logical IDs to one slot-resolution boundary, compact the referenced K/V rows into bounded scratch, and apply an online softmax that visits exactly those rows.","phase":"6 architecture","prerequisites":["AFN-011"],"project":{"contributing_url":"https://github.com/andreaborio/hebrus/blob/main/CONTRIBUTING.md","issues_url":"https://github.com/andreaborio/hebrus/issues","name":"Hebrus","repository_url":"https://github.com/andreaborio/hebrus"},"published":"2026-08-31","rejected_shortcut":"Building a dense boolean or additive mask from top-k IDs and calling ordinary dense attention while describing the path as sparse.","related_notes":["AFN-010","AFN-017","AFN-018"],"retrieval_triggers":["top-k mask still runs dense attention","selected keys but quadratic memory","prove physically sparse QSA","compact K/V gather and online softmax"],"retrieve_when":"You are implementing sparse or selected attention and need to distinguish mathematically sparse visibility from bounded memory traffic and compute.","status":"verified checkpoint","summary":"Selecting 2,051 keys does not make attention sparse if the backend still allocates or traverses the full query-by-key matrix.","supersedes":[],"title":"A sparse mask is not sparse attention"},{"architecture_area":"Determinism","canonical_url":"https://andreabor.io/agents/top-k-set-time-order/","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.","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.","estimated_tokens":{"full_note":705,"method":"UTF-8 source bytes divided by four; approximate","retrieval_capsule":412},"evidence":"Pinned Transformers and independent NumPy selected-ID capture; exact host full-raw/incremental equality; dense parity at 0–5 and 2,047–2,052 tokens; ascending-position tie tests; chunk/decode equality; actual-device Metal selection through 262,144 visible tokens","evidence_checkpoint":"Hebrus c3759b5","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.","featured":false,"id":"AFN-017","invariant":"Selection membership depends only on score and the frozen tie rule; the emitted token row is always chronological and is byte-identical to dense visibility whenever every complete group fits the budget.","keywords":["top-k selection","deterministic ordering","sparse attention","floating-point reproducibility","QSA","Qwen4Exp","Hebrus"],"markdown_url":"https://andreabor.io/agents/top-k-set-time-order/index.md","minimal_safe_implementation":"Select membership with descending score and ascending group-position ties, sort the surviving group IDs by position, expand each group contiguously, then append the raw tail.","phase":"6 architecture","prerequisites":["AFN-011"],"project":{"contributing_url":"https://github.com/andreaborio/hebrus/blob/main/CONTRIBUTING.md","issues_url":"https://github.com/andreaborio/hebrus/issues","name":"Hebrus","repository_url":"https://github.com/andreaborio/hebrus"},"published":"2026-08-31","rejected_shortcut":"Treating top-k rank order as the cache-read and reduction order merely because exact real-number attention is permutation invariant.","related_notes":["AFN-016","AFN-018"],"retrieval_triggers":["top-k membership versus output order","sparse row differs below budget","heap order changes floating attention","deterministic selected ID sequence"],"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.","status":"verified checkpoint","summary":"Ranking decides which sparse-attention groups survive; canonical logical order decides how the selected row is represented and reduced.","supersedes":[],"title":"Top-k chooses the set; time chooses the order"},{"architecture_area":"Cache semantics","canonical_url":"https://andreabor.io/agents/cache-hole-is-not-padding/","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.","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.","estimated_tokens":{"full_note":691,"method":"UTF-8 source bytes divided by four; approximate","retrieval_capsule":419},"evidence":"Host strict and ASan/UBSan tests for left-padding anchors, internal-hole rejection, slot reuse, wrap eviction, reset, copy, fork, rewind, shift, remove, serialization and atomic restore; actual-device Metal rejection of groups crossing a position hole","evidence_checkpoint":"Hebrus c3759b5","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.","featured":false,"id":"AFN-018","invariant":"Every live position in a visible sequence run has exactly one predecessor except the first; complete groups and the raw tail partition that run without gaps or overlap.","keywords":["KV cache","logical positions","sparse attention","cache holes","left padding","transactional state","Qwen4Exp","Hebrus"],"markdown_url":"https://andreabor.io/agents/cache-hole-is-not-padding/index.md","minimal_safe_implementation":"Anchor grouping at the first live logical position, enforce successor appends, validate contiguity before planning, and rebuild pooled groups transactionally after lifecycle operations.","phase":"6 architecture","prerequisites":["AFN-010","AFN-011"],"project":{"contributing_url":"https://github.com/andreaborio/hebrus/blob/main/CONTRIBUTING.md","issues_url":"https://github.com/andreaborio/hebrus/issues","name":"Hebrus","repository_url":"https://github.com/andreaborio/hebrus"},"published":"2026-08-31","rejected_shortcut":"Treating a missing middle slot as ordinary padding, grouping adjacent physical cells, or skipping the gap and continuing group numbering.","related_notes":["AFN-016","AFN-017"],"retrieval_triggers":["hole inside KV cache history","left padding versus missing token","group adjacent physical cache cells","sparse attention silently drops history"],"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.","status":"verified checkpoint","summary":"Left padding may move the first real token; a missing position inside the visible run destroys sparse-group semantics and must fail closed.","supersedes":[],"title":"A hole in cache history is not padding"},{"architecture_area":"Implementation boundary","canonical_url":"https://andreabor.io/agents/phase-handoff-needs-decision-delta/","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.","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.","estimated_tokens":{"full_note":686,"method":"UTF-8 source bytes divided by four; approximate","retrieval_capsule":410},"evidence":"Agent Field Notes schema v2 already separates fourteen Phase 0-5 decisions into retrieval capsules with explicit evidence and claim boundaries; the closeout rule makes that preservation step deterministic","evidence_checkpoint":"Agent Field Notes schema v2","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.","featured":false,"id":"AFN-015","invariant":"A verified phase handoff always states whether it produced a new reusable decision, and every published decision names public evidence plus the boundary of what that evidence does not prove.","keywords":["agent handoff","decision delta","architecture knowledge","evidence checkpoint","retrieval capsule","Hebrus"],"markdown_url":"https://andreabor.io/agents/phase-handoff-needs-decision-delta/index.md","minimal_safe_implementation":"At phase close, compare the work against the Field Notes selector, publish one compact note for each genuinely new evidence-backed decision, or record an explicit no-new-decision result in the handoff.","phase":"agent operations","prerequisites":["AFN-009"],"project":{"contributing_url":"https://github.com/andreaborio/hebrus/blob/main/CONTRIBUTING.md","issues_url":"https://github.com/andreaborio/hebrus/issues","name":"Hebrus","repository_url":"https://github.com/andreaborio/hebrus"},"published":"2026-08-31","rejected_shortcut":"Publishing a diary of changed files, copying the whole handoff into the archive, or labelling dirty and local-only work as a verified public checkpoint.","related_notes":["AFN-014"],"retrieval_triggers":["phase handoff missing reusable decisions","agent repeats settled architecture research","publish technical choice after implementation","closeout checklist for autonomous agent"],"retrieve_when":"You are closing an implementation phase or architecture checkpoint and need to preserve reusable reasoning without publishing progress logs or unverified claims.","status":"verified checkpoint","summary":"Finishing code is not the same as preserving reusable reasoning: every verified phase closes with either a new evidence-bound note or an explicit no-new-decision record.","supersedes":[],"title":"A phase handoff needs a decision delta"},{"architecture_area":"Implementation boundary","canonical_url":"https://andreabor.io/agents/label-contract-control-vectors/","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.","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.","estimated_tokens":{"full_note":717,"method":"UTF-8 source bytes divided by four; approximate","retrieval_capsule":366},"evidence":"Graph fixtures execute pinned Transformers at 42ca97014c85d71a88ad60d55f08cb9fb4d26e2c, cross-check independent NumPy/scalar C, and label non-upstream arrays as contract-control in per-array provenance","evidence_checkpoint":"Hebrus 0626603","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.","featured":false,"id":"AFN-014","invariant":"A fixture's provenance never claims that upstream produced an array which the collector constructed from the local contract.","keywords":["Hebrus","oracle provenance","golden vectors","Transformers","contract control","independent implementation","Qwen4Exp"],"markdown_url":"https://andreabor.io/agents/label-contract-control-vectors/index.md","minimal_safe_implementation":"Attach an origin to every array, execute pinned upstream for exposed values, independently recompute their math, and label synthetic token, state, tie, and overflow controls explicitly.","phase":"5","prerequisites":["AFN-008"],"project":{"contributing_url":"https://github.com/andreaborio/hebrus/blob/main/CONTRIBUTING.md","issues_url":"https://github.com/andreaborio/hebrus/issues","name":"Hebrus","repository_url":"https://github.com/andreaborio/hebrus"},"published":"2026-08-30","rejected_shortcut":"Calling the entire golden file upstream-backed because some arrays passed through the upstream runtime.","related_notes":["AFN-009","AFN-010"],"retrieval_triggers":["golden fixture generated by code under test","upstream framework does not expose cache state","per-array oracle provenance","synthetic control mislabeled as upstream"],"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.","status":"verified checkpoint","summary":"Pinned Transformers can author module outputs, but synthetic tokens, hashed PLE rows, and cache images need a different provenance label or the fixture overstates its authority.","supersedes":[],"title":"Do not call a contract vector an upstream capture"},{"architecture_area":"Implementation boundary","canonical_url":"https://andreabor.io/agents/correctness-code-can-stay-unreachable/","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.","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.","estimated_tokens":{"full_note":660,"method":"UTF-8 source bytes divided by four; approximate","retrieval_capsule":394},"evidence":"The host coordinator and Metal partition compile and pass model-free gates while remaining unselected; normal builds expose no physical profile, server route, downloader entry, or support claim","evidence_checkpoint":"Hebrus 0626603","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.","featured":false,"id":"AFN-013","invariant":"Passing private host or accelerator correctness tests cannot make the model selectable through normal loader, server, downloader, or support metadata.","keywords":["Hebrus","staged rollout","capability admission","Metal correctness","pinned not supported","product safety","Qwen4Exp"],"markdown_url":"https://andreabor.io/agents/correctness-code-can-stay-unreachable/index.md","minimal_safe_implementation":"Separate correctness symbols from product registration, require an absent physical profile or capability selector to reject normal execution, and test both the positive private seam and negative public route.","phase":"5","prerequisites":["AFN-004","AFN-008"],"project":{"contributing_url":"https://github.com/andreaborio/hebrus/blob/main/CONTRIBUTING.md","issues_url":"https://github.com/andreaborio/hebrus/issues","name":"Hebrus","repository_url":"https://github.com/andreaborio/hebrus"},"published":"2026-08-30","rejected_shortcut":"Using a hidden command-line flag, undocumented alias, or optimistic architecture match to expose code before the release evidence exists.","related_notes":["AFN-001","AFN-010","AFN-011"],"retrieval_triggers":["test backend accidentally exposed in production","compiled code mistaken for supported feature","staged model-family rollout","fail-closed product registration"],"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.","status":"verified checkpoint","summary":"Phase 5 links a resident graph coordinator and real Metal correctness kernels, yet normal Hebrus execution still rejects Qwen4Exp at physical-profile admission.","supersedes":[],"title":"Correctness code can exist without becoming a product feature"},{"architecture_area":"Implementation boundary","canonical_url":"https://andreabor.io/agents/ubatch-is-not-sequence-boundary/","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.","decision":"Own PLE history and dilated-convolution state by logical sequence, carrying it across ubatches and updating it in the frozen EOS order.","estimated_tokens":{"full_note":655,"method":"UTF-8 source bytes divided by four; approximate","retrieval_capsule":373},"evidence":"One-shot and 1/2/1-token ubatch plans produce identical PLE rows, convolution state, public digest, and logits; independent-sequence and current-EOS controls pass on host and Metal","evidence_checkpoint":"Hebrus 0626603","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.","featured":false,"id":"AFN-012","invariant":"For the same token sequence, PLE row IDs, convolution outputs, persistent state, and final logits are identical across every valid ubatch partition, while separate sequences share no mutable history.","keywords":["Hebrus","ubatch parity","PLE","dilated convolution","sequence state","EOS semantics","Qwen4Exp"],"markdown_url":"https://andreabor.io/agents/ubatch-is-not-sequence-boundary/index.md","minimal_safe_implementation":"Store history and the full dilated receptive-field tail per sequence, advance them token by token inside each ubatch, and parity-test multiple partitions plus EOS and independent-sequence controls.","phase":"5","prerequisites":["AFN-003","AFN-008"],"project":{"contributing_url":"https://github.com/andreaborio/hebrus/blob/main/CONTRIBUTING.md","issues_url":"https://github.com/andreaborio/hebrus/issues","name":"Hebrus","repository_url":"https://github.com/andreaborio/hebrus"},"published":"2026-08-30","rejected_shortcut":"Resetting convolution or n-gram history at each scheduler chunk, or indexing persistent state by a transient batch row without generation ownership.","related_notes":["AFN-010","AFN-013"],"retrieval_triggers":["prefill chunk size changes logits","dilated convolution state across batches","sequence state leaks between batch rows","EOS changes n-gram embedding history"],"retrieve_when":"You are chunking a stateful convolution, hash-derived embedding, or recurrent prefill path and need batching changes to preserve exact sequence semantics.","status":"verified checkpoint","summary":"Dilated PLE convolution and token-history hashing must survive arbitrary chunking without leaking state between sequences or changing the current-EOS transition.","supersedes":[],"title":"An ubatch is not a sequence boundary"},{"architecture_area":"Implementation boundary","canonical_url":"https://andreabor.io/agents/dense-reference-needs-expiry/","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.","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.","estimated_tokens":{"full_note":572,"method":"UTF-8 source bytes divided by four; approximate","retrieval_capsule":342},"evidence":"Host and physical-Metal boundary tests accept the inclusive 2,051-key dense case and reject 2,052 plus 262,143/262,144/262,145 before graph execution","evidence_checkpoint":"Hebrus 0626603","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.","featured":false,"id":"AFN-011","invariant":"No request above the declared dense-oracle ceiling can allocate or execute a dense Q-by-K QSA path.","keywords":["Hebrus","sparse attention","dense reference","QSA","long context","fail closed","Qwen4Exp"],"markdown_url":"https://andreabor.io/agents/dense-reference-needs-expiry/index.md","minimal_safe_implementation":"Encode the reference ceiling in geometry admission and backend dispatch, test the exact last accepted and first rejected values, and keep sparse support behind a later parity gate.","phase":"5","prerequisites":["AFN-001","AFN-008"],"project":{"contributing_url":"https://github.com/andreaborio/hebrus/blob/main/CONTRIBUTING.md","issues_url":"https://github.com/andreaborio/hebrus/issues","name":"Hebrus","repository_url":"https://github.com/andreaborio/hebrus"},"published":"2026-08-30","rejected_shortcut":"Calling the dense implementation temporary while leaving its context limit as documentation, an optional flag, or an unchecked allocation.","related_notes":["AFN-004","AFN-010","AFN-013"],"retrieval_triggers":["reference attention becomes production path","quadratic long-context allocation","dense versus sparse parity plan","boundary test at first unsupported context"],"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.","status":"verified checkpoint","summary":"Dense QSA is a useful correctness oracle through 2,051 visible keys; without a hard ceiling, temporary reference code silently becomes an impossible long-context implementation.","supersedes":[],"title":"A reference algorithm needs an expiry condition"},{"architecture_area":"Transactional state","canonical_url":"https://andreabor.io/agents/whole-chunk-transaction/","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.","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.","estimated_tokens":{"full_note":655,"method":"UTF-8 source bytes divided by four; approximate","retrieval_capsule":374},"evidence":"Token, chunk, and interleaved multi-turn equivalence; failure injection after every graph stage; non-finite rejection; Metal allocation, command, and status rollback","evidence_checkpoint":"Hebrus 0626603","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.","featured":true,"id":"AFN-010","invariant":"Public frontier, logits, residuals, GDN state, QSA caches, PLE state, and routing state always describe the same successfully completed chunk.","keywords":["Hebrus","transactional inference","double buffering","Metal rollback","recurrent state","KV cache","Qwen4Exp"],"markdown_url":"https://andreabor.io/agents/whole-chunk-transaction/index.md","minimal_safe_implementation":"Keep two complete state banks, copy the public snapshot into the private bank, run every fallible stage privately, validate finite values and accelerator status, then publish through one index swap.","phase":"5","prerequisites":["AFN-001","AFN-008"],"project":{"contributing_url":"https://github.com/andreaborio/hebrus/blob/main/CONTRIBUTING.md","issues_url":"https://github.com/andreaborio/hebrus/issues","name":"Hebrus","repository_url":"https://github.com/andreaborio/hebrus"},"published":"2026-08-30","rejected_shortcut":"Rolling back only the visibly changed buffer, or copying old bytes back after an accelerator command has partially completed.","related_notes":["AFN-012","AFN-013","AFN-014"],"retrieval_triggers":["failed inference corrupts the next request","partial KV or recurrent-state commit","transactional GPU graph publication","chunk and token execution diverge"],"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.","status":"verified checkpoint","summary":"A token chunk can touch recurrent state, caches, routing, residual streams, and logits; publishing any one of them early creates a state that never existed mathematically.","supersedes":[],"title":"One bank flip is enough: make the whole inference chunk transactional"},{"architecture_area":"Implementation boundary","canonical_url":"https://andreabor.io/agents/recovery-packets-for-autonomous-agents/","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.","decision":"Publish architectural knowledge in selector, recovery-capsule, full-note, and source-evidence tiers instead of handing every agent the whole project transcript.","estimated_tokens":{"full_note":1391,"method":"UTF-8 source bytes divided by four; approximate","retrieval_capsule":352},"evidence":"Applied schema-v2 capsules, graph edges, context estimates, build validation, and machine-readable indexes across AFN-001 through AFN-009","evidence_checkpoint":"Agent Field Notes schema v2","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.","featured":false,"id":"AFN-009","invariant":"The smallest retrieval tier must preserve the decision, invariant, failure signature, minimal safe path, rejected shortcut, evidence, and claim boundary.","keywords":["agent handoff","context engineering","recovery packet","llms.txt","project memory","autonomous coding agents","knowledge retrieval"],"markdown_url":"https://andreabor.io/agents/recovery-packets-for-autonomous-agents/index.md","minimal_safe_implementation":"Maintain a compact selector, a self-contained recovery capsule per decision, an optional full rationale, explicit note dependencies, and links to immutable evidence.","phase":"agent operations","prerequisites":[],"project":{"contributing_url":"https://github.com/andreaborio/hebrus/blob/main/CONTRIBUTING.md","issues_url":"https://github.com/andreaborio/hebrus/issues","name":"Hebrus","repository_url":"https://github.com/andreaborio/hebrus"},"published":"2026-08-30","rejected_shortcut":"One ever-growing project summary, a raw transcript dump, or a vector search result without status, provenance, and supersession boundaries.","related_notes":["AFN-001","AFN-008"],"retrieval_triggers":["agent handoff after long implementation","context compaction recovery","project knowledge consumes too many tokens","multiple agents repeat settled research"],"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.","status":"verified checkpoint","summary":"A layered handoff format that lets a new coding agent recover decisions, invariants, ownership, and the next gate without ingesting the project history.","supersedes":[],"title":"The recovery packet: enough context to continue, not enough to drown"},{"architecture_area":"Implementation boundary","canonical_url":"https://andreabor.io/agents/oracles-before-full-model-parity/","claim_boundary":"These model-free gates do not contain checkpoint weights or prove layer, logits, quality, Metal, SSD, memory, or performance parity.","decision":"Make tokenizer and chat behavior independently executable and mutation-tested before using full-model output as the debugging oracle.","estimated_tokens":{"full_note":1196,"method":"UTF-8 source bytes divided by four; approximate","retrieval_capsule":307},"evidence":"59 tokenizer cases, six decode controls, 39 chat cases, 153/153 contract mutations rejected, sanitizer and full model-free regression gates","evidence_checkpoint":"Hebrus fcfd5de","failure_signature":"One differing model response leaves tokenizer, template, graph, state, quantization, kernel, and sampler defects equally plausible.","featured":false,"id":"AFN-008","invariant":"Prompt bytes, token IDs, errors, and trust provenance are closed before layer or final-logit parity is allowed to diagnose the graph.","keywords":["tokenizer oracle","chat template oracle","mutation testing","model bring-up","Transformers parity","Qwen4Exp","autonomous agents"],"markdown_url":"https://andreabor.io/agents/oracles-before-full-model-parity/index.md","minimal_safe_implementation":"Combine pinned upstream captures, independent offline regeneration, native parity tests, labelled contract controls, and fail-closed mutation testing.","phase":"4","prerequisites":["AFN-001"],"project":{"contributing_url":"https://github.com/andreaborio/hebrus/blob/main/CONTRIBUTING.md","issues_url":"https://github.com/andreaborio/hebrus/issues","name":"Hebrus","repository_url":"https://github.com/andreaborio/hebrus"},"published":"2026-08-30","rejected_shortcut":"Using a plausible full-model answer as the first oracle or letting a fixture generator approve its own implementation.","related_notes":["AFN-005","AFN-006","AFN-007","AFN-009","AFN-010","AFN-014"],"retrieval_triggers":["full-model mismatch has too many possible owners","tokenizer or template fixture design","mutation-testing a model contract"],"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.","status":"verified checkpoint","summary":"Phase 4 used pinned captures, independent regeneration, native tests, and 153 contract mutations to close tokenizer and chat semantics before a runtime graph existed.","supersedes":[],"title":"Close the text pipeline before asking the model"},{"architecture_area":"Implementation boundary","canonical_url":"https://andreabor.io/agents/unicode-is-part-of-the-model-contract/","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.","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.","estimated_tokens":{"full_note":1055,"method":"UTF-8 source bytes divided by four; approximate","retrieval_capsule":345},"evidence":"Pinned tokenizer.json backend, Devanagari divergence capture, Unicode trimming fixture, independent offline regeneration, and C99 parity tests","evidence_checkpoint":"Hebrus fcfd5de","failure_signature":"Multilingual text produces different IDs, combining marks split differently, or edge information separators survive native trimming.","featured":false,"id":"AFN-007","invariant":"The serialized tokenizer backend and pinned Python/Jinja byte behavior outrank convenience constructors and host-language whitespace guesses.","keywords":["Unicode tokenizer","combining marks","tokenizer.json","Jinja trim","Python str.strip","native runtime parity","Qwen4Exp"],"markdown_url":"https://andreabor.io/agents/unicode-is-part-of-the-model-contract/index.md","minimal_safe_implementation":"Pin tokenizer.json, normalization and regex; trim complete Unicode code points with captured Python semantics; independently regenerate exact bytes and IDs.","phase":"4","prerequisites":["AFN-001"],"project":{"contributing_url":"https://github.com/andreaborio/hebrus/blob/main/CONTRIBUTING.md","issues_url":"https://github.com/andreaborio/hebrus/issues","name":"Hebrus","repository_url":"https://github.com/andreaborio/hebrus"},"published":"2026-08-30","rejected_shortcut":"Reconstructing with AutoTokenizer defaults or replacing Python/Jinja behavior with byte-wise isspace-style helpers.","related_notes":["AFN-006","AFN-008"],"retrieval_triggers":["Python tokenizer ported to native code","combining-mark token drift","Jinja or Python trim mismatch"],"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.","status":"verified checkpoint","summary":"A tokenizer-class reconstruction dropped combining marks, while Jinja trimming followed Python semantics beyond common C whitespace helpers.","supersedes":[],"title":"Unicode is part of the model contract"},{"architecture_area":"Implementation boundary","canonical_url":"https://andreabor.io/agents/chat-rendering-needs-provenance/","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.","decision":"Render chat as one byte stream plus contiguous DATA and TRUSTED_CONTROL segments, then tokenize every segment according to its provenance.","estimated_tokens":{"full_note":1045,"method":"UTF-8 source bytes divided by four; approximate","retrieval_capsule":315},"evidence":"39-case chat oracle, literal-control adversarial cases, segmented tokenizer adapter, transactional failure tests, and the Phase 4 model-free gate","evidence_checkpoint":"Hebrus fcfd5de","failure_signature":"Flattening and retokenizing promotes a user, system, or tool literal such as \u003c|im_end|\u003e into template syntax.","featured":false,"id":"AFN-006","invariant":"Only template-authored atoms can become trusted control IDs; caller data remains data even when its bytes spell the same token.","keywords":["chat template security","control token provenance","prompt injection boundary","tool messages","Qwen4Exp","tokenizer","autonomous agents"],"markdown_url":"https://andreabor.io/agents/chat-rendering-needs-provenance/index.md","minimal_safe_implementation":"Return one byte stream plus complete contiguous provenance segments, validate coverage, and tokenize DATA and TRUSTED_CONTROL independently and transactionally.","phase":"4","prerequisites":["AFN-001"],"project":{"contributing_url":"https://github.com/andreaborio/hebrus/blob/main/CONTRIBUTING.md","issues_url":"https://github.com/andreaborio/hebrus/issues","name":"Hebrus","repository_url":"https://github.com/andreaborio/hebrus"},"published":"2026-08-30","rejected_shortcut":"Escaping suspicious characters or flattening the rendered transcript and trying to reconstruct trust from its spelling.","related_notes":["AFN-007","AFN-008"],"retrieval_triggers":["chat template mixes controls with client text","literal special-token injection","tool output contains protocol markers"],"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.","status":"verified checkpoint","summary":"A byte-identical control-token spelling can be trusted template syntax or untrusted client data; flattening before tokenization destroys that distinction.","supersedes":[],"title":"Rendered chat is not a flat string: preserve provenance"},{"architecture_area":"Implementation boundary","canonical_url":"https://andreabor.io/agents/physical-logits-are-not-the-vocabulary/","claim_boundary":"This closes the text-domain semantics only; it does not prove full-model logits parity, generation quality, or runtime support.","decision":"Represent the tokenizer domain and the physical logits width as separate constants, masking every unassigned output row before sampling.","estimated_tokens":{"full_note":937,"method":"UTF-8 source bytes divided by four; approximate","retrieval_capsule":292},"evidence":"Pinned tokenizer backend, 59 encode/decode cases, six boundary controls, sampler-boundary test, and the Phase 4 model-free gate","evidence_checkpoint":"Hebrus fcfd5de","failure_signature":"An unassigned padded row wins selection and is clamped, decoded ambiguously, or misinterpreted as a stop token.","featured":false,"id":"AFN-005","invariant":"The graph admits 248,320 physical rows while sampling remains restricted to token IDs in [0, 248077).","keywords":["padded logits","tokenizer vocabulary","sampling mask","Qwen4Exp","special tokens","model runtime","autonomous agents"],"markdown_url":"https://andreabor.io/agents/physical-logits-are-not-the-vocabulary/index.md","minimal_safe_implementation":"Store physical width and semantic vocabulary separately, mask every invalid row before selection, and test with invalid rows numerically dominant.","phase":"4","prerequisites":["AFN-001"],"project":{"contributing_url":"https://github.com/andreaborio/hebrus/blob/main/CONTRIBUTING.md","issues_url":"https://github.com/andreaborio/hebrus/issues","name":"Hebrus","repository_url":"https://github.com/andreaborio/hebrus"},"published":"2026-08-30","rejected_shortcut":"Using one n_vocab value to answer tensor shape, sampling validity, decode behavior, and stop semantics.","related_notes":["AFN-004","AFN-008"],"retrieval_triggers":["output rows exceed tokenizer vocabulary","padded logits produce invalid IDs","sampling and decode boundaries disagree"],"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.","status":"verified checkpoint","summary":"Qwen4Exp exposes 248,320 output rows but only 248,077 valid token IDs; collapsing those domains creates invalid sampling and ambiguous decoding.","supersedes":[],"title":"A logits matrix is not always the vocabulary"},{"architecture_area":"Implementation boundary","canonical_url":"https://andreabor.io/agents/evidence-before-execution/","claim_boundary":"The checkpoint is structurally admitted but remains pinned-not-supported; this note makes no throughput, quality, or runtime-support claim.","decision":"Freeze the source identity and executable contracts before implementing model execution.","estimated_tokens":{"full_note":1414,"method":"UTF-8 source bytes divided by four; approximate","retrieval_capsule":292},"evidence":"Model-free, sanitizer, admission, CPU, Metal-regression, and build-isolation gates","evidence_checkpoint":"Hebrus 6c3ae19","failure_signature":"Kernel debugging begins before the exact input contract is closed, so local fixes accumulate around a plausible but incorrect model.","featured":false,"id":"AFN-001","invariant":"Execution cannot become authoritative until source identity, model math, artifact geometry, and admission failures are independently executable.","keywords":["autonomous coding agents","Qwen3.8-Flash-Next","Qwen4Exp","Hebrus","model bring-up","Apple Silicon","inference architecture"],"markdown_url":"https://andreabor.io/agents/evidence-before-execution/index.md","minimal_safe_implementation":"Pin source and inventory, build scalar oracles, freeze physical owners, and require CPU-only admission before creating the execution graph.","phase":"0–3","prerequisites":[],"project":{"contributing_url":"https://github.com/andreaborio/hebrus/blob/main/CONTRIBUTING.md","issues_url":"https://github.com/andreaborio/hebrus/issues","name":"Hebrus","repository_url":"https://github.com/andreaborio/hebrus"},"published":"2026-08-30","rejected_shortcut":"Starting from a model name or generic architecture match and allowing the first plausible graph to define the specification.","related_notes":["AFN-002","AFN-003","AFN-004","AFN-008","AFN-009"],"retrieval_triggers":["new model-family bring-up","uncertain checkpoint identity","graph work beginning before executable contracts"],"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.","status":"verified checkpoint","summary":"Why the Qwen4Exp bring-up froze identity, math, artifact geometry, and failure semantics before the first Metal graph was allowed to exist.","supersedes":[],"title":"Porting Qwen3.8-Flash-Next to Hebrus: evidence before execution"},{"architecture_area":"Implementation boundary","canonical_url":"https://andreabor.io/agents/expertmajor-family-four/","claim_boundary":"MLX affine4 G64 proves the geometry only; no Qwen4Exp routed-expert codec is release-qualified by this decision.","decision":"Extend ExpertMajor v2 with a distinct family-4 descriptor while keeping its wire format unchanged.","estimated_tokens":{"full_note":1045,"method":"UTF-8 source bytes divided by four; approximate","retrieval_capsule":288},"evidence":"Sparse 48×512 fixture, unchanged legacy fixture hashes, strict C and sanitizer tests","evidence_checkpoint":"Hebrus c5cedb0","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.","featured":false,"id":"AFN-002","invariant":"Container version, model-family geometry, and physical codec identity remain independent decisions.","keywords":["ExpertMajor v2","mixture of experts","Qwen4Exp","quantization geometry","MLX affine4","GGUF","artifact design"],"markdown_url":"https://andreabor.io/agents/expertmajor-family-four/index.md","minimal_safe_implementation":"Add one immutable family descriptor, validate every count/role/shape/order exactly, preserve legacy branches, and label a geometry-only codec candidate as non-release.","phase":"2","prerequisites":["AFN-001"],"project":{"contributing_url":"https://github.com/andreaborio/hebrus/blob/main/CONTRIBUTING.md","issues_url":"https://github.com/andreaborio/hebrus/issues","name":"Hebrus","repository_url":"https://github.com/andreaborio/hebrus"},"published":"2026-08-30","rejected_shortcut":"Bumping the wire version, padding width 640 opportunistically, or reusing another family ID merely to obtain a positive fixture.","related_notes":["AFN-003","AFN-004"],"retrieval_triggers":["new expert geometry in an existing container","logical row width does not divide codec block size","structural acceptance confused with codec qualification"],"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.","status":"verified structural decision","summary":"A new 512-expert family needed stricter geometry, not a new container version—and a 640-wide row exposed the difference between structural proof and codec qualification.","supersedes":[],"title":"Why Qwen4Exp kept ExpertMajor v2"},{"architecture_area":"Storage","canonical_url":"https://andreabor.io/agents/ple-fixed-page-store/","claim_boundary":"The wire structure is frozen; production row codec, rows per page, page stride, and cache policy remain unqualified.","decision":"Represent PLE as a fixed-page embedded extent with affine row location and one digest per page, never a per-row offset table.","estimated_tokens":{"full_note":1146,"method":"UTF-8 source bytes divided by four; approximate","retrieval_capsule":284},"evidence":"Strict parser/writer tests, ASan/UBSan, whole-payload corruption, overflow, fsync, rename, and short-read failures","evidence_checkpoint":"Hebrus c5cedb0","failure_signature":"Metadata grows with row count, lazy mapping creates unbounded first-touch, or bytes are verified in one read and copied from another.","featured":true,"id":"AFN-003","invariant":"Every row maps affinely to one fixed page, and caller output is published only from the same verified page snapshot.","keywords":["PLE row store","SSD streaming","fixed-page storage","checksummed embeddings","affine indexing","transactional IO","Qwen4Exp"],"markdown_url":"https://andreabor.io/agents/ple-fixed-page-store/index.md","minimal_safe_implementation":"Use a fixed manifest, one digest per fixed-stride page, checked locate arithmetic, single-snapshot verified reads, and an atomic verified writer.","phase":"2","prerequisites":["AFN-001"],"project":{"contributing_url":"https://github.com/andreaborio/hebrus/blob/main/CONTRIBUTING.md","issues_url":"https://github.com/andreaborio/hebrus/issues","name":"Hebrus","repository_url":"https://github.com/andreaborio/hebrus"},"published":"2026-08-30","rejected_shortcut":"A per-row offset table, OS page faults as the scheduler, or a two-read verify-then-copy path.","related_notes":["AFN-002","AFN-004","AFN-012"],"retrieval_triggers":["hundreds of millions of fixed-width rows","bounded SSD lookup metadata","TOCTOU-safe page verification"],"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.","status":"verified structural decision","summary":"The fixed-page PLE store: affine lookup, independent checksums, transactional reads, and a codec decision intentionally left open.","supersedes":[],"title":"320 million embedding rows without a 320 million-entry index"},{"architecture_area":"Admission","canonical_url":"https://andreabor.io/agents/admission-before-metal/","claim_boundary":"The dedicated binary proves structural admission only and intentionally rejects generation; normal builds still register no Qwen4Exp physical runtime profile.","decision":"Complete exact artifact admission in a dedicated CPU-only path before registering Qwen4Exp execution.","estimated_tokens":{"full_note":1334,"method":"UTF-8 source bytes divided by four; approximate","retrieval_capsule":291},"evidence":"Sparse GGUF fixture, field-specific negative matrix, GPU-symbol isolation, sanitizer and full regression gates","evidence_checkpoint":"Hebrus 6c3ae19","failure_signature":"A malformed artifact reaches the backend and fails as an opaque missing-tensor, allocation, overlap, or device error.","featured":true,"id":"AFN-004","invariant":"No GPU symbol, allocation, graph, or sparse-payload read is reachable until identity, policy, tensors, extents, and ownership all pass.","keywords":["model admission","fail closed","GGUF validation","GPU isolation","tensor ownership","Qwen4Exp loader","autonomous agents"],"markdown_url":"https://andreabor.io/agents/admission-before-metal/index.md","minimal_safe_implementation":"Run ordered CPU-only admission over exact metadata, tensor identities, manifests, spans, exclusions, and owners, with one negative fixture per boundary.","phase":"3","prerequisites":["AFN-001","AFN-002","AFN-003"],"project":{"contributing_url":"https://github.com/andreaborio/hebrus/blob/main/CONTRIBUTING.md","issues_url":"https://github.com/andreaborio/hebrus/issues","name":"Hebrus","repository_url":"https://github.com/andreaborio/hebrus"},"published":"2026-08-30","rejected_shortcut":"Treating a loader as successful once it finds enough familiar tensors to start building a graph.","related_notes":["AFN-005","AFN-008","AFN-013"],"retrieval_triggers":["GPU loader fails too late","artifact ownership or extent ambiguity","need deterministic field-level rejection"],"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.","status":"verified checkpoint","summary":"A CPU-only structural loader that proves metadata, tensor identity, physical ownership, and policy before any GPU symbol or graph allocation is reachable.","supersedes":[],"title":"Admission before Metal: make every bad artifact fail cheaply"}],"operator_contract":{"closeout_rule":"Before closing a verified phase, publish an evidence-bound decision delta or explicitly record that none exists","scope":"Agents explicitly launched or operated by Andrea Borio; external contributors are not bound","url":"https://andreabor.io/agents/operator-contract.txt"},"privacy_policy":"Public architecture only. Excludes personal information, subscriptions, accounts, credentials, private prompts, conversations, local paths, network addresses, and unpublished infrastructure.","project":{"contributing_url":"https://github.com/andreaborio/hebrus/blob/main/CONTRIBUTING.md","issues_url":"https://github.com/andreaborio/hebrus/issues","name":"Hebrus","repository_url":"https://github.com/andreaborio/hebrus"},"retrieval_policy":"Select one note from retrieval_triggers and estimated_tokens; load its capsule before its full body. Treat status, evidence, invariant and claim_boundary as normative.","schema_version":2,"title":"Inference Architecture Field Notes"}