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/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()
+    })
+  })
+})