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

src/brainy.ts

@@ -55,6 +55,7 @@ import {
   validateFindParams,
   recordQueryPerformance
 } from './utils/paramValidation.js'
+import { findCallerLocation } from './utils/callerLocation.js'
 import {
   SaveNounMetadataOperation,
   SaveNounOperation,
@@ -2773,7 +2774,7 @@ export class Brainy<T = any> implements BrainyInterface<T> {
     strict: boolean
   }): string {
     const typeLabel = opts.kind === 'noun' ? 'NounType' : 'VerbType'
-    const callSite = this.findCallerLocation()
+    const callSite = findCallerLocation()
     const vocab = opts.rule?.values ? Array.from(opts.rule.values).join(', ') : null
 
     let head: string
@@ -2803,28 +2804,9 @@ export class Brainy<T = any> implements BrainyInterface<T> {
     return [head, callerLine, guidance, docLink].filter(Boolean).join('\n')
   }
 
-  /**
-   * Extract the first non-Brainy frame from the current stack so error messages
-   * can point at the consumer's call site instead of Brainy internals. Returns
-   * `null` if the stack isn't available (some runtimes) or only contains Brainy
-   * frames.
-   */
-  private findCallerLocation(): string | null {
-    const stack = new Error().stack
-    if (!stack) return null
-    const lines = stack.split('\n').slice(1)  // drop the `Error` line
-    for (const raw of lines) {
-      const line = raw.trim()
-      // Skip frames inside Brainy's own files. We don't want to point the user
-      // at `brainy.ts:XXXX` — they need their own call site.
-      if (line.includes('/src/brainy.ts') || line.includes('/dist/brainy.js')) continue
-      if (line.includes('enforceSubtypeOn') || line.includes('formatSubtypeError')) continue
-      if (line.includes('findCallerLocation')) continue
-      // Strip leading `at ` if present so the caller can format consistently.
-      return line.replace(/^at /, '')
-    }
-    return null
-  }
+  // findCallerLocation is now exported from src/utils/callerLocation.ts so
+  // both the subtype enforcement errors here and the query-limit warnings in
+  // paramValidation.ts can share it without re-importing brainy.ts.
 
   /**
    * Validate a metadata bag (or top-level field assignment) against any registered
@@ -4163,9 +4145,10 @@ export class Brainy<T = any> implements BrainyInterface<T> {
       // Step 2: Copy storage ref (COW layer - instant!)
       await refManager.copyRef(currentBranch, branchName)
 
-      // CRITICAL FIX: Verify branch was actually created to prevent silent failures
-      // Without this check, fork() could complete successfully but branch wouldn't exist,
-      // causing subsequent checkout() calls to fail (see Workshop bug report).
+      // CRITICAL FIX: Verify branch was actually created to prevent silent failures.
+      // Without this check, fork() could complete successfully but the branch wouldn't
+      // exist on disk, causing subsequent checkout() calls to fail with a
+      // "Branch does not exist" error.
       const verifyBranch = await refManager.getRef(branchName)
       if (!verifyBranch) {
         throw new Error(
@@ -4553,7 +4536,7 @@ export class Brainy<T = any> implements BrainyInterface<T> {
    * - Subsequent queries: Same as normal Brainy (uses rebuilt indexes)
    * - Memory overhead: Snapshot has separate in-memory indexes
    *
-   * Use case: Workshop app - render file tree at historical commit
+   * Use case: rendering a file tree (or any indexed view) at a historical commit
    *
    * @param commitId - Commit hash to snapshot from
    * @returns Read-only Brainy instance with historical state
@@ -5379,7 +5362,7 @@ export class Brainy<T = any> implements BrainyInterface<T> {
 
   /**
    * Extract entities from text (alias for extract())
-   * Added for API clarity and Workshop team request
+   * Added for API clarity — `extractEntities()` reads more naturally at call sites
    *
    * Uses NeuralEntityExtractor with SmartExtractor ensemble (4-signal architecture):
    * - ExactMatch (40%) - Dictionary lookups

src/neural/presets.ts

@@ -183,7 +183,7 @@ export const ACCURATE_PRESET: PresetConfig = {
  * - Fast, deterministic results
  * - Perfect for Excel/CSV with "Related Terms" columns
  *
- * Use case: Workshop glossary, structured taxonomies
+ * Use case: structured taxonomies and glossaries from spreadsheet sources
  * Performance: ~5ms per row
  * Accuracy: ~99% (high confidence)
  */
@@ -290,7 +290,7 @@ export function autoDetectPreset(context: ImportContext = {}): PresetConfig {
   }
 
   // Rule 3: Structured data with explicit relationships → explicit preset
-  // Perfect for Workshop bug fix!
+  // (Handles spreadsheet imports where relationships are encoded in columns.)
   if (hasExplicitColumns && (fileType === 'excel' || fileType === 'csv')) {
     return EXPLICIT_PRESET
   }

src/storage/baseStorage.ts

@@ -719,7 +719,7 @@ export abstract class BaseStorage extends BaseStorageAdapter {
     // CRITICAL FIX: COW metadata (_cow/*) must NEVER be branch-scoped
     // Refs, commits, and blobs are global metadata with their own internal branching.
     // Branch-scoping COW paths causes fork() to write refs to wrong locations,
-    // leading to "Branch does not exist" errors on checkout (see Workshop bug report).
+    // leading to "Branch does not exist" errors on checkout.
     if (basePath.startsWith('_cow/')) {
       return basePath  // COW metadata is global across all branches
     }

src/utils/callerLocation.ts

@@ -0,0 +1,54 @@
+/**
+ * @module utils/callerLocation
+ * @description Stack-frame extraction utility used by error/warning messages
+ * across Brainy. The first non-Brainy frame on the stack is the consumer's
+ * actual call site — the one that's useful to point at in diagnostics.
+ *
+ * Used by:
+ * - Subtype enforcement errors in `brainy.ts` (7.30.1+) — guides consumers
+ *   from `requireSubtype()` rejections back to the offending call site.
+ * - Query-limit enforcement in `paramValidation.ts` (7.30.2+) — pairs with
+ *   the recalibrated limit cap so consumers see which `find({ limit })`
+ *   call triggered the warn-or-throw.
+ *
+ * No runtime dependencies. Pure stack walking + string matching.
+ */
+
+/**
+ * Extract the first non-Brainy frame from the current stack so error and
+ * warning messages can point at the consumer's call site instead of Brainy
+ * internals.
+ *
+ * The function walks `new Error().stack`, skips any frame inside Brainy's own
+ * source or compiled output, and returns the first remaining frame stripped of
+ * the leading `at ` token so the caller can compose the rendered line however
+ * it likes.
+ *
+ * @param extraSkipPatterns Optional list of substrings — frames matching ANY
+ *   of these are also skipped. Use for in-module helpers that show up between
+ *   the public API and the consumer (e.g. the formatter that builds the
+ *   error message itself).
+ * @returns The caller's location string (e.g. `"OrderService.create (/app/src/orders/service.ts:42:23)"`)
+ *   or `null` when the stack isn't available or only contains Brainy frames.
+ */
+export function findCallerLocation(extraSkipPatterns: string[] = []): string | null {
+  const stack = new Error().stack
+  if (!stack) return null
+  const lines = stack.split('\n').slice(1)  // drop the `Error` line
+  for (const raw of lines) {
+    const line = raw.trim()
+    // Always skip Brainy's own source + compiled output. Consumers need their
+    // own call site, not `brainy.ts:XXXX` or `dist/brainy.js:XXXX`.
+    if (line.includes('/src/brainy.ts') || line.includes('/dist/brainy.js')) continue
+    // Skip the validation + diagnostic helpers regardless of which file they
+    // live in — they're plumbing between the public API and the consumer.
+    if (line.includes('findCallerLocation')) continue
+    if (line.includes('paramValidation') && line.includes('validate')) continue
+    if (line.includes('enforceSubtypeOn') || line.includes('formatSubtypeError')) continue
+    // Caller-supplied patterns (e.g. specific formatter names)
+    if (extraSkipPatterns.some(p => line.includes(p))) continue
+    // Strip leading `at ` if present so the caller can format consistently.
+    return line.replace(/^at /, '')
+  }
+  return null
+}

src/utils/paramValidation.ts

@@ -7,6 +7,8 @@
 
 import { FindParams, AddParams, UpdateParams, RelateParams, UpdateRelationParams } from '../types/brainy.types.js'
 import { NounType, VerbType } from '../types/graphTypes.js'
+import { prodLog } from './logger.js'
+import { findCallerLocation } from './callerLocation.js'
 
 // Dynamic import for Node.js os and fs modules
 let os: any = null
@@ -116,6 +118,43 @@ const getContainerMemoryLimit = (): number | null => {
   }
 }
 
+/**
+ * Memory budget per query result, in KB. Used by the auto-configured
+ * `maxLimit` formula across all three memory-derived priorities (reserved /
+ * container / free).
+ *
+ * Calibration history:
+ * - Pre-7.30.2: `100` (assumed 100 KB per result). Way too conservative —
+ *   actual entity footprint in Brainy is 7-10 KB (384-dim float32 vector ≈
+ *   1.5 KB + standard fields + metadata). On a 900 MB free-memory box this
+ *   capped `limit` at 9_000, breaking common safety-cap call patterns like
+ *   `find({ type, where, limit: 10_000 })` that typically return 10-500
+ *   entities. Surfaced as `BR-MAXLIMIT-9000` in PLATFORM-HANDOFF.md.
+ * - 7.30.2+: `25` (assumes 25 KB per result). Generous over typical (7-10 KB),
+ *   comfortably under the worst case (~20 KB with large metadata blobs).
+ *   Same 900 MB box now gives ~36_000 — typical 10_000 limits pass silently,
+ *   the warning tier surfaces around 36-72 K (encouraging pagination), and
+ *   the throw tier still fires before OOM territory (72 K+).
+ */
+const MAX_LIMIT_KB_PER_RESULT = 25
+
+/**
+ * One-time-per-call-site warning dedup. Keyed on the caller location returned
+ * by `findCallerLocation()` plus the exceeding limit value so the warning fires
+ * once per offending source line (not once per query). Survives the lifetime of
+ * the process — that's intentional: the warning is a teaching signal, not a
+ * recurring nag. Used by the two-tier limit enforcement in `validateFindParams`.
+ */
+const seenLimitWarnings = new Set<string>()
+
+/**
+ * Reset the limit-warning dedup. For tests that need a clean slate; production
+ * code should never call this.
+ */
+export function resetLimitWarningCache(): void {
+  seenLimitWarnings.clear()
+}
+
 /**
  * Configuration options for ValidationConfig
  */
@@ -174,7 +213,7 @@ export class ValidationConfig {
     if (options?.reservedQueryMemory !== undefined) {
       this.maxLimit = Math.min(
         100000,
-        Math.floor(options.reservedQueryMemory / (1024 * 1024 * 100)) * 1000
+        Math.floor(options.reservedQueryMemory / (1024 * 1024 * MAX_LIMIT_KB_PER_RESULT)) * 1000
       )
       this.limitBasis = 'reservedMemory'
 
@@ -193,7 +232,7 @@ export class ValidationConfig {
 
       this.maxLimit = Math.min(
         100000,
-        Math.floor(queryMemory / (1024 * 1024 * 100)) * 1000
+        Math.floor(queryMemory / (1024 * 1024 * MAX_LIMIT_KB_PER_RESULT)) * 1000
       )
       this.limitBasis = 'containerMemory'
 
@@ -209,7 +248,7 @@ export class ValidationConfig {
 
     this.maxLimit = Math.min(
       100000,
-      Math.floor(availableMemory / (1024 * 1024 * 100)) * 1000
+      Math.floor(availableMemory / (1024 * 1024 * MAX_LIMIT_KB_PER_RESULT)) * 1000
     )
     this.limitBasis = 'freeMemory'
 
@@ -263,6 +302,95 @@ export class ValidationConfig {
   }
 }
 
+/**
+ * Two-tier limit enforcement for `find({ limit })`. Compares the requested
+ * limit against the auto-configured (or consumer-overridden) `maxLimit` and
+ * picks one of three outcomes:
+ *
+ * 1. **Pass** — `limit <= maxLimit`. The configured cap was set with this
+ *    consumer's use case in mind; no signal, no friction.
+ *
+ * 2. **Warn** — `maxLimit < limit <= 2 * maxLimit`. The consumer is asking
+ *    for more than the cap, but not enough to be in OOM territory. Log a
+ *    one-time warning per call site (dedup keyed on stack location + limit
+ *    value) explaining the cap, the three escape valves, and the docs link.
+ *    The query proceeds. Pre-7.30.2 code that relied on the cap silently
+ *    allowing typical safety-cap limits (`10_000`) keeps working; the
+ *    warning teaches the migration.
+ *
+ * 3. **Throw** — `limit > 2 * maxLimit`. Real OOM danger territory. Throw
+ *    with the same message format the warning uses so the consumer gets
+ *    consistent guidance whether they hit the soft or hard threshold.
+ *
+ * The 2× soft margin is chosen to absorb existing safety-cap patterns
+ * (`limit: 10_000` against a `maxLimit: 9_000` box, common case at 7.30 GA)
+ * without disabling OOM protection. Real OOM territory on a JS in-memory
+ * brain is hundreds of thousands of results, not 10× the safety cap.
+ *
+ * Both warning and throw paths use the same formatter so the rendered message
+ * is identical — consumers see the same recipe regardless of which threshold
+ * they crossed.
+ *
+ * @param limit - The requested `limit` value (already validated non-negative)
+ * @param config - The active ValidationConfig (carries `maxLimit` + basis)
+ * @throws When `limit > 2 * config.maxLimit`
+ *
+ * @since 7.30.2 (replaced the unconditional throw added in 7.30.0)
+ */
+function enforceLimitCap(limit: number, config: ValidationConfig): void {
+  if (limit <= config.maxLimit) return
+
+  const message = formatLimitMessage(limit, config)
+  const hardCeiling = config.maxLimit * 2
+
+  if (limit > hardCeiling) {
+    // OOM danger zone — throw to prevent runaway memory allocation
+    throw new Error(message)
+  }
+
+  // Soft margin: warn once per call site + limit value, then let the query proceed.
+  // Survives the lifetime of the process; the goal is to teach the migration recipe,
+  // not to spam the log every query.
+  const caller = findCallerLocation(['validateFindParams', 'enforceLimitCap', 'formatLimitMessage']) ?? '<unknown caller>'
+  const dedupKey = `${caller}|${limit}`
+  if (!seenLimitWarnings.has(dedupKey)) {
+    seenLimitWarnings.add(dedupKey)
+    prodLog.warn('[Brainy] ' + message)
+  }
+}
+
+/**
+ * Render the user-facing message used by both the warning tier and the throw
+ * tier of `enforceLimitCap`. Same body shape as the 7.30.1 enforcement-error
+ * messages: state the problem, name the recipe, point at the call site, link
+ * the docs.
+ */
+function formatLimitMessage(limit: number, config: ValidationConfig): string {
+  const cap = config.maxLimit
+  const basis = config.limitBasis
+  const basisLabel: Record<string, string> = {
+    override: 'consumer-supplied `maxQueryLimit`',
+    reservedMemory: 'consumer-supplied `reservedQueryMemory`',
+    containerMemory: 'detected container memory limit',
+    freeMemory: 'available free memory'
+  }
+  const basisText = basisLabel[basis] ?? 'available memory'
+  const caller = findCallerLocation(['enforceLimitCap', 'formatLimitMessage'])
+
+  const lines = [
+    `find({ limit: ${limit} }) exceeds the auto-configured query limit of ${cap} (basis: ${basisText}). Choose one:`,
+    `  • Increase the cap: new Brainy({ maxQueryLimit: ${Math.min(limit, 100000)} })`,
+    `  • Reserve more memory: new Brainy({ reservedQueryMemory: ${limit * MAX_LIMIT_KB_PER_RESULT * 1024} })`,
+    '  • Paginate: split the query with { limit, offset } pages'
+  ]
+  if (caller) {
+    lines.push(`  at ${caller}`)
+  }
+  lines.push('Docs: https://soulcraft.com/docs/guides/find-limits')
+
+  return lines.join('\n')
+}
+
 /**
  * Universal validations - things that are always invalid
  * These are mathematical/logical truths, not configuration
@@ -275,9 +403,7 @@ export function validateFindParams(params: FindParams): void {
     if (params.limit < 0) {
       throw new Error('limit must be non-negative')
     }
-    if (params.limit > config.maxLimit) {
-      throw new Error(`limit exceeds auto-configured maximum of ${config.maxLimit} (based on available memory)`)
-    }
+    enforceLimitCap(params.limit, config)
   }
   
   if (params.offset !== undefined && params.offset < 0) {