This repository has been archived on 2026-09-03. You can view files and clone it, but you cannot make any changes to it's state, such as pushing and creating new issues, pull requests or comments.
open-brainy/docs/architecture
David Snelling 4e058720b4
Some checks failed
CI / Node 22 (push) Waiting to run
CI / Node 24 (push) Waiting to run
CI / Integration + conformance (Node 22) (push) Waiting to run
CI / Bun (latest) (push) Waiting to run
Delta Gate / Delta gate — candidate vs control (push) Failing after 7s
fix(index): a field holds every value kind it was written with, not the first one
The metadata index fixed a field's value type from the first value it saw.
Every later value of another kind was coerced to that type, and when coercion
failed — `Number('electronics')` is NaN — the value was dropped from the index
with no error at all. The row stayed readable by id and by vector search and
vanished only from equality filters on that one field, which is what made it so
quiet: writing `category: 'electronics'` rows and then `category: 5` rows left
`where { category: 5 }` returning nothing, while the same rows in a
numbers-only corpus answered correctly.

The column store now keeps one posting column per (field, kind), where a kind
is a JavaScript typeof class. The first kind a field sees keeps the historical
`_column_index/<field>/` layout, so a single-kind field is byte-identical to
what earlier versions wrote and an index written before this opens unchanged;
each later kind takes its own column at `_column_index/<field>/k/<kind>/`.

Equality reads the column matching the query value's own kind, so `{c: 5}` and
`{c: '5'}` match different rows and neither is coerced into the other. Ranges
route by the kind of their bounds, and an unbounded range — the "has any value"
probe behind `exists` — reads every kind. A mixed field orders by kind first,
then by value, because a number and a string have no order between them. A
value that cannot be encoded for the column its own kind selected now raises
instead of being skipped: that path is unreachable by construction, and if it
is ever reached it is the silent drop this change exists to end.

Two neighbours fell out of the same routing. A boolean query value is now
encoded to the 1/0 the column stores, so boolean equality matches at all. And
an integer column widens to f64 the first time a non-integer arrives, so 4.5 is
stored as itself rather than rounded to 5 and answering the wrong query.

Field type inference reports every kind a field holds beside its dominant
reading, rather than leaving callers to treat one type as the whole answer.

Pins: mixed-kind equality in both write orders, `5` vs `'5'`, booleans mixed in,
a numeric range over a mixed field's numbers, close/reopen keeping every typed
posting, and an index in the pre-existing on-disk shape still reading.
`tests/critical-neural-validation.test.ts` — which writes `category` as strings
in one test and as numbers in another against one shared brain — passes whole
for the first time.

(cherry picked from commit a128f0eda5)
2026-09-03 09:07:43 -07:00
..
aggregation.md docs: rename the native provider to @soulcraft/cor across public docs and JSDoc 2026-07-02 15:11:41 -07:00
augmentations-actual.md refactor(8.0)!: remove distributed clustering subsystem — inert/orphaned, scale is single-process + native provider 2026-06-15 10:37:39 -07:00
augmentations.md fix: update all imports and references from BrainyData to Brainy 2025-09-30 17:09:15 -07:00
data-storage-architecture.md fix(index): a field holds every value kind it was written with, not the first one 2026-09-03 09:07:43 -07:00
finite-type-system.md chore: rename to @soulcraftlabs/brainy for Open Brainy on The Source 2026-08-27 17:07:09 -07:00
index-architecture.md docs(release): the 10.4.0 entry, the index-health concept doc, and the API surfaces — written from the tree, not the plan 2026-08-25 10:02:25 -07:00
initialization-and-rebuild.md docs(release): the 10.4.0 entry, the index-health concept doc, and the API surfaces — written from the tree, not the plan 2026-08-25 10:02:25 -07:00
multiprocess-storage-mixin.md chore: rename to @soulcraftlabs/brainy for Open Brainy on The Source 2026-08-27 17:07:09 -07:00
noun-verb-taxonomy.md chore: rename to @soulcraftlabs/brainy for Open Brainy on The Source 2026-08-27 17:07:09 -07:00
overview.md docs: rename the native provider to @soulcraft/cor across public docs and JSDoc 2026-07-02 15:11:41 -07:00
PERFORMANCE_ANALYSIS.md feat: Brainy 3.0 - Production-ready Triple Intelligence database 2025-09-11 16:23:32 -07:00
storage-architecture.md feat(8.0): API simplification — remove neural()/Db.search, one storage path key, integration→0 2026-06-20 13:31:11 -07:00
triple-intelligence.md docs(8.0): correct public docs to the real 8.0 API + honest perf claims 2026-06-29 10:03:02 -07:00
zero-config.md chore: rename to @soulcraftlabs/brainy for Open Brainy on The Source 2026-08-27 17:07:09 -07:00