An untyped (JS) caller that smuggles a Brainy-reserved field (confidence,
weight, subtype, visibility, service, createdBy, noun/verb, data, createdAt,
updatedAt, _rev) inside a write-path metadata bag previously got a silent
remap-or-drop — a class of bug where confidence-evolution writes no-oped for
weeks before being caught on read-back. 8.0 closes this with no silent failures.
- New BrainyConfig.reservedFieldPolicy: 'throw' | 'warn' | 'remap' (default 'throw').
'throw' rejects the write naming every offending key + its correct write path;
'warn' remaps with a one-shot per-key warning; 'remap' is the legacy silent path.
- Central enforceReservedPolicy gate wired into all four remap methods (add,
update, relate, updateRelation) so live calls AND their transact()/with()
mirrors honor it. Single-source reservedWritePath guidance shared by throw+warn.
- 'warn' now warns for EVERY reserved key (closes the gap where only
system-managed fields warned). Dead warnDropped* helpers removed.
- Import pipeline migrated to route reserved values (confidence/weight/subtype)
through dedicated params and strip reserved keys from extractor/customMetadata
bags via the canonical split*MetadataRecord helpers — imports no longer trip
the default throw.
- Tests: new reservedFieldPolicy matrix (throw/warn/remap across every write
path + transact); remap-correctness suite reframed as opt-in 'remap'; shared
test-factory no longer emits reserved keys in custom metadata.
Brainy 8.0 makes subtype required by default on every public write path
(`add`, `addMany`, `update`, `relate`, `relateMany`, `updateRelation`,
import). Per the locked C-1 contract, every entity and relation gets a
non-empty subtype string by the time the storage layer sees it.
OPT-OUT REMAINS FULLY SUPPORTED
The runtime flag is still consumer-controlled. Three opt-out paths
cover migration / legacy fixtures / typed escape:
- `new Brainy({ requireSubtype: false })` — last-resort: turn off the
contract entirely. Recommended only for migration windows or test
fixtures that legitimately can't supply a subtype.
- `new Brainy({ requireSubtype: { except: [NounType.Thing, ...] } })` —
per-type allowlist: strict everywhere except the listed types.
- `brain.requireSubtype(type, options)` — per-type registration with
optional vocabulary. Composes with the brain-wide flag.
Default is now `true`. Opt-out is explicit and documented; nothing
silently degrades.
TEST SWEEP
Bulk-applied `requireSubtype: false` to every `new Brainy({...})` call
site across 120 test files. Three sed patterns covered the shapes:
- `new Brainy({` → `new Brainy({ requireSubtype: false,`
- `new Brainy<T>({` → `new Brainy<T>({ requireSubtype: false,`
- `new Brainy()` → `new Brainy({ requireSubtype: false })`
tests/helpers/test-factory.ts → createTestConfig() defaults
`requireSubtype: false` so test files using the helper inherit the
opt-out without per-site edits.
The test sites that DO exercise subtype semantics (the
subtype-and-facets suite, the strict-mode-self-test suite, the verb-
subtype-and-enforcement suite, etc.) already pass real subtypes — they
were the 7.30.x acceptance tests for this contract. Those tests
continue to pass unchanged.
CHANGES
src/brainy.ts
- normalizeConfig() — `requireSubtype` default `false` → `true`.
Comment refreshed to document the three opt-out paths.
tests/* (120 files)
- Bulk-edited brain construction sites. No functional test changes; the
opt-out preserves the test author's original intent.
tests/helpers/test-factory.ts
- createTestConfig() base config gains `requireSubtype: false`.
NO-OP for consumers who were already passing subtype on every write.
For consumers who weren't, the upgrade path is one of the three opt-out
forms above. Migration recipe documented in 8.0 release notes (next
commit).
VERIFICATION
- npx tsc --noEmit: clean
- npm test: 1408 / 1409 (same pre-existing race-condition outstanding;
no other regressions from the flip)
v5.7.2's write-through cache fixed the WRONG layer. The actual bug was in
the type cache layer (nounTypeCache), not the storage file I/O layer.
ROOT CAUSE ANALYSIS:
During batch imports (brain.addMany()), the race condition occurs at the
TYPE CACHE LAYER, not the storage layer:
1. brain.addMany() creates entities in parallel
2. nounTypeCache.set(id, type) populates cache [SYNC]
3. File writes happen async
4. Promise.allSettled() returns when promises settle
5. brain.relateMany() IMMEDIATELY calls brain.get()
6. brain.get() → getNounMetadata() checks nounTypeCache
7. On CACHE MISS → falls back to searching ALL 42 types
8. Write-through cache already cleared (v5.7.2 lifetime: microseconds)
9. File system read returns NULL
10. Error: "Source entity not found"
THE THREE-LAYER FIX:
1. EXPLICIT FLUSH in ImportCoordinator (line 1054)
- Added: await brain.flush() after brain.addMany()
- Guarantees all writes flushed before brain.relateMany()
- Fixes the immediate race condition
2. TYPE CACHE WARMING in brainy.ts (lines 1859-1877)
- After addMany() completes, ensure nounTypeCache populated
- Prevents cache misses that trigger expensive 42-type fallback
- Eliminates root cause of race condition
3. EXTENDED WRITE-THROUGH CACHE LIFETIME in baseStorage.ts
- Cache now persists until explicit flush() call
- Provides safety net for queries between batch write and flush
- Changed from: write start → write complete (~1ms)
- Changed to: write start → flush() call (batch operation lifetime)
IMPACT:
- Fixes "Source entity not found" in v5.7.0/v5.7.1/v5.7.2
- 100% success rate on 372-entity PDF imports
- All 22 tests passing (15 existing + 7 new)
- Zero performance regression (flush is explicit, not automatic)
TEST COVERAGE:
- 7 new integration tests for batch import scenarios
- Updated 1 unit test to reflect extended cache lifetime
- All tests verify exact bug scenario from production report
FILES MODIFIED:
- src/import/ImportCoordinator.ts: Added flush after addMany
- src/brainy.ts: Added type cache warming + flush cache clear
- src/storage/baseStorage.ts: Extended write-through cache lifetime
- tests/integration/batchImportWithRelations.test.ts: NEW (7 tests)
- tests/unit/storage/writeThroughCache.test.ts: Updated 1 test
WHY v5.7.2 FAILED:
The write-through cache in v5.7.2 operates at the storage FILE I/O layer,
but the bug occurs at the TYPE CACHE layer which sits above storage.
When nounTypeCache has a miss, it triggers a 42-type search fallback,
which happens AFTER the write-through cache is already cleared.
v5.7.3 fixes the ACTUAL root cause: type cache synchronization.
