Status: Accepted for the bounded first-party managed HNSW candidate stage on 2026-10-04. Online projection, persisted index format and public ANN capability remain unqualified and gated by later contracts.
The accepted 2026-10-05 test-resource stage is REQ/AC-ANN-013 in
ManagedAnn. Root freezes/reviews/joins; a Luna
worker changes only native TUnit attributes on the specified six heavyweight
fixture methods to unkeyed [NotInParallel], as refined on 2026-10-07. The
unused named Search test-resource helper is removed. Only those six flows are
globally isolated within their TUnit process; there is no assembly-wide
serialization. Test bodies, corpus sizes, explicit concurrency tests, product
execution budgets and global runner settings remain unchanged. Verify
the private base/post packet, full strict build/format/governance, native TUnit normal
and scalar suites and exact-source Linux originals before any qualification
claim. The unchanged full R111 failure and focused pass indicate scheduling
sensitivity without proving the failure's cause. Rollback restores only the
prior test scheduling; there is no data,
dependency, public API or production admission change.
Exact vector scans are the correctness oracle and current public source path. The product prefers a managed-first ANN implementation; a native provider adds deployment, license, persistence, concurrency, deletion, and memory-ownership risks. Root selects an independently authored KeyLoad-owned packed managed HNSW candidate for the first computational stage, with no new package, native binary or project. This decision approves implementation of the bounded candidate and its independent real-store tests; it does not qualify recall, an online projection, a persisted format or a public capability.
Select a provider only after a pinned-source audit and real-store comparison against exact search. Required evidence includes recall by filter/selectivity, update/delete/reinsert behavior, concurrent access, persistence/rebuild, memory accounting, and platform/license dependencies. ANN remains optional until the exact oracle and fallback semantics are measurable.
flowchart LR
Write[Canonical vector mutation] --> Projection[Versioned derived ANN projection]
Projection --> Search[Filtered candidate retrieval]
Exact[Exact vector oracle] --> Compare[Recall and correctness qualification]
Search --> Compare
Compare -->|qualified| Enable[Capability manifest enables ANN]
Compare -->|not qualified| ExactOnly[Keep exact search]
- Always scan exact vectors: dependable oracle but scaling cost remains.
- Add an unreviewed native package: rejected until transitive binaries, licensing, and ownership are audited.
- Audited Hnsw.Net 0.1.4: not admitted. Its first vector chunk allocates 256 MiB, search/build lack cancellation and work admission, and pooled visited state has no retained concurrency cap. A consumer-side wrapper cannot supply cancellation inside its synchronous unbounded algorithm. This is a third-party package, not a ManagedCode-owned dependency repair.
- First-party packed managed HNSW: selected as the bounded computational candidate; lifecycle and public integration remain separate qualification stages.
Related: REQ-SEARCH-001/AC-SEARCH-001, REQ-SEARCH-003/AC-SEARCH-003, REQ-SEARCH-004/AC-SEARCH-004, REQ-SEARCH-005/AC-SEARCH-005, REQ-SEARCH-006/AC-SEARCH-006, ADR-006, ADR-009, ADR-018, ADR-022; KL-030..032, KL-059..060, KL-067. Current source: canonical vectors are document-revision-bound records in src/KeyLoad.Core/GraphAndSeries.cs, with the exact oracle in src/KeyLoad.Query/Features/Search/Queries/SearchEngine.cs. The node-local canonical vector and document-revision authority stays outside any provider; Search owns only a rebuildable derived ANN index/projection. The Search slice under src/KeyLoad.Query/Features/Search/ owns the provider unless a separate assembly is accepted.
- Freeze provider, license/platform matrix, score/filter API, exact-oracle boundary, and rebuildable generation contract.
- Add real-store property/differential tests for recall, mutation, deletion, filtered retrieval, concurrency, restart, and corrupted generation rejection.
- Implement projection generation and provider adapter in Search; never move node-local canonical vector or document-revision authority out of Core.
- Roll out behind an explicit capability setting; rollback disables the projection and rebuilds from canonical data without changing document state.
- Qualify the exact candidate source and workload on Linux GitHub CI, retaining scalar portability checks; publish exact source/package versions and resource/quality evidence.
No external ANN package or persisted index format is approved here. The root owner-authorized local development workflow applies: actual TUnit tests run through Aspire, and local results remain development evidence. Delivered-source Linux CI, recovery, Docker/Aspire RF3 and genuine GitHub comparison gates remain required. The current historical benchmark is not ANN qualification.
The complete computational API, bounds, requirements, acceptance criteria, slice ownership and rollout are frozen in ManagedAnn. Related tasks are KL-030/031/032/059/060; no task is closed by this decision.
Root accepts the bounded local R2A canonical input seam in ManagedAnnSeed, REQ/AC-ASD-001–006. The ordered contract assigns new Core/Search AnnSeed files to query_wave, independent new AnnSeed TUnit cases to cluster_wave, read-only review to lifecycle_wave and all shared/gate/Git joins to root. One current persisted-policy read cut captures owned visible full-space vectors, actual scalar source/applied/outbox metadata; budgeted metadata and the original vector view avoid double charging. Sorting and exact-bit hashing run only after the gate is released, with finite pre-allocation owned/peak reservations and work/cancellation checks. This is a historical computational seed, not pinned replay, durable generation, public approximation, current authorization or complete AC-ANN-007/008. Existing synchronous queued-gate cancellation and later policy/source/generation validation remain explicit later contracts; R2A changes no storage or client contract.
R2A source is joined and locally verified: full solution build23/formatter23/governance23 passed, and actual Aspire normal/scalar 34-case regressions passed unchanged source/runtime inventories. The linked seed spec retains all original passing reports, the earlier 31/33 failure and its concrete reservation/corruption fixes. This development checkpoint does not mark this ADR Implemented; persisted projection, replay, public admission and exact-source Linux/recovery/RF3 gates remain open.
- R1: implement the immutable packed computational candidate in new Query/Search files and independently authored real-ZoneTree metric, budget, filter, recall and rebuild tests. Root owns integration, all shared files, strict solution checks, Aspire execution and a stage commit. Public exact search and canonical stored data remain unchanged.
- R2: root must first accept an exact native-generated ZoneTree manifest/chunk and source-cut/outbox replay contract, including atomic publication, locks, leases, cancellation, corruption and crash recovery. Only then implement the node-local disposable projection. The current decision does not authorize workers to invent that current-format lifecycle.
- R3: root must first accept versioned SQL/SDK/MCP approximation, completeness, fallback, eligibility and freshness metadata. Only then integrate an explicit ANN capability with persisted authorization in one scoped read cut and genuine RF3 tests. No silent approximation or branch truncation is permitted.
- R4: retain actual loaded corpora, quality/resource counters, normal/scalar reports and exact-source Linux qualification. Global performance still requires the mandated 100,000/1,000,000-record matched GitHub workloads; R1's 10,000-record recall control is not that evidence.
The algorithm reference is the primary HNSW paper, algorithms 1–5. Code is independently authored within KeyLoad's own source ownership and root LICENSE; no source code or package is imported. The immutable source ordinal seeds bounded geometric levels, base degree is at most twice Connections and upper degree at most Connections. Current metric-specific selection uses the unchanged exact similarity oracle: diversification for Cosine/Euclidean and the paper's simple highest-score selection for DotProduct under the refinement below.
Vector-only PutVector updates can preserve DocumentRevision. R2 freshness therefore must bind committed source cuts and actual outbox positions, not only document revision. Logical index identity includes partition, collection, field and the complete VectorSpace; node identity/incarnation/data epoch and read-generation binding belong to the later physical projection contract. Orleans coordinates logical ownership and admission; open ZoneTree handles remain node-local.
Rollback of R1 removes the unused candidate. R2/R3 rollback disables its derived capability and rebuilds from canonical ZoneTree data without changing acknowledged writes, native WAL, replication or atomic recovery journals. R1 changes no public wire or persisted data; later stages require their separately accepted current-product contracts before implementation.
Root accepted the R1 packing/reservation refinement in ManagedAnn before the first runtime gate: actual-level upper offsets/edges, per-query visit bitmap, explicit conservative array/string/object accounting, reported build/search reservations and inclusive exact/excess/sparse admission. This corrects source-review findings without changing public search, canonical data or the unapproved R2/R3 contracts. Both workers retain their disjoint new-file scopes; root must review the revised source and execute every gate before any qualification claim.
The first real Aspire R1 run passed17/19 cases and failed both10,000-record builds on the unchanged work cap before recall/deadline assertions. Root accepts the insertion-work correction: Algorithm1 establishes Connections new edges, keeps base2M/upperM maximum degree, reselects reciprocal neighbors only on overflow, and uses validated source ordinals for identical ID ordering with truthful integer-comparison charges. TASK-ANN-R1-PACKED-ALGORITHM owns these changes; TASK-ANN-R1-INDEPENDENT-TESTS retains the same independent cases and limits; TASK-ANN-R1-ROOT-JOIN retains the original failure reports and repeats strict checks and actual Aspire normal/scalar evidence. This is an implementation correction, not a qualified performance result or waived acceptance gate.
The second original Aspire cohort also passed17/19 and hit the unchanged build work cap in FindWorst. Root accepts the operation-local worst-slot cache: reject against a validated cached worst, update on append, and fully recompute only after an accepted replacement. One scratch integer fits the declared fixed object reservation; graph state, arrays, work caps, metrics and independent tests remain unchanged. The same owned tasks must review reset/replacement invariants and repeat complete gates; no observed recall or performance improvement is claimed yet.
The third original Aspire cohort remains17/19 and hits the same cap in reciprocal-link work. Root accepts the bounded dual-heap search refinement, replacing repeated frontier/worst scans while preserving exact extraction/tie order and the diversified neighbor-selection rule. Three explicitly reserved int[E] heap arrays replace the old bool[E] processed array/cache; private admission formulas include every array before allocation. Root and independent review must prove map/remove/reset invariants and unchanged test outcomes. Reciprocal work, recall and deadline qualification remain open; the three original failures are retained and no cap/AC reduction is authorized.
The fourth original report reaches and passes all10 Cosine/Euclidean cells, but remains17/19 because DotProduct builds exceed the unchanged work cap. Root accepts simple DotProduct neighbor selection for both new and overflowing reciprocal edges, with unchanged exact dot scores and deterministic ties. This selects Algorithm3 for that nonmetric similarity while preserving diversification for the two qualified metric controls. It removes pair-diversity work without changing bounds or ACs; the potential bridge/recall cost must pass the unchanged five DotProduct cells. Whole-source guard failure from concurrent benchmark edits and separate unchanged ANN/runtime proof remain explicit; all results are local development evidence.
Unit44b's four ordinary build-deadline failures lead to the accepted packed-owned validation refinement, REQ/AC-ANN-009 and TASK-ANN-R1-OWNED-SCORES. Only privately copied finite vectors may use the internal trusted scorer; untrusted validation, metric arithmetic, quality, work/deadline limits and all existing tests remain mandatory. A unique DotProduct candidate copy may remove redundant membership work with actual charges and identical selection/ties. Root reviews the private Luna patch and retains full normal/scalar/Linux evidence before any qualification claim.
The 2026-10-05 prepared-value refinement accepts REQ/AC-ANN-010 and TASK-ANN-R1-PREPARED-VALUE. Replace per-candidate prepared-object allocations only in privately owned packed neighbor work with a finite-checked-carrier readonly value. One shared helper retains the exact current metric reduction and untrusted validation remains mandatory. Implement numeric extraction, private value, consumed diversification/overflow joins and independent exact-score/allocation regressions in that order. Query worker owns its private Search implementation packet, cluster worker owns its independent real-store test packet, and root owns complete review, joins, full checks, Aspire native/scalar corpus gates and original exact-source evidence. No data, wire, capability or persisted-format change is introduced; rollback reverts the value joins. This ADR remains unqualified until its original full acceptance is proven.
Root accepts the R2B pin prerequisite in ManagedAnnSeed, REQ/AC-ASD-007–009 and TASK-ANN-R2-PIN-CONTRACT-PROOF. Select the existing persisted administrator-gated canonical consumer operations: commit an observed current-Tail pin before seed capture, bridge exactly through the captured Tail with signed empty-effect receipts, and retain later history for replay. The bounded single-record bridge in independent real-store tests is a correctness control, not a production performance choice. Cluster worker owns only new private Search test files; root owns review, Aspire normal/scalar/full gates, original evidence and all-code checkpoints. This prerequisite accepts no physical generation, alias, format, public capability, or canonical-data change; the complete native ZoneTree projection/recovery contract remains required.
Root accepts TASK-ANN-R1-CONSTRUCTION-VALUE and REQ/AC-ANN-011 in the construction join. Use the existing finite-owned readonly value for construction, with one internal constrained generic traversal and explicit class/value contract implementations. Preserve every score, ordinal order, validation and work/deadline/cancellation charge. Root freezes and reviews the private implementation, joins independent class/value traversal and allocation tests, then retains full Release/static and Aspire native/scalar corpus evidence. Exact-source Linux and ANN lifecycle/RF3 acceptance remain required. No persistence or public transport changes occur; rollback reverts these computational joins, with no store change.
REQ/AC-ANN-014 and TASK-ANN-BUILD-OBSERVATION are frozen in ManagedAnn. The Luna worker owns only the four existing heavy Search case files and two new feature-local model/helper files in that contract; root owns review, join, strict checks, actual Aspire normal/scalar evidence and all-code commits. Measure the single existing synchronous Build after retaining its original budget. Emit safe counters, elapsed ticks and current-thread allocations only after it settles, with original/fatal failure priority. Preserve every original resource limit, input, assertion and admission setting. No dependency, production, data or wire change occurs; rollback removes only the diagnostic wrappers. This stage measures failure context without claiming a cause, deadline repair or performance gain.
Root accepts REQ/AC-ANN-015 and TASK-ANN-R1-NEIGHBOR-COUNT in ManagedAnn. Query's owned RAM adjacency packs the count into its existing first slot within the unchanged five-million-record/degree128 admission. Preserve neighbor order, metric arithmetic, actual edge charges and every original resource/deadline cap; there is no data or public-format change. One Luna worker owns the narrow PackedAnnGraph source packet and independent native graph/candidate regressions; root owns contract review, exact-base join, unchanged-work before/after development observations, strict checks and Aspire normal/scalar/full Linux gates. Rollback restores only the scan representation. Qualification remains pending until the original full quality, authorization, recovery and RF3 gates have evidence; this source-level work reduction is not a measured speedup claim.
Accepted bounded stage: REQ/AC-ANN-016 and TASK-ANN-DUPLICATE-BUDGET-CHECKS in REQ-AC-ANN-016.md.
AnnWorkBudget.Charge begins by calling Check, then validates the charge and updates the existing work counter. In eight frozen Search source files, twelve sites call Check immediately before Charge with no intervening operation. Remove only those twelve calls. Retain every Charge and its original amount, so each charged action still observes cancellation/deadline immediately before its counter update. Preserve other explicit checks, particularly any path that can exit without reaching a charge.
The Luna worker owns only the eight listed ANN source files in the private packet. Root owns exact-base review, integration, strict checks, and same-source genuine Aspire normal/scalar observations with no changes to the corpus, caps, deadline, test admission, or assertions. This is an equivalent-check-count optimization candidate, not a measured speedup, timeout diagnosis, or qualification. Rollback restores the eight source files. Persistence, public transport, and storage are outside this stage.
Candidate stage REQ/AC-ANN-017 / TASK-ANN-INNERLOOP-CHECKS in
REQ-AC-ANN-017.md.
The 10k Build report records 165M work units, 4.37M distances and 12.41M edge visits, but does not attribute their per-method source or prove the original deadline cause. Actual source walks HNSW edge lists, scores unseen neighbors, performs heap comparisons and diversifies / repairs reciprocal neighborhoods. These counters remain exact and unchanged in this stage.
In four binary-heap sift loops, a loop-entry budget.Check() is followed on
every executed iteration by IsBetter / IsWorse, which calls
budget.Charge(1) and therefore the same ReadExecutionBudget.Check() before
its work update. In Greedy, each loop iteration similarly reaches charged
NeighborCount. Remove only those five duplicated loop-entry checks. Preserve
every comparison, distance, edge, mutation and charge. Keep the SearchLayer
loop check because its PopBest sentinel may exit without charging; retain all
other checks, cancellation/deadline paths and original bounds.
The source owner is restricted to PackedAnnCandidateHeaps.cs and
PackedAnnLayerSearch.cs. Root owns cumulative source join with pending ANN
patches, review, normal/scalar unchanged-corpus observations, strict gates and
qualification. This is an unmeasured repeated-check optimization candidate,
not a deadline diagnosis or speed claim. Rollback restores the five checks.
REQ/AC-ANN-018 and TASK-ANN-RECIPROCAL-INSERTION in ManagedAnn freeze a narrow source-proven correction. Ascending private construction inserts a source once per layer; distinct prior reciprocal targets cannot already contain that new source at that layer. Remove only the target membership scan and unused helper, preserving the graph, candidate deduplication, scores, actual distance/edge work, cancellation, original deadlines and admission. Work counters must report the comparisons actually performed, without fabricated replacement charges.
The Luna owner supplies the guarded source packet and independent native adjacency regressions. Root compares complete successful controls, retains original incomplete Linux normal/scalar observations, and owns the join and all strict/Aspire gates. A partial failed build cannot prove graph equivalence or speed. R1 remains an internal immutable candidate with no serialized/public contract; R2/R3 require separate accepted contracts. Rollback restores only the removed scan and helper.
Root's successful-control observation joins AC-ANN-018 before code: fixed v1 SHA-256 framing covers the actual complete native IDs/revisions/levels and ordered adjacency plus entry point/maximum level. Build-only ticks/allocations are captured before independent snapshot/assertion/output; actual counters and fixed options are retained. Identical control/test source runs on the original and candidate in each native mode. Failed builds cannot supply a graph hash or equivalence baseline. This remains test-only evidence with no public or persistence contract, and does not qualify acceleration by itself.