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:

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
 

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"
@@ -248,17 +262,12 @@ else
   echo -e "${RED}⚠️  FORGEJO_RELEASE_TOKEN unset — no release page created; tag + CHANGELOG remain the record${NC}\n"
 fi
 
-# Step 12: Push public docs to the soulcraft.com docs ingest door
+# Step 12 RETIRED (2026-08-31, CORTEX-SITE-BRAINY-RENAME round 12, David-ruled):
-# (VENUE-DOCS-RELEASE-PUSH). Skips with a loud warning when
+# soulcraft.com/docs carries the paid product's documentation only. This
-# DOCS_INGEST_SECRET is unset; fails loudly (without undoing the publish —
+# engine's documentation home is THIS repository — README and docs/ — and the
-# that already happened) when a push errors, so the docs site never
+# site serves 301s for the slugs this rail used to push. The push script stays
-# silently trails npm.
+# in the tree for history; the rail no longer calls it.
-echo -e "${BLUE}1️⃣2️⃣ Pushing public docs to soulcraft.com/docs...${NC}"
+echo -e "${BLUE}Docs step: this engine documents itself in its own repo (site push retired 2026-08-31)${NC}"
-if node scripts/push-docs.js; then
-  echo -e "${GREEN}✅ Docs push step done${NC}\n"
-else
-  echo -e "${RED}❌ Docs push FAILED — soulcraft.com/docs trails npm until re-run or interim sync${NC}\n"
-fi
 
 echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
 echo -e "${GREEN}🎉 Release ${NEW_VERSION} complete!${NC}"

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

