Merge remote-tracking branch 'origin/ci/release-wall-step' into tmp/ob-main-merge

releases/open-brainy.json follows brainy.json out — the shared repo
(soulcraftlabs/releases on The Source) is now the one home for both
products' release notes; this repo hosts neither. The releases/
directory is gone.

RELEASES.md gains a pointer, under the heading, to the two raw URLs HQ's
/hq/releases door reads (this file stays as the human-readable quick
reference; those files are the source of truth).

.forgejo/workflows/ci.yml

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

.forgejo/workflows/publish-source.yml

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

CHANGELOG.md

@@ -2,18 +2,6 @@
 
 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)

RELEASES.md

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

package-lock.json

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

package.json

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

scripts/release.sh

@@ -154,7 +154,8 @@ else
 fi
 
 # Create new changelog entry
-CHANGELOG_ENTRY="### [${NEW_VERSION}](https://source.soulcraft.com/soulcraftlabs/open-brainy/compare/v${CURRENT_VERSION}...v${NEW_VERSION}) ($(date +%Y-%m-%d))
+RELEASE_DATE=$(date +%Y-%m-%d)
+CHANGELOG_ENTRY="### [${NEW_VERSION}](https://source.soulcraft.com/soulcraftlabs/open-brainy/compare/v${CURRENT_VERSION}...v${NEW_VERSION}) (${RELEASE_DATE})
 
 ${COMMITS}
 "
@@ -174,6 +175,19 @@ 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
@@ -237,7 +251,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/soulcraft/brainy/releases" \
+  if curl -sf -X POST "https://source.soulcraft.com/api/v1/repos/soulcraftlabs/open-brainy/releases" \
     -H "Authorization: token ${FORGEJO_RELEASE_TOKEN}" -H "Content-Type: application/json" \
     -d "{\"tag_name\":\"v${NEW_VERSION}\",\"name\":\"v${NEW_VERSION}\",\"prerelease\":${PRERELEASE}}" >/dev/null; then
     echo -e "${GREEN}✅ Release page created on The Source${NC}\n"

scripts/wall-entry.mjs

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

src/brainy.ts

@@ -15,7 +15,6 @@ 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 {
@@ -4204,19 +4203,32 @@ export class Brainy<T = any> implements BrainyInterface<T> {
    */
   /**
    * @description A JSON-safe view of a record bound for the metadata-index
-   * crossing — delegates to the shared {@link jsonSafeIndexMetadata} leaf,
+   * crossing. The seam's metadata is JSON-safe BY CONTRACT (a native provider
-   * which the metadata-index transaction operations ALSO apply at execute
+   * serializes it; u64 ints as Number corrupt above 2^53) — but
-   * and rollback time. This plan-time wrap alone proved insufficient: it
+   * {@link resolveVerbEndpointInts} MIRRORS the resolved endpoint ints onto
-   * returns the same reference when the record is clean, and `transact()`'s
+   * the verb object itself as BigInt (`verb.sourceInt`/`targetInt`), so a
-   * delete legs share that reference with a graph-retraction op whose
+   * verb object reused as index metadata carried BigInts into
-   * execute-time endpoint resolution mirrors BigInt ints onto it (the full
+   * JSON.stringify, which throws, aborting the whole transaction (found by
-   * aliasing story lives on the leaf module's doc).
+   * the first joint pair gate). Endpoint ints ride their OWN op params on the
+   * graph legs — the metadata crossing drops every BigInt-valued top-level
+   * key instead of guessing at a lossy numeric encoding.
    * @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 {
-    return jsonSafeIndexMetadata(metadata)
+    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
   }
 
   private metadataIndexRetractionOp(

src/storage/adapters/baseStorageAdapter.ts

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

src/storage/adapters/fileSystemStorage.ts

@@ -2400,15 +2400,8 @@ 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> {
-    // pid + timestamp alone collided: two writers of the same target inside
+    const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`
-    // one millisecond shared this path, and the loser's rename found the
-    // winner had already moved it (ENOENT). The sequence makes every call's
-    // temp path its own.
-    const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}-${++FileSystemStorage.atomicWriteSeq}`
     await fs.promises.writeFile(tmp, contents)
     await fs.promises.rename(tmp, filePath)
   }

src/transaction/operations/IndexOperations.ts

@@ -14,7 +14,6 @@ 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'
 
 /**
@@ -391,21 +390,13 @@ export class AddToMetadataIndexOperation implements Operation {
     // rollback so add + undo reference the same watermark.
     const generation = this.generationFn?.()
 
-    // The JSON-safe view is taken HERE, per crossing, never at construction:
+    // Add to metadata index (skipFlush=true for transaction atomicity)
-    // the entity reference this op holds can be mutated between plan and
+    await this.index.addToIndex(this.id, this.entity, true, false, generation)
-    // 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(
+      await this.index.removeFromIndex(this.id, this.entity, generation)
-        this.id, jsonSafeIndexMetadata(this.entity), generation
-      )
     }
   }
 }
@@ -441,21 +432,13 @@ export class RemoveFromMetadataIndexOperation implements Operation {
     // Resolve the removal generation once; reuse it for the rollback re-add.
     const generation = this.generationFn?.()
 
-    // Sanitized per crossing, never at construction — transact()'s delete
+    // Remove from metadata index
-    // legs hand this op the SAME verb object the graph-retraction op's
+    await this.index.removeFromIndex(this.id, this.entity, generation)
-    // 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(
+      await this.index.addToIndex(this.id, this.entity, true, false, generation)
-        this.id, jsonSafeIndexMetadata(this.entity), true, false, generation
-      )
     }
   }
 }

src/utils/jsonSafeIndexMetadata.ts

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

src/vfs/VirtualFileSystem.ts

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

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

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

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

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

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

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

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

@@ -0,0 +1,395 @@
+/**
+ * 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/)
+  })
+})