David Snelling
d02e522a3e
- id-normalization (#18): `brain.newId()` (UUID v7) + v7 default ids; non-UUID string ids are transparently normalized to a stable UUID v5 on creation AND every lookup — get/update/remove, relate(from,to), related, find({connected}), getMany, removeMany, the transact op-handler, and db.with() overlays — with the caller's original key preserved under `_originalId`. The engine only ever sees a UUID; real UUIDs pass through untouched. universal/uuid.ts gains v5/v7/isUUID + BRAINY_ID_NAMESPACE; new utils/idNormalization.ts (coerceNewEntityId / resolveEntityId). - aggregation min/max delete-safety: `queryAggregate` no longer leaves a stale min/max after deleting the current extreme — min/max now track a value multiset and recompute in-memory (no entity scan; that scan was the prior delete-then-hang a consumer reported). Other metrics were already exact across deletes. Regression test proves resolve-after-delete + correct new min/max. - release.sh RC-safe: explicit version arg, prerelease detection (npm `--tag rc` + GitHub `--prerelease`), full `test:ci` gate (unit + integration), current-branch push, npm-access verification after publish. - native-engine references point at `@soulcraft/cor` (8.0's partner) in user-facing strings/docs. Unit 1461/0 · integration 599/0 · tsc clean.
98 lines
3.6 KiB
TypeScript
98 lines
3.6 KiB
TypeScript
/**
|
|
* @description Brainy 8.0 IdSpace contract: the JS fallback
|
|
* `EntityIdMapper` caps at `u32::MAX` to match the metadata index's
|
|
* Roaring32 bitmap width. When `nextId` would exceed the ceiling,
|
|
* `getOrAssign` throws `EntityIdSpaceExceeded` with a message pointing
|
|
* at the cortex 3.0 binary mapper's `idSpace: 'u64'` mode as the
|
|
* migration path.
|
|
*
|
|
* This is the lockstep counterpart to cortex 3.0's Piece 10 / Step 15
|
|
* (TS wrapper + napi BigInt siblings + Roaring32-or-Treemap
|
|
* `PostingList` enum). Without this guard, a JS-only brainy install
|
|
* past 4.29 B entities would silently truncate entity ids into the
|
|
* low-32-bit range, zeroing query results and corrupting any
|
|
* persisted int-keyed structure that consumed the mapper.
|
|
*/
|
|
|
|
import { describe, it, expect } from 'vitest'
|
|
import {
|
|
EntityIdMapper,
|
|
EntityIdSpaceExceeded,
|
|
U32_ENTITY_ID_MAX,
|
|
} from '../../../src/utils/entityIdMapper.js'
|
|
|
|
/**
|
|
* Construct a fresh in-memory mapper without going through brainy's
|
|
* full storage adapter — we only exercise the in-RAM ceiling guard
|
|
* here, so a minimal `getMetadata`-returning shim is enough.
|
|
*/
|
|
function makeMapper(): EntityIdMapper {
|
|
const storage = {
|
|
getMetadata: async () => null,
|
|
setMetadata: async () => {},
|
|
getNouns: async () => ({ items: [], totalCount: 0 }),
|
|
} as any
|
|
return new EntityIdMapper({ storage })
|
|
}
|
|
|
|
describe('EntityIdMapper U32 IdSpace ceiling (Brainy 8.0)', () => {
|
|
it('U32_ENTITY_ID_MAX equals 0xFFFF_FFFF (u32 ceiling)', () => {
|
|
expect(U32_ENTITY_ID_MAX).toBe(0xffff_ffff)
|
|
})
|
|
|
|
it('EntityIdSpaceExceeded is an Error subclass with attempted + ceiling', () => {
|
|
const err = new EntityIdSpaceExceeded(0xffff_ffff + 1)
|
|
expect(err).toBeInstanceOf(Error)
|
|
expect(err.name).toBe('EntityIdSpaceExceeded')
|
|
expect(err.ceiling).toBe(0xffff_ffff)
|
|
expect(err.attempted).toBe(0x1_0000_0000)
|
|
expect(err.message).toMatch(/u32::MAX/)
|
|
expect(err.message).toMatch(/@soulcraft\/cor/)
|
|
expect(err.message).toMatch(/idSpace: 'u64'/)
|
|
})
|
|
|
|
it('normal allocations under the ceiling succeed', async () => {
|
|
const m = makeMapper()
|
|
await m.init()
|
|
const a = m.getOrAssign('uuid-a')
|
|
const b = m.getOrAssign('uuid-b')
|
|
expect(a).toBe(1)
|
|
expect(b).toBe(2)
|
|
expect(a).not.toBe(b)
|
|
})
|
|
|
|
it('throws EntityIdSpaceExceeded when nextId would exceed u32::MAX', async () => {
|
|
const m = makeMapper()
|
|
await m.init()
|
|
// Reach into the mapper to bump `nextId` past the ceiling without
|
|
// actually allocating 4.29 B entities at test time. This mirrors
|
|
// the runtime invariant the guard protects.
|
|
;(m as any).nextId = U32_ENTITY_ID_MAX + 1
|
|
expect(() => m.getOrAssign('uuid-overflow')).toThrow(EntityIdSpaceExceeded)
|
|
})
|
|
|
|
it('the last representable u32 int IS allocatable (boundary case)', async () => {
|
|
const m = makeMapper()
|
|
await m.init()
|
|
;(m as any).nextId = U32_ENTITY_ID_MAX
|
|
// `nextId === U32_ENTITY_ID_MAX` is still within range — the
|
|
// guard checks `> U32_ENTITY_ID_MAX`, so this last allocation
|
|
// succeeds.
|
|
const id = m.getOrAssign('uuid-at-ceiling')
|
|
expect(id).toBe(U32_ENTITY_ID_MAX)
|
|
// The NEXT allocation overflows.
|
|
expect(() => m.getOrAssign('uuid-after-ceiling')).toThrow(
|
|
EntityIdSpaceExceeded,
|
|
)
|
|
})
|
|
|
|
it('existing uuid lookup never overflows even when nextId is past ceiling', async () => {
|
|
const m = makeMapper()
|
|
await m.init()
|
|
const assigned = m.getOrAssign('uuid-existing')
|
|
;(m as any).nextId = U32_ENTITY_ID_MAX + 1
|
|
// Looking up an already-assigned UUID does NOT allocate; the
|
|
// guard is on the assign path only.
|
|
expect(m.getOrAssign('uuid-existing')).toBe(assigned)
|
|
})
|
|
})
|