fix: recalibrate find({ limit }) cap + two-tier enforcement + caller location

Brainy 7.30.0 introduced a memory-derived synchronous cap on `find({ limit })`
to prevent OOM. The cap was sound in intent but ~4x too conservative in
calibration: assumed 100 KB per result while typical entity footprint is 7-10 KB
(384-dim float32 vector ≈ 1.5 KB + standard fields + metadata). On a 900 MB
free-memory box the cap derived to 9000 — breaking common safety-cap patterns
like `find({ type, where, limit: 10_000 })` that typically return 10-500
entities. Surfaced as a runtime regression with cascading 500s degrading
production dashboards.

Three concurrent fixes:

A. RECALIBRATE THE FORMULA
- src/utils/paramValidation.ts:175,196,212 — the three memory-derived priorities
  (reservedQueryMemory / containerMemory / freeMemory) all divided by
  100 * 1024 * 1024 (100 KB per result, ~10-15x over conservative). Replaced
  with a new MAX_LIMIT_KB_PER_RESULT = 25 constant that matches observed
  entity size.
- Result: 4 GB container cap goes 10_000 → 40_000; 2 GB cap goes 5_000 →
  20_000; 900 MB free-memory cap goes 9_000 → ~36_000. 100k hard ceiling
  unchanged. `maxQueryLimit` / `reservedQueryMemory` constructor overrides
  unchanged in behavior.

B. TWO-TIER ENFORCEMENT (warn-then-throw)
- Below cap (limit <= maxLimit): silent pass, unchanged.
- Soft tier (maxLimit < limit <= 2 * maxLimit): NEW — one-time warning per
  call site (dedup keyed on caller stack frame + limit value), query
  proceeds. Pre-7.30.2 code that relied on the cap silently allowing typical
  safety-cap limits keeps working; the warning teaches the recipe so consumers
  can fix it intentionally.
- Hard tier (limit > 2 * maxLimit): throw with the same teaching message
  format. Real OOM territory; the cap stops being a recommendation and becomes
  a guardrail.
- The 2x soft margin absorbs typical safety-cap patterns (limit: 10_000
  against a 9 K-cap box) without disabling OOM protection. Real OOM territory
  on a JS in-memory brain is hundreds of thousands of results, not 10x the
  safety cap.

C. IMPROVED ERROR / WARNING MESSAGE
- Same shape as the 7.30.1 enforcement-error messages: state the problem,
  name the three escape valves (maxQueryLimit / reservedQueryMemory /
  pagination), include caller location, link to docs.
- Extracted findCallerLocation() helper from brainy.ts to a new
  src/utils/callerLocation.ts so both the subtype enforcement (7.30.1) and
  the limit enforcement (7.30.2) share one implementation without circular
  imports.

DOCS
- New docs/guides/find-limits.md (public: true) — full reference: why the cap
  exists, the four memory sources the auto-config considers, the three escape
  valves with when-to-use-which guidance, and an explicit "pagination is the
  future-proof pattern" callout (8.0 may tighten the cap further; pagination
  keeps working unchanged).
- docs/api/README.md find() entry gets a one-paragraph `limit` tip + pointer
  to the new guide.
- RELEASES.md v7.30.2 entry.

TESTS
- New tests/integration/find-limits.test.ts (9 tests): below-cap silent pass;
  soft-tier warns once per call site (dedup verified by exercising same vs.
  different source lines via wrapper closures); soft-tier message format
  (names all three escape valves + docs link); soft-tier message includes
  caller location; hard-tier throws; hard-tier message format same as
  soft-tier; consumer maxQueryLimit override raises the cap and shifts both
  tiers accordingly; pre-7.30.2 regression scenario explicitly covered.
- tests/unit/utils/memoryLimits.test.ts — 4 tests updated for the recalibrated
  cap values (hardcoded expected numbers bumped 4x to match new 25 KB/result
  assumption).
- tests/unit/utils/paramValidation.test.ts — auto-limit test extended to cover
  the three-tier semantics (below-cap pass / soft-tier silent / hard-tier
  throw).
- Existing suites unchanged: subtype-and-facets 26/26, verb-subtype-and-
  enforcement 30/30, strict-mode-self-test 13/13. Unit 1468/1468.

CORTEX COMPATIBILITY
- Zero Cortex changes required. Every change is JS-side: formula recalibration
  runs in ValidationConfig.constructor(), two-tier enforcement runs in
  validateFindParams(), both fire before any storage / index / Cortex call.
- The new guide notes that Brainy 8.0's Datomic-style Db.find() may tighten
  per-call limits to keep snapshot semantics cheap; pagination remains the
  pattern that's guaranteed to keep working.

REPO-WIDE CLEANUP
Brainy is the only Soulcraft project that is open source. This commit also
scrubs closed-source product names and product-specific class/field references
from every tracked file in the repo (src/, docs/, tests/, RELEASES.md,
CHANGELOG.md). Consumer-reported bugs, regression scenarios, and release
notes now refer to "a consumer", "a downstream application", "a production
deployment", or "an internal report" — never to the named product. Two
product-named test files renamed to neutral diagnostic names. CLAUDE.md gains
a project-level guard rule documenting the policy and an example list of the
identifiers that may not appear in tracked code.

Verification
- npx tsc --noEmit: clean
- npm test: 1468 / 1468 unit
- All four integration subtype + verb + strict + find-limits suites: 78/78
- npm run build: clean
- Closed-source product reference audit: clean

tests/integration/clear-persistence.test.ts

@@ -1,7 +1,7 @@
 /**
  * Integration tests for clear() bug fix (v5.10.4)
  *
- * Bug report: Workshop team reported that brain.clear() doesn't fully delete persistent storage.
+ * Bug report: a consumer team reported that brain.clear() doesn't fully delete persistent storage.
  * After calling clear() and creating a new Brainy instance, all data was restored from _cow/ directory.
  *
  * Root cause: Setting cowEnabled = false on old instance doesn't affect new instances.
@@ -33,7 +33,7 @@ describe('Clear Persistence Bug Fix (v5.10.4)', () => {
     }
   })
 
-  it('should fully clear persistent storage (Workshop scenario)', async () => {
+  it('should fully clear persistent storage (the reported scenario)', async () => {
     // Step 1: Create and populate instance
     const brain1 = new Brainy({
       storage: {

tests/integration/clear-vfs.test.ts

@@ -1,7 +1,7 @@
 /**
  * Integration tests for clear() VFS reinitialization fix (v7.3.1)
  *
- * Bug report: Workshop team reported that brain.clear() breaks VFS operations.
+ * Bug report: a consumer team reported that brain.clear() breaks VFS operations.
  * After calling clear(), VFS operations fail with:
  * "Error: Source entity 00000000-0000-0000-0000-000000000000 not found"
  *

tests/integration/cow-commit-storage.test.ts

@@ -6,7 +6,7 @@
  * commit objects on disk.
  *
  * Related bugs:
- * - Workshop team report: BRAINY_V5.3.0_SNAPSHOT_BUG_REPORT.md
+ * - v5.3.0 snapshot regression filed via consumer bug report (BRAINY_V5.3.0_SNAPSHOT_BUG_REPORT.md, internal)
  * - Root cause: BlobStorage.ts hardcoded 'blob:' prefix in 9 locations
  */
 

tests/integration/find-limits.test.ts

@@ -0,0 +1,191 @@
+/**
+ * @module tests/integration/find-limits
+ * @description Integration coverage for the 7.30.2 `find({ limit })` cap
+ * recalibration + two-tier enforcement (warn-then-throw). See
+ * `BR-MAXLIMIT-9000` in PLATFORM-HANDOFF.md for the original incident report
+ * and `docs/guides/find-limits.md` for the consumer-facing guide.
+ *
+ * Coverage:
+ *
+ * - Below cap: silent pass.
+ * - Soft tier (`maxLimit < limit <= 2 × maxLimit`): one-time warning logged
+ *   per call site, query returns without throwing.
+ * - Hard tier (`limit > 2 × maxLimit`): throw with the new message format
+ *   including the three escape valves and a docs link.
+ * - Consumer `maxQueryLimit` override raises the cap; warning/throw tiers
+ *   shift accordingly.
+ * - Warning message includes the caller's source location so consumers can
+ *   trace the offending call site without grepping.
+ *
+ * @since 7.30.2
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { Brainy } from '../../src/brainy'
+import { NounType } from '../../src/types/graphTypes'
+import {
+  ValidationConfig,
+  resetLimitWarningCache,
+  validateFindParams
+} from '../../src/utils/paramValidation'
+import * as logger from '../../src/utils/logger'
+
+describe('find({ limit }) two-tier enforcement (7.30.2)', () => {
+  let brain: Brainy<any>
+  let warnSpy: ReturnType<typeof vi.spyOn>
+
+  beforeEach(async () => {
+    // Reset the validation singleton + warning dedup so each test sees a
+    // freshly-derived cap rather than one fixed by an earlier test.
+    ValidationConfig.reset()
+    resetLimitWarningCache()
+    // Spy directly on `prodLog.warn` — the call site the limit enforcement
+    // actually uses. Spying on `console.warn` is unreliable here because
+    // `silent: true` brain config routes through a logger that may suppress
+    // before reaching console, and vitest module isolation can capture a
+    // different `console` reference than the one our logger references at
+    // runtime. The prodLog.warn entry point is what we control, so that's
+    // what we observe.
+    warnSpy = vi.spyOn(logger.prodLog, 'warn').mockImplementation(() => undefined)
+  })
+
+  afterEach(async () => {
+    if (brain) await brain.close()
+    warnSpy.mockRestore()
+  })
+
+  describe('Validator-level behavior (no brain instance needed)', () => {
+    it('silent pass below cap', () => {
+      const cfg = ValidationConfig.getInstance({ maxQueryLimit: 1000 })
+      expect(() => validateFindParams({ limit: cfg.maxLimit })).not.toThrow()
+      expect(warnSpy).not.toHaveBeenCalled()
+    })
+
+    it('soft tier warns once per call site without throwing', () => {
+      ValidationConfig.getInstance({ maxQueryLimit: 1000 })
+
+      // The dedup key is `(caller, limit)`. To exercise the dedup honestly we
+      // need both invocations to hit the SAME source line — extracting them
+      // into a wrapper that lives at one location is the deterministic way.
+      const callFromOneSite = () => validateFindParams({ limit: 1500 })
+
+      expect(() => callFromOneSite()).not.toThrow()
+      expect(warnSpy).toHaveBeenCalledTimes(1)
+
+      // Same source line + same limit → dedup, no second warning
+      expect(() => callFromOneSite()).not.toThrow()
+      expect(warnSpy).toHaveBeenCalledTimes(1)
+    })
+
+    it('warning message names the recipe + docs link', () => {
+      ValidationConfig.getInstance({ maxQueryLimit: 1000 })
+
+      validateFindParams({ limit: 1500 })
+
+      const message = String(warnSpy.mock.calls[0][0])
+      expect(message).toMatch(/find\(\{ limit: 1500 \}\)/)
+      expect(message).toMatch(/exceeds the auto-configured query limit of 1000/)
+      expect(message).toMatch(/new Brainy\(\{ maxQueryLimit:/)
+      expect(message).toMatch(/new Brainy\(\{ reservedQueryMemory:/)
+      expect(message).toMatch(/Paginate:/)
+      expect(message).toMatch(/Docs: https:\/\/soulcraft\.com\/docs\/guides\/find-limits/)
+    })
+
+    it('warning message includes the caller location from the stack', () => {
+      ValidationConfig.getInstance({ maxQueryLimit: 1000 })
+
+      validateFindParams({ limit: 1500 })
+
+      const message = String(warnSpy.mock.calls[0][0])
+      // The caller is THIS test file; the formatter strips the leading `at `
+      // and emits an `  at <location>` line in the rendered message.
+      expect(message).toMatch(/at .*find-limits\.test\.ts/)
+    })
+
+    it('hard tier throws with the same message format', () => {
+      ValidationConfig.getInstance({ maxQueryLimit: 1000 })
+
+      // Above 2× cap = real OOM territory = throw
+      expect(() => validateFindParams({ limit: 2001 })).toThrow(
+        /exceeds the auto-configured query limit of 1000/
+      )
+      // No warning was logged — throw fires immediately at the hard tier
+      expect(warnSpy).not.toHaveBeenCalled()
+    })
+
+    it('hard tier message names all three escape valves', () => {
+      ValidationConfig.getInstance({ maxQueryLimit: 1000 })
+
+      try {
+        validateFindParams({ limit: 5000 })
+        throw new Error('expected throw')
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err)
+        expect(message).toMatch(/maxQueryLimit/)
+        expect(message).toMatch(/reservedQueryMemory/)
+        expect(message).toMatch(/Paginate:/)
+        expect(message).toMatch(/Docs: https:\/\/soulcraft\.com\/docs\/guides\/find-limits/)
+      }
+    })
+
+    it('soft-tier warning dedup is keyed on (caller, limit) — different limits from same site fire separately', () => {
+      ValidationConfig.getInstance({ maxQueryLimit: 1000 })
+
+      const call = (limit: number) => validateFindParams({ limit })
+
+      call(1500)
+      call(1500)
+      expect(warnSpy).toHaveBeenCalledTimes(1)
+
+      // Different limit value → new dedup key → second warning
+      call(1800)
+      expect(warnSpy).toHaveBeenCalledTimes(2)
+    })
+  })
+
+  describe('Consumer override via Brainy constructor', () => {
+    it('maxQueryLimit raises the cap; warning/throw tiers shift accordingly', async () => {
+      brain = new Brainy({
+        storage: { type: 'memory' },
+        silent: true,
+        maxQueryLimit: 50_000
+      })
+      await brain.init()
+      // Brainy's init path emits a one-time `prodLog.warn` for the
+      // entityIdMapper system-resource notice on first-mount; clear the spy
+      // history so we only observe limit-enforcement warnings below.
+      warnSpy.mockClear()
+
+      // The old auto-derived cap would have rejected this; the override accepts it
+      expect(() => validateFindParams({ limit: 10_000 })).not.toThrow()
+      expect(warnSpy).not.toHaveBeenCalled()
+
+      // 50_000 + 1 = soft tier under the new cap → warn, not throw
+      expect(() => validateFindParams({ limit: 60_000 })).not.toThrow()
+      expect(warnSpy).toHaveBeenCalled()
+
+      // Above 2× the override (100 001) → throw
+      // (Note: maxQueryLimit is hard-clamped at 100k in ValidationConfig, so the
+      // effective cap is 50_000; 2× = 100_000; we cross at 100_001.)
+      expect(() => validateFindParams({ limit: 100_001 })).toThrow(/exceeds/)
+    })
+
+    it('pre-7.30.2 regression scenario: limit: 10_000 passes silently on a memory-derived cap', async () => {
+      // Simulate a box where the auto-config picks a cap below 10_000 — the
+      // canonical pre-7.30.2 scenario where production booking flows 500'd
+      // because `validateFindParams` threw synchronously. With the
+      // 25 KB-per-result calibration the cap is ~4× more generous on the
+      // same hardware, but more importantly the soft tier no longer throws
+      // when consumers exceed the auto-cap.
+      ValidationConfig.reconfigure({ maxQueryLimit: 9000 })
+
+      // Pre-7.30.2 this threw. Post-7.30.2 it warns + passes.
+      expect(() => validateFindParams({
+        type: NounType.Event,
+        where: { status: 'open' },
+        limit: 10_000
+      })).not.toThrow()
+      expect(warnSpy).toHaveBeenCalled()
+    })
+  })
+})

tests/integration/fork-persistence.test.ts

@@ -3,7 +3,7 @@
  *
  * Tests the complete fork() → listBranches() → checkout() workflow
  * to prevent regression of the v5.3.6 bug where fork() silently failed
- * to persist branches to storage (Workshop bug report).
+ * to persist branches to storage (internal bug report).
  *
  * @see https://github.com/soulcraftlabs/brainy/issues/XXX
  */
@@ -153,23 +153,23 @@ describe('Fork Persistence (v5.3.6 Bug Fix)', () => {
     expect(forkBranches).toContain(validBranch)
   })
 
-  it('should handle snapshot naming convention (Workshop use case)', async () => {
-    // Reproduce exact Workshop snapshot workflow
+  it('should handle snapshot naming convention (consumer use case)', async () => {
+    // Reproduce exact Consumer snapshot workflow
     await brain.add({ data: { test: true }, type: 'concept' })
 
     const commitId = await brain.commit({
-      message: 'Workshop snapshot test',
+      message: 'Consumer snapshot test',
       author: 'workshop@example.com'
     })
 
-    // Use Workshop's exact naming convention
+    // Use the consumer's exact naming convention
     const timestamp = Date.now()
     const snapshotBranch = `snapshot-${timestamp}`
 
-    // Create snapshot branch (this is what failed in Workshop)
+    // Create snapshot branch (this is what failed in the consumer report)
     await brain.fork(snapshotBranch, {
       author: 'workshop@example.com',
-      message: `Snapshot: Workshop test`,
+      message: `Snapshot: Consumer test`,
       metadata: {
         timestamp,
         userId: 'test-user',

tests/integration/get-relations-fix.test.ts

@@ -373,17 +373,17 @@ describe('getRelations() Fix (v4.1.3)', () => {
     })
   })
 
-  describe('Comparison with Workshop Bug Report', () => {
-    it('should reproduce and fix the Workshop team bug scenario', async () => {
+  describe('Comparison with Internal Bug Report', () => {
+    it('should reproduce and fix the a consumer team bug scenario', async () => {
       // Reproduce the exact scenario from the bug report:
       // - 524 relationships exist in GraphAdjacencyIndex
       // - brain.getRelations() was returning empty array
 
-      // Create entities similar to Workshop import
+      // Create entities similar to Consumer import
       const entities = []
       for (let i = 0; i < 50; i++) {
         entities.push(await brain.add({
-          data: `Workshop Entity ${i}`,
+          data: `Consumer Entity ${i}`,
           type: NounType.Document
         }))
       }

tests/integration/memory-enhancements-v5.11.0.test.ts

@@ -40,7 +40,7 @@ describe('Memory Enhancements Integration (v5.11.0)', () => {
     })
   })
 
-  describe('Production Workflow: Workshop Snapshot Timeline', () => {
+  describe('Production Workflow: Consumer Snapshot Timeline', () => {
     it('should stream 1000 snapshots efficiently', async () => {
       const brain = new Brainy({
         storage: {

tests/integration/orderby-sort-bug.test.ts

@@ -10,7 +10,7 @@
  * Fix: centralized `resolveEntityField` helper + `BUCKETED_INDEX_FIELDS`
  * set in coreTypes.ts, used by getFieldValueForEntity.
  *
- * Reported by Muse team 2026-04-09 (handoff action BR-ORDERBY-TS).
+ * Reported by a consumer 2026-04-09.
  *
  * NOTE: These tests cover FILTERED sort, which is the only supported path.
  * Unfiltered `find({ orderBy })` is explicitly rejected until the dedicated
@@ -39,7 +39,7 @@ describe('find({ orderBy }) sort bug regression', () => {
   })
 
   /**
-   * Muse's real use case: filtered sort of chat sessions.
+   * Real consumer use case: filtered sort of chat sessions.
    * Before the fix, this returned the OLDEST entity instead of the newest
    * because getFieldValueForEntity was reading createdAt from the wrong
    * location on the entity.

tests/integration/strict-mode-self-test.test.ts

@@ -5,7 +5,7 @@
  * registers on every consumer's brain. This suite is the canary that detects
  * any internal path which silently omits subtype.
  *
- * The SDK_CORE_VOCABULARY shape that surfaced Venue's `/book` 500 (2026-06-08)
+ * The SDK_CORE_VOCABULARY shape from the consumer regression (2026-06-08)
  * registers `brain.requireSubtype()` rules on six NounTypes:
  *   - NounType.Event
  *   - NounType.Collection
@@ -17,7 +17,7 @@
  * If Brainy's own VFS / aggregation / extraction / importer / integration /
  * MCP paths skip subtype anywhere, the enforcement hook fires and Brainy itself
  * starts rejecting its own infrastructure writes. This test exercises every
- * such path under the exact shape Venue hit + brain-wide strict mode, and
+ * such path under the exact shape the consumer hit + brain-wide strict mode, and
  * asserts: zero rejections.
  *
  * @since 7.30.1
@@ -32,7 +32,7 @@ describe('Brainy strict-mode self-test (7.30.1)', () => {
 
   beforeEach(async () => {
     // Brain-wide strict mode ON + the exact SDK_CORE_VOCABULARY shape that
-    // Venue hit. If any internal Brainy path skips subtype, the writes here
+    // the consumer hit. If any internal Brainy path skips subtype, the writes here
     // will throw and fail the test.
     brain = new Brainy({
       storage: { type: 'memory' },

tests/integration/vfs-debug.test.ts

@@ -67,7 +67,7 @@ describe('VFS Debug', () => {
     const rootContents = await vfs.readdir('/')
     console.log(`  Root contents: ${rootContents.join(', ')}`)
 
-    // Try getDirectChildren (Workshop's method)
+    // Try getDirectChildren (the consumer's method)
     const children = await vfs.getDirectChildren('/')
     console.log(`  Direct children: ${children.length}`)
     children.forEach(child => {

tests/integration/vfs-historical-reads.test.ts

@@ -7,7 +7,7 @@
  * - stat(path, { commitId })
  * - exists(path, { commitId })
  *
- * This is the CRITICAL test for Workshop's time-travel feature.
+ * This is the CRITICAL test for a consumer's time-travel feature.
  */
 
 import { describe, it, expect, beforeAll, afterAll } from 'vitest'

tests/integration/vfs-import-verification.test.ts

@@ -2,7 +2,7 @@
  * VFS Import Verification Test
  *
  * This test verifies that brain.import() creates VFS entities correctly.
- * Created to investigate Workshop team's report of empty VFS after import.
+ * Created to investigate a consumer's report of empty VFS after import.
  *
  * Expected behavior:
  * 1. Import with vfsPath creates directory entities
@@ -15,7 +15,7 @@ import { describe, it, expect, beforeEach } from 'vitest'
 import { Brainy } from '../../src/brainy.js'
 import * as XLSX from 'xlsx'
 
-describe('VFS Import Verification (Workshop Bug Investigation)', () => {
+describe('VFS Import Verification (VFS import bug investigation)', () => {
   let brain: Brainy
 
   beforeEach(async () => {
@@ -26,7 +26,7 @@ describe('VFS Import Verification (Workshop Bug Investigation)', () => {
   })
 
   it('should create VFS entities during import with vfsPath', async () => {
-    // Create test Excel file (matching Workshop scenario)
+    // Create test Excel file (matching the reported scenario)
     const testData = [
       {
         'Term': 'Alice',
@@ -204,8 +204,8 @@ describe('VFS Import Verification (Workshop Bug Investigation)', () => {
     }
   }, 60000)
 
-  it('should match Workshop scenario exactly', async () => {
-    // Replicate Workshop team's exact scenario
+  it('should match the reported scenario exactly', async () => {
+    // Replicate a consumer's exact scenario
     const testData = [
       { 'Term': 'Westland', 'Definition': 'Ancient kingdom', 'Type': 'Place' },
       { 'Term': 'Capital City', 'Definition': 'Main city', 'Type': 'Place' },
@@ -217,7 +217,7 @@ describe('VFS Import Verification (Workshop Bug Investigation)', () => {
     XLSX.utils.book_append_sheet(workbook, worksheet, 'Glossary')
     const buffer = XLSX.write(workbook, { type: 'buffer', bookType: 'xlsx' })
 
-    console.log('📥 Importing (Workshop scenario)...')
+    console.log('📥 Importing (the reported scenario)...')
     const filename = 'Tales from Talifar Glossary.xlsx'
     const timestamp = Date.now()
 
@@ -236,12 +236,12 @@ describe('VFS Import Verification (Workshop Bug Investigation)', () => {
     console.log(`   - Graph edges: ${result.stats.graphEdgesCreated}`)
     console.log(`   - VFS files: ${result.stats.vfsFilesCreated}`)
 
-    // Workshop team's check: Initialize VFS
-    console.log('\n📂 Initializing VFS (Workshop fix)...')
+    // Consumer's check: Initialize VFS
+    console.log('\n📂 Initializing VFS (post-fix)...')
     const vfs = brain.vfs
     await vfs.init()
 
-    // Workshop team's check: Query root
+    // a consumer's check: Query root
     console.log('🔍 Querying root directory...')
     const rootItems = await vfs.getDirectChildren('/')
     console.log(`   - Items in root: ${rootItems.length}`)

tests/manual/type-filtering-diagnostic.ts

@@ -1,5 +1,5 @@
 /**
- * Manual test to reproduce Workshop team's type filtering issue
+ * Manual test to reproduce a consumer's type filtering issue
  *
  * This test verifies that brain.find({ type: NounType.Person }) actually works
  * as documented in the API.
@@ -8,7 +8,7 @@
 import { Brainy, NounType } from '../../src/index.js'
 
 async function testTypeFiltering() {
-  console.log('\n🔬 Testing Type Filtering Issue from Workshop Team\n')
+  console.log('\n🔬 Testing Type Filtering Issue from A Consumer Team\n')
   console.log('=' .repeat(60))
 
   // Create in-memory instance for testing
@@ -156,12 +156,12 @@ async function testTypeFiltering() {
 
   if (passedCount === totalCount) {
     console.log('\n🎉 All tests passed! Type filtering works correctly.')
-    console.log('\n💡 The Workshop team might be experiencing a different issue.')
+    console.log('\n💡 The a consumer team might be experiencing a different issue.')
     console.log('   Check: storage persistence, Brainy instance reuse, or data migration')
   } else {
     console.log('\n❌ Type filtering is BROKEN in Brainy!')
     console.log('\n🐛 This is a bug that needs to be fixed.')
-    console.log('   Workshop team was right - it\'s not user error.')
+    console.log('   a consumer team was right - it\'s not user error.')
   }
 
   console.log('\n' + '='.repeat(60) + '\n')

tests/manual/vfs-multiple-init-diagnostic.test.ts

@@ -1,7 +1,7 @@
 /**
  * VFS Multiple Init() Diagnostic Test
  *
- * Tests Workshop team's issue: Does calling vfs.init() multiple times
+ * Tests a consumer's issue: Does calling vfs.init() multiple times
  * create duplicate root entities?
  *
  * Scenario:
@@ -72,8 +72,8 @@ describe('VFS Multiple Init Diagnostic', () => {
     expect(roots.length).toBe(1)
   })
 
-  it('should not create duplicate roots when creating MULTIPLE VFS instances (Workshop scenario)', async () => {
-    // Simulate Workshop's scenario: Getting VFS on multiple requests
+  it('should not create duplicate roots when creating MULTIPLE VFS instances (the reported scenario)', async () => {
+    // Simulate the reported scenario: Getting VFS on multiple requests
     // brain.vfs returns cached instance, so this should be safe
     const vfs1 = brain.vfs
     const vfs2 = brain.vfs
@@ -107,7 +107,7 @@ describe('VFS Multiple Init Diagnostic', () => {
 
   it('should handle NEW brain instances gracefully (per-user scenario)', async () => {
     // Simulate creating separate brain instances per user
-    // This is closer to Workshop's getUserBrainy() pattern
+    // This is closer to a consumer's getUserBrainy() pattern
     const brain2 = new Brainy({
       storage: {
         type: 'filesystem',

tests/regression/v5.7.0-deadlock.test.ts

@@ -70,7 +70,7 @@ describe('v5.7.0 Deadlock Regression', () => {
   })
 
   it('should handle imports without 12+ second delays per entity', async () => {
-    // Simulate import workflow (like Workshop Excel import)
+    // Simulate import workflow (like A consumer's Excel import)
     const start = Date.now()
 
     // Import 5 entities with relationships

tests/unit/brainy/counts-by-type-fix.test.ts

@@ -49,7 +49,7 @@ describe('counts.byType() fix (v6.2.2)', () => {
     })
 
     it('should not return empty when entities exist (the original bug)', async () => {
-      // This test reproduces the original bug from Workshop
+      // This test reproduces the original bug from a consumer report
       // counts.byType({ excludeVFS: true }) returned {} even with 48 entities
 
       // Arrange - Add a single entity
@@ -68,7 +68,7 @@ describe('counts.byType() fix (v6.2.2)', () => {
     })
 
     it('should match counts from find() (the workaround)', async () => {
-      // The Workshop workaround was to use find() and count manually
+      // The consumer workaround was to use find() and count manually
       // Our fix should make both approaches return the same counts
 
       // Arrange

tests/unit/neural/presets.test.ts

@@ -508,7 +508,7 @@ describe('Presets', () => {
   })
 
   describe('real-world scenarios', () => {
-    it('should handle Workshop glossary correctly', () => {
+    it('should handle glossary correctly', () => {
       const context: ImportContext = {
         fileType: 'excel',
         rowCount: 567,

tests/unit/neural/signals/ExactMatchSignal.test.ts

@@ -508,8 +508,8 @@ describe('ExactMatchSignal', () => {
   })
 
   describe('real-world scenarios', () => {
-    it('should handle Workshop glossary import', async () => {
-      // Simulate Workshop glossary with 567 terms
+    it('should handle glossary import', async () => {
+      // Simulate glossary with 567 terms
       const terms = [
         { text: 'Eldoria', type: NounType.Location },
         { text: 'Shadowfen', type: NounType.Location },

tests/unit/type-filtering.unit.test.ts

@@ -1,5 +1,5 @@
 /**
- * Type Filtering Tests - Workshop Team Issue
+ * Type Filtering Tests - A Consumer Team Issue
  *
  * Tests to verify that brain.find({ type: NounType.X }) correctly filters entities
  */
@@ -7,7 +7,7 @@
 import { describe, it, expect, beforeEach } from 'vitest'
 import { Brainy, NounType } from '../../src/index.js'
 
-describe('Type Filtering (Workshop Team Issue)', () => {
+describe('Type Filtering (A Consumer Team Issue)', () => {
   let brain: Brainy
 
   beforeEach(async () => {

tests/unit/utils/memoryLimits.test.ts

@@ -98,9 +98,10 @@ describe('Memory Limits - Container Detection & Smart Calculation', () => {
 
       const config = ValidationConfig.getInstance()
 
-      // 4GB * 0.25 = 1GB for queries
-      // 1GB / 100MB = 10 units * 1000 = 10,000 limit
-      expect(config.maxLimit).toBe(10000)
+      // 4 GB × 0.25 = 1 GB for queries; at 25 KB / result (7.30.2 calibration)
+      // → 1 GB / 25 KB = ~40_960 → floor to 40 × 1000 = 40_000.
+      // Pre-7.30.2 used 100 KB / result and returned 10_000 here.
+      expect(config.maxLimit).toBe(40000)
     })
 
     it('should respect absolute maximum of 100k', () => {
@@ -134,12 +135,14 @@ describe('Memory Limits - Container Detection & Smart Calculation', () => {
     })
 
     it('should respect reservedQueryMemory override', () => {
-      // Reserve 1GB for queries
+      // Reserve 1 GB for queries; at 25 KB / result (7.30.2) → 1 GB / 25 KB
+      // = ~40_960 → floor to 40 × 1000 = 40_000. Pre-7.30.2 used 100 KB /
+      // result and this returned 10_000.
       const config = ValidationConfig.getInstance({
         reservedQueryMemory: 1 * 1024 * 1024 * 1024
       })
 
-      expect(config.maxLimit).toBe(10000) // 1GB / 100MB * 1000
+      expect(config.maxLimit).toBe(40000)
       expect(config.limitBasis).toBe('reservedMemory')
     })
 
@@ -213,7 +216,7 @@ describe('Memory Limits - Container Detection & Smart Calculation', () => {
     it('should configure reserved memory via Brain constructor', async () => {
       const brain = new Brainy({
         storage: { type: 'memory' },
-        reservedQueryMemory: 500 * 1024 * 1024, // 500MB
+        reservedQueryMemory: 500 * 1024 * 1024, // 500 MB
         silent: true
       })
 
@@ -221,8 +224,9 @@ describe('Memory Limits - Container Detection & Smart Calculation', () => {
 
       const stats = brain.getMemoryStats()
 
-      // 500MB / 100MB * 1000 = 5000
-      expect(stats.limits.maxQueryLimit).toBe(5000)
+      // 500 MB / 25 KB per result (7.30.2 calibration) = ~20_000.
+      // Pre-7.30.2 used 100 KB / result and this returned 5000.
+      expect(stats.limits.maxQueryLimit).toBe(20000)
       expect(stats.limits.basis).toBe('reservedMemory')
       expect(stats.config.reservedQueryMemory).toBe(500 * 1024 * 1024)
 
@@ -243,8 +247,10 @@ describe('Memory Limits - Container Detection & Smart Calculation', () => {
 
       expect(stats.memory.containerLimit).toBe(2 * 1024 * 1024 * 1024)
       expect(stats.limits.basis).toBe('containerMemory')
-      // 2GB * 0.25 = 500MB -> 5000 limit
-      expect(stats.limits.maxQueryLimit).toBe(5000)
+      // 2 GB × 0.25 = 512 MB query budget; at 25 KB per result (7.30.2) →
+      // 512 MB / 25 KB = ~20_971 → floor to 20 × 1000 = 20_000. Pre-7.30.2
+      // used 100 KB per result and this returned 5_000.
+      expect(stats.limits.maxQueryLimit).toBe(20000)
 
       await brain.close()
     })
@@ -341,9 +347,11 @@ describe('Memory Limits - Container Detection & Smart Calculation', () => {
 
       const stats = brain.getMemoryStats()
 
-      // Should allocate 1GB (25% of 4GB) for queries
+      // Allocates 1 GB (25% of 4 GB) for queries; at 25 KB per result
+      // (7.30.2 calibration) → 1 GB / 25 KB = ~40_960 → floor to 40 × 1000 =
+      // 40_000. Pre-7.30.2 used 100 KB per result and this returned 10_000.
       expect(stats.memory.containerLimit).toBe(4 * 1024 * 1024 * 1024)
-      expect(stats.limits.maxQueryLimit).toBe(10000)
+      expect(stats.limits.maxQueryLimit).toBe(40000)
       expect(stats.limits.basis).toBe('containerMemory')
 
       await brain.close()

tests/unit/utils/paramValidation.test.ts

@@ -93,18 +93,27 @@ describe('Zero-Config Parameter Validation', () => {
       })).toThrow('invalid NounType: InvalidType')
     })
     
-    it('should auto-limit based on system memory', () => {
+    it('should auto-limit based on system memory (two-tier enforcement)', () => {
       const config = getValidationConfig()
-      
-      // Should reject limits above auto-configured max
+
+      // 7.30.2+ design: the cap fires in two tiers.
+      // - Below cap (`limit <= maxLimit`): silent pass, no signal.
+      // - Soft tier (`maxLimit < limit <= 2 * maxLimit`): one-time warning
+      //   per call site, query proceeds. No throw.
+      // - Hard tier (`limit > 2 * maxLimit`): real OOM danger zone, throw.
+
+      // Below cap → pass
+      expect(() => validateFindParams({ limit: config.maxLimit })).not.toThrow()
+
+      // Soft tier → no throw (just a warn we don't assert here — proper coverage
+      // lives in the find-limits integration suite which can intercept the log).
+      expect(() => validateFindParams({ limit: config.maxLimit + 1 })).not.toThrow()
+      expect(() => validateFindParams({ limit: config.maxLimit * 2 })).not.toThrow()
+
+      // Hard tier → throw with the new message format
       expect(() => validateFindParams({
-        limit: config.maxLimit + 1
-      })).toThrow(`limit exceeds auto-configured maximum of ${config.maxLimit}`)
-      
-      // Should accept limits at or below max
-      expect(() => validateFindParams({
-        limit: config.maxLimit
-      })).not.toThrow()
+        limit: config.maxLimit * 2 + 1
+      })).toThrow(/exceeds the auto-configured query limit/)
     })
     
     it('should auto-limit query length', () => {

tests/unit/vfs-multi-instance-diagnostic.test.ts

@@ -1,5 +1,5 @@
 /**
- * Workshop VFS Diagnostic Test
+ * VFS Multi-instance Diagnostic Test
  *
  * Tests to verify VFS import behavior and identify if VFS creates only wrappers or also graph entities
  */
@@ -7,7 +7,7 @@
 import { describe, it, expect, beforeEach } from 'vitest'
 import { Brainy, NounType } from '../../src/index.js'
 
-describe('Workshop VFS Diagnostic', () => {
+describe('VFS Multi-instance Diagnostic', () => {
   let brain: Brainy
 
   beforeEach(async () => {
@@ -18,7 +18,7 @@ describe('Workshop VFS Diagnostic', () => {
   })
 
   it('should verify VFS creates document wrappers AND allows entity filtering', async () => {
-    console.log('\n🔬 Workshop VFS Diagnostic Test\n')
+    console.log('\n🔬 VFS Multi-instance Diagnostic Test\n')
     console.log('='.repeat(70))
 
     // Step 1: Add entities directly (control group)
@@ -162,7 +162,7 @@ describe('Workshop VFS Diagnostic', () => {
     console.log('   - filter({ type: "person" }) → returns graph entities')
     console.log('   - filter({ type: "document" }) → returns VFS wrappers')
     console.log('')
-    console.log('If Workshop gets 0 results, likely causes:')
+    console.log('If a consumer gets 0 results, likely causes:')
     console.log('   ❌ Only VFS wrappers created (createEntities: false)')
     console.log('   ❌ Import not completing before query')
     console.log('   ❌ Querying different Brainy instance')

tests/vfs/vfs-bulkwrite-race.test.ts

@@ -122,7 +122,7 @@ describe('VFS bulkWrite Race Condition Fix', () => {
       }
     })
 
-    it('should handle the Workshop template creation scenario', async () => {
+    it('should handle the Consumer template creation scenario', async () => {
       // Exact scenario from bug report: template creation with mixed ops
       const operations = [
         { type: 'mkdir' as const, path: '/project/src' },