fix(graph): the verb fast paths honour every requested type, source, and target

related() with a verb-type ARRAY returned edges for only the first type — the storage fast paths collapsed `verbType` (and, in their sibling blocks, `sourceId` and `targetId`) arrays to their first element, silently dropping the rest of the ask. Every consumer passing a verb list under-traversed with no error and no narration: the same quiet-loss class as the graph-first paging defect, one seam over. All four fast paths now union over the full requested set, deduped by edge id, before the metadata filters and pagination run. Pinned in tests/integration/related-verb-array.test.ts: the second requested type's edge returns in both array orders, on the anchor side, the target side, and the type-only path; a one-element array equals the scalar; no duplicates on overlap; pagination walks the union consistently.
fix(storage): counts persistence is single-flight, coalesced, and never races its own temp file
2026-09-01 12:23:03 -07:00 · 2026-09-01 09:32:23 -07:00 · 2026-08-31 14:50:45 -07:00 · 2026-08-31 12:59:40 -07:00 · 2026-08-31 12:34:36 -07:00 · 2026-08-31 10:47:08 -07:00
18 changed files with 605 additions and 1009 deletions
--- a/.forgejo/workflows/ci.yml
+++ b/.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: ['**']
--- a/.forgejo/workflows/publish-source.yml
+++ b/.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:
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -2,6 +2,18 @@
 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.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)