@@ -12497,6 +12497,18 @@ export class Brainy<T = any> implements BrainyInterface<T> {
    * healed by `repairIndex()`, whose unconditional recount rebuilds the
    * rollups from a canonical walk and re-stamps. Best-effort: a stamp-write
    * fault warns loudly but never fails the flush that carried real data.
+   *
+   * THE SOURCE IS `committedGeneration()`, NEVER `generation()`. The latter is
+   * the ALLOCATED counter — a number a write in flight has claimed and may
+   * never commit. Stamping it made the stamp's generation label a claim about
+   * counts it was not taken at, and every crash inside a write window then
+   * 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). MEASURED on the
+   * crash-consistency lane before this line changed: 4 of 11 SIGKILL cycles on
+   * a coherent store raised one of those two verdicts, each of them naming
+   * `repairIndex()` — a whole-store recount — as the cure for nothing.
    */
   private async stampEntityTree(): Promise<void> {
     if (this.isReadOnly) return
@@ -12507,7 +12519,7 @@ export class Brainy<T = any> implements BrainyInterface<T> {
       ])
       await writeFamilyStamp(this.storage, ENTITY_TREE_STAMP_PATH, {
         family: 'entity-tree',
-        sourceGeneration: this.generationStore.generation(),
+        sourceGeneration: this.generationStore.committedGeneration(),
         members: { mode: 'rollup', invariants: { nounCount, verbCount } }
       })
     } catch (error) {
@@ -12520,16 +12532,24 @@ export class Brainy<T = any> implements BrainyInterface<T> {
 
   /**
    * @description Open-time coherence check for the entity tree's family stamp:
-   * compare `sourceGeneration` against the log head and the stamped rollup
+   * compare `sourceGeneration` against the store's COMMITTED generation and
-   * invariants against the live counters. Verdicts:
+   * the stamped rollup invariants against the live counters. Verdicts:
    * - `coherent` / `absent` (legacy store; first flush stamps) → silent.
    * - `behind` → benign for the tree (it is written BY the commit; only the
    *   stamp is stale — a crash landed between commit and flush). Refreshed at
    *   the next flush.
+   * - `torn` → a TORN GENERATION-LOG TAIL, handled by
+   *   {@link demoteTornEntityTreeStamp}: terminal, never a wait.
    * - `incoherent` → LOUD: the tree or its counters diverged from what was
    *   stamped — `repairIndex()` recounts from canonical and re-stamps.
    * Never blocks open; a fault reading the stamp is surfaced as unverifiable,
    * never conflated with absence.
+   *
+   * THE COMPARISON IS AGAINST `committedGeneration()`, matching what
+   * {@link stampEntityTree} writes and what every other open-time watermark in
+   * this class already reasons about (the fact-scan capability, the metadata /
+   * graph / HNSW watermark verdicts). Comparing against the allocated counter
+   * was the one place that disagreed, and disagreeing was the whole defect.
    */
   private async verifyEntityTreeStamp(): Promise<void> {
     let stamp: FamilyStamp | null
@@ -12546,11 +12566,16 @@ export class Brainy<T = any> implements BrainyInterface<T> {
       this.storage.getNounCount(),
       this.storage.getVerbCount()
     ])
-    const verdict = verifyFamilyStamp(stamp, this.generationStore.generation(), {
+    const verdict = verifyFamilyStamp(stamp, this.generationStore.committedGeneration(), {
       nounCount,
       verbCount
     })
-    if (verdict.state === 'incoherent') {
+    if (verdict.state === 'torn') {
+      await this.demoteTornEntityTreeStamp(stamp as FamilyStamp, verdict.stampSource, verdict.head, {
+        nounCount,
+        verbCount
+      })
+    } else if (verdict.state === 'incoherent') {
       prodLog.warn(
         `[Brainy] entity-tree stamp INCOHERENT at open: ${verdict.failures.join('; ')}. ` +
           `The canonical tree or its counters diverged from the stamped state — run ` +
@@ -12564,6 +12589,92 @@ export class Brainy<T = any> implements BrainyInterface<T> {
     }
   }
 
+  /**
+   * @description THE TERMINAL VERDICT for a torn generation-log tail.
+   *
+   * A stamp whose `sourceGeneration` sits ABOVE the store's committed
+   * watermark witnesses a generation that is not in the log: the stamp's fsync
+   * outlived the tail's. By the time this runs, log-authority recovery has
+   * already folded every intact fact above the manifest and advanced the
+   * watermark to cover them — so if the stamp is STILL ahead, the generation
+   * it names is not merely late, it is GONE. There is nothing to wait for.
+   *
+   * That is the whole point of this method. A field report of this class
+   * (single-process store, abrupt termination mid-fold) described a reopen
+   * that narrated the tear and then held 100% CPU with zero log growth for
+   * eight minutes before an operator wiped the directory. A recovery that
+   * cannot say what it is waiting for has no business spinning; the honest
+   * answer here is a verdict, taken now, at O(1) cost.
+   *
+   * WHAT THE VERDICT DOES — the stamped surface is UNUSABLE, so it is
+   * discarded rather than believed: the stamped counts describe a generation
+   * that never became durable, and comparing them against live counters can
+   * only produce noise. The tree itself is not in question (it IS canonical —
+   * every commit writes it, and the fold re-applied every after-image the log
+   * still holds), so the demotion is a re-derivation of this family's verified
+   * surface at the generation the store can actually show:
+   *
+   * - WRITER open → re-stamp at `committedGeneration()` from the live
+   *   counters — exactly what the next flush would write, taken now so the
+   *   tear cannot re-narrate on every subsequent open. Both count sets are
+   *   logged so an operator can see whether anything really moved.
+   * - READER open → a reader cannot re-stamp. Narrate the same terminal
+   *   verdict with the named cure and carry on serving; a read-only inspector
+   *   is never locked out of a store, and never left waiting either.
+   *
+   * BOUNDEDNESS: straight-line code. No loop, no retry, no await on any
+   * external progress signal — the two counter reads and one stamp write are
+   * the entire cost, and none of them scales with the store.
+   */
+  private async demoteTornEntityTreeStamp(
+    stamp: FamilyStamp,
+    stampSource: number,
+    head: number,
+    observed: { nounCount: number; verbCount: number }
+  ): Promise<void> {
+    const stamped = stamp.members.mode === 'rollup' ? stamp.members.invariants : {}
+    const detail =
+      `[Brainy] TORN GENERATION-LOG TAIL at open: ${ENTITY_TREE_STAMP_PATH} witnesses source ` +
+      `generation ${stampSource} (stamped ${stamp.committedAt}), but the store's committed ` +
+      `generation is ${head} after crash recovery — the stamp's fsync outlived the log tail's, ` +
+      `and generation ${stampSource} is not in the log to arrive. Stamped rollups ` +
+      `${JSON.stringify(stamped)}; observed ${JSON.stringify(observed)}.`
+
+    if (this.isReadOnly) {
+      prodLog.warn(
+        `${detail} This open is READ-ONLY, so the stamp cannot be re-derived: the entity-tree ` +
+          `family stays UNVERIFIED for this session (reads are unaffected — the canonical tree ` +
+          `is the truth this stamp only describes). Cure: open the store with a writer, or run ` +
+          `brain.repairIndex() there, to recount from canonical and re-stamp.`
+      )
+      return
+    }
+
+    const startedAt = Date.now()
+    try {
+      await writeFamilyStamp(this.storage, ENTITY_TREE_STAMP_PATH, {
+        family: 'entity-tree',
+        sourceGeneration: head,
+        members: {
+          mode: 'rollup',
+          invariants: { nounCount: observed.nounCount, verbCount: observed.verbCount }
+        }
+      })
+      prodLog.warn(
+        `${detail} DEMOTED: the unusable stamp was re-derived at committed generation ${head} ` +
+          `from the live counters in ${Date.now() - startedAt}ms — terminal, not a wait. If the ` +
+          `observed counts above look wrong for your data, run brain.repairIndex() to recount ` +
+          `from canonical.`
+      )
+    } catch (error) {
+      prodLog.warn(
+        `${detail} The demotion's re-stamp FAILED (${(error as Error).message}) — the tear will ` +
+          `narrate again at the next open, which is the honest outcome; the store still serves ` +
+          `from canonical. Cure: run brain.repairIndex() to recount from canonical and re-stamp.`
+      )
+    }
+  }
+
   /**
    * Ask the writer process serving this data directory to flush its in-memory
    * indexes to disk, so a read-only inspector can observe fresh state.

src/db/familyStamp.ts

@@ -12,9 +12,11 @@
  *   the verified surface is a small set of rollup invariants (entity/
  *   relationship counts) plus `sourceGeneration`.
  *
- * `sourceGeneration` is the generation of the source-of-truth log this
+ * `sourceGeneration` is the COMMITTED generation of the source-of-truth log
- * projection reflects — open-time coherence becomes a COMPARISON (stamp vs
+ * this projection reflects — never the allocated counter, which names a
- * log head), not a walk:
+ * generation that may never commit (see {@link StampVerdict.torn}) — so
+ * open-time coherence becomes a COMPARISON (stamp vs committed head), not a
+ * walk:
  *
  * - equal + invariants hold → coherent, serve.
  * - behind → the projection missed the tail (crash between commit and stamp);
@@ -24,6 +26,9 @@
  * - invariants FAIL at equal generation → genuine incoherence: loud, and the
  *   repair ritual (`repairIndex()`, whose recount rebuilds the rollups from a
  *   canonical walk) heals it.
+ * - AHEAD → a torn generation-log tail: the stamp's fsync outlived the log
+ *   tail's. TERMINAL, never a wait — the generation the stamp names does not
+ *   exist to arrive.
  *
  * Stamps are JSON on purpose — every incident gets debugged by reading a
  * stamp in a terminal.
@@ -70,6 +75,12 @@ export type StampVerdict =
   | { state: 'coherent' }
   | { state: 'absent' } // legacy store — first stamp writes at the next flush
   | { state: 'behind'; stampSource: number; head: number }
+  /**
+   * TORN GENERATION-LOG TAIL: the stamp witnesses a source generation the
+   * store's committed watermark can no longer show. TERMINAL — there is no
+   * generation to wait for, so the open demotes (or refuses) and never spins.
+   */
+  | { state: 'torn'; stampSource: number; head: number }
   | { state: 'incoherent'; failures: string[] }
   | { state: 'unverifiable'; reason: string } // a FAULT reading the stamp — never conflated with absence
 
@@ -118,12 +129,15 @@ export function verifyFamilyStamp(
 ): StampVerdict {
   if (stamp === null) return { state: 'absent' }
   if (stamp.sourceGeneration > head) {
-    // A stamp AHEAD of the log claims state that never committed — the
+    // A stamp AHEAD of committed truth witnesses a generation the store can no
-    // projection was stamped against truth that a crash rolled back.
+    // longer show: the stamp's fsync survived a crash that the log tail did
-    return {
+    // not. This is the TORN GENERATION-LOG TAIL — its own class, never folded
-      state: 'incoherent',
+    // in with `incoherent` (a count that drifted at a generation both sides
-      failures: [`sourceGeneration ${stamp.sourceGeneration} is ahead of the log head ${head}`]
+    // agree on), because the two have opposite cures: incoherence is recounted,
-    }
+    // a tear is DEMOTED. It is also terminal by construction — there is no
+    // generation the open can wait for, because the one the stamp names is
+    // gone.
+    return { state: 'torn', stampSource: stamp.sourceGeneration, head }
   }
   if (stamp.sourceGeneration < head) {
     return { state: 'behind', stampSource: stamp.sourceGeneration, head }

src/db/generationSegments.ts

@@ -147,6 +147,60 @@ export class GenerationSegmentStore {
     return this.coveringSegment(gen) !== null
   }
 
+  /**
+   * @description True when `meta` declares more generations than it holds
+   * frames — a segment sealed by a writer that folded across a hole. The
+   * manifest records `frames` at fold time, so this is an O(1) comparison
+   * against the declared span and needs no I/O.
+   */
+  private isSparse(meta: SegmentMeta): boolean {
+    return meta.lastGeneration - meta.firstGeneration + 1 !== meta.frames
+  }
+
+  /**
+   * @description The generations this tier ACTUALLY holds, as coalesced
+   * ascending intervals — not what the segments declare.
+   *
+   * Dense segments (every one a current writer produces) contribute their
+   * declared range with no I/O. A SPARSE segment — one sealed before the
+   * density law was enforced, whose declared range spans generations it has
+   * no frame for — has its real generation list read from its sidecar and
+   * contributed instead, with the discrepancy narrated once.
+   *
+   * This is what keeps a store that already carries the damage from wedging.
+   * `open()` seeds `committedRanges` from these intervals, so a hole is never
+   * re-admitted as a committed generation, and the auto-compaction pass that
+   * used to fail on every run with "packed history is damaged" simply never
+   * asks for the missing frame.
+   *
+   * @returns Ascending, non-overlapping `[first, last]` intervals.
+   */
+  async actualRanges(): Promise<Array<[number, number]>> {
+    const out: Array<[number, number]> = []
+    for (const meta of this.manifest.segments) {
+      if (!this.isSparse(meta)) {
+        out.push([meta.firstGeneration, meta.lastGeneration])
+        continue
+      }
+      const missing = meta.lastGeneration - meta.firstGeneration + 1 - meta.frames
+      prodLog.warn(
+        `[GenerationSegments] sealed segment ${meta.file} declares generations ` +
+          `${meta.firstGeneration}..${meta.lastGeneration} but holds only ${meta.frames} ` +
+          `frame(s) — ${missing} generation(s) in that span were never folded into it. ` +
+          `Serving the frames it actually holds; the declared span is not treated as ` +
+          `committed history. (Written by a pre-density-law writer that folded across a ` +
+          `gap; the segment itself is intact and no record is lost.)`
+      )
+      const idx = await this.sidecarFor(meta)
+      for (const [gen] of idx.generations) {
+        const last = out[out.length - 1]
+        if (last !== undefined && gen === last[1] + 1) last[1] = gen
+        else out.push([gen, gen])
+      }
+    }
+    return out
+  }
+
   /**
    * Fold consecutive generations into ONE new sealed segment + sidecar and
    * append it to the manifest atomically. Caller guarantees: `gens` is
@@ -164,6 +218,38 @@ export class GenerationSegmentStore {
         throw new Error('[GenerationSegments] fold() input must be strictly ascending')
       }
     }
+    // THE DENSITY LAW, MADE MECHANICAL.
+    //
+    // A sealed segment declares a 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. So a
+    // segment folded from a SPARSE input silently claims generations it does
+    // not hold, and the first read of one of those holes throws
+    // "inside sealed segment ... but has no frame — packed history is damaged".
+    //
+    // That is exactly how the damage was produced. `repackHistory` skipped
+    // generations mid-batch — ones absent from committedRanges, ones still in
+    // the pending buffer, ones whose tx.json would not read — and handed the
+    // survivors here, where the range was computed from the first and last of
+    // them. Worse, the mis-declared range was then merged back into
+    // committedRanges at the next open, which is what turned a quiet hole into
+    // a repeating auto-compaction failure on every subsequent run.
+    //
+    // Callers now split at discontinuities; this refusal is what keeps any
+    // future caller from reintroducing the class. A refusal here loses
+    // nothing — the generations stay in the live tier, readable, and the next
+    // pass folds them correctly.
+    for (let i = 1; i < gens.length; i++) {
+      if (gens[i].generation !== gens[i - 1].generation + 1) {
+        throw new Error(
+          `[GenerationSegments] fold() input is not contiguous: ${gens[i - 1].generation} → ` +
+            `${gens[i].generation} skips ${gens[i].generation - gens[i - 1].generation - 1} ` +
+            `generation(s). A sealed segment declares a dense range, so folding a sparse ` +
+            `batch would claim generations it does not hold. Split the batch at the gap.`
+        )
+      }
+    }
     const last = this.manifest.segments[this.manifest.segments.length - 1]
     if (last && gens[0].generation <= last.lastGeneration) {
       throw new Error(
@@ -364,12 +450,37 @@ export class GenerationSegmentStore {
         return this.decodeFrame(payload)
       }
     }
-    // In the covering range but not present: the packed tier is dense by
+    // Inside the covering range but with no frame. Two very different causes,
-    // construction (fold packs every generation it is handed, including
+    // and conflating them is what made this class wedge every maintenance pass
-    // record-less ones) — absence inside a sealed range is damage.
+    // on the affected stores.
+    //
+    // (1) A SPARSE SEGMENT — the manifest's own `frames` count is smaller than
+    //     the span it declares. That segment was sealed by a writer that
+    //     folded across a hole (the class this file's density law now bars).
+    //     The segment is INTACT and nothing is lost; it simply never held this
+    //     generation. Answering "not packed" is the honest answer, and it lets
+    //     the caller's two-tier read decide what a genuinely absent generation
+    //     means, instead of every compaction pass dying on a repeating throw.
+    //     `actualRanges()` keeps such holes out of committedRanges at open, so
+    //     in a healed store nobody asks this question in the first place.
+    //
+    // (2) A DENSE SEGMENT missing a frame it says it has — the manifest and
+    //     the sidecar disagree about a segment that claims to be complete.
+    //     That IS damage, and it stays loud.
+    if (this.isSparse(meta)) {
+      prodLog.warn(
+        `[GenerationSegments] generation ${gen} falls inside sealed segment ${meta.file}'s ` +
+          `declared range ${meta.firstGeneration}..${meta.lastGeneration}, but that segment ` +
+          `holds ${meta.frames} frame(s) for a ${meta.lastGeneration - meta.firstGeneration + 1}` +
+          `-generation span — it was sealed across a gap and never held this generation. ` +
+          `Reporting it as unpacked rather than as damage; no record is lost.`
+      )
+      return null
+    }
     throw new Error(
       `[GenerationSegments] generation ${gen} is inside sealed segment ${meta.file}'s declared ` +
-        `range but has no frame — packed history is damaged`
+        `range but has no frame, and that segment declares a complete ${meta.frames}-frame ` +
+        `span — the manifest and the sidecar disagree; packed history is damaged`
     )
   }
 

src/db/generationStore.ts

@@ -96,6 +96,35 @@ export const FOLD_CHECKPOINT_PATH = '_system/fold-checkpoint.json'
 /** Storage-root-relative prefix of the per-generation record directories. */
 export const GENERATIONS_PREFIX = '_generations'
 
+/**
+ * @description Split an ascending list of fold candidates into maximal
+ * CONTIGUOUS runs — `[7,8,9,12,13]` becomes `[[7,8,9],[12,13]]`.
+ *
+ * A sealed segment declares one dense range `[firstGeneration,
+ * lastGeneration]`, and every reader treats that range as containment. So a
+ * batch with a hole in it must never become one segment: it would claim a
+ * generation it does not hold, and the first read of that hole reports the
+ * packed history as damaged. One run, one segment — the ranges then describe
+ * exactly what the segments contain.
+ *
+ * @param gens - Fold candidates, strictly ascending by generation.
+ * @returns One array per contiguous run, in ascending order. Empty in, empty out.
+ */
+export function contiguousRuns(gens: FoldGeneration[]): FoldGeneration[][] {
+  const runs: FoldGeneration[][] = []
+  let run: FoldGeneration[] = []
+  for (const g of gens) {
+    const prev = run[run.length - 1]
+    if (prev !== undefined && g.generation !== prev.generation + 1) {
+      runs.push(run)
+      run = []
+    }
+    run.push(g)
+  }
+  if (run.length > 0) runs.push(run)
+  return runs
+}
+
 /**
  * @description Phases of the {@link GenerationStore.commitTransaction} commit
  * protocol at which a test-only fault injector can simulate a process crash.
@@ -784,9 +813,15 @@ export class GenerationStore {
     if (storageSupportsFactLog(this.storage)) {
       this.segments = new GenerationSegmentStore(this.storage)
       await this.segments.open()
-      const packedRanges = this.segments
+      // ACTUAL ranges, not declared ones. A segment sealed by a pre-density-law
-        .segments()
+      // writer can declare a span wider than the frames it holds; seeding
-        .map((s): [number, number] => [s.firstGeneration, Math.min(s.lastGeneration, this.committed)])
+      // committedRanges from the declared span re-admits those holes as
+      // committed generations, and every later maintenance pass then asks for a
+      // frame that was never written. `actualRanges()` reads the real
+      // generation list from the sidecar for exactly those segments (and does
+      // no I/O for the dense ones, which is all of them on a healthy store).
+      const packedRanges = (await this.segments.actualRanges())
+        .map((r): [number, number] => [r[0], Math.min(r[1], this.committed)])
         .filter(([lo, hi]) => lo <= hi)
       if (packedRanges.length > 0) {
         // Merge packed (older) + live (newer) interval sets — both ascending;
@@ -3121,13 +3156,26 @@ export class GenerationStore {
           foldInput.push({ generation: gen, timestamp: delta.timestamp, delta, records })
         }
         if (foldInput.length === 0) continue
-        await segments.fold(foldInput)
+        // SPLIT AT DISCONTINUITIES. `eligible` is NOT contiguous — three
-        segmentsCreated++
+        // filters above punch holes in it: a generation missing from
-        // Segment + manifest durable → the live copies retire.
+        // committedRanges never appears, one still in the pending buffer is
-        for (const g of foldInput) {
+        // skipped, and one whose tx.json will not read is skipped. A sealed
-          await this.storage.removeRawPrefix(`${GENERATIONS_PREFIX}/${g.generation}`)
+        // segment declares a DENSE range, so folding across such a hole makes
+        // the segment claim a generation it does not hold; the next open
+        // merges that mis-declared range into committedRanges, and every
+        // subsequent auto-compaction pass then asks for the missing frame and
+        // fails with "packed history is damaged". Fold each contiguous RUN as
+        // its own segment instead — same bytes, honest ranges.
+        for (const run of contiguousRuns(foldInput)) {
+          if (deadline !== undefined && Date.now() >= deadline) break
+          await segments.fold(run)
+          segmentsCreated++
+          // Segment + manifest durable → the live copies retire.
+          for (const g of run) {
+            await this.storage.removeRawPrefix(`${GENERATIONS_PREFIX}/${g.generation}`)
+          }
+          folded += run.length
         }
-        folded += foldInput.length
       }
       if (folded > 0) {
         prodLog.info(

tests/integration/entity-tree-stamp.test.ts

@@ -57,7 +57,11 @@ describe('entity-tree family stamp', () => {
     const invariants = (stamp.members as any).invariants
     expect(invariants.nounCount).toBe(await brain.storage.getNounCount())
     expect(invariants.verbCount).toBe(await brain.storage.getVerbCount())
-    expect(stamp.sourceGeneration).toBe(brain.generation())
+    // THE SOURCE IS COMMITTED TRUTH, never the allocated counter. Stamping the
+    // counter labelled the stamp with a generation a write in flight had merely
+    // claimed, so every crash inside a write window produced a spurious verdict
+    // at the next open (see the torn-tail pins below).
+    expect(stamp.sourceGeneration).toBe(brain.generationStore.committedGeneration())
     expect(stamp.generation).toBeGreaterThanOrEqual(1)
   })
 
@@ -112,6 +116,96 @@ describe('entity-tree family stamp', () => {
     expect(stillIncoherent).toEqual([])
   })
 
+  /**
+   * Rewrite the on-disk stamp so its `sourceGeneration` sits ABOVE the store's
+   * committed watermark — the durable shape a torn generation-log tail leaves
+   * behind (the stamp's fsync outlived the tail's). Fabricated rather than
+   * crash-produced so the pin is deterministic; the seeded-SIGKILL lane
+   * (`scripts/crash-consistency.mjs` in the engine repo) produces the same
+   * shape from a real abrupt termination.
+   */
+  const fabricateTear = (ahead: number): FamilyStamp => {
+    const file = path.join(dir, `${ENTITY_TREE_STAMP_PATH}.gz`)
+    const zlib = require('node:zlib')
+    const raw = JSON.parse(zlib.gunzipSync(fs.readFileSync(file)).toString('utf-8')) as FamilyStamp
+    const torn: FamilyStamp = { ...raw, sourceGeneration: raw.sourceGeneration + ahead }
+    fs.writeFileSync(file, zlib.gzipSync(JSON.stringify(torn)))
+    return torn
+  }
+
+  it('a torn generation-log tail is a TERMINAL VERDICT at open: narrated, demoted, never a wait', async () => {
+    for (let i = 0; i < 3; i++)
+      await brain.add({ data: `torn${i}`, type: 'document', metadata: { i } })
+    await brain.close()
+    const torn = fabricateTear(5)
+
+    const warn = vi.spyOn(prodLog, 'warn')
+    const startedAt = Date.now()
+    brain = await open()
+    const openMs = Date.now() - startedAt
+
+    const tearLines = warn.mock.calls.filter((c) => String(c[0]).includes('TORN GENERATION-LOG TAIL'))
+    expect(tearLines.length).toBe(1)
+    const said = String(tearLines[0][0])
+    // Narrated PRECISELY: both generations, the file, and the named cure.
+    expect(said).toContain(`source generation ${torn.sourceGeneration}`)
+    expect(said).toContain(`committed generation ${brain.generationStore.committedGeneration()}`)
+    expect(said).toContain(ENTITY_TREE_STAMP_PATH)
+    expect(said).toContain('DEMOTED')
+    expect(said).toMatch(/repairIndex\(\)/)
+    // Terminal, not a wait: the demotion is O(1) straight-line work, so a tear
+    // cannot turn an open into the 8-minute spin this class was reported as.
+    expect(openMs).toBeLessThan(30_000)
+
+    // The store SERVES — a tear in a stamp never locks an owner out of the
+    // canonical tree the stamp merely describes.
+    expect((await brain.find({ type: 'document', limit: 100 })).length).toBe(3)
+
+    // The demotion CONVERGED: the stamp now names committed truth, and the
+    // next open is quiet. A verdict that re-narrates every open is a wait
+    // wearing a different hat.
+    const restamped = (await readFamilyStamp(brain.storage, ENTITY_TREE_STAMP_PATH)) as FamilyStamp
+    expect(restamped.sourceGeneration).toBe(brain.generationStore.committedGeneration())
+    await brain.close()
+    const warn2 = vi.spyOn(prodLog, 'warn')
+    brain = await open()
+    expect(warn2.mock.calls.filter((c) => String(c[0]).includes('TORN'))).toEqual([])
+  })
+
+  it('a READ-ONLY open on a torn tail refuses to guess: terminal verdict + named cure, no re-stamp', async () => {
+    await brain.add({ data: 'ro', type: 'document', metadata: {} })
+    await brain.close()
+    const torn = fabricateTear(3)
+
+    const warn = vi.spyOn(prodLog, 'warn')
+    const reader: any = await Brainy.openReadOnly({
+      requireSubtype: false,
+      storage: { type: 'filesystem', path: dir },
+      silent: true,
+      dimensions: 384
+    })
+    const tearLines = warn.mock.calls.filter((c) => String(c[0]).includes('TORN GENERATION-LOG TAIL'))
+    expect(tearLines.length).toBe(1)
+    const said = String(tearLines[0][0])
+    expect(said).toContain('READ-ONLY')
+    expect(said).toContain('UNVERIFIED')
+    expect(said).toMatch(/repairIndex\(\)/)
+    await reader.close()
+
+    // A reader never rewrites the store: read the bytes back off disk (not
+    // through a writer open, which would demote them) — the torn stamp is
+    // exactly as it was found.
+    const onDisk = JSON.parse(
+      require('node:zlib')
+        .gunzipSync(fs.readFileSync(path.join(dir, `${ENTITY_TREE_STAMP_PATH}.gz`)))
+        .toString('utf-8')
+    ) as FamilyStamp
+    expect(onDisk.sourceGeneration).toBe(torn.sourceGeneration)
+    expect(onDisk.generation).toBe(torn.generation)
+
+    brain = await open()
+  })
+
   it('the one verifier handles both member modes', () => {
     const rollup: FamilyStamp = {
       family: 'x',
@@ -127,7 +221,13 @@ describe('entity-tree family stamp', () => {
       stampSource: 5,
       head: 9
     })
-    expect(verifyFamilyStamp(rollup, 3, { nounCount: 10 }).state).toBe('incoherent') // ahead of head
+    // AHEAD is its own class — a torn generation-log tail, never folded in
+    // with `incoherent`: the two have opposite cures (recount vs demote).
+    expect(verifyFamilyStamp(rollup, 3, { nounCount: 10 })).toEqual({
+      state: 'torn',
+      stampSource: 5,
+      head: 3
+    })
     expect(verifyFamilyStamp(null, 5, {})).toEqual({ state: 'absent' })
 
     const enumerated: FamilyStamp = {

tests/integration/history-repacking.test.ts

@@ -16,6 +16,7 @@ import { describe, it, expect, afterEach } from 'vitest'
 import * as fs from 'node:fs'
 import * as path from 'node:path'
 import * as os from 'node:os'
+import * as zlib from 'node:zlib'
 import { Brainy } from '../../src/brainy.js'
 import { NounType } from '../../src/types/graphTypes.js'
 import { GenerationStore } from '../../src/db/generationStore.js'
@@ -57,6 +58,107 @@ describe('history repacking — the two-tier lifecycle', () => {
     }
   })
 
+  /**
+   * THE HOLE, END TO END — the shape a real store carries.
+   *
+   * A forensic fixture was measured with generation directories 1..2503
+   * present except for exactly one: 1416. Its fact-log segment already showed
+   * the tell — `seg-...1410.bfl` declaring firstGeneration 1410, lastGeneration
+   * 1940 (531 generations) while recording only 530 facts.
+   *
+   * Before the fix, repacking such a store folded ACROSS that hole: the batch
+   * skipped 1416 (no readable delta) and the sealed segment declared a range
+   * spanning it anyway. The next open merged that declared range back into
+   * committedRanges, re-admitting 1416 as committed history, and every
+   * subsequent auto-compaction pass then asked the packed tier for a frame
+   * that was never written — producing, on EVERY run, the non-fatal narration
+   *
+   *   Auto-compaction of generational history failed (non-fatal): generation
+   *   N is inside sealed segment seg-....bgs's declared range but has no frame
+   *   — packed history is damaged
+   *
+   * This pin removes a generation directory to make the same hole, then
+   * requires repack + reopen + compaction to complete cleanly.
+   */
+  it('a missing generation directory does not poison the packed tier', async () => {
+    const dir = tempDir()
+    // `retention: 'all'` throughout: close() otherwise auto-compacts the
+    // history away, and this pin needs the cold generations still on disk so
+    // there is something to punch a hole in. The live window stays at its
+    // production default for the build phase, so nothing folds yet.
+    const archival = async (): Promise<Brainy> => {
+      const b = new Brainy({
+        requireSubtype: false,
+        storage: { type: 'filesystem', path: dir },
+        embeddingFunction: stub,
+        retention: 'all'
+      })
+      await b.init()
+      return b
+    }
+    const brain = await archival()
+
+    const id = await brain.add({
+      data: 'holed-entity',
+      type: NounType.Document,
+      metadata: { v: 0 }
+    })
+    // One flush per update: single-op writes coalesce inside a flush window,
+    // so a history deep enough to have a middle needs the windows separated.
+    for (let v = 1; v <= 12; v++) {
+      await brain.update({ id, metadata: { v } })
+      await brain.flush()
+    }
+    await brain.close()
+
+    // Punch the hole: delete ONE generation directory in the middle of the
+    // cold range, exactly as the real store presents it.
+    const genRoot = path.join(dir, '_generations')
+    const numeric = fs
+      .readdirSync(genRoot, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && /^\d+$/.test(e.name))
+      .map((e) => Number(e.name))
+      .sort((a, b) => a - b)
+    expect(numeric.length).toBeGreaterThan(6)
+    const victim = numeric[Math.floor(numeric.length / 2)]
+    fs.rmSync(path.join(genRoot, String(victim)), { recursive: true, force: true })
+
+    // Now shrink the live window and reopen. close() repacks automatically
+    // (brainy.ts phase 0b), so this is the production sequence exactly: a
+    // store with a hole in its history gets folded by ordinary housekeeping,
+    // with nobody asking for it.
+    ;(GenerationStore as any).REPACK_LIVE_WINDOW = 3
+    const reopened = await archival()
+    const result = await reopened.repackHistory()
+    expect(result.foldedGenerations).toBeGreaterThan(0)
+
+    const segDir = path.join(dir, SEGMENTS_PREFIX)
+    const manifestPath = ['manifest.json', 'manifest.json.gz']
+      .map((f) => path.join(segDir, f))
+      .find((p) => fs.existsSync(p))!
+    const raw = manifestPath.endsWith('.gz')
+      ? zlib.gunzipSync(fs.readFileSync(manifestPath)).toString('utf8')
+      : fs.readFileSync(manifestPath, 'utf8')
+    const manifest = JSON.parse(raw) as {
+      segments: Array<{ firstGeneration: number; lastGeneration: number; frames: number }>
+    }
+
+    // THE LAW: every sealed segment declares exactly as many generations as it
+    // holds frames, and none of them spans the victim.
+    for (const s of manifest.segments) {
+      expect(s.lastGeneration - s.firstGeneration + 1).toBe(s.frames)
+      expect(victim >= s.firstGeneration && victim <= s.lastGeneration).toBe(false)
+    }
+
+    await reopened.close()
+
+    // And the pass that used to fail on every run now completes: reopen (which
+    // re-seeds committedRanges from the packed tier) then compact history.
+    const third = await openBrain(dir)
+    await expect(third.compactHistory({ maxGenerations: 2 })).resolves.toBeDefined()
+    await third.close()
+  })
+
   it('repack preserves every historical read across cold reopen; folded dirs are gone', async () => {
     ;(GenerationStore as any).REPACK_LIVE_WINDOW = 3
     const dir = tempDir()

tests/unit/db/generation-segments.test.ts

@@ -147,4 +147,119 @@ describe('db/GenerationSegmentStore — the D1+D3 packed tier', () => {
     await expect(store.fold([gen(4), gen(4)])).rejects.toThrow(/strictly ascending/)
     await expect(store.fold([])).rejects.toThrow(/at least one generation/)
   })
+
+  // ==========================================================================
+  // THE DENSITY LAW
+  // ==========================================================================
+  //
+  // A sealed segment declares a CONTIGUOUS range and every reader treats that
+  // range as containment. Folding a sparse batch therefore makes the segment
+  // claim generations it does not hold — and because `open()` merges declared
+  // ranges back into committedRanges, the hole is re-admitted as committed
+  // history and every later maintenance pass fails asking for a frame that was
+  // never written. That is the "generation N is inside sealed segment
+  // seg-....bgs's declared range but has no frame — packed history is damaged"
+  // narration seen on every run of the affected stores.
+
+  it('fold REFUSES a batch with a hole — a dense range may not be declared over sparse input', async () => {
+    await expect(store.fold([gen(1), gen(2), gen(4)])).rejects.toThrow(
+      /not contiguous: 2 → 4 skips 1 generation/
+    )
+    // The refusal loses nothing: no segment was sealed, so the generations
+    // stay in the live tier and the next pass folds them correctly.
+    expect(store.segments()).toHaveLength(0)
+    expect(store.hasGeneration(1)).toBe(false)
+  })
+
+  it('a wider gap names how many generations it would have swallowed', async () => {
+    await expect(store.fold([gen(10), gen(20)])).rejects.toThrow(
+      /not contiguous: 10 → 20 skips 9 generation\(s\)/
+    )
+  })
+
+  it('two contiguous runs folded separately declare honest ranges', async () => {
+    // What the caller now does instead of folding across the gap.
+    const a = await store.fold([gen(1), gen(2), gen(3)])
+    const b = await store.fold([gen(7), gen(8)])
+    expect(a).toMatchObject({ firstGeneration: 1, lastGeneration: 3, frames: 3 })
+    expect(b).toMatchObject({ firstGeneration: 7, lastGeneration: 8, frames: 2 })
+    // The gap is honestly outside the packed tier.
+    for (const g of [4, 5, 6]) expect(store.hasGeneration(g)).toBe(false)
+    for (const g of [1, 2, 3, 7, 8]) expect(store.hasGeneration(g)).toBe(true)
+    expect(await store.actualRanges()).toEqual([
+      [1, 3],
+      [7, 8]
+    ])
+  })
+
+  it('actualRanges() is exact and I/O-free for dense segments', async () => {
+    await store.fold([gen(1), gen(2)])
+    await store.fold([gen(3), gen(4)])
+    // Adjacent dense segments each contribute their declared range.
+    expect(await store.actualRanges()).toEqual([
+      [1, 2],
+      [3, 4]
+    ])
+  })
+
+  // ---- pre-existing damage: a store sealed by the old writer ----------------
+
+  /**
+   * Seal a SPARSE segment the way the pre-fix writer did: write the bytes and
+   * sidecar for a contiguous run, then rewrite the manifest so the segment
+   * declares a wider range than the frames it holds. This reproduces on disk
+   * exactly what the affected stores carry, without needing the old code.
+   */
+  const sealSparseSegment = async (): Promise<void> => {
+    await store.fold([gen(1), gen(2), gen(3)])
+    const manifest = (await storage.readRawObject(`${SEGMENTS_PREFIX}/manifest.json`)) as any
+    // Declare 1..5 while holding frames for 1..3 — generations 4 and 5 become
+    // holes inside a sealed range.
+    manifest.segments[0].lastGeneration = 5
+    await storage.writeRawObject(`${SEGMENTS_PREFIX}/manifest.json`, manifest)
+  }
+
+  it('a pre-existing sparse segment reports its holes as UNPACKED, not as damage', async () => {
+    await sealSparseSegment()
+    const reopened = new GenerationSegmentStore(storage as any)
+    await reopened.open()
+
+    // The frames it really holds still serve, byte-faithfully.
+    expect((await reopened.readDelta(2))?.timestamp).toBe(1_700_000_000_002)
+    expect(await reopened.readRecords(3)).toHaveLength(2)
+
+    // The holes answer "not packed" instead of throwing. This is the fix for
+    // the wedge: the old reader threw here on EVERY maintenance pass.
+    expect(await reopened.readDelta(4)).toBeNull()
+    expect(await reopened.readRecords(5)).toBeNull()
+  })
+
+  it('actualRanges() excludes the holes so they are never re-admitted as committed', async () => {
+    await sealSparseSegment()
+    const reopened = new GenerationSegmentStore(storage as any)
+    await reopened.open()
+    // Declared 1..5; actually holds 1..3. The store seeds committedRanges from
+    // THIS, so generations 4 and 5 never become committed history again.
+    expect(await reopened.actualRanges()).toEqual([[1, 3]])
+  })
+
+  it('a DENSE segment missing a frame is still loud damage', async () => {
+    // The other side of the branch: when the manifest claims a complete span,
+    // a missing frame means the manifest and sidecar disagree — real damage,
+    // and it must not be quietly downgraded to "unpacked".
+    await store.fold([gen(1), gen(2), gen(3)])
+    const idxPath = `${SEGMENTS_PREFIX}/seg-${String(1).padStart(20, '0')}.idx`
+    const raw = (await storage.readRawBytes(idxPath))!
+    const { decode, encode } = await import('@msgpack/msgpack')
+    const idx = decode(raw) as any
+    // Drop generation 2's entry while the manifest still declares 3 frames.
+    idx.generations = idx.generations.filter(([g]: [number]) => g !== 2)
+    await storage.writeRawBytes(idxPath, encode(idx))
+
+    const reopened = new GenerationSegmentStore(storage as any)
+    await reopened.open()
+    await expect(reopened.readDelta(2)).rejects.toThrow(
+      /manifest and the sidecar disagree; packed history is damaged/
+    )
+  })
 })

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