feat(8.0)!: flip requireSubtype default to true (BRAINY-8.0-SUBTYPE-CONTRACT § C-1)
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)
This commit is contained in:
parent
221fc45889
commit
780fb6444b
117 changed files with 282 additions and 282 deletions
|
|
@ -79,7 +79,7 @@ describe('HNSW Index Rebuild (Integration Tests)', () => {
|
|||
console.log('🧪 Test 1: Basic HNSW rebuild with 20 entities...')
|
||||
|
||||
// Phase 1: Create Brainy instance and add data
|
||||
const brain1 = new Brainy({
|
||||
const brain1 = new Brainy({ requireSubtype: false,
|
||||
storage: {
|
||||
type: 'filesystem',
|
||||
fileSystemStorage: { path: testDir }
|
||||
|
|
@ -122,7 +122,7 @@ describe('HNSW Index Rebuild (Integration Tests)', () => {
|
|||
// Phase 2: Simulate container restart - create new Brainy instance
|
||||
console.log('🔄 Simulating container restart...')
|
||||
|
||||
const brain2 = new Brainy({
|
||||
const brain2 = new Brainy({ requireSubtype: false,
|
||||
storage: {
|
||||
type: 'filesystem',
|
||||
fileSystemStorage: { path: testDir }
|
||||
|
|
@ -168,7 +168,7 @@ describe('HNSW Index Rebuild (Integration Tests)', () => {
|
|||
console.log('🧪 Test 2: HNSW rebuild with 100 entities...')
|
||||
|
||||
// Phase 1: Build initial index
|
||||
const brain1 = new Brainy({
|
||||
const brain1 = new Brainy({ requireSubtype: false,
|
||||
storage: {
|
||||
type: 'filesystem',
|
||||
fileSystemStorage: { path: testDir }
|
||||
|
|
@ -205,7 +205,7 @@ describe('HNSW Index Rebuild (Integration Tests)', () => {
|
|||
// Phase 2: Rebuild
|
||||
console.log('🔄 Rebuilding HNSW index...')
|
||||
|
||||
const brain2 = new Brainy({
|
||||
const brain2 = new Brainy({ requireSubtype: false,
|
||||
storage: {
|
||||
type: 'filesystem',
|
||||
fileSystemStorage: { path: testDir }
|
||||
|
|
@ -240,7 +240,7 @@ describe('HNSW Index Rebuild (Integration Tests)', () => {
|
|||
console.log('🧪 Test 3: Large dataset HNSW rebuild (1000 entities)...')
|
||||
|
||||
// Phase 1: Build large index
|
||||
const brain1 = new Brainy({
|
||||
const brain1 = new Brainy({ requireSubtype: false,
|
||||
storage: {
|
||||
type: 'filesystem',
|
||||
fileSystemStorage: { path: testDir }
|
||||
|
|
@ -275,7 +275,7 @@ describe('HNSW Index Rebuild (Integration Tests)', () => {
|
|||
// Phase 2: Rebuild large index
|
||||
console.log('🔄 Rebuilding large HNSW index...')
|
||||
|
||||
const brain2 = new Brainy({
|
||||
const brain2 = new Brainy({ requireSubtype: false,
|
||||
storage: {
|
||||
type: 'filesystem',
|
||||
fileSystemStorage: { path: testDir }
|
||||
|
|
@ -315,7 +315,7 @@ describe('HNSW Index Rebuild (Integration Tests)', () => {
|
|||
console.log('🧪 Test 4: HNSW rebuild with memory storage...')
|
||||
|
||||
// Phase 1: Build index in memory
|
||||
const brain1 = new Brainy({
|
||||
const brain1 = new Brainy({ requireSubtype: false,
|
||||
storage: { type: 'memory' },
|
||||
embeddingFunction: async (text: string) => {
|
||||
const hash = text.split('').reduce((acc, char) => acc + char.charCodeAt(0), 0)
|
||||
|
|
@ -364,7 +364,7 @@ describe('HNSW Index Rebuild (Integration Tests)', () => {
|
|||
console.log('🧪 Test 5: Parallel rebuild of all indexes...')
|
||||
|
||||
// Phase 1: Create data with relationships
|
||||
const brain1 = new Brainy({
|
||||
const brain1 = new Brainy({ requireSubtype: false,
|
||||
storage: {
|
||||
type: 'filesystem',
|
||||
fileSystemStorage: { path: testDir }
|
||||
|
|
@ -425,7 +425,7 @@ describe('HNSW Index Rebuild (Integration Tests)', () => {
|
|||
// Phase 2: Restart and rebuild all indexes
|
||||
console.log('🔄 Restarting and rebuilding all 3 indexes...')
|
||||
|
||||
const brain2 = new Brainy({
|
||||
const brain2 = new Brainy({ requireSubtype: false,
|
||||
storage: {
|
||||
type: 'filesystem',
|
||||
fileSystemStorage: { path: testDir }
|
||||
|
|
@ -480,7 +480,7 @@ describe('HNSW Index Rebuild (Integration Tests)', () => {
|
|||
it('should handle empty storage gracefully (no rebuild needed)', async () => {
|
||||
console.log('🧪 Test 6: Empty storage rebuild...')
|
||||
|
||||
const brain = new Brainy({
|
||||
const brain = new Brainy({ requireSubtype: false,
|
||||
storage: {
|
||||
type: 'filesystem',
|
||||
fileSystemStorage: { path: testDir }
|
||||
|
|
@ -510,7 +510,7 @@ describe('HNSW Index Rebuild (Integration Tests)', () => {
|
|||
console.log('🧪 Test 7: Rebuild with single entity...')
|
||||
|
||||
// Phase 1: Add one entity
|
||||
const brain1 = new Brainy({
|
||||
const brain1 = new Brainy({ requireSubtype: false,
|
||||
storage: {
|
||||
type: 'filesystem',
|
||||
fileSystemStorage: { path: testDir }
|
||||
|
|
@ -531,7 +531,7 @@ describe('HNSW Index Rebuild (Integration Tests)', () => {
|
|||
await brain1.close()
|
||||
|
||||
// Phase 2: Rebuild
|
||||
const brain2 = new Brainy({
|
||||
const brain2 = new Brainy({ requireSubtype: false,
|
||||
storage: {
|
||||
type: 'filesystem',
|
||||
fileSystemStorage: { path: testDir }
|
||||
|
|
@ -558,7 +558,7 @@ describe('HNSW Index Rebuild (Integration Tests)', () => {
|
|||
console.log('🧪 Test 8: Rebuild with potential data inconsistencies...')
|
||||
|
||||
// Phase 1: Create data
|
||||
const brain1 = new Brainy({
|
||||
const brain1 = new Brainy({ requireSubtype: false,
|
||||
storage: {
|
||||
type: 'filesystem',
|
||||
fileSystemStorage: { path: testDir }
|
||||
|
|
@ -577,7 +577,7 @@ describe('HNSW Index Rebuild (Integration Tests)', () => {
|
|||
await brain1.close()
|
||||
|
||||
// Phase 2: Rebuild (should handle any missing HNSW data gracefully)
|
||||
const brain2 = new Brainy({
|
||||
const brain2 = new Brainy({ requireSubtype: false,
|
||||
storage: {
|
||||
type: 'filesystem',
|
||||
fileSystemStorage: { path: testDir }
|
||||
|
|
@ -616,7 +616,7 @@ describe('HNSW Index Rebuild (Integration Tests)', () => {
|
|||
it('should persist HNSW graph structure to disk', async () => {
|
||||
console.log('🧪 Test 9: Validate HNSW persistence files...')
|
||||
|
||||
const brain = new Brainy({
|
||||
const brain = new Brainy({ requireSubtype: false,
|
||||
storage: {
|
||||
type: 'filesystem',
|
||||
fileSystemStorage: { path: testDir }
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue