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)
Fixed three critical bugs in v5.3.0:
1. COW ref resolution bug (lines 2354, 2856, 2895 in src/brainy.ts):
- getHistory(), commit(), deleteBranch() were prepending 'heads/' to branch names
- This caused RefManager to resolve 'heads/main' to 'refs/heads/heads/main'
- Actual ref file at 'refs/heads/main' could not be found
- Result: "Ref not found: heads/main" error breaking all COW operations
2. VersionManager commitHash bug (lines 212, 222 in src/versioning/VersionManager.ts):
- save() was assigning entire Ref object to commitHash instead of ref.commitHash
- Expected string, got object causing type mismatches in version metadata
3. Test mock improvements (tests/unit/versioning/VersionManager.test.ts):
- Fixed searchByMetadata to skip metadata check for 'type' property
- Added glob pattern support for tag filtering (e.g. 'v1.*')
- Added deleteNounMetadata mock
- Fixed getNounMetadata to return null for missing version entities
Fixes:
- src/brainy.ts (3 lines): Remove 'heads/' prefix from ref resolution calls
- src/versioning/VersionManager.ts (2 lines): Use ref.commitHash instead of ref
- tests/unit/versioning/VersionManager.test.ts: Fix test mocks
- tests/integration/history-ref-resolution-bug.test.ts: Add regression tests
Test Results:
- Before: 16 test failures
- After: 0 failures in VersionManager tests, 1183/1208 total tests passing (98%)
