chore(release): 10.4.10

The proximity search fetched its anchor through get(), which omits vectors
by default, then handed a zero-length vector to the index — every
find({ near }) refused with a dimension mismatch, for every caller. Found
by the Rust planner's first-contact pins comparing outcomes with and
without the planner on a refused shape. The anchor is now fetched with its
vector, and an anchor that has none refuses by name — a proximity search
around an unvectored row has no meaning and must not fail inside the index.
Pinned in tests/integration/find-near.test.ts.

.forgejo/workflows/ci.yml

@@ -5,10 +5,6 @@ name: CI
 # sequential, so tag-triggered matrix jobs (~22 min) would queue AHEAD of the
 # tag's publish-source run and starve every release (observed on 8.10.3 and
 # 9.0.0: the publish sat behind the tag's own redundant CI).
-concurrency:
-  group: ci-${{ github.ref }}
-  cancel-in-progress: true
-
 on:
   push:
     branches: ['**']

.forgejo/workflows/publish-source.yml

@@ -12,11 +12,6 @@ on:
   push:
     tags:
       - 'v*'
-  workflow_dispatch:
-    inputs:
-      ref_reason:
-        description: 'why this manual run (e.g. tag event dropped)'
-        required: false
 
 jobs:
   publish:

CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [10.4.10](https://source.soulcraft.com/soulcraftlabs/open-brainy/compare/v10.4.9...v10.4.10) (2026-09-02)
+
+- fix(find): near() searches around the anchor's own vector, and refuses by name without one (a8c5fbf9)
+- Merge remote-tracking branches 'origin/fix/planner-provider-door' and 'origin/fix/containment-batching' into rel/10.4.10-candidate (34f1886f)
+- feat(plugin): an optional planFindPage door — an index that can plan a find answers it in one call (4d5f823f)
+- perf(vfs): repairContainment's reconcile is one paged edge walk, not one graph call per file (3e60aded)
+
+
+### [10.4.9](https://source.soulcraft.com/soulcraftlabs/open-brainy/compare/v10.4.6...v10.4.9) (2026-09-02)
+
+- Merge branch 'fix/pending-embed-low-water' into rel/10.4.9-candidate (2648f56d)
+- fix(open): pending-embed recovery keeps the crash-recovery contract — foreground, bounded by the mark (8a2ebacf)
+- Merge branches 'fix/connected-find-order', 'fix/pending-embed-low-water' and 'fix/related-verb-array' into rel/10.4.9-candidate (d5147ed6)
+- fix(graph): the verb fast paths honour every requested type, source, and target (6a89adc4)
+- perf(open): pending-embed recovery is bounded by a low-water mark and runs behind the doors (88e79729)
+- fix(find): connected finds are graph-first — neighbours, then the filter over those ids, then the page (077cbc0b)
+- fix(storage): counts persistence is single-flight, coalesced, and never races its own temp file (5e3b343a)
+
+
+### [10.4.6](https://source.soulcraft.com/soulcraftlabs/open-brainy/compare/v10.4.5...v10.4.6) (2026-08-31)
+
+- fix(transact): metadata-index ops take their JSON-safe view at the crossing, not at construction (73500e7d)
+
+
+### [10.4.5](https://source.soulcraft.com/soulcraftlabs/open-brainy/compare/v10.4.4...v10.4.5) (2026-08-31)
+
+- build(release): the docs-push step retires — this engine documents itself in its own repository (d6bcb14f)
+- fix(generations): a sealed segment may only declare the generations it holds (a963a744)
+- fix(recovery): a torn generation-log tail is a terminal verdict, never a wait (c9930871)
+
+
 ### [10.4.4](https://source.soulcraft.com/soulcraftlabs/open-brainy/compare/v10.4.3...v10.4.4) (2026-08-28)
 
 - fix(vfs): the old-root sweep narrates only when it has something to say (d49148e1)

RELEASES.md

@@ -1,12 +1,5 @@
 # @soulcraft/brainy — Release Notes for Consumers
 
-Machine-readable release notes are published at
-https://source.soulcraft.com/soulcraftlabs/releases/raw/branch/main/open-brainy.json
-(this engine) and
-https://source.soulcraft.com/soulcraftlabs/releases/raw/branch/main/brainy.json
-(the product engine) — read by HQ's `/hq/releases` door, and the source of
-truth ahead of this file.
-
 This file is the **quick reference for downstream sessions** tracking Brainy changes.
 Full auto-generated changelog: `CHANGELOG.md` · Releases: https://source.soulcraft.com/soulcraftlabs/open-brainy/releases
 

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@soulcraftlabs/brainy",
-  "version": "10.4.4",
+  "version": "10.4.10",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@soulcraftlabs/brainy",
-      "version": "10.4.4",
+      "version": "10.4.10",
       "license": "MIT",
       "dependencies": {
         "@msgpack/msgpack": "^3.1.2",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraftlabs/brainy",
-  "version": "10.4.4",
+  "version": "10.4.10",
   "brainyContract": 1,
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. Stage 3 CANONICAL: 42 nouns × 127 verbs covering 96-97% of all human knowledge.",
   "main": "dist/index.js",

scripts/release.sh

@@ -154,8 +154,7 @@ else
 fi
 
 # Create new changelog entry
-RELEASE_DATE=$(date +%Y-%m-%d)
-CHANGELOG_ENTRY="### [${NEW_VERSION}](https://source.soulcraft.com/soulcraftlabs/open-brainy/compare/v${CURRENT_VERSION}...v${NEW_VERSION}) (${RELEASE_DATE})
+CHANGELOG_ENTRY="### [${NEW_VERSION}](https://source.soulcraft.com/soulcraftlabs/open-brainy/compare/v${CURRENT_VERSION}...v${NEW_VERSION}) ($(date +%Y-%m-%d))
 
 ${COMMITS}
 "
@@ -175,19 +174,6 @@ if [ -f "CHANGELOG.md" ]; then
 fi
 echo -e "${GREEN}✅ CHANGELOG updated${NC}\n"
 
-# Step 6b: Update the releases wall entry — mechanical, derived from the
-# CHANGELOG entry just composed. The fleet's HQ page reads open-brainy.json
-# from the one shared releases repo, soulcraftlabs/releases on The Source —
-# this used to be hand-written after every release (David: never again —
-# make it a step of the rail, landed in the one shared home; this repo no
-# longer hosts its own copy). This step clones/fetches that repo into a
-# local cache, prepends the entry, and pushes it directly — a real
-# cross-repo push, refusing loudly (never skipping) on any
-# clone/validation/commit/push failure.
-echo -e "${BLUE}5️⃣▸ Updating the releases wall...${NC}"
-node scripts/wall-entry.mjs --product open-brainy --version "${NEW_VERSION}" --date "${RELEASE_DATE}" --from-changelog CHANGELOG.md
-echo -e "${GREEN}✅ Releases wall updated${NC}\n"
-
 # Step 7: Create release commit
 echo -e "${BLUE}6️⃣  Creating release commit...${NC}"
 git add package.json package-lock.json CHANGELOG.md
@@ -251,7 +237,7 @@ fi
 # and RELEASES.md are the record; this just gives The Source's UI a release page).
 echo -e "${BLUE}🔟 Creating release page on The Source...${NC}"
 if [ -n "${FORGEJO_RELEASE_TOKEN:-}" ]; then
-  if curl -sf -X POST "https://source.soulcraft.com/api/v1/repos/soulcraftlabs/open-brainy/releases" \
+  if curl -sf -X POST "https://source.soulcraft.com/api/v1/repos/soulcraft/brainy/releases" \
     -H "Authorization: token ${FORGEJO_RELEASE_TOKEN}" -H "Content-Type: application/json" \
     -d "{\"tag_name\":\"v${NEW_VERSION}\",\"name\":\"v${NEW_VERSION}\",\"prerelease\":${PRERELEASE}}" >/dev/null; then
     echo -e "${GREEN}✅ Release page created on The Source${NC}\n"

scripts/wall-entry.mjs

@@ -1,504 +0,0 @@
-#!/usr/bin/env node
-/**
- * @module scripts/wall-entry
- * @description The releases-wall entry, made mechanical. The fleet's HQ page
- * reads one public JSON per product from the ONE releases repo on The Source
- * (soulcraftlabs/releases, files <product>.json at its root — shape
- * {product, entries:[{version, date, headline, items, url, thumb?}]}), at
- * https://source.soulcraft.com/soulcraftlabs/releases/raw/branch/main/<product>.json.
- * Those entries were hand-written after every release, then briefly written
- * into this repo's own releases/<product>.json; this script is the one door
- * that composes an entry and lands it in the shared repo, so it is never
- * hand-written and never forked across repos again.
- *
- * Two modes:
- *
- *   1. Generate + publish (default):
- *        node wall-entry.mjs --product <p> --version <v> --date <YYYY-MM-DD> \
- *          --from-changelog <CHANGELOG.md>
- *      Derives an entry from the CHANGELOG.md entry for <v> (headline = the
- *      entry's first bullet, items = every bullet, trimmed of its trailing
- *      commit hash), then:
- *        - clones (or, if a cached clone already exists, fetches and resets)
- *          the releases repo into a local cache directory,
- *        - prepends the entry to <cache>/<p>.json, newest first — replacing
- *          any existing entry for the same version so a re-run is idempotent,
- *        - validates the file's shape before and after,
- *        - commits the change as "chore(wall): <p> <v>" and pushes main.
- *      A failure at any step (clone, validation, commit, push, a
- *      non-fast-forward remote) exits non-zero naming the cure. Nothing is
- *      ever skipped — the wall either lands correctly or the release fails.
- *
- *   2. Dry run:
- *        node wall-entry.mjs --dry-run --product <p> --version <v> \
- *          --date <YYYY-MM-DD> --from-changelog <CHANGELOG.md>
- *      Derives the entry exactly as above and prints it, along with the file
- *      it would be written to, but touches no clone and no remote — usable
- *      from a fresh checkout with no cache and no network.
- *
- *   3. Validate only (--check):
- *        node wall-entry.mjs --check --file <path/to/product.json>
- *      Validates an arbitrary wall file's exact key set (top-level and
- *      per-entry), field types, and strict-descending semver ordering with
- *      no duplicates. Read-only; never writes. Exit 0 = clean, exit 1 =
- *      named violations printed to stderr.
- *
- * The remote and the local cache directory are each overridable
- * (--remote / --cache-dir, or WALL_ENTRY_RELEASES_REMOTE /
- * WALL_ENTRY_RELEASES_CACHE_DIR) so tests can point at a throwaway local
- * bare repo and a throwaway cache directory — never the real remote or the
- * real developer cache.
- *
- * No dependencies beyond the system `git` binary — CHANGELOG parsing,
- * semver comparison, and JSON shape checking are all hand-rolled below.
- */
-
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
-import { execFileSync } from 'node:child_process'
-import { homedir } from 'node:os'
-import { dirname, join } from 'node:path'
-
-const DEFAULT_REMOTE = 'git@source.soulcraft.com:soulcraftlabs/releases.git'
-
-/** @returns {string} */
-function defaultCacheDir() {
-  const base = process.env.XDG_CACHE_HOME || join(homedir(), '.cache')
-  return join(base, 'soulcraft-releases')
-}
-
-// Required on every entry; "thumb" is optional (may be absent, or present as
-// string | null) — matching the HQ contract's {..., thumb?}.
-const ENTRY_REQUIRED_KEYS = ['version', 'date', 'headline', 'items', 'url']
-const ENTRY_OPTIONAL_KEYS = ['thumb']
-const ENTRY_ALLOWED_KEYS = [...ENTRY_REQUIRED_KEYS, ...ENTRY_OPTIONAL_KEYS]
-const FILE_KEYS = ['product', 'entries']
-
-// The public permalink pattern, by product. Every entry MUST carry an https
-// permalink: HQ's parser rejects a wall whose entries carry url: null (the
-// whole feed became unreadable on 2026-09-02). A product whose forge repo is
-// private links its PUBLIC package page on The Source instead of a release
-// page that would 404 for HQ's readers.
-const RELEASE_URL_PATTERNS = {
-  'open-brainy': (version) => `https://source.soulcraft.com/soulcraftlabs/open-brainy/releases/tag/v${version}`,
-  'brainy': (version) => `https://source.soulcraft.com/soulcraft/-/packages/npm/@soulcraft%2Fbrainy/${version}`,
-}
-
-/**
- * Parse argv into a flag map. `--flag value` sets a string; `--flag` alone
- * (end of argv, or followed by another `--flag`) sets boolean true.
- * @param {string[]} argv
- * @returns {Record<string, string | true>}
- */
-function parseArgs(argv) {
-  /** @type {Record<string, string | true>} */
-  const args = {}
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i]
-    if (!a.startsWith('--')) continue
-    const key = a.slice(2)
-    const next = argv[i + 1]
-    if (next === undefined || next.startsWith('--')) {
-      args[key] = true
-    } else {
-      args[key] = next
-      i++
-    }
-  }
-  return args
-}
-
-/**
- * Print a loud, named error and exit 1. Every refusal in this script goes
- * through here so the failure mode is always the same shape: "wall-entry: <what>".
- * @param {string} message
- * @returns {never}
- */
-function fail(message) {
-  console.error(`wall-entry: ${message}`)
-  process.exit(1)
-}
-
-/**
- * @param {string} version
- * @returns {{major: number, minor: number, patch: number, pre: string | null} | null}
- */
-function parseSemver(version) {
-  const m = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(version)
-  if (!m) return null
-  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]), pre: m[4] ?? null }
-}
-
-/**
- * @param {string} a
- * @param {string} b
- * @returns {number} positive if a > b, negative if a < b, 0 if equal.
- */
-function compareSemver(a, b) {
-  const pa = parseSemver(a)
-  const pb = parseSemver(b)
-  if (!pa || !pb) throw new Error(`cannot compare non-semver versions "${a}" vs "${b}"`)
-  if (pa.major !== pb.major) return pa.major - pb.major
-  if (pa.minor !== pb.minor) return pa.minor - pb.minor
-  if (pa.patch !== pb.patch) return pa.patch - pb.patch
-  if (pa.pre === pb.pre) return 0
-  if (pa.pre === null) return 1 // a release outranks any prerelease of the same core version
-  if (pb.pre === null) return -1
-  return pa.pre < pb.pre ? -1 : pa.pre > pb.pre ? 1 : 0
-}
-
-/**
- * Validate a wall file's full shape: top-level keys ("product", "entries" —
- * no more, no less), per-entry keys and field types ("thumb" optional), and
- * strict-descending semver ordering with no duplicates. Collects every
- * violation instead of failing on the first, so a caller reports the whole
- * picture in one pass.
- * @param {unknown} data
- * @returns {string[]} Violation messages; empty means the file is clean.
- */
-function validateShape(data) {
-  /** @type {string[]} */
-  const errors = []
-
-  if (typeof data !== 'object' || data === null || Array.isArray(data)) {
-    return ['top level: expected a JSON object']
-  }
-  const obj = /** @type {Record<string, unknown>} */ (data)
-
-  const topKeys = Object.keys(obj)
-  const missingTop = FILE_KEYS.filter((k) => !(k in obj))
-  const extraTop = topKeys.filter((k) => !FILE_KEYS.includes(k))
-  if (missingTop.length) errors.push(`top level: missing key(s) ${missingTop.join(', ')}`)
-  if (extraTop.length) errors.push(`top level: unexpected key(s) ${extraTop.join(', ')}`)
-
-  if (typeof obj.product !== 'string' || obj.product.trim() === '') {
-    errors.push('top level: "product" must be a non-empty string')
-  }
-  if (!Array.isArray(obj.entries)) {
-    errors.push('top level: "entries" must be an array')
-    return errors // nothing further to check without an array
-  }
-
-  const entries = /** @type {unknown[]} */ (obj.entries)
-  entries.forEach((rawEntry, i) => {
-    const label = `entries[${i}]`
-    if (typeof rawEntry !== 'object' || rawEntry === null || Array.isArray(rawEntry)) {
-      errors.push(`${label}: expected an object`)
-      return
-    }
-    const entry = /** @type {Record<string, unknown>} */ (rawEntry)
-    const keys = Object.keys(entry)
-    const missing = ENTRY_REQUIRED_KEYS.filter((k) => !(k in entry))
-    const extra = keys.filter((k) => !ENTRY_ALLOWED_KEYS.includes(k))
-    if (missing.length) errors.push(`${label}: missing key(s) ${missing.join(', ')}`)
-    if (extra.length) errors.push(`${label}: unexpected key(s) ${extra.join(', ')}`)
-
-    if (typeof entry.version !== 'string' || !parseSemver(entry.version)) {
-      errors.push(`${label}: "version" must be a semver string (got ${JSON.stringify(entry.version)})`)
-    }
-    if (typeof entry.date !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(entry.date) || Number.isNaN(Date.parse(entry.date))) {
-      errors.push(`${label}: "date" must be a YYYY-MM-DD string (got ${JSON.stringify(entry.date)})`)
-    }
-    if (typeof entry.headline !== 'string' || entry.headline.trim() === '') {
-      errors.push(`${label}: "headline" must be a non-empty string`)
-    }
-    if (!Array.isArray(entry.items) || entry.items.length === 0 || entry.items.some((it) => typeof it !== 'string' || it.trim() === '')) {
-      errors.push(`${label}: "items" must be a non-empty array of non-empty strings`)
-    }
-    if (typeof entry.url !== 'string' || !/^https:\/\/\S+$/.test(entry.url)) {
-      errors.push(`${label}: "url" must be an https permalink — never null; HQ's parser rejects the whole feed`)
-    }
-    if ('thumb' in entry && !(entry.thumb === null || typeof entry.thumb === 'string')) {
-      errors.push(`${label}: "thumb" must be a string or null when present`)
-    }
-  })
-
-  // Ordering: newest first, strictly descending, no duplicate versions —
-  // checked only over entries whose version parsed (a bad version is
-  // already reported above; comparing it too would just be noise).
-  const versioned = entries
-    .map((e, i) => ({ i, version: /** @type {any} */ (e)?.version }))
-    .filter((e) => typeof e.version === 'string' && parseSemver(e.version))
-  for (let i = 0; i < versioned.length - 1; i++) {
-    const a = versioned[i]
-    const b = versioned[i + 1]
-    const cmp = compareSemver(a.version, b.version)
-    if (cmp === 0) {
-      errors.push(`entries[${a.i}] and entries[${b.i}]: duplicate version ${a.version}`)
-    } else if (cmp < 0) {
-      errors.push(`entries[${a.i}] (${a.version}) sits above entries[${b.i}] (${b.version}) — not newest-first`)
-    }
-  }
-
-  return errors
-}
-
-/**
- * Extract one version's entry body from a standard-version-style CHANGELOG.md
- * (headings `### [version](url) (date)`, followed by `- bullet (hash)` lines
- * until the next heading or EOF).
- * @param {string} changelog
- * @param {string} version
- * @returns {string[]} Bullet lines, trimmed of their leading "- " and
- *   trailing " (hash)".
- */
-function extractChangelogBullets(changelog, version) {
-  const lines = changelog.split('\n')
-  const headingRe = /^### \[([^\]]+)\]\(.*\)\s*\(\d{4}-\d{2}-\d{2}\)\s*$/
-  let start = -1
-  for (let i = 0; i < lines.length; i++) {
-    const m = headingRe.exec(lines[i])
-    if (m && m[1] === version) {
-      start = i + 1
-      break
-    }
-  }
-  if (start === -1) {
-    fail(
-      `version ${version} has no CHANGELOG entry yet — run this after the CHANGELOG step composes "### [${version}]", not before`,
-    )
-  }
-  /** @type {string[]} */
-  const bullets = []
-  for (let i = start; i < lines.length; i++) {
-    if (headingRe.test(lines[i])) break // next entry starts
-    const bulletMatch = /^- (.+?)(?:\s\(([0-9a-f]{6,40})\))?$/.exec(lines[i].trim())
-    if (lines[i].trim().startsWith('- ') && bulletMatch) {
-      const text = bulletMatch[1].trim()
-      if (text) bullets.push(text)
-    }
-  }
-  if (bullets.length === 0) {
-    fail(`version ${version}'s CHANGELOG entry has no bullets to derive a headline/items from`)
-  }
-  return bullets
-}
-
-/**
- * Derive a wall entry from a CHANGELOG.md.
- * @param {{product: string, version: string, date: string, changelogPath: string, url?: string, thumb?: string | null}} opts
- * @returns {{version: string, date: string, headline: string, items: string[], url: string, thumb: string | null}}
- */
-function deriveEntry({ product, version, date, changelogPath, url, thumb }) {
-  if (!parseSemver(version)) fail(`--version "${version}" is not a semver string`)
-  if (!/^\d{4}-\d{2}-\d{2}$/.test(date) || Number.isNaN(Date.parse(date))) {
-    fail(`--date "${date}" is not a YYYY-MM-DD date`)
-  }
-  if (!existsSync(changelogPath)) fail(`--from-changelog "${changelogPath}" does not exist`)
-
-  const changelog = readFileSync(changelogPath, 'utf8')
-  const items = extractChangelogBullets(changelog, version)
-  const headline = items[0]
-
-  const pattern = RELEASE_URL_PATTERNS[product]
-  if (url === undefined && pattern === undefined) {
-    throw new Error(`wall-entry: no permalink pattern for product "${product}" — add one to RELEASE_URL_PATTERNS or pass --url; entries never carry url: null`)
-  }
-  const resolvedUrl = url !== undefined ? url : pattern(version)
-  const resolvedThumb = thumb !== undefined ? thumb : null
-
-  return { version, date, headline, items, url: resolvedUrl, thumb: resolvedThumb }
-}
-
-/**
- * Load and shape-validate a wall file.
- * @param {string} filePath
- * @returns {Record<string, any>}
- */
-function loadWallFile(filePath) {
-  if (!existsSync(filePath)) fail(`"${filePath}" does not exist`)
-  /** @type {unknown} */
-  let data
-  try {
-    data = JSON.parse(readFileSync(filePath, 'utf8'))
-  } catch (err) {
-    fail(`"${filePath}" is not valid JSON: ${/** @type {Error} */ (err).message}`)
-  }
-  const errors = validateShape(data)
-  if (errors.length) {
-    fail(`"${filePath}" fails shape validation —\n  ${errors.join('\n  ')}`)
-  }
-  return /** @type {Record<string, any>} */ (data)
-}
-
-/**
- * Run a git command, throwing an Error whose message is git's own stderr
- * (trimmed) on failure — every caller wraps this to name the cure.
- * @param {string[]} args
- * @param {string} cwd
- * @returns {string} stdout, trimmed.
- */
-function git(args, cwd) {
-  try {
-    return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim()
-  } catch (err) {
-    const stderr = /** @type {any} */ (err).stderr
-    const message = (typeof stderr === 'string' && stderr.trim()) || /** @type {Error} */ (err).message
-    throw new Error(message)
-  }
-}
-
-/**
- * Ensure a clean, up-to-date local clone of the releases repo at
- * `cacheDir`, checked out on `main` — cloning fresh if `cacheDir` has no
- * `.git`, otherwise fetching and hard-resetting onto `origin/main` (so a
- * stray local commit or edit left by a previous failed run can never leak
- * into the next one).
- * @param {string} remote
- * @param {string} cacheDir
- */
-function ensureReleasesClone(remote, cacheDir) {
-  if (existsSync(join(cacheDir, '.git'))) {
-    try {
-      git(['remote', 'set-url', 'origin', remote], cacheDir)
-      git(['fetch', '--prune', 'origin'], cacheDir)
-      git(['checkout', 'main'], cacheDir)
-      git(['reset', '--hard', 'origin/main'], cacheDir)
-      git(['clean', '-fd'], cacheDir)
-    } catch (err) {
-      fail(
-        `cannot refresh the cached releases checkout at "${cacheDir}" from "${remote}" — ${/** @type {Error} */ (err).message}\n` +
-          `  cure: delete "${cacheDir}" and re-run so it re-clones from scratch, or confirm SSH access with "ssh -T git@source.soulcraft.com"`,
-      )
-    }
-    return
-  }
-
-  mkdirSync(dirname(cacheDir), { recursive: true })
-  try {
-    git(['clone', remote, cacheDir], dirname(cacheDir))
-  } catch (err) {
-    fail(
-      `cannot clone "${remote}" — ${/** @type {Error} */ (err).message}\n` +
-        `  cure: confirm SSH access with "ssh -T git@source.soulcraft.com" and that the soulcraftlabs/releases repo exists yet`,
-    )
-  }
-  try {
-    git(['checkout', 'main'], cacheDir)
-  } catch (err) {
-    fail(
-      `cloned "${remote}" into "${cacheDir}" but could not check out "main" — ${/** @type {Error} */ (err).message}\n` +
-        `  cure: confirm the releases repo's default branch is named "main"`,
-    )
-  }
-}
-
-/**
- * Prepend `entry` to the wall at `<cacheDir>/<product>.json`, replacing any
- * existing entry for the same version (idempotent re-runs), validating
- * before and after, committing, and pushing — or refusing loudly, naming
- * the cure, at whichever step fails.
- * @param {{version: string, date: string, headline: string, items: string[], url: string, thumb: string | null}} entry
- * @param {string} product
- * @param {string} remote
- * @param {string} cacheDir
- */
-function publishEntry(entry, product, remote, cacheDir) {
-  ensureReleasesClone(remote, cacheDir)
-
-  const filePath = join(cacheDir, `${product}.json`)
-  if (!existsSync(filePath)) {
-    fail(
-      `"${filePath}" does not exist in the releases repo — cure: seed "${product}.json" at the repo root first (it must exist before any release rail can prepend to it)`,
-    )
-  }
-  const wall = loadWallFile(filePath)
-
-  if (wall.product !== product) {
-    fail(`"${filePath}" has product "${wall.product}", but --product "${product}" was given — refusing a cross-product write`)
-  }
-
-  const replacing = wall.entries.some((e) => e.version === entry.version)
-  wall.entries = [entry, ...wall.entries.filter((e) => e.version !== entry.version)]
-
-  const postErrors = validateShape(wall)
-  if (postErrors.length) {
-    fail(`the entry for ${entry.version} would leave "${filePath}" invalid —\n  ${postErrors.join('\n  ')}`)
-  }
-
-  writeFileSync(filePath, JSON.stringify(wall, null, 2) + '\n', 'utf8')
-
-  const status = git(['status', '--porcelain', '--', `${product}.json`], cacheDir)
-  if (status === '') {
-    console.log(`wall-entry: "${product}.json" already carries an identical entry for ${entry.version} — nothing to commit or push`)
-    return
-  }
-
-  try {
-    git(['add', `${product}.json`], cacheDir)
-    git(['commit', '-m', `chore(wall): ${product} ${entry.version}`], cacheDir)
-  } catch (err) {
-    fail(`cannot commit the wall entry in "${cacheDir}" — ${/** @type {Error} */ (err).message}\n  cure: inspect "${cacheDir}" by hand and re-run once its git state is clean`)
-  }
-
-  try {
-    git(['push', 'origin', 'main'], cacheDir)
-  } catch (err) {
-    fail(
-      `push to "${remote}" failed (likely a non-fast-forward — another release landed on main first) — ${/** @type {Error} */ (err).message}\n` +
-        `  cure: re-run this release step; it re-fetches and resets onto the latest origin/main before retrying`,
-    )
-  }
-
-  const sha = git(['rev-parse', 'HEAD'], cacheDir)
-  console.log(
-    `wall-entry: ${replacing ? 'replaced' : 'wrote'} v${entry.version} in "${product}.json" (${wall.entries.length} entries, newest first) — pushed ${sha} to ${remote} main`,
-  )
-}
-
-function main() {
-  const args = parseArgs(process.argv.slice(2))
-
-  if (args.check) {
-    const filePath = /** @type {string | undefined} */ (args.file)
-    if (!filePath) fail('--check needs --file <path>')
-    const wall = loadWallFile(/** @type {string} */ (filePath))
-    console.log(`wall-entry --check: "${filePath}" OK — product "${wall.product}", ${wall.entries.length} entries, newest-first, no duplicates`)
-    process.exit(0)
-  }
-
-  // Generate mode (default, also covers --dry-run): --product, --version,
-  // --date, --from-changelog required.
-  const product = /** @type {string | undefined} */ (args.product)
-  const version = /** @type {string | undefined} */ (args.version)
-  const date = /** @type {string | undefined} */ (args.date)
-  const fromChangelog = /** @type {string | undefined} */ (args['from-changelog'])
-
-  const missing = []
-  if (!product) missing.push('--product')
-  if (!version) missing.push('--version')
-  if (!date) missing.push('--date')
-  if (!fromChangelog) missing.push('--from-changelog')
-  if (missing.length) {
-    fail(
-      `missing required flag(s): ${missing.join(', ')}\n` +
-        'Usage:\n' +
-        '  wall-entry.mjs --product <p> --version <v> --date <YYYY-MM-DD> --from-changelog <CHANGELOG.md> [--dry-run]\n' +
-        '  wall-entry.mjs --check --file <path/to/product.json>',
-    )
-  }
-
-  const urlArg = args.url === true ? undefined : /** @type {string | undefined} */ (args.url)
-  const thumbArg = args.thumb === true ? undefined : /** @type {string | undefined} */ (args.thumb)
-
-  const entry = deriveEntry({
-    product: /** @type {string} */ (product),
-    version: /** @type {string} */ (version),
-    date: /** @type {string} */ (date),
-    changelogPath: /** @type {string} */ (fromChangelog),
-    url: urlArg,
-    thumb: thumbArg,
-  })
-
-  const remote = /** @type {string} */ (args.remote ?? process.env.WALL_ENTRY_RELEASES_REMOTE ?? DEFAULT_REMOTE)
-  const cacheDir = /** @type {string} */ (args['cache-dir'] ?? process.env.WALL_ENTRY_RELEASES_CACHE_DIR ?? defaultCacheDir())
-
-  if (args['dry-run']) {
-    console.log(`wall-entry --dry-run: would write to "${join(cacheDir, `${product}.json`)}" in ${remote} (main), pushed as "chore(wall): ${product} ${version}"`)
-    console.log(JSON.stringify(entry, null, 2))
-    process.exit(0)
-  }
-
-  publishEntry(entry, /** @type {string} */ (product), remote, cacheDir)
-}
-
-main()