--- a/RELEASES.md
+++ b/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
--- a/package-lock.json
+++ b/package-lock.json
@ -1,12 +1,12 @@
 {
  "name": "@soulcraftlabs/brainy",
-  "version": "10.4.4",
+  "version": "10.4.6",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "@soulcraftlabs/brainy",
-      "version": "10.4.4",
+      "version": "10.4.6",
      "license": "MIT",
      "dependencies": {
        "@msgpack/msgpack": "^3.1.2",
--- a/package.json
+++ b/package.json
@ -1,6 +1,6 @@
 {
  "name": "@soulcraftlabs/brainy",
-  "version": "10.4.4",
+  "version": "10.4.6",
  "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",
--- a/scripts/release.sh
+++ b/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}) ($(date +%Y-%m-%d))
 CHANGELOG_ENTRY="### [${NEW_VERSION}](https://source.soulcraft.com/soulcraftlabs/open-brainy/compare/v${CURRENT_VERSION}...v${NEW_VERSION}) (${RELEASE_DATE})
 ${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"
--- a/scripts/wall-entry.mjs
+++ b/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()
--- a/src/brainy.ts
+++ b/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 {
@ -4203,32 +4204,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
+   * crossing — delegates to the shared {@link jsonSafeIndexMetadata} leaf,
-   * serializes it; u64 ints as Number corrupt above 2^53) — but
+   * which the metadata-index transaction operations ALSO apply at execute
-   * {@link resolveVerbEndpointInts} MIRRORS the resolved endpoint ints onto
+   * and rollback time. This plan-time wrap alone proved insufficient: it
-   * the verb object itself as BigInt (`verb.sourceInt`/`targetInt`), so a
+   * returns the same reference when the record is clean, and `transact()`'s
-   * verb object reused as index metadata carried BigInts into
+   * delete legs share that reference with a graph-retraction op whose
-   * JSON.stringify, which throws, aborting the whole transaction (found by
+   * execute-time endpoint resolution mirrors BigInt ints onto it (the full
-   * the first joint pair gate). Endpoint ints ride their OWN op params on the
+   * aliasing story lives on the leaf module's doc).
   * graph legs — the metadata crossing drops every BigInt-valued top-level
   * key instead of guessing at a lossy numeric encoding.
   * @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
+    return jsonSafeIndexMetadata(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
  }
  private metadataIndexRetractionOp(
--- a/src/storage/adapters/baseStorageAdapter.ts
+++ b/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 {
+    // SINGLE-FLIGHT, COALESCED. Counts are write-through on every change, so
-      // Persist to storage (implemented by subclass)
+    // a burst of writes used to launch one persist per change, all in flight
-      await this.persistCounts()
+    // together. Two of them inside the same millisecond shared the atomic
-      this.pendingCountPersist = false
+    // writer's temp path (`.tmp-<pid>-<ms>`): both wrote it, the first rename
-    } catch (error) {
+    // consumed it, the second rename found nothing — ENOENT, ~1,500 times a
-      console.error('CRITICAL: Failed to flush counts to storage:', error)
+    // day on a busy production brain, with a full ledger write per change
-      // Keep pending flag set so we retry on next operation
+    // behind it. Now exactly one persist runs at a time; requests that arrive
-      throw error
+    // 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
  }
  /**
--- a/src/storage/adapters/fileSystemStorage.ts
+++ b/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)
  }
--- a/src/storage/baseStorage.ts
+++ b/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)
+        const sourceIds = Array.isArray(options.filter.sourceId)
-          ? options.filter.sourceId[0]
+          ? options.filter.sourceId
-          : options.filter.sourceId
+          : [options.filter.sourceId]
-        const verbType = Array.isArray(options.filter.verbType)
+        // EVERY requested verb type is honoured — an array used to collapse to
-          ? options.filter.verbType[0]
+        // its first element here, silently dropping the rest of the ask.
-          : options.filter.verbType
+        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),
+        // Get verbs by source (union over every requested source), filter by the
-        // then apply the subtype / visibility metadata filters on the candidate set.
+        // requested type SET (O(1) graph lookup + O(n) type filter), then apply
-        const verbsBySource = await this.getVerbsBySource_internal(sourceId)
+        // 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)
+        // EVERY requested source is honoured — an array used to collapse to
-          ? options.filter.sourceId[0]
+        // its first element here, silently dropping the rest of the ask.
-          : options.filter.sourceId
+        const onlySourceIds = Array.isArray(options.filter.sourceId)
-
+          ? options.filter.sourceId
-        // Get verbs by source directly (hydrated with metadata), then apply the
+          : [options.filter.sourceId]
-        // subtype / visibility metadata filters on the O(degree) candidate set.
+        const sourceUnion: HNSWVerbWithMetadata[] = []
-        const verbsBySource = this.applyVerbMetadataFilters(
+        const seenSourceVerbIds = new Set<string>()
-          await this.getVerbsBySource_internal(sourceId),
+        for (const oneSource of onlySourceIds) {
-          options.filter
+          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)
+        // EVERY requested target is honoured — an array used to collapse to
-          ? options.filter.targetId[0]
+        // its first element here, silently dropping the rest of the ask.
-          : options.filter.targetId
+        const onlyTargetIds = Array.isArray(options.filter.targetId)
-
+          ? options.filter.targetId
-        // Get verbs by target directly (hydrated with metadata), then apply the
+          : [options.filter.targetId]
-        // subtype / visibility metadata filters on the O(degree) candidate set.
+        const targetUnion: HNSWVerbWithMetadata[] = []
-        const verbsByTarget = this.applyVerbMetadataFilters(
+        const seenTargetVerbIds = new Set<string>()
-          await this.getVerbsByTarget_internal(targetId),
+        for (const oneTarget of onlyTargetIds) {
-          options.filter
+          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)
+        // EVERY requested verb type is honoured — an array used to collapse to
-          ? options.filter.verbType[0]
+        // its first element here, silently dropping the rest of the ask.
-          : options.filter.verbType
+        const verbTypes = Array.isArray(options.filter.verbType)
          ? options.filter.verbType
          : [options.filter.verbType]
-        // Get verbs by type directly (hydrated with metadata), then apply the
+        // Get verbs by each requested type (hydrated with metadata), deduped by
-        // subtype / visibility metadata filters on the candidate set.
+        // id, then apply the subtype / visibility metadata filters on the set.
-        const verbsByType = this.applyVerbMetadataFilters(
+        const byType: HNSWVerbWithMetadata[] = []
-          await this.getVerbsByType_internal(verbType),
+        const seenTypeVerbIds = new Set<string>()
-          options.filter
+        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)
--- a/src/transaction/operations/IndexOperations.ts
+++ b/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)
+    // The JSON-safe view is taken HERE, per crossing, never at construction:
-    await this.index.addToIndex(this.id, this.entity, true, false, generation)
+    // 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
+    // Sanitized per crossing, never at construction — transact()'s delete
-    await this.index.removeFromIndex(this.id, this.entity, generation)
+    // 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
      )
    }
  }
 }
--- a/src/utils/jsonSafeIndexMetadata.ts
+++ b/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
 }
--- a/tests/integration/counts-persist-single-flight.test.ts
+++ b/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)
  })
 })
--- a/tests/integration/related-verb-array.test.ts
+++ b/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)
  })
 })
--- a/tests/integration/transact-edge-delete-bigint-aliasing.test.ts
+++ b/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([[], []])
  })
 })
--- a/tests/unit/release/wall-entry.test.ts
+++ b/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/)
  })
 })
Author	SHA1	Message	Date
David Snelling	6a89adc468	fix(graph): the verb fast paths honour every requested type, source, and target Some checks failed CI / Node 22 (push) Successful in 12m21s Details CI / Node 24 (push) Successful in 12m11s Details CI / Bun (latest) (push) Successful in 12m24s Details CI / Integration + conformance (Node 22) (push) Failing after 16m55s Details related() with a verb-type ARRAY returned edges for only the first type — the storage fast paths collapsed `verbType` (and, in their sibling blocks, `sourceId` and `targetId`) arrays to their first element, silently dropping the rest of the ask. Every consumer passing a verb list under-traversed with no error and no narration: the same quiet-loss class as the graph-first paging defect, one seam over. All four fast paths now union over the full requested set, deduped by edge id, before the metadata filters and pagination run. Pinned in tests/integration/related-verb-array.test.ts: the second requested type's edge returns in both array orders, on the anchor side, the target side, and the type-only path; a one-element array equals the scalar; no duplicates on overlap; pagination walks the union consistently.	2026-09-01 12:23:03 -07:00
David Snelling	5e3b343a0e	fix(storage): counts persistence is single-flight, coalesced, and never races its own temp file Some checks failed CI / Node 24 (push) Successful in 12m24s Details CI / Node 22 (push) Successful in 12m35s Details CI / Integration + conformance (Node 22) (push) Failing after 17m25s Details CI / Bun (latest) (push) Successful in 12m19s Details persistCounts() was write-through on every count change with no serialization, and the atomic writer named its temp file with millisecond granularity. Two persists inside one millisecond shared the temp path: both wrote it, the first rename consumed it, the second rename found nothing — ENOENT, roughly 1,500 times a day on a busy production brain, with a full ledger write per change behind it. No data was lost (the surviving rename carried a complete ledger and the next change re-persisted), but the race was real and the write rate absurd. flushCounts() now runs exactly one persist at a time; requests arriving during it collapse into one trailing pass that carries the burst's final state — N changes cost at most two writes. writeFileAtomic() adds a per-process sequence to the temp name so no two writes can share a path. Pinned: a 25-change burst → ≤2 ledger writes, zero errors, ledger equal to memory; parallel real writes land complete; three same-instant atomic writes own three distinct temp paths.	2026-09-01 09:32:23 -07:00
David Snelling	4014e0f125	chore(release): 10.4.6 Some checks failed Publish (The Source) / Publish to The Source registry (push) Successful in 12m31s Details CI / Node 22 (push) Successful in 12m25s Details CI / Node 24 (push) Successful in 12m20s Details CI / Bun (latest) (push) Successful in 12m29s Details CI / Integration + conformance (Node 22) (push) Failing after 16m56s Details	2026-08-31 14:50:45 -07:00
David Snelling	73500e7d10	fix(transact): metadata-index ops take their JSON-safe view at the crossing, not at construction Some checks failed CI / Node 24 (push) Successful in 12m30s Details CI / Node 22 (push) Successful in 12m35s Details CI / Integration + conformance (Node 22) (push) Failing after 16m54s Details CI / Bun (latest) (push) Successful in 12m26s Details transact()'s delete legs (direct unrelate and the noun-remove cascade) hand the SAME verb object to the graph-retraction op and the metadata-retraction op. The metadata leg sanitized at PLAN time, when the verb was still clean, so the wrap returned the same reference — then the graph op's execute-time endpoint resolution (deliberately deferred for same-batch forward refs) mirrored BigInt sourceInt/targetInt onto the shared object, and the metadata op crossed the seam with them. A strict provider rightly refuses that crossing, so every transact-wrapped edge delete aborted; direct unrelate() resolves ints at build time, before its sanitize, which is why no existing gate saw it. The JSON-safe view now lives in a shared leaf (utils/jsonSafeIndexMetadata) and is applied INSIDE AddToMetadataIndexOperation and RemoveFromMetadataIndexOperation at execute and rollback time — the one place no plan-vs-execute ordering can bypass. Pins: the fleet repro, the cascade shape, a mixed batch, and unit pins that mutate the entity after construction against a strict seam (5 red before, 5 green after).	2026-08-31 12:59:40 -07:00
David Snelling	0f0022b1c9	chore(release): 10.4.5 Some checks failed CI / Node 24 (push) Successful in 12m32s Details CI / Node 22 (push) Successful in 12m35s Details Publish (The Source) / Publish to The Source registry (push) Successful in 13m3s Details CI / Bun (latest) (push) Successful in 12m29s Details CI / Integration + conformance (Node 22) (push) Failing after 16m45s Details	2026-08-31 12:34:36 -07:00
David Snelling	d6bcb14f69	build(release): the docs-push step retires — this engine documents itself in its own repository Some checks failed CI / Node 22 (push) Successful in 12m27s Details CI / Node 24 (push) Successful in 12m26s Details CI / Integration + conformance (Node 22) (push) Failing after 17m1s Details CI / Bun (latest) (push) Successful in 12m26s Details The one-doc-set ruling (2026-08-31) gives soulcraft.com/docs to the paid product alone; the site serves redirects for the slugs this rail used to push. The push script stays in the tree as history; the rail stops calling it. (cherry picked from commit `655aa13ea7`)	2026-08-31 10:47:08 -07:00
David Snelling	a963a744cc	fix(generations): a sealed segment may only declare the generations it holds Diagnosis of the "packed history is damaged" narration that fires on every run of the affected stores. It is a WRITER defect, and the reader's refusal was the symptom rather than the cause. A sealed segment declares one contiguous range [firstGeneration, lastGeneration], and every reader treats that range as containment: coveringSegment is an interval test, hasGeneration returns true for anything inside it, and open() seeds committedRanges from it. repackHistory handed fold() a SPARSE batch. Three filters punch holes in its candidate list mid-run — a generation absent from committedRanges never appears, one still in the pending buffer is skipped, one whose tx.json will not read is skipped — and fold() then computed the range from the first and last survivor, claiming every generation in between. The next open merged that mis-declared range back into committedRanges, re-admitting the hole as committed history, so the following auto-compaction pass asked the packed tier for a frame that was never written and failed. Re-merged at every open, which is why it repeated on every run. Confirmed against a forensic fixture: generation directories 1..2503 present except exactly one, 1416; and its fact-log segment already showed the tell — seg-...1410.bfl declaring 1410..1940 (531 generations) while recording 530 facts. Three changes: - repackHistory folds each contiguous RUN as its own segment (`contiguousRuns`), so ranges describe exactly what the segments contain. - fold() REFUSES a non-contiguous batch, naming the gap and its width. The density law is now mechanical, so no future caller can reintroduce it. A refusal loses nothing: the generations stay live and readable. - Stores already carrying the damage heal instead of wedging. A segment whose declared span exceeds its frame count is SPARSE; `actualRanges()` reads the real generation list from its sidecar so open() never re-admits the holes, and readFrame reports such a hole as unpacked with a narration naming the segment, rather than throwing. A DENSE segment missing a frame is still loud damage — that one means the manifest and sidecar disagree. Pins: nine unit cases (refusal and its message, honest ranges for separately folded runs, a reconstructed pre-fix sparse segment serving its real frames while reporting holes as unpacked, holes excluded from actualRanges, and the dense-segment damage path still throwing) plus an end-to-end case that deletes a generation directory and drives the real sequence — ordinary close()-time repacking folds over the hole, then reopen and compact must both complete. Verified red without the fix: the segment declared an 11-generation span while holding 10 frames. (cherry picked from commit `9a888c37e9`)	2026-08-31 10:47:08 -07:00
David Snelling	c99308710a	fix(recovery): a torn generation-log tail is a terminal verdict, never a wait Two halves of one defect, found by a seeded-SIGKILL crash lane. THE FALSE POSITIVE. stampEntityTree() recorded generationStore.generation() — the ALLOCATED counter, a number a write in flight has claimed and may never commit — while the JSDoc beside it already said the source is the committed generation. Every crash inside a write window therefore produced a spurious verdict at the next open: either 'sourceGeneration N is ahead of the log head N-1' (the allocated generation died with the process) or 'rollup invariant nounCount: stamped X, observed Y' (the recovery fold folded facts the stamp's counts predate). Both told the operator to run repairIndex() — a whole-store recount — for a store that was coherent. Measured before this commit: 4 of 11 SIGKILL cycles on a healthy store raised one of the two. The stamp and the open now both read committedGeneration(), which is what every other open-time watermark in the class already reasons about. THE TERMINAL VERDICT. A stamp still ahead of committed truth after the recovery fold witnesses a generation that is not in the log — the stamp's fsync outlived the tail's, and there is nothing to arrive. That is its own verdict state now ('torn'), never folded in with 'incoherent': the two have opposite cures. A writer open demotes it — the unusable stamped surface is re-derived at the committed generation from the live counters, O(1), straight-line, no loop and no await on external progress, narrated with both count sets, the stamp's path and its committedAt. A read-only open cannot re-stamp, so it says so and names the cure instead of guessing, and still serves. Neither branch waits, and neither locks an owner out of a canonical tree the stamp only describes. Pins: the verifier returns the torn verdict with both generations; a fabricated head-behind-source store narrates precisely, demotes inside a bounded open, serves its rows, and is quiet at the next open (the demotion converges); a read-only open narrates the same verdict and leaves the bytes untouched. (cherry picked from commit `298cb6daca`)	2026-08-31 10:47:08 -07:00