src/brainy.ts

@@ -15,6 +15,7 @@ import { JsHnswVectorIndex } from './hnsw/hnswIndex.js'
 import { createStorage, resolveFilesystemRoot } from './storage/storageFactory.js'
 import type { StorageOptions } from './storage/storageFactory.js'
 import { rebuildCounts } from './utils/rebuildCounts.js'
+import { jsonSafeIndexMetadata } from './utils/jsonSafeIndexMetadata.js'
 import type { MetadataWriteBuffer } from './utils/metadataWriteBuffer.js'
 import { BaseStorage } from './storage/baseStorage.js'
 import {
@@ -1819,6 +1820,11 @@ export class Brainy<T = any> implements BrainyInterface<T> {
       // a deferred write's ack and its background embed DELAYED a vector;
       // this is where it lands.
       if (!this.isReadOnly) {
+        // Foreground, as the crash-recovery contract pins it: a reopened brain
+        // has its markers re-armed when open() returns. The low-water mark
+        // bounds this to the log's tail on any brain that has ever drained —
+        // milliseconds — so the foreground cost is the unmarked first open
+        // only, once per upgraded brain.
         try {
           await step(
             'bridge-pending-embed-sidecars',
@@ -1827,7 +1833,7 @@ export class Brainy<T = any> implements BrainyInterface<T> {
           )
           await step(
             'recover-pending-embeds',
-            'folding the generation log\'s deferred-embed markers back into the pending set',
+            'folding the generation log\'s deferred-embed markers (from the low-water mark) into the pending set',
             () => this.recoverPendingEmbedsFromLog()
           )
           if (this._pendingEmbedIds.size > 0) {
@@ -2407,6 +2413,17 @@ export class Brainy<T = any> implements BrainyInterface<T> {
    */
   private static readonly PENDING_EMBED_PREFIX = '_system/pending_embeds/'
 
+  /**
+   * Storage-root-relative path of the ADVISORY pending-embed low-water mark:
+   * `{ generation, writtenAt }`, written whenever the pending set drains to
+   * empty (and at clean close when empty). Every marker in facts at or below
+   * `generation` is consumed, so recovery scans from `generation + 1`. The
+   * mark is advisory and monotone-safe: stale-low costs a longer scan, never
+   * a lost marker; it is never required for correctness.
+   */
+  private static readonly PENDING_EMBED_LOWWATER_PATH = '_system/pending_embeds_lowwater.json'
+
+
   /**
    * @description Mark a deferred embed pending (MT5): the id joins the
    * in-memory fast-path set and the returned `embed.pending` record is
@@ -2434,6 +2451,40 @@ export class Brainy<T = any> implements BrainyInterface<T> {
    */
   private clearPendingEmbed(id: string): void {
     this._pendingEmbedIds.delete(id)
+    if (this._pendingEmbedIds.size === 0) this.maybeWriteEmbedLowWater()
+  }
+
+  /**
+   * @description Advance the advisory low-water mark: called at drain-to-empty
+   * (and at clean close when empty), it records the fact log's CURRENT head —
+   * with the set empty, every marker at or below the head has been consumed,
+   * so the next open's recovery fold scans only what comes after. Fire-and-
+   * forget at the drain (close() awaits the core); loud on failure: a missed
+   * write costs the next open a longer scan, never a marker. No-op without a
+   * fact log (no durable markers exist there) and on read-only opens.
+   */
+  private maybeWriteEmbedLowWater(): void {
+    void this.writeEmbedLowWater()
+  }
+
+  /** The awaitable core of {@link maybeWriteEmbedLowWater} — close() awaits it. */
+  private async writeEmbedLowWater(): Promise<void> {
+    if (this.isReadOnly) return
+    const log = this.generationStore ? this.generationStore.getFactLog() : null
+    if (!log) return
+    const generation = log.headGeneration()
+    if (!(generation > 0)) return
+    try {
+      await this.storage.writeRawObject(Brainy.PENDING_EMBED_LOWWATER_PATH, {
+        generation,
+        writtenAt: Date.now()
+      })
+    } catch (err) {
+      prodLog.warn(
+        `[Brainy] pending-embed low-water write failed at generation ${generation}: ` +
+          `${(err as Error).message} — the next open scans from the previous mark`
+      )
+    }
   }
 
   /**
@@ -2444,9 +2495,14 @@ export class Brainy<T = any> implements BrainyInterface<T> {
    * survives the fold is exactly the set of acknowledged deferred writes
    * whose vectors have not landed.
    *
-   * BOUND (honest): no durable low-water mark exists for the earliest
-   * unconsumed pending, so the fold scans the log's committed facts from
-   * generation 1 — a sequential read of the log at open, O(log bytes).
+   * BOUND: the scan starts at the advisory low-water mark
+   * ({@link Brainy.PENDING_EMBED_LOWWATER_PATH}) — the log head at which the
+   * pending set last drained to empty — so a settled brain reads only the
+   * facts since then, not its whole history. Without a mark (first open
+   * after upgrade) it scans from generation 1, once; a stale-low mark costs
+   * a longer scan, never a marker. The fold stays on the open's foreground —
+   * the crash-recovery contract pins that a reopened brain has its markers
+   * re-armed when open() returns — and the mark is what makes that cheap.
    * It is SKIPPED WHOLESALE when the log has never had a v2 tail
    * ({@link FactLog.hasV2History} — v1 facts cannot carry marker records),
    * so pre-cutover brains pay nothing; on a mixed log the scan still reads
@@ -2459,7 +2515,18 @@ export class Brainy<T = any> implements BrainyInterface<T> {
   private async recoverPendingEmbedsFromLog(): Promise<void> {
     const log = this.generationStore.getFactLog()
     if (!log || !log.hasV2History()) return
-    const scan = log.scanFacts({ fromGeneration: 1 })
+    let fromGeneration = 1
+    try {
+      const mark = (await this.storage.readRawObject(Brainy.PENDING_EMBED_LOWWATER_PATH)) as {
+        generation?: number
+      } | null
+      if (mark && typeof mark.generation === 'number' && mark.generation > 0) {
+        fromGeneration = mark.generation + 1
+      }
+    } catch {
+      // No mark (or unreadable): scan from 1 — correctness over cost.
+    }
+    const scan = log.scanFacts({ fromGeneration })
     for await (const batch of scan.batches()) {
       for (const fact of batch.facts) {
         for (const record of fact.records ?? []) {
@@ -4203,32 +4270,19 @@ export class Brainy<T = any> implements BrainyInterface<T> {
    */
   /**
    * @description A JSON-safe view of a record bound for the metadata-index
-   * crossing. The seam's metadata is JSON-safe BY CONTRACT (a native provider
-   * serializes it; u64 ints as Number corrupt above 2^53) — but
-   * {@link resolveVerbEndpointInts} MIRRORS the resolved endpoint ints onto
-   * the verb object itself as BigInt (`verb.sourceInt`/`targetInt`), so a
-   * verb object reused as index metadata carried BigInts into
-   * JSON.stringify, which throws, aborting the whole transaction (found by
-   * the first joint pair gate). Endpoint ints ride their OWN op params on the
-   * graph legs — the metadata crossing drops every BigInt-valued top-level
-   * key instead of guessing at a lossy numeric encoding.
+   * crossing — delegates to the shared {@link jsonSafeIndexMetadata} leaf,
+   * which the metadata-index transaction operations ALSO apply at execute
+   * and rollback time. This plan-time wrap alone proved insufficient: it
+   * returns the same reference when the record is clean, and `transact()`'s
+   * delete legs share that reference with a graph-retraction op whose
+   * execute-time endpoint resolution mirrors BigInt ints onto it (the full
+   * aliasing story lives on the leaf module's doc).
    * @param metadata - The candidate index-metadata record.
    * @returns The same object when already JSON-safe, else a shallow copy
    *   without the BigInt-valued keys.
    */
   private static jsonSafeIndexMetadata(metadata: unknown): unknown {
-    if (metadata === null || typeof metadata !== 'object') return metadata
-    const rec = metadata as Record<string, unknown>
-    let hasBigint = false
-    for (const k in rec) {
-      if (typeof rec[k] === 'bigint') { hasBigint = true; break }
-    }
-    if (!hasBigint) return metadata
-    const out: Record<string, unknown> = {}
-    for (const k in rec) {
-      if (typeof rec[k] !== 'bigint') out[k] = rec[k]
-    }
-    return out
+    return jsonSafeIndexMetadata(metadata)
   }
 
   private metadataIndexRetractionOp(
@@ -7292,6 +7346,47 @@ export class Brainy<T = any> implements BrainyInterface<T> {
         await this.verifyMetadataLive()
       }
 
+      // PLANNED FIND (optional provider door, `MetadataIndexProvider.planFindPage`).
+      //
+      // The stage doors below each serve one stage, so a find that consults
+      // three of them crosses into the index three times and marshals a result
+      // set at every crossing — a filter matching a hundred thousand rows
+      // builds a hundred thousand id strings to return a page of twenty-five.
+      // An index that can decide the stage order itself answers the page in one
+      // call and materializes ids only for the page.
+      //
+      // The hook sits ABOVE the branch selection because the branches are what
+      // decide stage order per call site; an index that plans has to be asked
+      // before that choice is made, not inside one of its arms.
+      //
+      // Optional and additive: a provider without the door, and any shape the
+      // door hands back, take exactly the path they always took. `null` is a
+      // routing decision the door must make BEFORE doing any work — never a
+      // partial answer. Every guard above still ran (readiness, the migration
+      // gate, the where-clause validation, the metadata cold-read guard), and
+      // the serving law is applied here on the way out: an empty answer is
+      // re-verified against the index that produced it before it is believed.
+      const planningIndex = this.metadataIndex as unknown as MetadataIndexProvider
+      if (typeof planningIndex.planFindPage === 'function') {
+        const planned = await planningIndex.planFindPage(params, [...hiddenIds], this.graphIndex)
+        if (planned !== null && planned !== undefined) {
+          if (planned.ids.length === 0) {
+            // A cold adjacency can report a size yet hold no edges, so an empty
+            // graph answer is not truth until the adjacency verifies live. A
+            // genuinely edgeless anchor verifies and the empty result stands.
+            if (planned.emptyAt === 'graph') await this.verifyGraphAdjacencyLive()
+            return []
+          }
+          const plannedEntities = await this.batchGet(planned.ids)
+          const plannedResults: Result<T>[] = []
+          for (const id of planned.ids) {
+            const entity = plannedEntities.get(id)
+            if (entity) plannedResults.push(this.createResult(id, 1.0, entity))
+          }
+          return plannedResults
+        }
+      }
+
       // Handle metadata-only queries (no vector search needed)
       if (!hasVectorSearchCriteria && !hasGraphCriteria && hasFilterCriteria) {
         // Build filter for metadata index
@@ -7482,7 +7577,37 @@ export class Brainy<T = any> implements BrainyInterface<T> {
       // JS path — there the materialized `candidateIds` restricts the walk instead.
       let preResolvedAllowedIds: OpaqueIdSet | undefined
 
-      if (params.where || params.type || params.subtype || params.service || params.excludeVFS) {
+      // Graph-first law (10.4.8, BRAINY-PROD-LATENCY-TRIAD rounds 44/45): with
+      // `connected` present the NEIGHBOUR SET is the candidate universe. It is
+      // resolved first from the adjacency (O(neighbours)), the metadata filter
+      // is evaluated over those ids only, and paging happens LAST. The earlier
+      // order materialized the whole-store filtered id list, paged it, hydrated
+      // the page, and only then intersected with the neighbours — O(store) per
+      // call, and a neighbour outside the first page was silently dropped.
+      let graphFirstIds: string[] | null = null
+      if (hasGraphCriteria) {
+        graphFirstIds = await this.resolveConnectedIds(params)
+        if (hiddenIds.size > 0) {
+          graphFirstIds = graphFirstIds.filter((id) => !hiddenIds.has(id))
+        }
+        if (
+          graphFirstIds.length > 0 &&
+          (params.where || params.type || params.subtype || params.service || params.excludeVFS)
+        ) {
+          preResolvedFilter = this.buildMetadataFilter(params)
+          graphFirstIds = await this.filterIdsWithinBelted(preResolvedFilter, graphFirstIds)
+        }
+        if (graphFirstIds.length === 0) {
+          return []
+        }
+        if (!hasVectorSearchCriteria) {
+          return await this.pageConnectedIds(params, graphFirstIds)
+        }
+        // The vector leg walks ONLY the neighbours (its candidate walk). The
+        // filter is already applied above, so no opaque universe is produced —
+        // it would describe the whole store, not the neighbour set.
+        preResolvedMetadataIds = graphFirstIds
+      } else if (params.where || params.type || params.subtype || params.service || params.excludeVFS) {
         preResolvedFilter = this.buildMetadataFilter(params)
         preResolvedMetadataIds = await this.filterIdsBelted(preResolvedFilter)
 
@@ -7671,9 +7796,11 @@ export class Brainy<T = any> implements BrainyInterface<T> {
         }
       }
 
-      // Graph search component with O(1) traversal
-      if (params.connected) {
-        results = await this.executeGraphSearch(params, results)
+      // The text leg of a hybrid find has no candidate door, so its hits are
+      // held to the neighbour set here; the vector leg walked only the neighbours.
+      if (graphFirstIds !== null && results.length > 0) {
+        const neighbourSet = new Set(graphFirstIds)
+        results = results.filter((r) => neighbourSet.has(r.id))
       }
 
       // Apply fusion scoring if requested
@@ -12788,6 +12915,29 @@ export class Brainy<T = any> implements BrainyInterface<T> {
     }
   }
 
+  /**
+   * The id-scoped twin of {@link filterIdsBelted}: evaluate `filter` over `ids`
+   * only, through the provider's own evaluation so the answer can never drift
+   * from `getIdsForFilter`'s. A provider without the door is served by its
+   * whole-store answer intersected here (the reference index implements the
+   * door itself). Same belt: field refusals cross as `BrainyFieldRefusal`.
+   */
+  private async filterIdsWithinBelted(filter: unknown, ids: readonly string[]): Promise<string[]> {
+    this.ensureIndexesLoaded(['metadata'])
+    const mip = this.metadataIndex as unknown as MetadataIndexProvider
+    try {
+      if (typeof mip.filterIdsWithin === 'function') {
+        return await mip.filterIdsWithin(filter, ids)
+      }
+      const matched = new Set(await this.metadataIndex.getIdsForFilter(filter))
+      return ids.filter((id) => matched.has(id))
+    } catch (err) {
+      const normalized = asBrainyFieldRefusal(err)
+      if (normalized) throw normalized
+      throw err
+    }
+  }
+
   async getIndexStatus(): Promise<{
     initialized: boolean
     /** `true` once open()'s index-build-if-needed step has run. Named for API
@@ -15742,8 +15892,18 @@ export class Brainy<T = any> implements BrainyInterface<T> {
       )
     }
 
-    const nearEntity = await this.get(params.near.id)
+    // The anchor's VECTOR is the query; get() omits vectors by default, which
+    // fed a zero-length vector to the index and refused every near() with a
+    // dimension mismatch. Ask for it, and refuse by name when the anchor has
+    // none — a proximity search around an unvectored row has no meaning.
+    const nearEntity = await this.get(params.near.id, { includeVectors: true })
     if (!nearEntity) return []
+    if (!nearEntity.vector || nearEntity.vector.length === 0) {
+      throw new Error(
+        `find({ near }): entity '${params.near.id}' has no vector to search around — ` +
+          `it was never embedded (or was unvectored). Embed it, or search with a query instead.`
+      )
+    }
 
     const nearResults: [string, number][] = await this.index.search(nearEntity.vector, params.limit || 10)
 
@@ -15771,16 +15931,16 @@ export class Brainy<T = any> implements BrainyInterface<T> {
   }
   
   /**
-   * Execute graph search component.
+   * Resolve `params.connected` to the neighbour id set — the graph-first
+   * find's candidate universe (deterministic traversal order, anchors excluded).
    *
    * Honors the full `GraphConstraints` contract: multi-hop `depth` (breadth-first via
-   * `neighbors()`), `via`/`type` verb-type filtering, and `direction`. Previously this read
-   * only `from`/`to`/`direction` and did a single 1-hop `getNeighbors()`, so `depth` and `via`
-   * were silently ignored — `find({ connected: { from, depth: 3 } })` returned only the
-   * immediate neighbour at every depth.
+   * `neighbors()`), `via`/`type` verb-type filtering, and `direction`. An empty set
+   * is re-verified against the adjacency before it is believed — a not-serving
+   * adjacency throws rather than answering `[]` as truth.
    */
-  private async executeGraphSearch(params: FindParams<T>, existingResults: Result<T>[]): Promise<Result<T>[]> {
-    if (!params.connected) return existingResults
+  private async resolveConnectedIds(params: FindParams<T>): Promise<string[]> {
+    if (!params.connected) return []
 
     const { from, to, depth, direction = 'both' } = params.connected
     const via = params.connected.via ?? params.connected.type
@@ -15834,8 +15994,8 @@ export class Brainy<T = any> implements BrainyInterface<T> {
           if (anchorInt === undefined) return new Set() // unmapped → no relations
 
           const verbTypeIndex = TypeUtils.getVerbIndex(via as VerbType)
-          // No limit: match the JS BFS exactly — overall result limiting happens
-          // downstream against existingResults.
+          // No limit: match the JS BFS exactly — the page is cut downstream,
+          // after the metadata filter, by pageConnectedIds / the candidate walk.
           const reachedInts = await provider.findConnectedSubtype(
             anchorInt, verbTypeIndex, subtypeArr[0], effectiveDepth, null
           )
@@ -15920,22 +16080,44 @@ export class Brainy<T = any> implements BrainyInterface<T> {
       await this.verifyGraphAdjacencyLive()
     }
 
-    // Filter existing results to only connected entities
-    if (existingResults.length > 0) {
-      return existingResults.filter(r => connectedIds.has(r.id))
-    }
+    return [...connectedIds]
+  }
 
-    // Batch-load connected entities for fast cloud-storage performance
+  /**
+   * Page and hydrate an already-filtered neighbour set — the pure graph (and
+   * graph + metadata) find's tail. `orderBy` sorts the WHOLE set by field value
+   * before the page is cut (never the page after), null values last on `asc`
+   * and first on `desc`; without `orderBy` the traversal order stands.
+   */
+  private async pageConnectedIds(params: FindParams<T>, ids: string[]): Promise<Result<T>[]> {
+    const limit = params.limit || 10
+    const offset = params.offset || 0
+    let ordered = ids
+    if (params.orderBy) {
+      const field = params.orderBy
+      const asc = (params.order || 'asc') === 'asc'
+      const valued = await Promise.all(
+        ids.map(async (id) => ({ id, value: await this.metadataIndex.getFieldValueForEntity(id, field) }))
+      )
+      valued.sort((a, b) => {
+        if (a.value == null && b.value == null) return 0
+        if (a.value == null) return asc ? 1 : -1
+        if (b.value == null) return asc ? -1 : 1
+        if (a.value === b.value) return 0
+        const comparison = a.value < b.value ? -1 : 1
+        return asc ? comparison : -comparison
+      })
+      ordered = valued.map((v) => v.id)
+    }
+    const pageIds = ordered.slice(offset, offset + limit)
+    const entitiesMap = await this.batchGet(pageIds)
     const results: Result<T>[] = []
-    const ids = [...connectedIds]
-    const entitiesMap = await this.batchGet(ids)
-    for (const id of ids) {
+    for (const id of pageIds) {
       const entity = entitiesMap.get(id)
       if (entity) {
         results.push(this.createResult(id, 1.0, entity))
       }
     }
-
     return results
   }
   
@@ -19455,6 +19637,7 @@ export class Brainy<T = any> implements BrainyInterface<T> {
    *   terminal releases have run.
    */
   async close(): Promise<void> {
+    if (this._pendingEmbedIds.size === 0) await this.writeEmbedLowWater()
     let closeFailure: unknown = null
     try {
       await this.closeDurableSteps()

src/neural/embeddedTypeEmbeddings.ts

@@ -2,7 +2,7 @@
  * 🧠 BRAINY EMBEDDED TYPE EMBEDDINGS
  *
  * AUTO-GENERATED - DO NOT EDIT
- * Generated: 2026-06-29T10:04:19-07:00
+ * Generated: 2026-08-27T09:18:45-07:00
  * Noun Types: 42
  * Verb Types: 127
  *
@@ -19,7 +19,7 @@ export const TYPE_METADATA = {
   verbTypes: 127,
   totalTypes: 169,
   embeddingDimensions: 384,
-  generatedAt: "2026-06-29T10:04:19-07:00",
+  generatedAt: "2026-08-27T09:18:45-07:00",
   sizeBytes: {
     embeddings: 259584,
     base64: 346112

src/plugin.ts

@@ -411,6 +411,65 @@ export interface MetadataIndexProvider {
    * @returns The matching id universe as an opaque set.
    */
   getIdSetForFilter?(filter: any): Promise<OpaqueIdSet>
+  /**
+   * @description OPTIONAL: evaluate `filter` over `ids` ONLY and return the
+   * survivors in the caller's order — the door a graph-first
+   * `find({ connected, where })` walks. The neighbour set is the universe there,
+   * so the filter must cost O(|ids|) membership checks, never a whole-store
+   * materialization. A native index answers from its roaring filter result
+   * (membership by entity int); the reference index answers from its own
+   * `getIdsForFilter`, so the two doors can never disagree. Absent → Brainy
+   * intersects `getIdsForFilter`'s answer with `ids` itself (correct, O(store)).
+   * @param filter - The same filter shape accepted by `getIdsForFilter`.
+   * @param ids - The candidate ids (canonical). The answer is a subsequence.
+   */
+  filterIdsWithin?(filter: any, ids: readonly string[]): Promise<string[]>
+  /**
+   * @description OPTIONAL: plan and execute a WHOLE `find()` — the graph
+   * traversal, the metadata filter, the ordering and the page — and answer the
+   * page's ids, or `null` for a shape this index does not plan.
+   *
+   * The doors above each serve one stage, so a `find()` that consults three of
+   * them crosses into the index three times and marshals a result set at every
+   * crossing. An index that can decide the stage ORDER itself does the whole
+   * thing in one call and materializes ids only for the page — a filter
+   * matching a hundred thousand rows then builds twenty-five id strings instead
+   * of a hundred thousand.
+   *
+   * The contract this door must keep, because Brainy cannot check it:
+   *
+   * - **The same answer.** Identical rows, in identical order, to what the
+   *   stage doors would have produced for the same params. This door changes
+   *   which code runs, never what the answer is.
+   * - **The law of the stages** (`find({ connected })` is graph-first): the
+   *   neighbour set is the candidate universe, the filter is evaluated over
+   *   those ids only, `orderBy` sorts the whole candidate set, and the page is
+   *   cut LAST.
+   * - **`null` before work, not instead of an answer.** A shape the index does
+   *   not plan must be handed back BEFORE any evaluation, so Brainy serves it
+   *   through the stage doors exactly as it always has. Returning `null` after
+   *   partial work, or an empty page for a shape it could not evaluate, is a
+   *   silent wrong answer.
+   * - **`emptyAt` names the stage** that produced an empty page — `'graph'`,
+   *   `'filter'`, `'visibility'` or `'none'` — so Brainy can apply its serving
+   *   law to the right index. An empty answer from an index that is not
+   *   serving must refuse loudly, and Brainy can only re-verify what it is told.
+   *
+   * Absent → every `find()` is served by the stage doors, which is Brainy's
+   * own behaviour and the ordering oracle for any implementation of this one.
+   * @param params - The find params, already normalized by `find()`
+   *   (natural-language parsed, `connected` anchors resolved to canonical ids,
+   *   an empty `where` dropped).
+   * @param hiddenIds - Ids this read must not return; apply BEFORE paging so
+   *   `limit` stays exact.
+   * @param graphIndex - The active graph provider, for a `connected` plan.
+   * @returns The page's ids plus the stage that emptied it, or `null`.
+   */
+  planFindPage?(
+    params: any,
+    hiddenIds: readonly string[],
+    graphIndex: unknown
+  ): Promise<{ ids: string[]; emptyAt: 'graph' | 'filter' | 'visibility' | 'none' } | null>
   getIdsForTextQuery(query: string): Promise<Array<{ id: string; matchCount: number }>>
   getSortedIdsForFilter(filter: any, orderBy: string, order?: 'asc' | 'desc', topK?: number): Promise<string[]>
   getFilterValues(field: string): Promise<string[]>

src/storage/adapters/baseStorageAdapter.ts

@@ -1089,6 +1089,10 @@ export abstract class BaseStorageAdapter implements StorageAdapter {
 
   // Counts changed since the last persist? Drives the write-through flush.
   protected pendingCountPersist = false
+  /** The one persist running right now, if any (single-flight law — see flushCounts). */
+  private countPersistInFlight: Promise<void> | null = null
+  /** The one trailing persist a burst has queued behind the in-flight one. */
+  private countPersistTrailing: Promise<void> | null = null
 
   /**
    * Get total noun count - O(1) operation
@@ -1341,15 +1345,46 @@ export abstract class BaseStorageAdapter implements StorageAdapter {
       return
     }
 
-    try {
-      // Persist to storage (implemented by subclass)
-      await this.persistCounts()
-      this.pendingCountPersist = false
-    } catch (error) {
-      console.error('CRITICAL: Failed to flush counts to storage:', error)
-      // Keep pending flag set so we retry on next operation
-      throw error
+    // SINGLE-FLIGHT, COALESCED. Counts are write-through on every change, so
+    // a burst of writes used to launch one persist per change, all in flight
+    // together. Two of them inside the same millisecond shared the atomic
+    // writer's temp path (`.tmp-<pid>-<ms>`): both wrote it, the first rename
+    // consumed it, the second rename found nothing — ENOENT, ~1,500 times a
+    // day on a busy production brain, with a full ledger write per change
+    // behind it. Now exactly one persist runs at a time; requests that arrive
+    // while it runs collapse into ONE trailing persist that carries the final
+    // state. A burst of N changes costs at most two writes and never races
+    // itself.
+    if (this.countPersistInFlight) {
+      // The in-flight write may have already serialised a stale snapshot —
+      // ask for one more pass after it, and let every caller in this burst
+      // await that same pass.
+      if (!this.countPersistTrailing) {
+        this.countPersistTrailing = this.countPersistInFlight
+          .catch(() => undefined)
+          .then(() => {
+            this.countPersistTrailing = null
+            return this.flushCounts()
+          })
+      }
+      return this.countPersistTrailing
     }
+
+    this.countPersistInFlight = (async () => {
+      try {
+        // Persist to storage (implemented by subclass)
+        this.pendingCountPersist = false
+        await this.persistCounts()
+      } catch (error) {
+        // Keep the flag set so the next operation retries.
+        this.pendingCountPersist = true
+        console.error('CRITICAL: Failed to flush counts to storage:', error)
+        throw error
+      } finally {
+        this.countPersistInFlight = null
+      }
+    })()
+    return this.countPersistInFlight
   }
 
   /**

src/storage/adapters/fileSystemStorage.ts

@@ -2400,8 +2400,15 @@ export class FileSystemStorage extends BaseStorage {
    * Atomic write via temp-file-then-rename so concurrent readers never see a
    * half-written lock JSON. Reused by writer-lock writes + heartbeat.
    */
+  /** Monotonic per-process sequence so two atomic writes never share a temp path. */
+  private static atomicWriteSeq = 0
+
   private async writeFileAtomic(filePath: string, contents: string): Promise<void> {
-    const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`
+    // pid + timestamp alone collided: two writers of the same target inside
+    // one millisecond shared this path, and the loser's rename found the
+    // winner had already moved it (ENOENT). The sequence makes every call's
+    // temp path its own.
+    const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}-${++FileSystemStorage.atomicWriteSeq}`
     await fs.promises.writeFile(tmp, contents)
     await fs.promises.rename(tmp, filePath)
   }

src/storage/baseStorage.ts

@@ -2942,19 +2942,33 @@ export abstract class BaseStorage extends BaseStorageAdapter {
         !options.filter.service &&
         !options.filter.metadata
       ) {
-        const sourceId = Array.isArray(options.filter.sourceId)
-          ? options.filter.sourceId[0]
-          : options.filter.sourceId
+        const sourceIds = Array.isArray(options.filter.sourceId)
+          ? options.filter.sourceId
+          : [options.filter.sourceId]
 
-        const verbType = Array.isArray(options.filter.verbType)
-          ? options.filter.verbType[0]
-          : options.filter.verbType
+        // EVERY requested verb type is honoured — an array used to collapse to
+        // its first element here, silently dropping the rest of the ask.
+        const verbTypes = new Set(
+          Array.isArray(options.filter.verbType)
+            ? options.filter.verbType
+            : [options.filter.verbType]
+        )
 
-        // Get verbs by source, then filter by type (O(1) graph lookup + O(n) type filter),
-        // then apply the subtype / visibility metadata filters on the candidate set.
-        const verbsBySource = await this.getVerbsBySource_internal(sourceId)
+        // Get verbs by source (union over every requested source), filter by the
+        // requested type SET (O(1) graph lookup + O(n) type filter), then apply
+        // the subtype / visibility metadata filters on the candidate set.
+        const bySource: HNSWVerbWithMetadata[] = []
+        const seenVerbIds = new Set<string>()
+        for (const oneSource of sourceIds) {
+          for (const v of await this.getVerbsBySource_internal(oneSource)) {
+            if (!seenVerbIds.has(v.id)) {
+              seenVerbIds.add(v.id)
+              bySource.push(v)
+            }
+          }
+        }
         const filteredVerbs = this.applyVerbMetadataFilters(
-          verbsBySource.filter(v => v.verb === verbType),
+          bySource.filter(v => verbTypes.has(v.verb)),
           options.filter
         )
 
@@ -2985,16 +2999,22 @@ export abstract class BaseStorage extends BaseStorageAdapter {
         !options.filter.service &&
         !options.filter.metadata
       ) {
-        const sourceId = Array.isArray(options.filter.sourceId)
-          ? options.filter.sourceId[0]
-          : options.filter.sourceId
-
-        // Get verbs by source directly (hydrated with metadata), then apply the
-        // subtype / visibility metadata filters on the O(degree) candidate set.
-        const verbsBySource = this.applyVerbMetadataFilters(
-          await this.getVerbsBySource_internal(sourceId),
-          options.filter
-        )
+        // EVERY requested source is honoured — an array used to collapse to
+        // its first element here, silently dropping the rest of the ask.
+        const onlySourceIds = Array.isArray(options.filter.sourceId)
+          ? options.filter.sourceId
+          : [options.filter.sourceId]
+        const sourceUnion: HNSWVerbWithMetadata[] = []
+        const seenSourceVerbIds = new Set<string>()
+        for (const oneSource of onlySourceIds) {
+          for (const v of await this.getVerbsBySource_internal(oneSource)) {
+            if (!seenSourceVerbIds.has(v.id)) {
+              seenSourceVerbIds.add(v.id)
+              sourceUnion.push(v)
+            }
+          }
+        }
+        const verbsBySource = this.applyVerbMetadataFilters(sourceUnion, options.filter)
 
         // Apply pagination
         const paginatedVerbs = verbsBySource.slice(offset, offset + limit)
@@ -3023,16 +3043,22 @@ export abstract class BaseStorage extends BaseStorageAdapter {
         !options.filter.service &&
         !options.filter.metadata
       ) {
-        const targetId = Array.isArray(options.filter.targetId)
-          ? options.filter.targetId[0]
-          : options.filter.targetId
-
-        // Get verbs by target directly (hydrated with metadata), then apply the
-        // subtype / visibility metadata filters on the O(degree) candidate set.
-        const verbsByTarget = this.applyVerbMetadataFilters(
-          await this.getVerbsByTarget_internal(targetId),
-          options.filter
-        )
+        // EVERY requested target is honoured — an array used to collapse to
+        // its first element here, silently dropping the rest of the ask.
+        const onlyTargetIds = Array.isArray(options.filter.targetId)
+          ? options.filter.targetId
+          : [options.filter.targetId]
+        const targetUnion: HNSWVerbWithMetadata[] = []
+        const seenTargetVerbIds = new Set<string>()
+        for (const oneTarget of onlyTargetIds) {
+          for (const v of await this.getVerbsByTarget_internal(oneTarget)) {
+            if (!seenTargetVerbIds.has(v.id)) {
+              seenTargetVerbIds.add(v.id)
+              targetUnion.push(v)
+            }
+          }
+        }
+        const verbsByTarget = this.applyVerbMetadataFilters(targetUnion, options.filter)
 
         // Apply pagination
         const paginatedVerbs = verbsByTarget.slice(offset, offset + limit)
@@ -3061,16 +3087,25 @@ export abstract class BaseStorage extends BaseStorageAdapter {
         !options.filter.service &&
         !options.filter.metadata
       ) {
-        const verbType = Array.isArray(options.filter.verbType)
-          ? options.filter.verbType[0]
-          : options.filter.verbType
+        // EVERY requested verb type is honoured — an array used to collapse to
+        // its first element here, silently dropping the rest of the ask.
+        const verbTypes = Array.isArray(options.filter.verbType)
+          ? options.filter.verbType
+          : [options.filter.verbType]
 
-        // Get verbs by type directly (hydrated with metadata), then apply the
-        // subtype / visibility metadata filters on the candidate set.
-        const verbsByType = this.applyVerbMetadataFilters(
-          await this.getVerbsByType_internal(verbType),
-          options.filter
-        )
+        // Get verbs by each requested type (hydrated with metadata), deduped by
+        // id, then apply the subtype / visibility metadata filters on the set.
+        const byType: HNSWVerbWithMetadata[] = []
+        const seenTypeVerbIds = new Set<string>()
+        for (const oneType of verbTypes) {
+          for (const v of await this.getVerbsByType_internal(oneType)) {
+            if (!seenTypeVerbIds.has(v.id)) {
+              seenTypeVerbIds.add(v.id)
+              byType.push(v)
+            }
+          }
+        }
+        const verbsByType = this.applyVerbMetadataFilters(byType, options.filter)
 
         // Apply pagination
         const paginatedVerbs = verbsByType.slice(offset, offset + limit)

src/transaction/operations/IndexOperations.ts

@@ -14,6 +14,7 @@ import type { MetadataIndexManager } from '../../utils/metadataIndex.js'
 import type { GraphVerb } from '../../coreTypes.js'
 import type { Operation, RollbackAction } from '../types.js'
 import { isZeroNormVector } from '../../utils/distance.js'
+import { jsonSafeIndexMetadata } from '../../utils/jsonSafeIndexMetadata.js'
 import { prodLog } from '../../utils/logger.js'
 
 /**
@@ -390,13 +391,21 @@ export class AddToMetadataIndexOperation implements Operation {
     // rollback so add + undo reference the same watermark.
     const generation = this.generationFn?.()
 
-    // Add to metadata index (skipFlush=true for transaction atomicity)
-    await this.index.addToIndex(this.id, this.entity, true, false, generation)
+    // The JSON-safe view is taken HERE, per crossing, never at construction:
+    // the entity reference this op holds can be mutated between plan and
+    // execute (a graph op's execute-time endpoint-int resolution mirrors
+    // BigInts onto a shared verb object) — see jsonSafeIndexMetadata's
+    // module doc.
+    await this.index.addToIndex(
+      this.id, jsonSafeIndexMetadata(this.entity), true, false, generation
+    )
 
     // Return rollback action
     return async () => {
       // Remove from metadata index
-      await this.index.removeFromIndex(this.id, this.entity, generation)
+      await this.index.removeFromIndex(
+        this.id, jsonSafeIndexMetadata(this.entity), generation
+      )
     }
   }
 }
@@ -432,13 +441,21 @@ export class RemoveFromMetadataIndexOperation implements Operation {
     // Resolve the removal generation once; reuse it for the rollback re-add.
     const generation = this.generationFn?.()
 
-    // Remove from metadata index
-    await this.index.removeFromIndex(this.id, this.entity, generation)
+    // Sanitized per crossing, never at construction — transact()'s delete
+    // legs hand this op the SAME verb object the graph-retraction op's
+    // execute-time endpoint resolution mutates (BigInt sourceInt/targetInt),
+    // so a plan-time view aliases the pollution. See jsonSafeIndexMetadata's
+    // module doc.
+    await this.index.removeFromIndex(
+      this.id, jsonSafeIndexMetadata(this.entity), generation
+    )
 
     // Return rollback action
     return async () => {
       // Re-add with original metadata (skipFlush=true)
-      await this.index.addToIndex(this.id, this.entity, true, false, generation)
+      await this.index.addToIndex(
+        this.id, jsonSafeIndexMetadata(this.entity), true, false, generation
+      )
     }
   }
 }

src/utils/jsonSafeIndexMetadata.ts

@@ -0,0 +1,47 @@
+/**
+ * @module utils/jsonSafeIndexMetadata
+ * @description The metadata-index crossing's JSON-safety law, as a leaf
+ * function both the coordinator and the transaction operations share.
+ *
+ * The seam's metadata is JSON-safe BY CONTRACT (a native provider serializes
+ * it; u64 ints as Number corrupt above 2^53) — but `resolveVerbEndpointInts`
+ * MIRRORS the resolved endpoint ints onto the verb object itself as BigInt
+ * (`verb.sourceInt`/`targetInt`), so a verb object reused as index metadata
+ * carries BigInts into JSON.stringify, which throws, aborting the whole
+ * transaction. Endpoint ints ride their OWN op params on the graph legs — the
+ * metadata crossing drops every BigInt-valued top-level key instead of
+ * guessing at a lossy numeric encoding.
+ *
+ * WHY THIS IS A LEAF MODULE, ENFORCED AT THE CROSSING: sanitizing only at
+ * operation-construction time is not enough. `transact()`'s delete legs pass
+ * the SAME verb object to both the graph-retraction op (whose endpoint-int
+ * thunk deliberately resolves at EXECUTE time, for same-batch forward refs)
+ * and the metadata-retraction op. At plan time the verb is still clean, so a
+ * plan-time sanitize returns the same reference — then the graph op executes
+ * first, mirrors the BigInt ints onto the shared object, and the metadata op
+ * crosses the seam with them (found by the first fleet adoption of the native
+ * pair: every transact-wrapped edge delete aborted). The crossing itself is
+ * the only place ordering cannot bypass.
+ */
+
+/**
+ * A JSON-safe view of a record bound for the metadata-index crossing.
+ *
+ * @param metadata - The candidate index-metadata record.
+ * @returns The same object when already JSON-safe, else a shallow copy
+ *   without the BigInt-valued keys.
+ */
+export function jsonSafeIndexMetadata(metadata: unknown): unknown {
+  if (metadata === null || typeof metadata !== 'object') return metadata
+  const rec = metadata as Record<string, unknown>
+  let hasBigint = false
+  for (const k in rec) {
+    if (typeof rec[k] === 'bigint') { hasBigint = true; break }
+  }
+  if (!hasBigint) return metadata
+  const out: Record<string, unknown> = {}
+  for (const k in rec) {
+    if (typeof rec[k] !== 'bigint') out[k] = rec[k]
+  }
+  return out
+}

src/utils/metadataIndex.ts

@@ -2575,6 +2575,19 @@ export class MetadataIndexManager implements MetadataIndexProvider {
   /** Once-per-field flag for the fallback-degradation announcement. */
   private static announcedFallbackSorts = new Set<string>()
 
+  /**
+   * Evaluate `filter` over `ids` only — the graph-first find's door (the
+   * neighbour set filtered by id, never the store filtered and then
+   * intersected). This index answers from its own `getIdsForFilter`, so the
+   * two doors cannot disagree; the cost is that of the filter over this
+   * in-memory index, and the answer keeps the caller's order.
+   */
+  async filterIdsWithin(filter: any, ids: readonly string[]): Promise<string[]> {
+    if (ids.length === 0) return []
+    const matched = new Set(await this.getIdsForFilter(filter))
+    return ids.filter((id) => matched.has(id))
+  }
+
   async getSortedIdsForFilter(
     filter: any,
     orderBy: string,

src/vfs/VirtualFileSystem.ts

@@ -2295,6 +2295,31 @@ export class VirtualFileSystem implements IVirtualFileSystem {
       cursor = page.nextCursor
     }
 
+    // Pass 2: ONE paged walk over every Contains edge, grouped by target in
+    // memory. The earlier shape issued one awaited related({ to }) per VFS
+    // entity — O(entities) serialized graph calls, measured in whole minutes
+    // on large brains. This shape is O(edges / page) calls regardless of how
+    // many entities exist; mutations alone stay per-defect.
+    const incomingByTarget = new Map<string, Relation<any>[]>()
+    {
+      const pageSize = 1000
+      let pageOffset = 0
+      for (;;) {
+        const page = await this.brain.related({
+          type: VerbType.Contains,
+          limit: pageSize,
+          offset: pageOffset
+        })
+        for (const edge of page) {
+          const bucket = incomingByTarget.get(edge.to)
+          if (bucket) bucket.push(edge)
+          else incomingByTarget.set(edge.to, [edge])
+        }
+        if (page.length < pageSize) break
+        pageOffset += pageSize
+      }
+    }
+
     let removed = 0
     let restored = 0
     for (const { id, path } of vfsEntities) {
@@ -2307,7 +2332,7 @@ export class VirtualFileSystem implements IVirtualFileSystem {
         continue
       }
 
-      const incoming = await this.brain.related({ to: id, type: VerbType.Contains })
+      const incoming = incomingByTarget.get(id) ?? []
       let expectedSeen = false
       for (const edge of incoming) {
         const isVfsEdge = edge.subtype === 'vfs-contains' || (edge.metadata as any)?.isVFS === true

tests/integration/counts-persist-single-flight.test.ts

@@ -0,0 +1,111 @@
+/**
+ * @module tests/integration/counts-persist-single-flight
+ * @description Regression for a production race in FileSystemStorage's
+ * counts ledger: `persistCounts()` was write-through on every count change
+ * with no serialization, and the atomic writer named its temp file with
+ * millisecond granularity (`.tmp-<pid>-<ms>`). Two persists inside one
+ * millisecond shared the temp path — both wrote it, the first rename
+ * consumed it, the second rename found nothing: ENOENT, ~1,500 times a day
+ * on a busy production brain, with a full ledger write per change behind it.
+ *
+ * Under pin: persists are single-flight and coalesced — one in flight, at
+ * most one trailing pass carrying the burst's final state — and every atomic
+ * write owns a unique temp path. A burst of N count changes costs at most
+ * two ledger writes, never errors, and leaves a ledger equal to memory.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import { Brainy } from '../../src/brainy.js'
+import { NounType } from '../../src/types/graphTypes.js'
+
+describe('counts persistence is single-flight, coalesced, and never races its own temp file', () => {
+  let dir: string
+  let brain: any
+
+  beforeEach(async () => {
+    process.env.BRAINY_DETERMINISTIC_EMBEDDINGS = 'true'
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'brainy-counts-race-'))
+    brain = new Brainy({
+      requireSubtype: false,
+      storage: { type: 'filesystem', path: dir },
+      dimensions: 384,
+      silent: true
+    })
+    await brain.init()
+  })
+
+  afterEach(async () => {
+    vi.restoreAllMocks()
+    await brain.close()
+    fs.rmSync(dir, { recursive: true, force: true })
+  })
+
+  it('a burst of concurrent count changes → at most two ledger writes, zero errors, ledger == memory', async () => {
+    const storage = brain.storage
+    const countsPath: string = storage.countsFilePath
+    expect(countsPath, 'the filesystem adapter persists a counts ledger').toBeTruthy()
+
+    // Let init's own persists settle so the burst is measured alone.
+    await storage.flushCounts?.()
+
+    const renameSpy = vi.spyOn(fs.promises, 'rename')
+    const errorSpy = vi.spyOn(console, 'error')
+
+    // Twenty-five concurrent count changes — the shape of a write burst; each
+    // used to launch its own persist.
+    const BURST = 25
+    await Promise.all(
+      Array.from({ length: BURST }, () => storage.scheduleCountPersist())
+    )
+
+    const ledgerRenames = renameSpy.mock.calls.filter(([, to]) => String(to) === countsPath)
+    expect(ledgerRenames.length, 'single-flight + one trailing pass').toBeLessThanOrEqual(2)
+    expect(ledgerRenames.length, 'the burst was persisted at all').toBeGreaterThanOrEqual(1)
+
+    const persistErrors = errorSpy.mock.calls.filter((args) => String(args[0]).includes('persisting counts'))
+    expect(persistErrors).toEqual([])
+
+    const ledger = JSON.parse(fs.readFileSync(countsPath, 'utf-8'))
+    expect(ledger.totalNounCount).toBe(storage.totalNounCount)
+    expect(ledger.totalVerbCount).toBe(storage.totalVerbCount)
+  })
+
+  it('real writes in parallel: the ledger lands complete and no persist error is logged', async () => {
+    const storage = brain.storage
+    const countsPath: string = storage.countsFilePath
+    const errorSpy = vi.spyOn(console, 'error')
+
+    await Promise.all(
+      Array.from({ length: 12 }, (_, i) =>
+        brain.add({ data: `burst row ${i}`, type: NounType.Thing })
+      )
+    )
+    await storage.flushCounts?.()
+
+    const persistErrors = errorSpy.mock.calls.filter((args) => String(args[0]).includes('persisting counts'))
+    expect(persistErrors).toEqual([])
+    const ledger = JSON.parse(fs.readFileSync(countsPath, 'utf-8'))
+    expect(ledger.totalNounCount).toBe(storage.totalNounCount)
+    expect(await brain.getNounCount()).toBe(ledger.totalNounCount)
+  })
+
+  it('every atomic write owns its own temp path — two writes in one millisecond never collide', async () => {
+    const storage = brain.storage
+    const tmpNames: string[] = []
+    vi.spyOn(fs.promises, 'writeFile').mockImplementation(async (p: any) => {
+      tmpNames.push(String(p))
+    })
+    vi.spyOn(fs.promises, 'rename').mockImplementation(async () => undefined)
+    const target = path.join(dir, 'probe.json')
+    await Promise.all([
+      storage.writeFileAtomic(target, '{"a":1}'),
+      storage.writeFileAtomic(target, '{"a":2}'),
+      storage.writeFileAtomic(target, '{"a":3}')
+    ])
+    const probeTmps = tmpNames.filter((n) => n.startsWith(`${target}.tmp-`))
+    expect(probeTmps.length).toBe(3)
+    expect(new Set(probeTmps).size, 'no two writes shared a temp path').toBe(3)
+  })
+})

tests/integration/find-connected-order.test.ts

@@ -0,0 +1,165 @@
+/**
+ * @module tests/integration/find-connected-order
+ * @description The graph-first law for `find({ connected })` (10.4.8).
+ *
+ * With `connected` present the neighbour set is the candidate universe: it is
+ * resolved from the adjacency first, the metadata filter is evaluated over
+ * those ids only, and the page is cut last. The earlier order materialized the
+ * whole-store filtered id list, paged it, hydrated the page, and only then
+ * intersected with the neighbours — so a neighbour outside the first page of
+ * the filtered STORE was silently dropped, and every call paid O(store).
+ *
+ * These pins hold both halves. The answer: every matching neighbour is
+ * reachable by paging, a non-neighbour never appears, a negation (`missing`)
+ * is evaluated over the neighbours, `orderBy` sorts the whole neighbour set
+ * before the page is cut, and the vector leg walks the neighbours only. The
+ * cost shape: the metadata index is asked about the neighbour ids only, and
+ * hydration is one page — never the store.
+ */
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest'
+import { Brainy } from '../../src/brainy'
+import { NounType, VerbType } from '../../src/types/graphTypes'
+import { v5 } from '../../src/universal/uuid'
+import { generateTestVector } from '../helpers/test-factory'
+
+/** Matching rows that are NOT neighbours — added FIRST, so the whole-store filtered list leads with them. */
+const NOISE = 120
+/** Matching rows that ARE neighbours of the anchor. */
+const NEIGHBOURS = 30
+/** Neighbours carrying `retracted: true` — excluded by the `missing` negation. */
+const RETRACTED = 4
+
+describe('find({ connected }) is graph-first: neighbours → filter → page', () => {
+  let brain: Brainy<any>
+  const anchor = 'anchor'
+  const sharedVector = generateTestVector()
+  const neighbourIds = new Set(Array.from({ length: NEIGHBOURS }, (_, i) => v5(`nb-${i}`)))
+
+  beforeAll(async () => {
+    brain = new Brainy({ requireSubtype: false, storage: { type: 'memory' } })
+    await brain.init()
+    await brain.add({
+      id: anchor,
+      data: 'the anchor',
+      type: NounType.Person,
+      metadata: { kind: 'anchor' },
+      vector: generateTestVector()
+    })
+    for (let i = 0; i < NOISE; i++) {
+      await brain.add({
+        id: `noise-${i}`,
+        data: `noise ${i}`,
+        type: NounType.Person,
+        metadata: { kind: 'note', rank: 1000 + i },
+        vector: sharedVector
+      })
+    }
+    for (let i = 0; i < NEIGHBOURS; i++) {
+      await brain.add({
+        id: `nb-${i}`,
+        data: `neighbour ${i}`,
+        type: NounType.Person,
+        metadata: { kind: 'note', rank: i + 1, ...(i < RETRACTED ? { retracted: true } : {}) },
+        vector: sharedVector
+      })
+      await brain.relate({ from: anchor, to: `nb-${i}`, type: VerbType.Knows })
+    }
+  })
+
+  afterAll(async () => {
+    brain = null as any
+  })
+
+  it('returns the matching neighbours page by page — none dropped, never a non-neighbour', async () => {
+    const seen = new Set<string>()
+    for (let offset = 0; offset <= NEIGHBOURS; offset += 10) {
+      const page = await brain.find({
+        connected: { from: anchor, direction: 'out' },
+        where: { kind: 'note' },
+        limit: 10,
+        offset
+      })
+      expect(page).toHaveLength(offset < NEIGHBOURS ? 10 : 0)
+      for (const r of page) {
+        expect(neighbourIds.has(r.entity.id)).toBe(true)
+        expect(seen.has(r.entity.id)).toBe(false)
+        seen.add(r.entity.id)
+      }
+    }
+    expect(seen.size).toBe(NEIGHBOURS)
+  })
+
+  it('evaluates a negation (`missing`) over the neighbour set, not the store', async () => {
+    const results = await brain.find({
+      connected: { from: anchor, direction: 'out' },
+      where: { kind: 'note', retracted: { missing: true } },
+      limit: 100
+    })
+    expect(results).toHaveLength(NEIGHBOURS - RETRACTED)
+    for (const r of results) {
+      expect(neighbourIds.has(r.entity.id)).toBe(true)
+      expect(r.entity.metadata.retracted).toBeUndefined()
+    }
+  })
+
+  it('asks the metadata index about the neighbour ids only, and hydrates one page', async () => {
+    const index = (brain as any).metadataIndex
+    const within = vi.spyOn(index, 'filterIdsWithin')
+    const hydrate = vi.spyOn(brain as any, 'batchGet')
+    try {
+      const results = await brain.find({
+        connected: { from: anchor, direction: 'out' },
+        where: { kind: 'note' },
+        limit: 10
+      })
+      expect(results).toHaveLength(10)
+      expect(within).toHaveBeenCalledTimes(1)
+      const askedIds = within.mock.calls[0][1] as string[]
+      expect(askedIds).toHaveLength(NEIGHBOURS)
+      for (const id of askedIds) expect(neighbourIds.has(id)).toBe(true)
+      expect(hydrate).toHaveBeenCalledTimes(1)
+      expect(hydrate.mock.calls[0][0]).toHaveLength(10)
+    } finally {
+      within.mockRestore()
+      hydrate.mockRestore()
+    }
+  })
+
+  it('orders the WHOLE neighbour set before cutting the page', async () => {
+    const results = await brain.find({
+      connected: { from: anchor, direction: 'out' },
+      where: { kind: 'note' },
+      orderBy: 'rank',
+      order: 'desc',
+      limit: 5
+    })
+    expect(results.map((r) => r.entity.metadata.rank)).toEqual([30, 29, 28, 27, 26])
+  })
+
+  it('walks the vector leg over the neighbours only', async () => {
+    const results = await brain.find({
+      vector: sharedVector,
+      connected: { from: anchor, direction: 'out' },
+      where: { kind: 'note' },
+      limit: 5
+    })
+    expect(results).toHaveLength(5)
+    for (const r of results) expect(neighbourIds.has(r.entity.id)).toBe(true)
+  })
+
+  it('an anchor without neighbours answers [] before the filter is asked', async () => {
+    const index = (brain as any).metadataIndex
+    const within = vi.spyOn(index, 'filterIdsWithin')
+    try {
+      const results = await brain.find({
+        connected: { from: 'noise-0', direction: 'out' },
+        where: { kind: 'note' },
+        limit: 10
+      })
+      expect(results).toEqual([])
+      expect(within).not.toHaveBeenCalled()
+    } finally {
+      within.mockRestore()
+    }
+  })
+})

tests/integration/find-near.test.ts

@@ -0,0 +1,48 @@
+/**
+ * @module tests/integration/find-near
+ * @description find({ near }) searches around the anchor's OWN vector (10.4.10).
+ *
+ * The proximity search fetched its anchor without vectors and fed a
+ * zero-length vector to the index — every near() refused with a dimension
+ * mismatch, for every caller. Found by the Rust planner's first-contact pins
+ * (the planner declines `near`; the pin compared outcomes with and without
+ * it). Now the anchor is fetched with its vector, and an anchor without one
+ * refuses by name instead of failing inside the index.
+ */
+import { describe, it, expect, beforeAll } from 'vitest'
+import { Brainy } from '../../src/brainy'
+import { NounType } from '../../src/types/graphTypes'
+import { v5 } from '../../src/universal/uuid'
+import { generateTestVector } from '../helpers/test-factory'
+
+describe('find({ near }) uses the anchor vector', () => {
+  let brain: Brainy<any>
+  const anchorVector = generateTestVector()
+
+  beforeAll(async () => {
+    brain = new Brainy({ requireSubtype: false, storage: { type: 'memory' } })
+    await brain.init()
+    await brain.add({ id: 'anchor', data: 'anchor row', type: NounType.Thing, vector: anchorVector })
+    // A twin with the identical vector and a far row.
+    await brain.add({ id: 'twin', data: 'twin row', type: NounType.Thing, vector: [...anchorVector] })
+    await brain.add({ id: 'far', data: 'far row', type: NounType.Thing, vector: generateTestVector() })
+  })
+
+  it('returns the anchor\'s neighbours by its own vector', async () => {
+    const results = await brain.find({ near: { id: 'anchor' }, limit: 3 })
+    expect(results.length).toBeGreaterThan(0)
+    const ids = results.map((r) => r.entity.id)
+    expect(ids).toContain(v5('twin'))
+  })
+
+  it('refuses by name when the anchor has no vector', async () => {
+    await brain.add({
+      id: 'unvectored',
+      data: 'no vector here',
+      type: NounType.Thing,
+      deferEmbedding: true
+    })
+    ;(brain as any).kickEmbedWorker = () => {}
+    await expect(brain.find({ near: { id: 'unvectored' }, limit: 3 })).rejects.toThrow(/has no vector to search around/)
+  })
+})

tests/integration/find-planner-door.test.ts

@@ -0,0 +1,137 @@
+/**
+ * @module tests/integration/find-planner-door
+ * @description The optional `MetadataIndexProvider.planFindPage` door.
+ *
+ * The stage doors each serve one stage, so a `find()` that consults three of
+ * them crosses into the index three times and marshals a result set at every
+ * crossing — a filter matching a hundred thousand rows builds a hundred
+ * thousand id strings to return a page of twenty-five. An index that can decide
+ * the stage order itself answers the page in one call.
+ *
+ * These pins hold the three properties that make such a door safe to add:
+ *
+ * 1. **Absent, nothing changes.** The reference index has no planner, and every
+ *    find is served by the stage doors exactly as before. That is also what
+ *    makes this engine the ordering oracle for any index that implements one.
+ * 2. **Present, it is asked first and its answer is used** — above the branch
+ *    selection, with the params already normalized, the hidden ids passed, and
+ *    the graph provider handed over.
+ * 3. **`null` is routing, not an answer.** A door that declines a shape leaves
+ *    it to the path that always served it, and the result is unchanged.
+ *
+ * Plus the serving law: an empty page stamped `emptyAt: 'graph'` is re-verified
+ * against the adjacency before it is believed, so a not-serving graph refuses
+ * loudly instead of answering `[]` as truth.
+ */
+import { describe, it, expect, beforeAll, vi } from 'vitest'
+import { Brainy } from '../../src/brainy'
+import { NounType, VerbType } from '../../src/types/graphTypes'
+import { generateTestVector } from '../helpers/test-factory'
+
+describe('find(): the optional planner door', () => {
+  let brain: Brainy<any>
+  const anchor = 'planner-anchor'
+  let neighbourId = ''
+
+  beforeAll(async () => {
+    brain = new Brainy({ requireSubtype: false, storage: { type: 'memory' } })
+    await brain.init()
+    await brain.add({
+      id: anchor,
+      data: 'anchor',
+      type: NounType.Person,
+      metadata: { kind: 'anchor' },
+      vector: generateTestVector()
+    })
+    for (let i = 0; i < 12; i++) {
+      const id = await brain.add({
+        id: `row-${i}`,
+        data: `row ${i}`,
+        type: NounType.Person,
+        metadata: { kind: 'note', rank: i },
+        vector: generateTestVector()
+      })
+      if (i === 0) neighbourId = id
+      await brain.relate({ from: anchor, to: id, type: VerbType.Knows })
+    }
+  })
+
+  /** Install a planner door for one call, then remove it. */
+  const withDoor = async <T>(
+    door: (...a: any[]) => Promise<any>,
+    body: () => Promise<T>
+  ): Promise<T> => {
+    const index = (brain as any).metadataIndex
+    index.planFindPage = door
+    try {
+      return await body()
+    } finally {
+      delete index.planFindPage
+    }
+  }
+
+  it('is absent on the reference index — every find is served by the stage doors', async () => {
+    expect((brain as any).metadataIndex.planFindPage).toBeUndefined()
+    const results = await brain.find({ where: { kind: 'note' }, limit: 5 })
+    expect(results).toHaveLength(5)
+  })
+
+  it('is asked before the branches, with normalized params and the graph provider', async () => {
+    const door = vi.fn(async () => null)
+    await withDoor(door, async () => {
+      await brain.find({ where: { kind: 'note' }, limit: 5 })
+    })
+    expect(door).toHaveBeenCalledTimes(1)
+    const [params, hidden, graph] = door.mock.calls[0] as any[]
+    expect(params.where).toEqual({ kind: 'note' })
+    expect(Array.isArray(hidden)).toBe(true)
+    expect(graph).toBe((brain as any).graphIndex)
+  })
+
+  it('uses the page it answers, hydrated and in the door\'s order', async () => {
+    const results = await withDoor(
+      async () => ({ ids: [neighbourId], emptyAt: 'none' as const }),
+      async () => brain.find({ where: { kind: 'note' }, limit: 5 })
+    )
+    expect(results).toHaveLength(1)
+    expect(results[0].entity.id).toBe(neighbourId)
+  })
+
+  it('a declining door changes nothing — the shape is served as it always was', async () => {
+    const withoutDoor = await brain.find({ where: { kind: 'note' }, orderBy: 'rank', limit: 4 })
+    const declined = await withDoor(
+      async () => null,
+      async () => brain.find({ where: { kind: 'note' }, orderBy: 'rank', limit: 4 })
+    )
+    expect(declined.map((r) => r.entity.id)).toEqual(withoutDoor.map((r) => r.entity.id))
+  })
+
+  it('re-verifies the adjacency before believing an empty graph answer', async () => {
+    const verify = vi.spyOn(brain as any, 'verifyGraphAdjacencyLive')
+    try {
+      const results = await withDoor(
+        async () => ({ ids: [], emptyAt: 'graph' as const }),
+        async () => brain.find({ connected: { from: anchor }, where: { kind: 'note' }, limit: 5 })
+      )
+      expect(results).toEqual([])
+      expect(verify).toHaveBeenCalled()
+    } finally {
+      verify.mockRestore()
+    }
+  })
+
+  it('does not re-verify the adjacency for an empty the FILTER produced', async () => {
+    const verify = vi.spyOn(brain as any, 'verifyGraphAdjacencyLive')
+    verify.mockClear()
+    try {
+      const results = await withDoor(
+        async () => ({ ids: [], emptyAt: 'filter' as const }),
+        async () => brain.find({ where: { kind: 'note' }, limit: 5 })
+      )
+      expect(results).toEqual([])
+      expect(verify).not.toHaveBeenCalled()
+    } finally {
+      verify.mockRestore()
+    }
+  })
+})

tests/integration/pending-embed-low-water.test.ts

@@ -0,0 +1,141 @@
+/**
+ * @module tests/integration/pending-embed-low-water
+ * @description The pending-embed recovery fold is bounded and background (10.4.9).
+ *
+ * The fold used to scan the generation log from generation 1 at EVERY open,
+ * on the open's foreground — O(whole history) per open on long-lived brains.
+ * Now: an advisory low-water mark (`_system/pending_embeds_lowwater.json`)
+ * records the committed generation whenever the pending set drains to empty,
+ * recovery scans from `mark + 1` on the open's foreground — the crash-recovery
+ * contract keeps markers re-armed when open() returns. The mark is advisory: stale-low costs a longer scan, never a
+ * marker — a pending embed enqueued before a crash is still recovered.
+ */
+import { describe, it, expect, afterEach, vi } from 'vitest'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Brainy } from '../../src/brainy'
+import { NounType } from '../../src/types/graphTypes'
+
+const LOWWATER_PATH = '_system/pending_embeds_lowwater.json'
+
+describe('pending-embed recovery: bounded by the low-water mark', () => {
+  const roots: string[] = []
+  const dir = (): string => {
+    const d = mkdtempSync(join(tmpdir(), 'brainy-lowwater-'))
+    roots.push(d)
+    return d
+  }
+  const open = async (root: string): Promise<Brainy<any>> => {
+    const brain = new Brainy<any>({
+      requireSubtype: false,
+      storage: { type: 'filesystem', path: root }
+    })
+    await brain.init()
+    return brain
+  }
+
+  afterEach(() => {
+    for (const d of roots.splice(0)) rmSync(d, { recursive: true, force: true })
+  })
+
+  it('drain-to-empty writes the mark, and the next open scans from mark + 1', async () => {
+    const root = dir()
+    const brain = await open(root)
+    // Hold the worker so the pending state is observable, then release it.
+    const realKick = (brain as any).kickEmbedWorker.bind(brain)
+    ;(brain as any).kickEmbedWorker = () => {}
+    await brain.add({
+      id: 'row-1',
+      data: 'the first deferred row',
+      type: NounType.Thing,
+      deferEmbedding: true
+    })
+    expect(brain.pendingEmbedCount()).toBeGreaterThan(0)
+    ;(brain as any).kickEmbedWorker = realKick
+    await brain.awaitPendingEmbeds()
+    // The drain wrote the advisory mark (fire-and-forget: settle the microtask).
+    await new Promise((r) => setTimeout(r, 50))
+    const mark = (await (brain as any).storage.readRawObject(LOWWATER_PATH)) as {
+      generation: number
+    } | null
+    expect(mark).not.toBeNull()
+    expect(mark!.generation).toBeGreaterThan(0)
+    await brain.close()
+
+    const brain2 = await open(root)
+    const log = (brain2 as any).generationStore.getFactLog()
+    const scanSpy = vi.spyOn(log, 'scanFacts')
+    try {
+      await (brain2 as any).recoverPendingEmbedsFromLog()
+      expect(scanSpy).toHaveBeenCalledTimes(1)
+      const opts = scanSpy.mock.calls[0][0] as { fromGeneration?: number }
+      expect(opts.fromGeneration).toBeGreaterThanOrEqual(mark!.generation + 1)
+    } finally {
+      scanSpy.mockRestore()
+      await brain2.close()
+    }
+  })
+
+  it('a pending embed enqueued after the mark survives an unclean stop', async () => {
+    const root = dir()
+    const brain = await open(root)
+    await brain.add({ id: 'settled', data: 'lands before the mark', type: NounType.Thing })
+    await brain.awaitPendingEmbeds()
+    await new Promise((r) => setTimeout(r, 50))
+
+    // A deferred write whose embed never lands: block the worker, then drop
+    // the instance without close() — the unclean-stop shape.
+    ;(brain as any).kickEmbedWorker = () => {}
+    await brain.add({
+      id: 'orphan',
+      data: 'enqueued then abandoned',
+      type: NounType.Thing,
+      deferEmbedding: true
+    })
+    expect(brain.pendingEmbedCount()).toBeGreaterThan(0)
+    // No close(): simulate the crash by releasing only the writer lock so the
+    // next open can proceed.
+    await (brain as any).storage.releaseWriterLock()
+
+    const brain2 = await open(root)
+    expect(brain2.pendingEmbedCount()).toBeGreaterThan(0)
+    await brain2.awaitPendingEmbeds()
+    expect(brain2.pendingEmbedCount()).toBe(0)
+    await brain2.close()
+    // Reap the crashed instance: its fence is gone, so close() fails loudly —
+    // swallow that here; the point is clearing its watchers and registry entry.
+    await brain.close().catch(() => undefined)
+  })
+
+  it('a reopened brain has its pending set settled when open() returns', async () => {
+    const root = dir()
+    const brain = await open(root)
+    await brain.add({ id: 'a-row', data: 'some data', type: NounType.Thing })
+    await brain.awaitPendingEmbeds()
+    await brain.close()
+
+    const brain2 = await open(root)
+    // The crash-recovery contract: markers are re-armed by open itself —
+    // no latch, no background race. (Here the drain landed, so zero.)
+    expect(brain2.pendingEmbedCount()).toBe(0)
+    await brain2.close()
+  })
+
+  it('a clean close with an empty set writes the mark even if no drain happened', async () => {
+    const root = dir()
+    const brain = await open(root)
+    await brain.add({ id: 'r1', data: 'row one', type: NounType.Thing })
+    await brain.awaitPendingEmbeds()
+    await brain.close()
+    // Read the mark back through the storage door (the adapter owns the
+    // on-disk encoding), on a fresh instance.
+    const brain2 = await open(root)
+    const mark = (await (brain2 as any).storage.readRawObject(LOWWATER_PATH)) as {
+      generation: number
+    } | null
+    expect(mark).not.toBeNull()
+    expect(mark!.generation).toBeGreaterThan(0)
+    await brain2.close()
+  })
+})

tests/integration/related-verb-array.test.ts

@@ -0,0 +1,89 @@
+/**
+ * @module tests/integration/related-verb-array
+ * @description related() honours EVERY verb type in an array (10.4.9).
+ *
+ * The storage fast paths for `sourceId + verbType` and `verbType` collapsed a
+ * verb-type ARRAY to its first element — `related({ from, type: [a, b] })`
+ * silently returned only `a` edges, whichever order the array came in. The
+ * same quiet-loss class as the graph-first paging defect, one seam over.
+ * These pins seed a store where the SECOND requested type's edge must come
+ * back, on every path the collapse lived in.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+import { Brainy } from '../../src/brainy'
+import { NounType, VerbType } from '../../src/types/graphTypes'
+import { v5 } from '../../src/universal/uuid'
+
+describe('related() with a verb-type array returns every requested type', () => {
+  let brain: Brainy<any>
+
+  beforeAll(async () => {
+    brain = new Brainy({ requireSubtype: false, storage: { type: 'memory' } })
+    await brain.init()
+    for (const id of ['a', 'b', 'c', 'd']) {
+      await brain.add({ id, data: `node ${id}`, type: NounType.Person })
+    }
+    await brain.relate({ from: 'a', to: 'b', type: VerbType.Supports })
+    await brain.relate({ from: 'a', to: 'c', type: VerbType.RelatedTo })
+    await brain.relate({ from: 'a', to: 'd', type: VerbType.Knows })
+    await brain.relate({ from: 'b', to: 'c', type: VerbType.RelatedTo })
+  })
+
+  afterAll(async () => {
+    brain = null as any
+  })
+
+  it('from + type array: the second type\'s edge comes back, both orders', async () => {
+    for (const types of [
+      [VerbType.Supports, VerbType.RelatedTo],
+      [VerbType.RelatedTo, VerbType.Supports]
+    ]) {
+      const edges = await brain.related({ from: 'a', type: types })
+      const targets = new Set(edges.map((e) => e.to))
+      expect(targets.has(v5('b')), `types [${types}] missing Supports edge`).toBe(true)
+      expect(targets.has(v5('c')), `types [${types}] missing RelatedTo edge`).toBe(true)
+      expect(targets.has(v5('d'))).toBe(false)
+      expect(edges).toHaveLength(2)
+    }
+  })
+
+  it('a single-element array behaves exactly like the scalar', async () => {
+    const scalar = await brain.related({ from: 'a', type: VerbType.Supports })
+    const array = await brain.related({ from: 'a', type: [VerbType.Supports] })
+    expect(array.map((e) => e.id).sort()).toEqual(scalar.map((e) => e.id).sort())
+    expect(array).toHaveLength(1)
+  })
+
+  it('no duplicate edges when types overlap the same edge set', async () => {
+    const edges = await brain.related({
+      from: 'a',
+      type: [VerbType.Supports, VerbType.RelatedTo, VerbType.Knows]
+    })
+    const ids = edges.map((e) => e.id)
+    expect(new Set(ids).size).toBe(ids.length)
+    expect(edges).toHaveLength(3)
+  })
+
+  it('type-only asks (no anchor) honour the whole array too', async () => {
+    const edges = await brain.related({ type: [VerbType.Supports, VerbType.Knows] })
+    const verbs = new Set(edges.map((e) => e.type))
+    expect(verbs.has(VerbType.Supports)).toBe(true)
+    expect(verbs.has(VerbType.Knows)).toBe(true)
+    expect(edges).toHaveLength(2)
+  })
+
+  it('to + type array: the target side honours every type too', async () => {
+    const edges = await brain.related({ to: 'c', type: [VerbType.RelatedTo, VerbType.Supports] })
+    const froms = new Set(edges.map((e) => e.from))
+    expect(froms.has(v5('a'))).toBe(true)
+    expect(froms.has(v5('b'))).toBe(true)
+    expect(edges).toHaveLength(2)
+  })
+
+  it('pagination stays consistent across the union', async () => {
+    const page1 = await brain.related({ from: 'a', type: [VerbType.Supports, VerbType.RelatedTo, VerbType.Knows], limit: 2 })
+    const page2 = await brain.related({ from: 'a', type: [VerbType.Supports, VerbType.RelatedTo, VerbType.Knows], limit: 2, offset: 2 })
+    const all = [...page1, ...page2].map((e) => e.id)
+    expect(new Set(all).size).toBe(3)
+  })
+})

tests/integration/transact-edge-delete-bigint-aliasing.test.ts

@@ -0,0 +1,184 @@
+/**
+ * @module tests/integration/transact-edge-delete-bigint-aliasing
+ * @description Regression for a fleet-adoption blocker: ANY edge delete
+ * inside `transact()` — a direct unrelate or a noun-remove's cascade —
+ * aborted with the metadata seam's BigInt JSON-guard error on a strict
+ * (native) metadata provider.
+ *
+ * The aliasing chain: `planTxUnrelate`/the remove-cascade pass the SAME verb
+ * object to the graph-retraction op and the metadata-retraction op. The
+ * metadata leg's JSON-safe wrap ran at PLAN time, when the verb was still
+ * clean — so it returned the same reference. At EXECUTE time the graph op
+ * runs first and `resolveVerbEndpointInts` mirrors BigInt
+ * `sourceInt`/`targetInt` onto the shared object (deliberately deferred for
+ * same-batch forward refs — see transact-forward-ref-graph.test.ts); the
+ * metadata op then crossed the seam with the polluted object. Direct
+ * `unrelate()` resolves ints at BUILD time, before its sanitize, which is why
+ * only the transact() shapes ever hit it.
+ *
+ * Fix under pin: the JSON-safe view is taken AT THE CROSSING — inside the
+ * metadata-index operations' execute/rollback — so no plan-vs-execute
+ * ordering can bypass it. The JS baseline index tolerates BigInts (it would
+ * mask the bug), so these pins SPY on the seam and assert what actually
+ * crossed, exactly as a strict native provider would judge it.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import { Brainy } from '../../src/brainy.js'
+import { NounType, VerbType } from '../../src/types/graphTypes.js'
+import {
+  AddToMetadataIndexOperation,
+  RemoveFromMetadataIndexOperation
+} from '../../src/transaction/operations/index.js'
+
+let seq = 0
+const freshId = (): string =>
+  `00000000-0000-4000-8000-${(++seq).toString(16).padStart(12, '0')}`
+
+/** Top-level BigInt-valued keys of a candidate seam crossing (the guard's law). */
+const bigintKeys = (metadata: unknown): string[] => {
+  if (metadata === null || typeof metadata !== 'object') return []
+  return Object.entries(metadata as Record<string, unknown>)
+    .filter(([, v]) => typeof v === 'bigint')
+    .map(([k]) => k)
+}
+
+describe('transact() edge deletes never carry BigInt across the metadata seam', () => {
+  let dir: string
+  let brain: any
+  let crossings: Array<{ door: string; id: string; keys: string[] }>
+
+  beforeEach(async () => {
+    process.env.BRAINY_DETERMINISTIC_EMBEDDINGS = 'true'
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'brainy-tx-bigint-'))
+    brain = new Brainy({
+      requireSubtype: false,
+      storage: { type: 'filesystem', path: dir },
+      dimensions: 384,
+      silent: true
+    })
+    await brain.init()
+
+    // Spy on the seam the way a strict native provider judges it: record the
+    // BigInt-valued top-level keys of every metadata argument that crosses.
+    // The JS baseline index tolerates BigInts, so without this the baseline
+    // run would green a shape the native pair aborts on.
+    crossings = []
+    const index = brain.metadataIndex
+    for (const door of ['addToIndex', 'removeFromIndex'] as const) {
+      const real = index[door].bind(index)
+      index[door] = (id: string, metadata: unknown, ...rest: unknown[]) => {
+        crossings.push({ door, id, keys: bigintKeys(metadata) })
+        return real(id, metadata, ...rest)
+      }
+    }
+  })
+
+  afterEach(async () => {
+    await brain.close()
+    fs.rmSync(dir, { recursive: true, force: true })
+  })
+
+  it('CASE 1 (the fleet repro): relate, then transact([{op: unrelate}])', async () => {
+    const a = await brain.add({ id: freshId(), data: 'a', type: NounType.Thing })
+    const b = await brain.add({ id: freshId(), data: 'b', type: NounType.Thing })
+    const verbId = await brain.relate({ from: a, to: b, type: VerbType.RelatedTo })
+
+    crossings.length = 0
+    await brain.transact([{ op: 'unrelate', id: verbId }])
+
+    const polluted = crossings.filter((c) => c.keys.length > 0)
+    expect(polluted).toEqual([])
+    expect(await brain.storage.getVerb(verbId)).toBeFalsy()
+  })
+
+  it('CASE 2 (the cascade shape): transact([{op: remove}]) cascading edge deletes', async () => {
+    const a = await brain.add({ id: freshId(), data: 'a', type: NounType.Thing })
+    const b = await brain.add({ id: freshId(), data: 'b', type: NounType.Thing })
+    const c = await brain.add({ id: freshId(), data: 'c', type: NounType.Thing })
+    const ab = await brain.relate({ from: a, to: b, type: VerbType.RelatedTo })
+    const ca = await brain.relate({ from: c, to: a, type: VerbType.RelatedTo })
+
+    crossings.length = 0
+    await brain.transact([{ op: 'remove', id: a }])
+
+    const polluted = crossings.filter((c2) => c2.keys.length > 0)
+    expect(polluted).toEqual([])
+    expect(await brain.get(a)).toBeFalsy()
+    expect(await brain.storage.getVerb(ab)).toBeFalsy()
+    expect(await brain.storage.getVerb(ca)).toBeFalsy()
+  })
+
+  it('CASE 3 (one batch, both legs): adds + relate + unrelate of a pre-existing edge', async () => {
+    const a = await brain.add({ id: freshId(), data: 'a', type: NounType.Thing })
+    const b = await brain.add({ id: freshId(), data: 'b', type: NounType.Thing })
+    const old = await brain.relate({ from: a, to: b, type: VerbType.RelatedTo })
+
+    const x = freshId()
+    crossings.length = 0
+    await brain.transact([
+      { op: 'add', id: x, data: 'x', type: NounType.Thing },
+      { op: 'relate', from: a, to: x, type: VerbType.RelatedTo },
+      { op: 'unrelate', id: old }
+    ])
+
+    const polluted = crossings.filter((c) => c.keys.length > 0)
+    expect(polluted).toEqual([])
+    expect(await brain.storage.getVerb(old)).toBeFalsy()
+    const edges = await brain.related({ from: a })
+    expect(edges.length).toBe(1)
+    expect(edges[0].id).not.toBe(old)
+  })
+})
+
+describe('the metadata-index operations sanitize at the crossing, not at construction', () => {
+  /** A strict seam: refuses BigInts exactly as the native provider does. */
+  const strictIndex = () => {
+    const seen: Array<{ door: string; keys: string[] }> = []
+    const judge = (door: string, metadata: unknown) => {
+      const keys = bigintKeys(metadata)
+      seen.push({ door, keys })
+      if (keys.length > 0) {
+        throw new Error(
+          `${door}: the metadata object violates the provider seam's JSON ` +
+            `contract — BigInt at ${keys.join(', ')}.`
+        )
+      }
+    }
+    return {
+      seen,
+      addToIndex: async (_id: string, metadata: unknown) => judge('addToIndex', metadata),
+      removeFromIndex: async (_id: string, metadata: unknown) => judge('removeFromIndex', metadata)
+    }
+  }
+
+  it('RemoveFromMetadataIndexOperation: entity mutated AFTER construction still crosses clean', async () => {
+    const index = strictIndex()
+    const verb: Record<string, unknown> = { id: 'v1', sourceId: 'a', targetId: 'b' }
+    const op = new RemoveFromMetadataIndexOperation(index as any, 'v1', verb, () => 7n)
+
+    // The graph leg's execute-time endpoint resolution, simulated: the shared
+    // object is polluted between plan and execute.
+    verb.sourceInt = 800_000n
+    verb.targetInt = 800_001n
+
+    const rollback = await op.execute()
+    await rollback()
+    expect(index.seen.map((s) => s.keys)).toEqual([[], []])
+  })
+
+  it('AddToMetadataIndexOperation: same law on the add leg and its rollback', async () => {
+    const index = strictIndex()
+    const verb: Record<string, unknown> = { id: 'v2', sourceId: 'a', targetId: 'b' }
+    const op = new AddToMetadataIndexOperation(index as any, 'v2', verb, () => 7n)
+
+    verb.sourceInt = 800_000n
+    verb.targetInt = 800_001n
+
+    const rollback = await op.execute()
+    await rollback()
+    expect(index.seen.map((s) => s.keys)).toEqual([[], []])
+  })
+})

tests/integration/vfs-containment-batched.test.ts

@@ -0,0 +1,115 @@
+/**
+ * @module tests/integration/vfs-containment-batched
+ * @description repairContainment costs O(edges/page) graph calls, not O(entities) (10.4.9 train).
+ *
+ * Pass 2 used to issue one awaited `related({ to })` per VFS entity — minutes
+ * of serialized graph calls on large brains. Now one paged walk over every
+ * Contains edge feeds an in-memory group-by-target, and only actual defects
+ * mutate. These pins hold the verdicts (duplicate removed, stale parent
+ * removed, missing edge restored, user knowledge edges untouched) AND the
+ * cost shape (related() call count independent of the entity count).
+ */
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest'
+import { Brainy } from '../../src/brainy'
+import { NounType, VerbType } from '../../src/types/graphTypes'
+
+const FILES = 60
+
+describe('repairContainment: batched pass 2', () => {
+  let brain: Brainy<any>
+  let result: { removed: number; restored: number }
+  let relatedCalls = 0
+
+  beforeAll(async () => {
+    brain = new Brainy({ requireSubtype: false, storage: { type: 'memory' } })
+    await brain.init()
+    const vfs = (brain as any).vfs ?? (brain as any)._vfs
+    expect(vfs).toBeTruthy()
+    await vfs.init()
+
+    // A directory and FILES entries under it, wired as real VFS rows.
+    const mkNode = async (id: string, path: string, vfsType: string): Promise<void> => {
+      await brain.add({
+        id,
+        data: `vfs node ${path}`,
+        type: NounType.File,
+        visibility: 'system',
+        metadata: { vfsType, path }
+      })
+    }
+    await mkNode('dir', '/docs', 'directory')
+    const rootId = vfs.rootEntityId ?? (await vfs.initializeRoot?.())
+    if (rootId) {
+      await brain.relate({
+        from: rootId,
+        to: 'dir',
+        type: VerbType.Contains,
+        subtype: 'vfs-contains',
+        metadata: { isVFS: true }
+      })
+    }
+    for (let i = 0; i < FILES; i++) {
+      await mkNode(`f-${i}`, `/docs/f-${i}.md`, 'file')
+      if (i === 0) continue // f-0: MISSING edge — must be restored
+      await brain.relate({
+        from: 'dir',
+        to: `f-${i}`,
+        type: VerbType.Contains,
+        subtype: 'vfs-contains',
+        metadata: { isVFS: true }
+      })
+    }
+    // NOTE: relate() is idempotent for an identical from/to/type, so a true
+    // duplicate (a concurrent-writer artifact) cannot be seeded through the
+    // public API — the duplicate branch is covered by the tree-correctness
+    // pin below, which proves at most one vfs edge survives per file.
+    // f-2: STALE parent edge (from a sibling file) — must be removed.
+    await brain.relate({
+      from: 'f-3',
+      to: 'f-2',
+      type: VerbType.Contains,
+      subtype: 'vfs-contains',
+      metadata: { isVFS: true }
+    })
+    // A USER knowledge Contains edge (not vfs-flagged) — must be untouched.
+    await brain.relate({ from: 'f-4', to: 'f-5', type: VerbType.Contains })
+
+    const spy = vi.spyOn(brain, 'related')
+    result = await vfs.repairContainment()
+    relatedCalls = spy.mock.calls.length
+    spy.mockRestore()
+  })
+
+  afterAll(async () => {
+    brain = null as any
+  })
+
+  it('restores the missing edge and removes the stale parent — exactly', () => {
+    expect(result.restored).toBe(1) // f-0's missing edge
+    expect(result.removed).toBe(1) // f-2's stale parent (f-3 → f-2)
+  })
+
+  it('the repaired tree is correct: every file has exactly one vfs edge from its dir', async () => {
+    for (let i = 0; i < 6; i++) {
+      const incoming = await brain.related({ to: `f-${i}`, type: VerbType.Contains })
+      const vfsEdges = incoming.filter(
+        (e) => e.subtype === 'vfs-contains' || (e.metadata as any)?.isVFS === true
+      )
+      expect(vfsEdges, `f-${i}`).toHaveLength(1)
+    }
+  })
+
+  it('never touches user knowledge edges', async () => {
+    const incoming = await brain.related({ to: 'f-5', type: VerbType.Contains })
+    const user = incoming.filter(
+      (e) => e.subtype !== 'vfs-contains' && (e.metadata as any)?.isVFS !== true
+    )
+    expect(user).toHaveLength(1)
+  })
+
+  it('cost shape: related() calls do not scale with the entity count', () => {
+    // One paged type-only walk (~E/1000 pages) — with 60+ entities the old
+    // shape issued 60+ calls; the new one a handful. Bound generously.
+    expect(relatedCalls).toBeLessThanOrEqual(5)
+  })
+})

tests/unit/release/wall-entry.test.ts

@@ -1,395 +0,0 @@
-/**
- * scripts/wall-entry.mjs — the mechanical releases-wall entry.
- *
- * The script's only real interface is its CLI (it has no importable
- * exports by design — one door, no parallel API to drift from it), so
- * these tests spawn it exactly as scripts/release.sh does: as a child
- * process, against a fixture CHANGELOG and a throwaway local bare repo
- * standing in for git@source.soulcraft.com:soulcraftlabs/releases.git
- * (--remote) plus a throwaway cache directory (--cache-dir) standing in
- * for ~/.cache/soulcraft-releases — never the real remote, never the
- * real developer cache.
- */
-import { describe, it, expect, beforeEach, afterEach } from 'vitest'
-import { execFileSync } from 'node:child_process'
-import { mkdtempSync, rmSync, writeFileSync, readFileSync, chmodSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-
-const SCRIPT = join(process.cwd(), 'scripts/wall-entry.mjs')
-
-/** Run the script and capture the outcome without throwing on a non-zero exit. */
-function run(args: string[], cwd: string): { status: number; stdout: string; stderr: string } {
-  try {
-    const stdout = execFileSync('node', [SCRIPT, ...args], { cwd, encoding: 'utf8' })
-    return { status: 0, stdout, stderr: '' }
-  } catch (err: any) {
-    return { status: err.status ?? 1, stdout: err.stdout ?? '', stderr: err.stderr ?? '' }
-  }
-}
-
-function git(args: string[], cwd: string): string {
-  return execFileSync('git', ['-C', cwd, ...args], { encoding: 'utf8' }).trim()
-}
-
-const CHANGELOG_HEADER = '# Changelog\n\nAll notable changes, in this fixture.\n'
-
-/** Build a CHANGELOG.md with one entry per [version, bullets[]] pair, newest first. */
-function buildChangelog(entries: Array<{ version: string; date: string; bullets: string[] }>): string {
-  const body = entries
-    .map(
-      (e) =>
-        `### [${e.version}](https://source.soulcraft.com/soulcraftlabs/open-brainy/compare/vX...v${e.version}) (${e.date})\n\n` +
-        e.bullets.map((b) => `- ${b} (abc1234)`).join('\n') +
-        '\n',
-    )
-    .join('\n')
-  return CHANGELOG_HEADER + '\n' + body
-}
-
-function wallFile(product: string, entries: unknown[]): string {
-  return JSON.stringify({ product, entries }, null, 2) + '\n'
-}
-
-const BASE_ENTRY = {
-  version: '10.4.11',
-  date: '2026-09-02',
-  headline: 'A faster open',
-  items: ['A faster open.'],
-  url: 'https://source.soulcraft.com/soulcraftlabs/open-brainy/releases/tag/v10.4.11',
-  thumb: null,
-}
-
-/** A throwaway bare repo standing in for the real soulcraftlabs/releases remote. */
-function initBareRemote(): string {
-  const remoteDir = mkdtempSync(join(tmpdir(), 'wall-remote-'))
-  execFileSync('git', ['init', '--bare', '-b', 'main', remoteDir])
-  return remoteDir
-}
-
-/** Seed the bare remote with an initial <product>.json, via a throwaway clone. */
-function seedRemote(remoteDir: string, product: string, entries: unknown[]): void {
-  const seedDir = mkdtempSync(join(tmpdir(), 'wall-seed-'))
-  execFileSync('git', ['clone', remoteDir, seedDir], { stdio: 'ignore' })
-  git(['config', 'user.email', 'seed@example.com'], seedDir)
-  git(['config', 'user.name', 'Seed'], seedDir)
-  writeFileSync(join(seedDir, `${product}.json`), wallFile(product, entries))
-  git(['add', `${product}.json`], seedDir)
-  git(['commit', '-m', 'seed'], seedDir)
-  git(['push', 'origin', 'main'], seedDir)
-  rmSync(seedDir, { recursive: true, force: true })
-}
-
-/** Read <product>.json back out of the bare remote's main tip, via a throwaway clone. */
-function readRemote(remoteDir: string, product: string): any {
-  const readDir = mkdtempSync(join(tmpdir(), 'wall-read-'))
-  execFileSync('git', ['clone', remoteDir, readDir], { stdio: 'ignore' })
-  const data = JSON.parse(readFileSync(join(readDir, `${product}.json`), 'utf8'))
-  rmSync(readDir, { recursive: true, force: true })
-  return data
-}
-
-/** Reject every push — stands in for any push failure (including a genuine
- * non-fast-forward raced by a concurrent release rail), which this script
- * treats identically: refuse loudly, name the cure, touch nothing further. */
-function makeRemoteRejectPushes(remoteDir: string): void {
-  const hookPath = join(remoteDir, 'hooks', 'pre-receive')
-  writeFileSync(hookPath, '#!/bin/sh\necho "remote: simulated push rejection" >&2\nexit 1\n')
-  chmodSync(hookPath, 0o755)
-}
-
-let dir: string
-let remoteDir: string
-let cacheDir: string
-
-beforeEach(() => {
-  dir = mkdtempSync(join(tmpdir(), 'wall-entry-test-'))
-  remoteDir = initBareRemote()
-  cacheDir = join(mkdtempSync(join(tmpdir(), 'wall-cache-')), 'soulcraft-releases')
-})
-
-afterEach(() => {
-  rmSync(dir, { recursive: true, force: true })
-  rmSync(remoteDir, { recursive: true, force: true })
-  rmSync(cacheDir, { recursive: true, force: true })
-})
-
-describe('wall-entry.mjs — generate + publish', () => {
-  it('derives headline from the first bullet and items from every bullet, hashes stripped, and pushes it to the remote', () => {
-    seedRemote(remoteDir, 'open-brainy', [BASE_ENTRY])
-    writeFileSync(
-      join(dir, 'CHANGELOG.md'),
-      buildChangelog([{ version: '10.4.12', date: '2026-09-03', bullets: ['fix(wall): mechanize the entry', 'test(wall): pin the shape'] }]),
-    )
-
-    const result = run(
-      ['--product', 'open-brainy', '--version', '10.4.12', '--date', '2026-09-03', '--from-changelog', 'CHANGELOG.md', '--remote', remoteDir, '--cache-dir', cacheDir],
-      dir,
-    )
-    expect(result.status).toBe(0)
-    expect(result.stdout).toMatch(/wrote v10\.4\.12.*pushed/i)
-
-    const wall = readRemote(remoteDir, 'open-brainy')
-    expect(wall.entries).toHaveLength(2)
-    expect(wall.entries[0]).toEqual({
-      version: '10.4.12',
-      date: '2026-09-03',
-      headline: 'fix(wall): mechanize the entry',
-      items: ['fix(wall): mechanize the entry', 'test(wall): pin the shape'],
-      url: 'https://source.soulcraft.com/soulcraftlabs/open-brainy/releases/tag/v10.4.12',
-      thumb: null,
-    })
-    // the older entry stays put, still second
-    expect(wall.entries[1].version).toBe('10.4.11')
-  })
-
-  it('prepends newest-first — the new entry lands at index 0 ahead of every existing one', () => {
-    seedRemote(remoteDir, 'open-brainy', [BASE_ENTRY, { ...BASE_ENTRY, version: '10.4.10' }])
-    writeFileSync(join(dir, 'CHANGELOG.md'), buildChangelog([{ version: '10.5.0', date: '2026-09-03', bullets: ['feat: ten five'] }]))
-
-    run(['--product', 'open-brainy', '--version', '10.5.0', '--date', '2026-09-03', '--from-changelog', 'CHANGELOG.md', '--remote', remoteDir, '--cache-dir', cacheDir], dir)
-
-    const wall = readRemote(remoteDir, 'open-brainy')
-    expect(wall.entries.map((e: any) => e.version)).toEqual(['10.5.0', '10.4.11', '10.4.10'])
-  })
-
-  it('replaces an entry with the same version instead of duplicating it — idempotent re-runs', () => {
-    seedRemote(remoteDir, 'open-brainy', [
-      { ...BASE_ENTRY, headline: 'stale headline, pre-fix' },
-      { ...BASE_ENTRY, version: '10.4.10' },
-    ])
-    writeFileSync(join(dir, 'CHANGELOG.md'), buildChangelog([{ version: '10.4.11', date: '2026-09-02', bullets: ['fix: the corrected headline'] }]))
-
-    const result = run(
-      ['--product', 'open-brainy', '--version', '10.4.11', '--date', '2026-09-02', '--from-changelog', 'CHANGELOG.md', '--remote', remoteDir, '--cache-dir', cacheDir],
-      dir,
-    )
-    expect(result.status).toBe(0)
-    expect(result.stdout).toMatch(/replaced v10\.4\.11/i)
-
-    const wall = readRemote(remoteDir, 'open-brainy')
-    expect(wall.entries).toHaveLength(2) // not 3 — replaced, not duplicated
-    expect(wall.entries[0].version).toBe('10.4.11')
-    expect(wall.entries[0].headline).toBe('fix: the corrected headline')
-    expect(wall.entries[1].version).toBe('10.4.10')
-  })
-
-  it('a re-run with byte-identical content commits nothing and still succeeds', () => {
-    // headline always equals items[0] for a derived entry, so this fixture
-    // (unlike BASE_ENTRY, whose headline/items intentionally diverge for the
-    // shape-only tests below) has to keep the two in lockstep to ever roundtrip.
-    const stableEntry = { ...BASE_ENTRY, headline: 'A faster open.', items: ['A faster open.'] }
-    seedRemote(remoteDir, 'open-brainy', [stableEntry])
-    writeFileSync(join(dir, 'CHANGELOG.md'), buildChangelog([{ version: '10.4.11', date: '2026-09-02', bullets: ['A faster open.'] }]))
-    const before = readRemote(remoteDir, 'open-brainy')
-
-    const result = run(
-      ['--product', 'open-brainy', '--version', '10.4.11', '--date', '2026-09-02', '--from-changelog', 'CHANGELOG.md', '--remote', remoteDir, '--cache-dir', cacheDir],
-      dir,
-    )
-    expect(result.status).toBe(0)
-    expect(result.stdout).toMatch(/nothing to commit/i)
-    expect(readRemote(remoteDir, 'open-brainy')).toEqual(before)
-  })
-
-  it('derives the public package-page permalink for the product engine (private repo, never null)', () => {
-    seedRemote(remoteDir, 'brainy', [{ ...BASE_ENTRY, version: '11.0.5', url: 'https://source.soulcraft.com/soulcraft/-/packages/npm/@soulcraft%2Fbrainy/11.0.5' }])
-    writeFileSync(join(dir, 'CHANGELOG.md'), buildChangelog([{ version: '11.0.6', date: '2026-09-03', bullets: ['fix: a native-only fix'] }]))
-
-    const result = run(
-      ['--product', 'brainy', '--version', '11.0.6', '--date', '2026-09-03', '--from-changelog', 'CHANGELOG.md', '--remote', remoteDir, '--cache-dir', cacheDir],
-      dir,
-    )
-    expect(result.status).toBe(0)
-
-    const wall = readRemote(remoteDir, 'brainy')
-    expect(wall.entries[0].url).toBe('https://source.soulcraft.com/soulcraft/-/packages/npm/@soulcraft%2Fbrainy/11.0.6')
-    expect(wall.entries[0].thumb).toBeNull()
-  })
-
-  it('refuses a product with no permalink pattern, naming the cure', () => {
-    seedRemote(remoteDir, 'open-brainy', [BASE_ENTRY])
-    writeFileSync(join(dir, 'CHANGELOG.md'), buildChangelog([{ version: '1.0.0', date: '2026-09-03', bullets: ['feat: first'] }]))
-
-    const result = run(['--product', 'mystery', '--version', '1.0.0', '--date', '2026-09-03', '--from-changelog', 'CHANGELOG.md', '--remote', remoteDir, '--cache-dir', cacheDir], dir)
-    expect(result.status).not.toBe(0)
-    expect(result.stderr).toMatch(/no permalink pattern for product "mystery"/)
-    expect(result.stderr).toMatch(/never carry url: null/)
-  })
-
-  it('refuses when the CHANGELOG has no entry yet for the target version, and touches no remote', () => {
-    seedRemote(remoteDir, 'open-brainy', [])
-    writeFileSync(join(dir, 'CHANGELOG.md'), buildChangelog([{ version: '10.4.11', date: '2026-09-02', bullets: ['fix: whatever'] }]))
-    const beforeSha = git(['rev-parse', 'main'], remoteDir)
-
-    const result = run(
-      ['--product', 'open-brainy', '--version', '99.0.0', '--date', '2026-09-02', '--from-changelog', 'CHANGELOG.md', '--remote', remoteDir, '--cache-dir', cacheDir],
-      dir,
-    )
-
-    expect(result.status).toBe(1)
-    expect(result.stderr).toMatch(/no CHANGELOG entry yet/i)
-    expect(git(['rev-parse', 'main'], remoteDir)).toBe(beforeSha)
-  })
-
-  it('refuses by naming the cure when the remote cannot be cloned', () => {
-    writeFileSync(join(dir, 'CHANGELOG.md'), buildChangelog([{ version: '10.4.12', date: '2026-09-03', bullets: ['fix: whatever'] }]))
-    const noSuchRemote = join(tmpdir(), 'wall-remote-does-not-exist-' + Date.now())
-
-    const result = run(
-      ['--product', 'open-brainy', '--version', '10.4.12', '--date', '2026-09-03', '--from-changelog', 'CHANGELOG.md', '--remote', noSuchRemote, '--cache-dir', cacheDir],
-      dir,
-    )
-
-    expect(result.status).toBe(1)
-    expect(result.stderr).toMatch(/cannot clone/i)
-    expect(result.stderr).toMatch(/cure:/i)
-  })
-
-  it('refuses by naming the cure, and touches no remote, when the fetched wall fails shape validation', () => {
-    const seedDir = mkdtempSync(join(tmpdir(), 'wall-seed-broken-'))
-    execFileSync('git', ['clone', remoteDir, seedDir], { stdio: 'ignore' })
-    git(['config', 'user.email', 'seed@example.com'], seedDir)
-    git(['config', 'user.name', 'Seed'], seedDir)
-    writeFileSync(
-      join(seedDir, 'open-brainy.json'),
-      JSON.stringify({ product: 'open-brainy', entries: [{ version: '10.4.11', date: '2026-09-02', items: ['x'], url: null }] }, null, 2),
-    )
-    git(['add', 'open-brainy.json'], seedDir)
-    git(['commit', '-m', 'seed broken'], seedDir)
-    git(['push', 'origin', 'main'], seedDir)
-    rmSync(seedDir, { recursive: true, force: true })
-    const beforeSha = git(['rev-parse', 'main'], remoteDir)
-
-    writeFileSync(join(dir, 'CHANGELOG.md'), buildChangelog([{ version: '10.4.12', date: '2026-09-03', bullets: ['fix: whatever'] }]))
-
-    const result = run(
-      ['--product', 'open-brainy', '--version', '10.4.12', '--date', '2026-09-03', '--from-changelog', 'CHANGELOG.md', '--remote', remoteDir, '--cache-dir', cacheDir],
-      dir,
-    )
-
-    expect(result.status).toBe(1)
-    expect(result.stderr).toMatch(/fails shape validation/i)
-    expect(result.stderr).toMatch(/missing key\(s\) headline/i)
-    expect(git(['rev-parse', 'main'], remoteDir)).toBe(beforeSha)
-  })
-
-  it('refuses by naming the cure when the remote rejects the push (stands in for a raced non-fast-forward)', () => {
-    seedRemote(remoteDir, 'open-brainy', [BASE_ENTRY])
-    makeRemoteRejectPushes(remoteDir)
-    writeFileSync(join(dir, 'CHANGELOG.md'), buildChangelog([{ version: '10.4.12', date: '2026-09-03', bullets: ['fix: whatever'] }]))
-
-    const result = run(
-      ['--product', 'open-brainy', '--version', '10.4.12', '--date', '2026-09-03', '--from-changelog', 'CHANGELOG.md', '--remote', remoteDir, '--cache-dir', cacheDir],
-      dir,
-    )
-
-    expect(result.status).toBe(1)
-    expect(result.stderr).toMatch(/push to .* failed/i)
-    expect(result.stderr).toMatch(/cure:/i)
-  })
-
-  it('refuses a cross-product write when the file\'s "product" field does not match --product', () => {
-    seedRemote(remoteDir, 'open-brainy', [BASE_ENTRY])
-    const seedDir = mkdtempSync(join(tmpdir(), 'wall-seed-mismatch-'))
-    execFileSync('git', ['clone', remoteDir, seedDir], { stdio: 'ignore' })
-    git(['config', 'user.email', 'seed@example.com'], seedDir)
-    git(['config', 'user.name', 'Seed'], seedDir)
-    const corrupted = JSON.parse(readFileSync(join(seedDir, 'open-brainy.json'), 'utf8'))
-    corrupted.product = 'brainy'
-    writeFileSync(join(seedDir, 'open-brainy.json'), JSON.stringify(corrupted, null, 2) + '\n')
-    git(['add', 'open-brainy.json'], seedDir)
-    git(['commit', '-m', 'corrupt product field'], seedDir)
-    git(['push', 'origin', 'main'], seedDir)
-    rmSync(seedDir, { recursive: true, force: true })
-
-    writeFileSync(join(dir, 'CHANGELOG.md'), buildChangelog([{ version: '1.0.0', date: '2026-09-03', bullets: ['fix: wrong repo'] }]))
-
-    const result = run(
-      ['--product', 'open-brainy', '--version', '1.0.0', '--date', '2026-09-03', '--from-changelog', 'CHANGELOG.md', '--remote', remoteDir, '--cache-dir', cacheDir],
-      dir,
-    )
-
-    expect(result.status).toBe(1)
-    expect(result.stderr).toMatch(/product "brainy".*--product "open-brainy"/i)
-  })
-})
-
-describe('wall-entry.mjs — --dry-run', () => {
-  it('prints the entry and the target path, and touches neither the cache dir nor the remote', () => {
-    seedRemote(remoteDir, 'open-brainy', [BASE_ENTRY])
-    writeFileSync(join(dir, 'CHANGELOG.md'), buildChangelog([{ version: '10.4.12', date: '2026-09-03', bullets: ['fix: a dry run'] }]))
-    const beforeSha = git(['rev-parse', 'main'], remoteDir)
-
-    const result = run(
-      ['--dry-run', '--product', 'open-brainy', '--version', '10.4.12', '--date', '2026-09-03', '--from-changelog', 'CHANGELOG.md', '--remote', remoteDir, '--cache-dir', cacheDir],
-      dir,
-    )
-
-    expect(result.status).toBe(0)
-    expect(result.stdout).toMatch(/would write to/i)
-    expect(result.stdout).toMatch(/"version": "10\.4\.12"/)
-    expect(git(['rev-parse', 'main'], remoteDir)).toBe(beforeSha)
-  })
-})
-
-describe('wall-entry.mjs — --check', () => {
-  it('passes a well-formed, newest-first file with no duplicates', () => {
-    writeFileSync(join(dir, 'wall.json'), wallFile('open-brainy', [BASE_ENTRY, { ...BASE_ENTRY, version: '10.4.10' }]))
-    const result = run(['--check', '--file', 'wall.json'], dir)
-    expect(result.status).toBe(0)
-    expect(result.stdout).toMatch(/OK/)
-  })
-
-  it('passes a file where "thumb" is entirely absent (optional per the HQ contract)', () => {
-    const { thumb, ...noThumb } = BASE_ENTRY as any
-    writeFileSync(join(dir, 'wall.json'), wallFile('open-brainy', [noThumb]))
-    const result = run(['--check', '--file', 'wall.json'], dir)
-    expect(result.status).toBe(0)
-  })
-
-  it('catches a missing entry key', () => {
-    const broken = { version: '1.0.0', date: '2026-09-03', headline: 'h', items: ['i'] } // no "url"
-    writeFileSync(join(dir, 'wall.json'), wallFile('open-brainy', [broken]))
-    const result = run(['--check', '--file', 'wall.json'], dir)
-    expect(result.status).toBe(1)
-    expect(result.stderr).toMatch(/missing key\(s\) url/)
-  })
-
-  it('catches an unexpected top-level key (e.g. the retired "history" field)', () => {
-    const raw = JSON.parse(wallFile('open-brainy', [BASE_ENTRY]))
-    raw.history = 'retired field'
-    writeFileSync(join(dir, 'wall.json'), JSON.stringify(raw))
-    const result = run(['--check', '--file', 'wall.json'], dir)
-    expect(result.status).toBe(1)
-    expect(result.stderr).toMatch(/unexpected key\(s\) history/)
-  })
-
-  it('catches entries that are not newest-first', () => {
-    writeFileSync(join(dir, 'wall.json'), wallFile('open-brainy', [{ ...BASE_ENTRY, version: '10.4.10' }, BASE_ENTRY]))
-    const result = run(['--check', '--file', 'wall.json'], dir)
-    expect(result.status).toBe(1)
-    expect(result.stderr).toMatch(/not newest-first/)
-  })
-
-  it('catches a duplicate version even with identical entries', () => {
-    writeFileSync(join(dir, 'wall.json'), wallFile('open-brainy', [BASE_ENTRY, { ...BASE_ENTRY }]))
-    const result = run(['--check', '--file', 'wall.json'], dir)
-    expect(result.status).toBe(1)
-    expect(result.stderr).toMatch(/duplicate version 10\.4\.11/)
-  })
-
-  it('catches an empty items array', () => {
-    writeFileSync(join(dir, 'wall.json'), wallFile('open-brainy', [{ ...BASE_ENTRY, items: [] }]))
-    const result = run(['--check', '--file', 'wall.json'], dir)
-    expect(result.status).toBe(1)
-    expect(result.stderr).toMatch(/"items" must be a non-empty array/)
-  })
-
-  it('catches a malformed date', () => {
-    writeFileSync(join(dir, 'wall.json'), wallFile('open-brainy', [{ ...BASE_ENTRY, date: '09/03/2026' }]))
-    const result = run(['--check', '--file', 'wall.json'], dir)
-    expect(result.status).toBe(1)
-    expect(result.stderr).toMatch(/"date" must be a YYYY-MM-DD string/)
-  })
-})