@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/package-core.js

@@ -0,0 +1,1200 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/bongos/package-core.js — produce the Cloud Bongos CORE as a versioned,
+// installable, PINNABLE artifact a downstream project vendors.
+// GDS-V4 R84 (task 1688), implementing ADR 0100 §1 (the two-repo instance model).
+//
+// This is the FIRST step of the R84 → R85 → R86 spine: package the core (here) →
+// stand Mercury up on a pinned core (R85, #1689) → make `bongos upgrade` a real
+// update-consumption channel (R86, #1690). A Cloud Bongos *instance* may be a
+// SEPARATE repository that installs a pinned version of this core and layers its
+// own content/branding/modules on top (the physical realization of ADR 0062 §1).
+//
+// WHAT "the core" IS — reused, never re-defined:
+//   The core is exactly the subtree scripts/bongos/publish-manifest.isPublishable()
+//   already defines (ADR 0098) — the portable methodology + platform + neutral
+//   branding. There is NO second allow-list here; this tool CONSUMES that one.
+//
+// HOW IT DIFFERS FROM public-mirror-export.js (R72 / ADR 0099):
+//   - The mirror is the DELAYED (≈6-month), redacted, PUBLIC open-source surface —
+//     a whole separate git repo, published on a schedule. Its job is transparency,
+//     so it REDACTS every file (topology + brand kept out of a world-readable repo).
+//   - This artifact is a CURRENT, versioned, installable UNIT a downstream repo
+//     vendors + pins to a version. Its job is dependency consumption. No lag. It must
+//     BOOT, so functional files ship VERBATIM — redacting them corrupts npm integrity
+//     hashes + SQL identifiers (the R88 boot failure; task 1824). Only DOCS (.md) are
+//     genericized; brand/topology in code ships as-is (public, not secrets).
+//   The two share the same file SELECTION (isPublishable) and REUSE the same redaction
+//   primitives (redactBlob/findLeaks), but apply them differently — see processCoreFile.
+//
+// ONE FAIL-CLOSED PASS (task 1824 — docs redacted, functional verbatim):
+//   1. Resolve the source ref → commit; enumerate its tree (git ls-tree).
+//   2. PARTITION through isPublishable() — the single source of truth.
+//   3. Per file, IN MEMORY (processCoreFile): DOCS (.md) are genericized + secret-scrubbed
+//      like the mirror; FUNCTIONAL files are kept VERBATIM and scanned only for an exact
+//      live-credential leak (brand/IP hits are non-fatal ADVISORIES, surfaced for a human).
+//   3b. RELEASE NOTES (task 1004218): release-notes.json — what each release brought in,
+//      generated from the ref's HISTORY (scripts/bongos/release-notes.js), its prose redacted
+//      exactly like a doc, and pinned like every other file. Skipped, with a line saying
+//      so, where there is no history to read (--from-worktree, a shallow clone).
+//   4. NO-LEAK GATE (fail-closed): if any DOC leaks post-redaction, or any FUNCTIONAL file
+//      carries a live credential verbatim, PRODUCE NOTHING — dist/ is never touched. The
+//      in-memory pass makes the abort atomic (same discipline as the mirror export).
+//   5. Only when the whole set is clean: write the tree to
+//      dist/bongos-core-<version>/, the .tgz, and the pin MANIFEST.
+//
+// THE VERSION STAMP is the platform version — src/module-api.js CORE_VERSION,
+// read via the SAME fail-soft accessor scripts/bongos/module.js + bongos upgrade use
+// (task 1203). That shared coordinate is what keeps the R84→R86 spine coherent.
+//
+// THE PIN is `tree_sha256` in the manifest: a canonical hash over the redacted
+// core files (path\0mode\0filehash per line, sorted). It is INDEPENDENT of the
+// tar/gzip byte layout, so a consumer pins on { core_version, source_commit,
+// tree_sha256 } and verifies an install by recomputing it from the unpacked tree.
+// The manifest ALSO records tarball.sha256 to verify the exact downloaded bytes.
+//
+// USAGE:
+//   node scripts/bongos/package-core.js [--ref <git-ref> | --from-worktree] [--out-dir dist]
+//        [--version <v>] [--droplet-ip <ip>] [--self-verify [--self-verify-boot]] [--publish [--live]]
+//   Defaults: --ref HEAD, --out-dir dist, --version = platform CORE_VERSION.
+//   --from-worktree  build from the files ON DISK instead of a commit, for a core checkout
+//                    that carries no git history — which is exactly what the shipped
+//                    self-host image is (.dockerignore excludes .git by design), and the
+//                    only way the provisioning scaffold inside it can vendor a core into a
+//                    child instance (task 1003995). Selection is unchanged (isPublishable);
+//                    the artifact simply has no commit to anchor to, so source_commit is null
+//                    and the tree_sha256 pin is the whole lineage. It packages what is ON DISK,
+//                    which in the image is exactly what `COPY . .` put there — so on a DEV
+//                    checkout prefer the ref build: measured on this repo the two select an
+//                    IDENTICAL 2793-file set, but a Windows working tree hands back CRLF where
+//                    the blob is LF, which changes every text file's hash and would ship a
+//                    CRLF shebang. That is why rung 4 in provision-repo.js is reached only
+//                    when there is no history to build from.
+//   --self-verify    after building, prove the artifact reproduces its pin (unpack the .tgz,
+//                    recompute tree_sha256 == manifest + verify tarball.sha256). Fatal on mismatch.
+//                    (task 1002218 / audit H3) — deterministic + network-free.
+//   --self-verify-boot   ALSO `npm install <tgz>` into a throwaway consumer + boot /healthz
+//                    (reuses tests/consumer_layout_boot.mjs; needs npm/registry access).
+//   --no-leak-scan   THE ONLY ESCAPE from the post-build leak scan: skips it entirely.
+//                    The scan is FAIL-CLOSED by default — an un-allowlisted prior-instance
+//                    literal in the built artifact aborts the build (task 1003870 / H6).
+//   --leak-scan-strict   accepted as an explicit no-op; fatal IS the default since task
+//                    1003870. Kept so CI can state the intent it relies on out loud.
+//   Outputs (nothing is committed — dist/ is gitignored):
+//     dist/bongos-core-<version>/           the redacted core tree (inspectable)
+//     dist/bongos-core-<version>.tgz        the installable unit
+//     dist/bongos-core-<version>.manifest.json   the PIN (tree hash + per-file hashes)
+//   --publish        after building, `npm publish` the .tgz as a PUBLIC scoped
+//                    package (--access public). DRY-RUN unless --live is added
+//                    (task 1003872 / ADR 0283, superseding ADR 0134's restricted
+//                    posture). Needs `npm login` as a member of the @bongos org;
+//                    this script holds no token.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const zlib = require('node:zlib');
+const crypto = require('node:crypto');
+const { execFileSync, spawnSync } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// Reuse — never re-type. The core definition, the redaction, and the tree parser
+// all already exist and are unit-tested at their homes.
+const { isPublishable, PUBLISH_ALLOWLIST } = require(path.join(REPO_ROOT, 'scripts/bongos/publish-manifest.js'));
+const { sha256hex, canonicalTreeHash, normalizeMode, octal, tarChecksum, ustarHeader, splitUstarName, buildTar } = require('./artifact-format');
+const {
+  buildRedactionRules, collectSensitiveLiterals, findLeaks,
+} = require(path.join(REPO_ROOT, 'scripts/bongos/mirror-redact.js'));
+const { collectEnvSecrets } = require(path.join(REPO_ROOT, 'modules/security/secret-scrub.js'));
+const { redactBlob, parseLsTree } = require(path.join(REPO_ROOT, 'scripts/public-mirror-export.js'));
+const { partitionHits, unusedEntries } = require(path.join(REPO_ROOT, 'scripts/bongos/leak-scan-allowlist.js'));
+// The release notes shipped beside package.json (task 1004218). Required by a literal path:
+// the module is pure and requires nothing, so it adds no computed require to this file's
+// executed closure (tests/executed_closure.mjs counts those).
+const {
+  RELEASE_NOTES_FILE, RELEASE_NOTES_MAX_BYTES, generateReleaseNotes, boundReleaseNotes, serializeReleaseNotes,
+} = require('./release-notes.js');
+
+// The generated API spec, reference and typed client (task 1004866): gitignored, so never
+// in a ref's tree — generated into every tarball by generateApiArtifacts() below.
+const { API_ARTIFACT_PATHS } = require('./api-artifacts.js');
+
+const MANIFEST_SCHEMA = 1;
+const ARTIFACT_NAME = 'bongos-core';
+// The tar internal root MUST be `package/` — that is the one hardcoded npm
+// convention for an installable tarball (`npm install ./x.tgz` / `npm pack`
+// output both use it; npm does not read the directory name to find package.json,
+// it always looks for `package/package.json`). The ARTIFACT_NAME-named on-disk
+// stage dir (stageDirName, below) is unrelated — that is just a local inspection
+// path, not what ships inside the .tgz (ADR 0108 §2, task 1882).
+const TAR_ROOT = 'package/';
+// The self-describing manifest carried INSIDE the artifact (minus tarball.* — a
+// file cannot contain its own hash). The authoritative PIN is the side-car next
+// to the .tgz, which adds tarball.{sha256,bytes}.
+const INNER_MANIFEST = `${TAR_ROOT}.bongos-core.json`;
+
+// ---------------------------------------------------------------------------
+// The platform version — read CORE_VERSION via the doorway, lazily + fail-soft,
+// mirroring scripts/bongos/module.js:coreVersion() so this artifact stamps the SAME
+// coordinate `bongos upgrade` and the module loader compare against (task 1203).
+// ---------------------------------------------------------------------------
+function coreVersion() {
+  try { return require(path.join(REPO_ROOT, 'src/module-api')).CORE_VERSION; }
+  catch { return '1.0.0'; }
+}
+
+// ---------------------------------------------------------------------------
+// Pure helpers (exported for tests — no I/O, no git, no network)
+// ---------------------------------------------------------------------------
+
+
+// ---------------------------------------------------------------------------
+// CONSUMER-CORE extraction policy (task 1824) — the file-classification layer.
+//
+// The R84 packager wrongly reused the PUBLIC-MIRROR redaction (redactBlob) over EVERY
+// file, which CORRUPTED the functional core: the secret scrubber blanks npm integrity
+// hashes (base64 → looks secret) + Postgres identifiers (matched an env-secret substring),
+// which broke `npm ci` and turned 63 migrations into `CREATE FUNCTION <redacted>()` SQL
+// errors — the R88 boot failure (proof: docs/reviews/2026-07-03-cloud-bongos-separation-proof.md).
+//
+// The correction: the consumer core takes FUNCTIONAL files (code, SQL, JSON, lockfiles —
+// everything that is not a .md doc) VERBATIM. Redaction stays a DOCS + public-mirror
+// concern (ADR 0099). Brand identity (domain/owner/world) and the droplet IP legitimately
+// pepper the functional core — hall-link comments (`example.com/builders#/task/N`), the
+// `DROPLET` deploy constant in ship.js, seed migrations — and are PUBLIC, not secrets, so
+// they ship as-is (a downstream instance rebrands via config) and are only WARNED about,
+// never scrubbed or aborted-on. Aborting on them would fail ~189 files and the extraction
+// would never succeed. The ONE hard gate on a functional file is an exact live-CREDENTIAL
+// match (an env-secret VALUE appearing verbatim) — that IS a real leak. Genuine secrets are
+// already kept out at SOURCE (husky + CI TruffleHog) and .env* is manifest-excluded, so this
+// gate has ~zero false positives (a real high-entropy token never appears by accident).
+// ---------------------------------------------------------------------------
+const DOC_RE = /\.(md|markdown)$/i;
+function isDocPath(p) { return DOC_RE.test(String(p || '')); }
+
+// ---------------------------------------------------------------------------
+// Agent-doc STUB (task 2121; surfaced by the 2026-07-08 demo task-creation audit).
+// Claude Code AUTO-LOADS the nearest file named CLAUDE.md (or AGENTS.md) into the
+// live session whenever an agent opens a sibling file. In a CONSUMER instance the
+// core installs at node_modules/@bongos/core/, so the core repo's OWN CLAUDE.md tree
+// (root + scripts/bongos + src/bongos + every module) would silently inject the
+// platform's project memory — wrong project title, hundreds of lines, dangling links
+// — into the instance's context the moment an agent reads any core file.
+//   The PUBLIC MIRROR deliberately publishes CLAUDE.md as the portable methodology
+// (ADR 0065 §4), so this cannot live in the shared publish-manifest — it is a
+// package-core-only transform. We keep the files PRESENT (nothing that probes for
+// them by path breaks) but replace their body with a tiny, brand-free stub, turning
+// the auto-load into a harmless "this doesn't govern you" redirect.
+const AGENT_DOC_RE = /(^|\/)(CLAUDE|AGENTS)\.md$/i;
+function isAgentDoc(p) { return AGENT_DOC_RE.test(String(p || '')); }
+const CORE_AGENT_DOC_STUB = `# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
+
+This file is a placeholder shipped inside the **@bongos/core** package. The core's own
+internal agent notes are intentionally omitted from the published artifact so they cannot
+load into your instance's context.
+
+**It does not govern this repository.** Your own root \`CLAUDE.md\`, your \`.claude/\`
+directory, and the live Bongos database are the source of truth for how work happens here
+and who may do what.
+
+You are seeing this only because an agent opened a file under \`node_modules/@bongos/core/\`.
+Nothing in here needs to be read to use the platform — run \`bongos help\` for commands.
+
+_To work ON the platform core itself, use the standalone @bongos/core source repository,
+not this vendored copy._
+`;
+
+// Fail-loud gate for a FUNCTIONAL file: only an exact live-credential value (an env-secret
+// VALUE present verbatim, >= 8 chars) is a real leak. The sample is withheld (it's a secret).
+function functionalSecretLeaks(view, envSecrets) {
+  const out = [];
+  for (const s of envSecrets || []) {
+    if (typeof s === 'string' && s.length >= 8 && view.includes(s)) out.push({ label: 'live-credential' });
+  }
+  return out;
+}
+
+// Classify + process one publishable file → { buf, leaks, advisories, kind }.
+//   * DOC (.md): genericized + secret-scrubbed like the mirror (redactBlob), gated with the
+//     full detector — a downstream's vendored ADRs/recipes should not carry this brand. Any
+//     residual leak after redaction is FATAL (`leaks`).
+//   * FUNCTIONAL: VERBATIM buffer. `leaks` = exact live-credential matches only (FATAL).
+//     `advisories` = brand-identity substrings + public IPs that ship as-is (non-fatal, for
+//     human awareness) — REUSES findLeaks so the detector is defined once.
+function processCoreFile({ pathRel, raw, rules, sensitiveLiterals, envSecrets, knownDocNames }) {
+  // An auto-loaded agent doc (CLAUDE.md/AGENTS.md) → ship a brand-free stub, never the
+  // core's own project memory (task 2121). The stub is brand-free by construction, so it
+  // needs no redaction and can never leak — it short-circuits ahead of the doc path.
+  if (isAgentDoc(pathRel)) {
+    return { buf: Buffer.from(CORE_AGENT_DOC_STUB, 'utf8'), leaks: [], advisories: [], kind: 'stub' };
+  }
+  if (isDocPath(pathRel)) {
+    const r = redactBlob({ buf: raw, rules, sensitiveLiterals, envSecrets, knownDocNames });
+    const leaks = r.leaks.map((l) => ({ label: `doc:${l.label}`, sample: l.sample }));
+    if (r.secret) leaks.push({ label: 'doc:secret-shape' });
+    return { buf: r.buf, leaks, advisories: [], kind: 'doc' };
+  }
+  const view = raw.toString('latin1'); // ASCII-safe byte view for both text + binary
+  return {
+    buf: raw,
+    leaks: functionalSecretLeaks(view, envSecrets),
+    advisories: findLeaks(view, sensitiveLiterals),
+    kind: 'functional',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// npm-STRIPPED special files (idea 1000543) — the file-SELECTION gate that keeps
+// the pin HONEST about what a consumer actually installs.
+//
+// `npm install <tgz>` never materializes certain special files into the installed
+// package — most notably `.gitignore` (confirmed live: installing the 1.18.1 core
+// .tgz drops exactly one file, ./.gitignore), plus `.npmignore` and `.npmrc`. But
+// package-core enumerates the GIT tree, so isPublishable() happily selects a tracked
+// `.gitignore`. If it lands in the manifest files[] + tree_sha256 pin, the tree a
+// consumer recomputes over node_modules/@bongos/core is MISSING it → verifyInstalledPin
+// (upgrade.js) reports `missing installed file: .gitignore` → hash mismatch → the bump
+// auto-rolls-back. That breaks EVERY vendored `bongos upgrade` with pin-verify ON, and
+// the unattended auto-upgrade subscription (task 2150 / ADR 0136) has no way to pass
+// --skip-pin-verify — so it would roll back every patch (the fix reported in idea 1000543).
+//
+// The manifest must describe exactly what npm installs, so these files are dropped BEFORE
+// they enter the tarball, filesMeta, or the pin (main(), below). Matched by BASENAME at any
+// depth — npm strips nested ones too. The asymmetry is deliberately safe: excluding a file
+// npm WOULD have kept only slightly weakens the pin (verifyInstalledPin iterates the manifest
+// files[], so an un-pinned file is simply not checked); FAILING to exclude one npm strips is
+// FATAL. And these files are useless inside a vendored dependency anyway.
+const NPM_STRIPPED_BASENAMES = new Set(['.gitignore', '.npmignore', '.npmrc']);
+function isNpmStripped(pathRel) {
+  const base = String(pathRel || '').split('/').pop();
+  return NPM_STRIPPED_BASENAMES.has(base);
+}
+
+// ---------------------------------------------------------------------------
+// The CORE's own package.json + package-lock.json (task 1882, ADR 0108 §2).
+//
+// The source repo's package.json/package-lock.json (isPublishable() includes
+// both) are GAME-heavy — colyseus/phaser/sharp/discord.js plus the repo's own
+// name/version — and are not what a downstream `npm install @bongos/core`
+// should see. These two files are SYNTHESIZED here (never copied verbatim from
+// git) and staged in their place. Everything else still ships through the
+// normal isPublishable()/processCoreFile path.
+//
+// Core deps are express + pg + pino (+ an undici pin) — ADR 0108 §Context.
+// pino joined the core boot path with the structured logger (task 1003130:
+// platform-server → serve-internal → routes → middleware/audit → logger); a
+// published core without it crashes MODULE_NOT_FOUND at startup (task 1003160).
+// discord.js (+ its undici requirement) is an OPTIONAL MODULE dependency, not
+// core; a consumer that enables the discord module installs it itself.
+const CORE_DEP_NAMES = ['express', 'pg', 'pino'];
+
+// Pure — takes the source package.json's `dependencies`/`overrides` as plain
+// objects so this is unit-testable with no disk I/O. Throws if a required core
+// dep is missing from the source (a real inconsistency, not a silent drop).
+function buildPackageJson({ version, sourceDeps, sourceOverrides }) {
+  const dependencies = {};
+  for (const name of CORE_DEP_NAMES) {
+    const range = sourceDeps && sourceDeps[name];
+    if (!range) throw new Error(`package-core: source package.json is missing required core dependency "${name}"`);
+    dependencies[name] = range;
+  }
+  const pkg = {
+    name: '@bongos/core',
+    version,
+    description: 'Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).',
+    license: 'AGPL-3.0-or-later',
+    main: 'src/platform-server.js',
+    bin: { bongos: 'bin/bongos.js' },
+    // Named exports a consumer imports directly, alongside the default entry
+    // (buildPlatformApp, from `main`). Two groups:
+    //   • the platform surface — serve-internal (the shared host-routing surface
+    //     both server.js and platform-server.js call) + the module-api doorway a
+    //     module's routes/seams are authored against.
+    //   • the GAME-HOST KIT (rehearsal F3, task 2161) — the core internals a
+    //     game-bearing instance's own entrypoint (server.js, kept host per task
+    //     2134) wires directly: the API-404 shaping, the uptime poller, the module
+    //     loader, the enabled-module gate, and the seam registry. A game-less
+    //     instance boots via `.`/platform-server.js and never imports these; a game
+    //     instance's server.js requires them, and the cutover codemod
+    //     (scripts/bongos/cutover-codemod.js) rewrites its relative `./src/*` requires
+    //     to exactly these subpaths. Every subpath the codemod's CORE_INTERNAL_MAP
+    //     targets MUST appear here or the rewritten require won't resolve.
+    exports: {
+      '.': './src/platform-server.js',
+      './serve-internal': './src/bongos/serve-internal.js',
+      './module-api': './src/module-api.js',
+      './bongos/api-path-404': './src/bongos/api-path-404.js',
+      './module-loader/loader': './src/module-loader/loader.js',
+      './modules': './src/modules.js',
+      './module-seams': './src/module-seams.js',
+    },
+    engines: { node: '>=22' },
+    // Distribution posture: PUBLIC (task 1003872, ADR 0283 — supersedes ADR 0134's
+    // pre-launch `restricted`). The private posture existed so a pre-launch artifact
+    // could not leak; what it actually cost was that a tokenless `npm install` 404s,
+    // which broke every co-tenant upgrade, the nightly auto-upgrade sweep (silently,
+    // since 2026-08-25), and every newly scaffolded instance.
+    //
+    // The safety this replaces is NOT "nobody can read it" — it is the three gates
+    // that now run on every build: the branding/credential no-leak gate, the
+    // prior-instance leak scan (fatal by default since task 1003870), and the
+    // fixture confirmation of task 1003871. Those decide what is IN the tarball;
+    // access decides who may fetch it. Do not re-conflate them.
+    publishConfig: { access: 'public' },
+    dependencies,
+  };
+  if (sourceOverrides && sourceOverrides.undici) pkg.overrides = { undici: sourceOverrides.undici };
+  return pkg;
+}
+
+// ---------------------------------------------------------------------------
+// package-lock.json pruning — restrict the shipped lockfile to the CORE's own
+// dependency closure (express + pg), dropping the game's ~225 other transitive
+// packages. Pure + OFFLINE: walks the EXISTING (already-resolved) lockfile
+// graph with the same node_modules lookup order Node's own require() uses
+// (check "<pkgPath>/node_modules/<dep>", then walk up stripping the trailing
+// "node_modules/<segment>" and retry, up to the top-level "node_modules/<dep>")
+// rather than re-resolving against the npm registry — so packaging never needs
+// network access, and can never disagree with how the source lockfile itself
+// was resolved (verified against the live 307-package lockfile: an 82-package
+// closure, including the nested send/node_modules/ms version-conflict case).
+// ---------------------------------------------------------------------------
+
+// Resolve `depName` as required FROM `fromPath` (a "node_modules/..." packages
+// key, or '' for the root) against `packages` — returns the matching key, or
+// undefined if genuinely absent.
+function resolveLockDep(packages, fromPath, depName) {
+  const segments = fromPath ? fromPath.split('/node_modules/') : [];
+  for (let i = segments.length; i >= 0; i--) {
+    const prefix = segments.slice(0, i).join('/node_modules/');
+    const candidate = prefix ? `${prefix}/node_modules/${depName}` : `node_modules/${depName}`;
+    if (packages[candidate]) return candidate;
+  }
+  return undefined;
+}
+
+// BFS the dependency + optionalDependency closure of `rootDepNames` from the
+// lockfile root. Throws on an unresolvable dependency — a real lockfile
+// inconsistency, not something to silently drop from the shipped artifact.
+function lockfileClosure(packages, rootDepNames) {
+  const keep = new Set();
+  const queue = [];
+  for (const name of rootDepNames) {
+    const key = resolveLockDep(packages, '', name);
+    if (!key) throw new Error(`package-core: lockfile has no resolved entry for root dependency "${name}"`);
+    queue.push(key);
+  }
+  while (queue.length) {
+    const key = queue.shift();
+    if (keep.has(key)) continue;
+    keep.add(key);
+    const deps = { ...(packages[key].dependencies || {}), ...(packages[key].optionalDependencies || {}) };
+    for (const depName of Object.keys(deps)) {
+      const depKey = resolveLockDep(packages, key, depName);
+      if (!depKey) throw new Error(`package-core: lockfile has no resolved entry for "${depName}" required by "${key}"`);
+      if (!keep.has(depKey)) queue.push(depKey);
+    }
+  }
+  return keep;
+}
+
+// Pure — takes the already-parsed source lockfile + the CORE's own
+// name/version/dependency-ranges (the same ranges buildPackageJson emitted, so
+// the two files never drift). `rootDepNames` defaults to CORE_DEP_NAMES.
+function prunePackageLock(sourceLock, { name, version, rootRanges, rootDepNames = CORE_DEP_NAMES }) {
+  const packages = sourceLock.packages || {};
+  const keep = lockfileClosure(packages, rootDepNames);
+  const prunedPackages = {
+    '': { name, version, license: 'AGPL-3.0-or-later', dependencies: { ...rootRanges } },
+  };
+  for (const key of [...keep].sort()) prunedPackages[key] = packages[key];
+  return {
+    name,
+    version,
+    lockfileVersion: sourceLock.lockfileVersion,
+    requires: true,
+    packages: prunedPackages,
+  };
+}
+
+// The PIN (canonicalTreeHash) and normalizeMode live in scripts/bongos/artifact-format.js
+// (task 1004271) — the module store verifies with the same functions.
+
+// The pin manifest (WITHOUT tarball.* — added by withTarballInfo for the side-car).
+function buildCoreManifest({
+  version, coreContract, sourceCommit, sourceRef, builtAtIso, files, treeHash, redaction,
+}) {
+  return {
+    artifact: ARTIFACT_NAME,
+    manifest_schema: MANIFEST_SCHEMA,
+    generator: 'scripts/bongos/package-core.js',
+    // core_version is the PIN coordinate (the platform version, task 1203).
+    // core_contract is the module-doorway semver (src/module-api CORE_VERSION);
+    // equal to core_version unless --version overrides. A module pinned to
+    // "^core_contract" is guaranteed to load against this core.
+    core_version: version,
+    core_contract: coreContract,
+    source_commit: sourceCommit,
+    source_ref: sourceRef,
+    built_at: builtAtIso,
+    redaction: redaction || null,
+    file_count: files.length,
+    // tree_sha256 is the authoritative integrity pin (see canonicalTreeHash).
+    tree_sha256: treeHash,
+    files: files.map((f) => ({ path: f.path, mode: normalizeMode(f.mode), sha256: f.sha256 })),
+  };
+}
+
+// The side-car pin = the inner manifest + the exact-bytes coordinate of THIS .tgz.
+function withTarballInfo(manifest, tarball) {
+  return { ...manifest, tarball };
+}
+
+function tarballName(version) { return `${ARTIFACT_NAME}-${version}.tgz`; }
+function manifestName(version) { return `${ARTIFACT_NAME}-${version}.manifest.json`; }
+function stageDirName(version) { return `${ARTIFACT_NAME}-${version}`; }
+
+// The ustar+gzip writer (buildTar and its header helpers) lives in
+// scripts/bongos/artifact-format.js (task 1004271), shared with the module store.
+
+// ---- the git-LESS source: enumerate the working tree (task 1003995) --------
+//
+// Everything below the enumeration step is already git-free, so the ONE thing that
+// makes package-core unrunnable without history is `git ls-tree`. That matters because
+// the shipped self-host image IS a core checkout with no `.git` (.dockerignore excludes
+// it by design), and the provisioning scaffold inside it has no other way to build the
+// tarball it vendors into a child instance — the fourth rung of the ladder in
+// scripts/bongos/provision-repo.js.
+//
+// The walk starts at PUBLISH_ALLOWLIST's own entries rather than the repo root. The
+// allowlist is already the single source of truth for what the core is, so starting
+// there means node_modules/ and dist/ are never descended into at all. Selection still
+// runs through isPublishable() in main(), so the denylist applies exactly as it does on
+// the git path — this function only decides what is OFFERED, never what is kept.
+//
+// Rows match parseLsTree's shape ({ path, type, mode }) minus `sha`: there is no object
+// to name, so main() reads these blobs off disk instead. Mode is derived the way git
+// derives it — the executable bit and nothing else. fs injectable for tests.
+function walkWorktreeEntries(root, { allow = PUBLISH_ALLOWLIST, fsImpl = fs } = {}) {
+  const out = [];
+  const addFile = (rel) => {
+    let st;
+    try { st = fsImpl.statSync(path.join(root, rel)); } catch { return; }   // absent here → simply not in the core set
+    if (st.isFile()) out.push({ path: rel, type: 'blob', mode: (st.mode & 0o111) ? '100755' : '100644' });
+  };
+  const walk = (rel) => {
+    let children;
+    try { children = fsImpl.readdirSync(path.join(root, rel), { withFileTypes: true }); } catch { return; }
+    for (const child of children) {
+      const childRel = `${rel}/${child.name}`;
+      if (child.isDirectory()) walk(childRel);
+      else if (child.isFile()) addFile(childRel);
+    }
+  };
+  for (const entry of allow) {
+    if (entry.endsWith('/')) walk(entry.replace(/\/$/, ''));
+    else addFile(entry);
+  }
+  return out.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+
+// ---- generated API artifacts (task 1004866) -------------------------------
+// The spec, reference and typed client are gitignored, so neither a ref's tree nor a fresh
+// worktree carries them — yet every project is built from this tarball (ADR 0292) and serves
+// /docs + /lib/bongos-client.js from it. So the build GENERATES them, from the very source
+// files it is packing: those files are written to a throwaway tree, and the generators THAT
+// tree carries (gen-api-docs.js, then gen-api-client.js) run there. A --ref build therefore
+// documents the ref's routes, never whatever the working tree happens to hold.
+//
+// Fail-closed: a generator that exits non-zero, or a run that leaves any of the eight
+// missing or empty, throws — the caller aborts the build rather than ship a core whose docs
+// and client are silently absent. `run`, `fsImpl`, `tmpRoot` and `env` are injectable for tests.
+//
+// Executed path: the scripts run out of the throwaway tree, a runtime path. That is the point
+// (a --ref build must document the ref's routes with the ref's generators), and it is safe for
+// the same reason the build is: every byte in that tree is the source being packed, chosen by
+// the maintainer running this CLI — nothing request-derived, and this never runs in the server
+// (exec-path-guard.js scans the server tree only). *_INSTANCE_ROOT is stripped from the env.
+function generateApiArtifacts(sources, {
+  run = (cmd, args, opts) => spawnSync(cmd, args, opts),
+  fsImpl = fs,
+  tmpRoot = os.tmpdir(),
+  env = process.env,
+} = {}) {
+  const dir = fsImpl.mkdtempSync(path.join(tmpRoot, 'package-core-api-'));
+  try {
+    for (const { path: rel, buf } of sources) {
+      const abs = path.join(dir, rel);
+      fsImpl.mkdirSync(path.dirname(abs), { recursive: true });
+      fsImpl.writeFileSync(abs, buf);
+    }
+    // Strip any *_INSTANCE_ROOT pointer: it would redirect the generators' docs root out
+    // of the throwaway tree (the same hardening conflict-resolve.js applies).
+    const childEnv = {};
+    for (const [k, v] of Object.entries(env)) if (!/_INSTANCE_ROOT$/.test(k)) childEnv[k] = v;
+    for (const script of ['scripts/bongos/gen-api-docs.js', 'scripts/bongos/gen-api-client.js']) {
+      const r = run(process.execPath, [path.join(dir, script)], { cwd: dir, env: childEnv, encoding: 'utf8' });
+      if (!r || r.error || r.status !== 0) {
+        const why = r && r.error ? r.error.message : `exit ${r ? r.status : '?'}`;
+        const detail = r && r.stderr ? `: ${String(r.stderr).trim().split('\n').slice(-3).join(' | ')}` : '';
+        throw new Error(`${script} failed (${why})${detail}`);
+      }
+    }
+    const out = [];
+    for (const rel of API_ARTIFACT_PATHS) {
+      let buf;
+      try { buf = fsImpl.readFileSync(path.join(dir, rel)); } catch { throw new Error(`generation left no ${rel}`); }
+      if (!buf || buf.length === 0) throw new Error(`generation left ${rel} empty`);
+      out.push({ path: rel, buf });
+    }
+    return out;
+  } finally {
+    try { fsImpl.rmSync(dir, { recursive: true, force: true }); } catch { /* best effort */ }
+  }
+}
+
+// ---- git plumbing (impure) ------------------------------------------------
+function git(args) {
+  return execFileSync('git', ['-C', REPO_ROOT, ...args], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+}
+function gitBuf(args) {
+  return execFileSync('git', ['-C', REPO_ROOT, ...args], { maxBuffer: 256 * 1024 * 1024 });
+}
+
+function arg(name, fallback = null) {
+  const i = process.argv.indexOf(name);
+  return i >= 0 && i + 1 < process.argv.length ? process.argv[i + 1] : fallback;
+}
+
+// npm is `npm.cmd` on Windows and can't be execFile'd bare; unix uses `npm`.
+const NPM_BIN = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+
+// Pure — the exact `npm publish` argv for the built core tarball. The package
+// publishes PUBLIC via publishConfig.access:"public" (buildPackageJson); we ALSO
+// pass `--access public` so the posture is stated at the call site and a stray
+// `publishConfig` edit can't silently take it back to restricted — the same
+// belt-and-braces the restricted era used, pointed the other way (task 1003872).
+//
+// NOTE for whoever reads this after a failed rollout: `--access` on publish governs
+// what THIS publish declares. A package that is already `private` on the registry
+// also needs the one-time, registry-side `npm access set status=public @bongos/core`
+// — the flag alone has historically been a no-op on re-publish. ADR 0283 records
+// that flip as a separate, deliberate owner step for exactly that reason.
+// `--dry-run` unless `live` (the permanent owner step).
+function publishArgs(tgzPath, live) {
+  const a = ['publish', tgzPath, '--access', 'public'];
+  if (!live) a.push('--dry-run');
+  return a;
+}
+
+// Publish (or dry-run) the built .tgz to npm. Auth is npm's own concern — this
+// never holds a token; it shells out to `npm publish` and the owner's `npm login`
+// provides it. The package is PUBLIC (task 1003872, ADR 0283), so no paid org plan
+// is involved — a public scoped publish needs none.
+// The child's stdout is routed to OUR stderr so main()'s machine-readable pin on
+// stdout stays clean for CI capture.
+function publishTarball({ tgzPath, live }) {
+  const args = publishArgs(tgzPath, live);
+  console.error('');
+  console.error(`[package-core] ${live ? 'PUBLISH (permanent)' : 'publish DRY-RUN'} → ${NPM_BIN} ${args.join(' ')}`);
+  if (!live) {
+    console.error('  Dry-run: nothing is uploaded. To publish for real: re-run with --publish --live.');
+    console.error('  That is PERMANENT and PUBLIC (ADR 0283) — anyone can fetch it, and a version is never');
+    console.error('  reusable once taken. It requires `npm login`; no paid org plan (the package is public).');
+  }
+  const r = spawnSync(NPM_BIN, args, { cwd: REPO_ROOT, stdio: ['inherit', process.stderr, 'inherit'] });
+  if (r.error || r.status !== 0) {
+    console.error(`[package-core] npm publish ${live ? '' : '--dry-run '}FAILED (${r.error ? r.error.message : `exit ${r.status}`}).`);
+    if (live) console.error('  Common causes: not logged in (`npm login`), no publish rights on the @bongos scope, that version already taken, or 2FA.');
+    process.exit(r.status || 1);
+  }
+  console.error(`[package-core] npm publish ${live ? 'succeeded — @bongos/core is live and PUBLIC on the registry.' : 'dry-run OK — the tarball is publishable.'}`);
+}
+
+// The neutral FLOOR — customer-zero identity tokens a portable core must never carry (task 1002220
+// / H6 + task 1002217 / H4, finding F2). When packaging from the NEUTRAL trunk there is no
+// config/branding.json, so the branding-DERIVED redaction + gate see ZERO literals and report
+// "clean" while stripping nothing. This fixed floor closes that gap two ways, both keyed off ONE
+// definition:
+//   • DOC path (H4, fail-closed): injected as `extra` {tokens, owners} into buildRedactionRules +
+//     collectSensitiveLiterals, so the existing doc-redaction STRIPS these from published docs
+//     (tokens→NEUTRAL_TOKEN, owners→NEUTRAL_OWNER) and the fail-closed no-leak gate ABORTS the build
+//     if one SURVIVES — even with no branding.json. The floor lives HERE and is injected at call
+//     time, so mirror-redact.js stays literal-free (its self-leak invariant holds); functional files
+//     still ship VERBATIM (the R88 fix) and are covered by the H6 advisory below, not this gate.
+//   • SCAN path (H6, advisory): scanArtifactForLeaks measures the flat list across the WHOLE artifact.
+// findLeaks' public-IP floor separately catches the old droplet IP.
+const PRIOR_INSTANCE_FLOOR = { tokens: ['amazonprimea', 'off the boats'], owners: ['lars589'] };
+const PRIOR_INSTANCE_LITERALS = [...PRIOR_INSTANCE_FLOOR.tokens, ...PRIOR_INSTANCE_FLOOR.owners];
+
+// High-signal committed-credential shapes for the secret WARNING (task 1002220 / audit H6, finding
+// F3). Deliberately NARROW — well-known provider token prefixes + PEM private-key headers + an
+// explicit secret=<literal> assignment — rather than the generic entropy catch-all, which fires on
+// ordinary long identifiers / base64 data and buries a real hit (an early cut warned on 339 files,
+// ~all benign). A match is a WARNING to eyeball; the HARD gate against live env-secret VALUES is
+// functionalSecretLeaks in the build loop. Scans functional files (docs are redacted + gated already).
+const CREDENTIAL_SHAPE_PATTERNS = [
+  ['anthropic-key', /\bsk-ant-[A-Za-z0-9_-]{16,}/],
+  ['openai-key', /\bsk-[A-Za-z0-9]{24,}/],
+  ['github-token', /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}\b|\bgithub_pat_[A-Za-z0-9_]{20,}/],
+  ['aws-access-key-id', /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/],
+  ['google-api-key', /\bAIza[A-Za-z0-9_-]{30,}/],
+  ['slack-token', /\bxox[baprs]-[A-Za-z0-9-]{10,}/],
+  ['private-key-pem', /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/],
+  ['secret-assignment', /\b(?:api[_-]?key|secret|password|passwd|access[_-]?token|auth[_-]?token)\b\s*[:=]\s*['"][^'"\s]{16,}['"]/i],
+];
+function credentialShapeHits(text) {
+  const names = [];
+  for (const [name, re] of CREDENTIAL_SHAPE_PATTERNS) if (re.test(text)) names.push(name);
+  return names;
+}
+
+// classify a shipped path for the scan — mirrors processCoreFile's doc/stub/functional split.
+function scanKindOf(pathRel) {
+  if (isAgentDoc(pathRel)) return 'stub';
+  if (isDocPath(pathRel)) return 'doc';
+  return 'functional';
+}
+
+// The post-build leak scan's POLICY, split out of main() so a test can plant a literal and prove
+// the build refuses without running a full 2-minute package (task 1003870). Pure: argv in, verdict
+// out. Fail-closed — any un-allowlisted prior-instance literal is fatal unless the operator has
+// explicitly said --no-leak-scan, which skips the scan altogether rather than downgrading it.
+// `--leak-scan-strict` is honoured as a no-op: it named this behaviour before it became default.
+function leakScanVerdict(remainingLiteralHits, argv = process.argv) {
+  if (argv.includes('--no-leak-scan')) return { run: false, fatal: false, reason: 'skipped' };
+  const n = (remainingLiteralHits || []).length;
+  if (n === 0) return { run: true, fatal: false, reason: 'clean' };
+  return { run: true, fatal: true, reason: 'prior-instance-literals' };
+}
+
+// Independent post-build leak scan over the built core file set (task 1002220 / audit H6). Two layers:
+//   • INSTANCE LITERALS — findLeaks() over PRIOR_INSTANCE_LITERALS (+ the public-IP floor) across
+//     EVERY shipped file: brand/owner/history that must not ship in a portable core. This is the
+//     "prove no leak" measurement the neutral trunk was missing (F2).
+//   • CREDENTIAL SHAPES — credentialShapeHits() over FUNCTIONAL files only (docs are redacted+gated
+//     already): a high-signal WARNING that a committed credential shape shipped.
+// `files` = [{ path, content }]. Pure — returns findings; the caller decides warn vs fatal.
+function scanArtifactForLeaks(files, { literals = PRIOR_INSTANCE_LITERALS } = {}) {
+  const literalHits = []; // { path, label, sample }
+  const secretWarnings = []; // { path, shapes }
+  for (const f of files || []) {
+    const text = Buffer.isBuffer(f.content) ? f.content.toString('utf8') : String(f.content == null ? '' : f.content);
+    for (const lk of findLeaks(text, literals)) literalHits.push({ path: f.path, label: lk.label, sample: lk.sample });
+    if (scanKindOf(f.path) === 'functional') {
+      const shapes = credentialShapeHits(text);
+      if (shapes.length) secretWarnings.push({ path: f.path, shapes });
+    }
+  }
+  return { literalHits, secretWarnings };
+}
+
+// release-notes.json — the one file the core carries that is derived from HISTORY rather
+// than from a committed file (task 1004218). It only exists where the history does, which
+// is the CI pack (publish.yml checks out at fetch-depth 0). main() stages it into the SAME
+// staged/filesMeta arrays as package.json, so the pin manifest covers it and --self-verify
+// reproduces it; a file written into the stage dir behind the manifest's back would fail
+// self-verify at publish time.
+//
+// ITS PROSE IS TREATED AS A DOC. These are merge summaries — builder-authored sentences — so
+// the neutral floor applies exactly as it does to a shipped .md: redacted with the same rules
+// (redactBlob), and any residue after redaction is a fatal no-leak failure. Not optional:
+// ten of the 1,399 summaries in the history (measured 2026-09-25) name a prior instance or
+// its owner, and history cannot be edited — shipped verbatim, they would fail the fail-closed
+// post-build scan on EVERY pack from now on, and the lane would never publish again. That
+// scan still reads the finished file, as it reads every staged one.
+//
+// Pure: notes + the rules main() already built in, `{ buf, notes, dropped, summaries,
+// redacted, leaks }` out.
+function releaseNotesArtifact(notes, { rules, sensitiveLiterals, envSecrets, knownDocNames, maxBytes = RELEASE_NOTES_MAX_BYTES }) {
+  const leaks = [];
+  let redacted = 0;
+  const clean = {};
+  for (const [version, entries] of Object.entries(notes || {})) {
+    clean[version] = entries.map((e) => {
+      const r = redactBlob({ buf: Buffer.from(e.text, 'utf8'), rules, sensitiveLiterals, envSecrets, knownDocNames });
+      for (const l of r.leaks) leaks.push({ label: `doc:${l.label}`, sample: l.sample });
+      if (r.secret) leaks.push({ label: 'doc:secret-shape' });
+      const text = r.buf.toString('utf8');
+      if (text !== e.text) redacted++;
+      return e.id ? { id: e.id, text } : { text };
+    });
+  }
+  const bounded = boundReleaseNotes(clean, maxBytes);
+  const summaries = Object.values(bounded.notes).reduce((n, list) => n + list.length, 0);
+  return { buf: serializeReleaseNotes(bounded.notes), notes: bounded.notes, dropped: bounded.dropped, summaries, redacted, leaks };
+}
+
+// Self-verify the built artifact (task 1002218 / audit H3, findings F1+F5). The packager
+// claims a consumer "verifies an install by recomputing [the pin] from the unpacked tree" —
+// this proves the packager's OWN output actually does, at build time, on the produce side:
+//   1. REPRODUCE THE PIN (always; deterministic, network-free): unpack the built .tgz and
+//      recompute tree_sha256 over the unpacked tree, asserting it equals the manifest — plus
+//      the on-disk .tgz bytes vs manifest.tarball.sha256. Catches a tar-writer bug, a corrupt
+//      write, or pin drift BEFORE the artifact is trusted or published (the R88 failure class).
+//   2. BARE-INSTALL BOOT (opt-in --self-verify-boot; needs npm/registry): `npm install <tgz>`
+//      into a throwaway consumer and boot /healthz, by reusing the proven consumer-layout
+//      harness (tests/consumer_layout_boot.mjs) with CORE_TGZ set — no duplication. The deeper
+//      standing CI gate is task 1002221; this is the packager's own quick smoke.
+// Fatal (exit 1) on a reproduce mismatch or a boot failure — a self-verify that finds a
+// problem must stop the build, never warn-and-ship.
+// Pure recompute — read each pinned file from an unpacked tree, rebuild the canonical tree
+// hash (using the manifest's already-canonical modes), and compare to the manifest, plus the
+// on-disk .tgz bytes vs manifest.tarball.sha256. No process.exit / no spawn → unit-testable.
+// Returns { ok, problems, fileCount }.
+function reproducePinFromTree({ treeRoot, sidecar, tgzPath }, fsImpl = fs) {
+  const problems = [];
+  const recomputed = [];
+  for (const f of sidecar.files || []) {
+    const abs = path.join(treeRoot, ...String(f.path).split('/'));
+    let buf;
+    try { buf = fsImpl.readFileSync(abs); } catch { problems.push(`missing in artifact: ${f.path}`); continue; }
+    const sha = sha256hex(buf);
+    if (sha !== f.sha256) problems.push(`content mismatch: ${f.path}`);
+    recomputed.push({ path: f.path, mode: f.mode, sha256: sha });
+  }
+  const treeHash = canonicalTreeHash(recomputed);
+  if (problems.length === 0 && treeHash !== sidecar.tree_sha256) {
+    problems.push(`recomputed tree_sha256 ${treeHash.slice(0, 12)}… ≠ manifest ${String(sidecar.tree_sha256).slice(0, 12)}…`);
+  }
+  if (tgzPath && sidecar.tarball && sidecar.tarball.sha256) {
+    const tgzSha = sha256hex(fsImpl.readFileSync(tgzPath));
+    if (tgzSha !== sidecar.tarball.sha256) {
+      problems.push(`on-disk .tgz sha256 ${tgzSha.slice(0, 12)}… ≠ manifest.tarball.sha256 ${String(sidecar.tarball.sha256).slice(0, 12)}…`);
+    }
+  }
+  return { ok: problems.length === 0, problems, fileCount: (sidecar.files || []).length };
+}
+
+function selfVerify({ tgzPath, sidecar, outDir, boot }) {
+  console.error('');
+  console.error('[self-verify] verifying the built artifact reproduces its pin …');
+
+  // 1. reproduce the pin from the built .tgz.
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'bongos-selfverify-'));
+  try {
+    let treeRoot;
+    const x = spawnSync('tar', ['-xzf', tgzPath, '-C', tmp], { encoding: 'utf8' });
+    if (!x.error && x.status === 0) {
+      treeRoot = path.join(tmp, TAR_ROOT.replace(/\/$/, '')); // the `package/` root inside the tarball
+    } else {
+      // tar unavailable — fall back to the on-disk stage dir (the SAME staged buffers written
+      // to the .tgz), so the pin is still recomputed from a materialized tree. Less faithful
+      // (won't catch a tar-writer bug), so it's a loud warning, not silent.
+      treeRoot = path.join(outDir, stageDirName(sidecar.core_version));
+      console.error(`[self-verify] ! tar unavailable (${x.error ? x.error.message : 'exit ' + x.status}); recomputing over the stage dir ${path.relative(REPO_ROOT, treeRoot)} instead of the unpacked .tgz.`);
+      if (!fs.existsSync(treeRoot)) { console.error('[self-verify] FAILED — neither `tar` nor the stage dir is available to recompute the pin.'); process.exit(1); }
+    }
+    const rep = reproducePinFromTree({ treeRoot, sidecar, tgzPath });
+    if (!rep.ok) {
+      console.error(`[self-verify] FAILED — the built artifact does NOT reproduce its pin (${rep.problems.length} problem(s)):`);
+      for (const p of rep.problems.slice(0, 20)) console.error('   ' + p);
+      if (rep.problems.length > 20) console.error(`   … +${rep.problems.length - 20} more`);
+      process.exit(1);
+    }
+    console.error(`[self-verify] ✓ pin reproduced — tree_sha256 + tarball.sha256 match the manifest (${rep.fileCount} files).`);
+  } finally {
+    try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* best-effort */ }
+  }
+
+  // 2. bare-install boot (opt-in) — reuse the proven consumer-layout harness with CORE_TGZ.
+  if (boot) {
+    const harness = path.join(REPO_ROOT, 'tests', 'consumer_layout_boot.mjs');
+    if (!fs.existsSync(harness)) {
+      console.error('[self-verify] • bare-install boot skipped — tests/consumer_layout_boot.mjs not present (packaging from an installed core, where tests/ is not shipped).');
+      return;
+    }
+    console.error('[self-verify] bare-install boot: `npm install <tgz>` + boot /healthz (via consumer_layout_boot, CORE_TGZ set) …');
+    const r = spawnSync(process.execPath, [harness], {
+      cwd: REPO_ROOT, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024,
+      env: { ...process.env, CORE_TGZ: tgzPath }, stdio: ['ignore', process.stderr, process.stderr],
+    });
+    if (r.error || r.status !== 0) {
+      console.error(`[self-verify] FAILED — the packaged core did not install + boot (${r.error ? r.error.message : 'exit ' + r.status}).`);
+      process.exit(1);
+    }
+    console.error('[self-verify] ✓ bare-install boot OK — the packaged core installs and serves /healthz.');
+  }
+}
+
+function main() {
+  // --from-worktree: build from the files on disk instead of a commit (task 1003995).
+  // The lineage anchor of such a build is the tree hash alone — there is no commit to
+  // name — so source_commit is null and source_ref says where it came from.
+  const fromWorktree = process.argv.includes('--from-worktree');
+  const ref = fromWorktree ? '(worktree)' : arg('--ref', 'HEAD');
+  const outDir = path.resolve(REPO_ROOT, arg('--out-dir', 'dist'));
+  const version = arg('--version', coreVersion());
+  const contract = coreVersion();
+  const dropletIp = arg('--droplet-ip', process.env.DROPLET_IP || null);
+
+  // 1. Resolve the source ref → commit SHA (the lineage anchor of this artifact).
+  let sha = null;
+  if (!fromWorktree) {
+    try { sha = git(['rev-parse', ref]).trim(); }
+    catch (e) { console.error(`refusing: could not resolve --ref "${ref}": ${e.message}`); process.exit(2); }
+  }
+
+  // 2. Enumerate + partition the tree through the manifest (single source of truth).
+  //    package.json/package-lock.json are SYNTHESIZED (task 1882, ADR 0108 §2) —
+  //    isPublishable() still selects them (they're not manifest-excluded, the mirror
+  //    ships them verbatim), but the core package needs its OWN identity + a pruned
+  //    dependency set, not the game's. Pulled out of the generic per-file loop below.
+  const SYNTHESIZED_PATHS = new Set(['package.json', 'package-lock.json']);
+  const entries = fromWorktree
+    ? walkWorktreeEntries(REPO_ROOT)
+    : parseLsTree(git(['ls-tree', '-r', sha])).filter((e) => e.type === 'blob');
+  // A blob is named by its git object on the ref path and by its own path on the
+  // worktree path; everything downstream just wants the bytes.
+  // Generated API artifacts (task 1004866) carry their bytes in `buf`; every other entry
+  // is a git object on the ref path and a file on disk on the worktree path.
+  const readBlob = (e) => (e.buf ? e.buf : fromWorktree ? fs.readFileSync(path.join(REPO_ROOT, e.path)) : gitBuf(['cat-file', 'blob', e.sha]));
+  // Any copy of the eight generated API files that IS on hand (a stale untracked one in a
+  // worktree, or one committed on an older ref) is dropped: the copy that ships is the one
+  // generated in 2a from the routes being packed.
+  const API_GENERATED = new Set(API_ARTIFACT_PATHS);
+  const selected = entries.filter((e) => isPublishable(e.path) && !SYNTHESIZED_PATHS.has(e.path) && !API_GENERATED.has(e.path));
+  // Drop npm-never-installed files (.gitignore, .npmignore, .npmrc) so the manifest +
+  // tree_sha256 pin describe exactly what `npm install` materializes — otherwise the
+  // consumer's verifyInstalledPin fails on the missing file and the vendored upgrade
+  // auto-rolls-back (idea 1000543). Done here, so they never reach the tarball or the pin.
+  const npmStripped = selected.filter((e) => isNpmStripped(e.path));
+  const publishable = selected.filter((e) => !isNpmStripped(e.path));
+  // The worktree walk is already allowlist-scoped and never offers the two synthesized
+  // paths, so only the ref path discounts them from what it enumerated.
+  const excludedCount = entries.length - selected.length - (fromWorktree ? 0 : SYNTHESIZED_PATHS.size);
+  console.error(`[package-core] ${ref}${sha ? ` = ${sha.slice(0, 12)}` : ''} — ${entries.length} files, ${publishable.length} in the core (+2 synthesized), ${excludedCount} excluded.`);
+  if (npmStripped.length) {
+    console.error(`[package-core] dropped ${npmStripped.length} npm-never-installed file(s) from the pin (npm strips these on install; idea 1000543): ${npmStripped.map((e) => e.path).join(', ')}`);
+  }
+  if (publishable.length === 0) {
+    console.error('refusing: the core set is EMPTY — almost certainly a manifest/ref mismatch, not intentional. Aborting.');
+    process.exit(1);
+  }
+
+  // 2a. Generate the API spec, reference and typed client from the routes being packed
+  //     (task 1004866). Fatal on failure: a core without them serves no /docs and no client.
+  //     gen-api-docs stamps the spec with the version in package.json, so the throwaway
+  //     tree gets the SOURCE package.json beside the packed files.
+  {
+    const sources = publishable.map((e) => ({ path: e.path, buf: readBlob(e) }));
+    const pkgEntry = fromWorktree ? null : entries.find((e) => e.path === 'package.json');
+    const pkgPath = path.join(REPO_ROOT, 'package.json');
+    const pkg = fromWorktree ? (fs.existsSync(pkgPath) ? fs.readFileSync(pkgPath) : null) : (pkgEntry ? readBlob(pkgEntry) : null);
+    if (pkg) sources.push({ path: 'package.json', buf: pkg });
+    let generated;
+    try { generated = generateApiArtifacts(sources); }
+    catch (err) {
+      console.error(`refusing: generating the API spec + client FAILED — ${err.message}. A core without them serves no /docs and no /lib/bongos-client.js. Nothing was built.`);
+      process.exit(1);
+    }
+    for (const g of generated) {
+      if (!isPublishable(g.path)) {
+        console.error(`refusing: generated ${g.path} is not in the publish allowlist (scripts/bongos/publish-manifest.js).`);
+        process.exit(1);
+      }
+      publishable.push({ path: g.path, type: 'blob', mode: '100644', buf: g.buf });
+    }
+    // Joined to `publishable`, so the eight go through EVERYTHING below exactly like a
+    // committed file: processCoreFile (doc redaction + the fail-closed no-leak gate), the
+    // pin manifest, the tarball, and the post-build scanArtifactForLeaks over `staged`.
+    publishable.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    console.error(`[package-core] generated ${generated.length} API artifact(s) from the packed routes: ${generated.map((g) => g.path).join(', ')}.`);
+  }
+
+  // 2b. Synthesize the core's own package.json + pruned package-lock.json from the
+  //     SOURCE files at this ref (never the live working tree, so --ref stays
+  //     reproducible) — express+pg only, name @bongos/core, version = the
+  //     platform version being packaged.
+  //     On the worktree path there is no ref to stay reproducible against, so the two
+  //     files come off disk beside everything else in the build.
+  const sourceRootFile = (rel) => {
+    if (fromWorktree) {
+      const abs = path.join(REPO_ROOT, rel);
+      return fs.existsSync(abs) ? fs.readFileSync(abs) : null;
+    }
+    const blob = entries.find((e) => e.path === rel);
+    return blob ? gitBuf(['cat-file', 'blob', blob.sha]) : null;
+  };
+  const pkgJsonRaw = sourceRootFile('package.json');
+  const pkgLockRaw = sourceRootFile('package-lock.json');
+  if (!pkgJsonRaw || !pkgLockRaw) {
+    console.error(`refusing: source package.json/package-lock.json not found at ${fromWorktree ? 'the repo root' : 'this ref'} — cannot synthesize the core package.`);
+    process.exit(1);
+  }
+  const sourcePkgJson = JSON.parse(pkgJsonRaw.toString('utf8'));
+  const sourcePkgLock = JSON.parse(pkgLockRaw.toString('utf8'));
+  const corePkgJson = buildPackageJson({ version, sourceDeps: sourcePkgJson.dependencies, sourceOverrides: sourcePkgJson.overrides });
+  const corePkgLock = prunePackageLock(sourcePkgLock, {
+    name: corePkgJson.name, version, rootRanges: { express: corePkgJson.dependencies.express, pg: corePkgJson.dependencies.pg },
+  });
+  console.error(`[package-core] synthesized package.json (${Object.keys(corePkgJson.dependencies).join(', ')}) + pruned package-lock.json (${Object.keys(corePkgLock.packages).length - 1} of ${Object.keys(sourcePkgLock.packages).length - 1} locked packages kept).`);
+
+  // 3. Redaction rules from THIS instance's branding (current HEAD) + the droplet
+  //    IP as an exact extra literal (sourced here, never written into a file).
+  let branding = {};
+  try { branding = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'config/branding.json'), 'utf8')); }
+  catch { /* vanilla instance: derive from the public-IP floor only */ }
+  const ownerAliases = String(process.env.OWNER_ALIASES || '').split(',').map((s) => s.trim()).filter(Boolean);
+  // The NEUTRAL FLOOR (task 1002217 / audit H4): always inject the fixed prior-instance tokens so
+  // docs de-brand + the no-leak gate fires against them EVEN WITH NO branding.json (the F2 gap).
+  // Merged on top of this instance's own branding — for a branded instance the floor is harmless
+  // extra; for the neutral trunk it is the only thing standing between a doc and customer-zero's name.
+  const extra = {
+    owners: [...ownerAliases, ...PRIOR_INSTANCE_FLOOR.owners],
+    tokens: [...PRIOR_INSTANCE_FLOOR.tokens],
+    literals: dropletIp ? [dropletIp] : [],
+  };
+  const rules = buildRedactionRules(branding, extra);
+  const sensitiveLiterals = collectSensitiveLiterals(branding, extra);
+  const envSecrets = collectEnvSecrets();
+  console.error(`[package-core] ${rules.length} redaction rule(s), ${sensitiveLiterals.length} gate literal(s) + public-IP floor + ${envSecrets.length} env-secret literal(s) (incl. the neutral floor).`);
+
+  // 4. Process every file IN MEMORY (processCoreFile: docs redacted, functional verbatim)
+  //    + the fail-closed no-leak gate. Nothing touches dist/ until the ENTIRE set is proven
+  //    clean (atomic abort). Brand/topology in functional files are non-fatal ADVISORIES.
+  // task 1002460 — the doc-link allowlist. The entropy sweep cannot tell a long
+  // ADR filename from a secret by shape, so it collapsed every one of them to
+  // <redacted>.md on the way out. This is the set of names actually being
+  // published, so a name in it is a FILE and not a guess; anything else, secrets
+  // included, is redacted exactly as before.
+  const knownDocNames = new Set(
+    publishable.map((e) => e.path.split('/').pop()).filter((n) => /\.(md|sql)$/i.test(n)),
+  );
+  const staged = []; // { name, mode, buf }  (name includes TAR_ROOT)
+  const filesMeta = []; // { path, mode, sha256 }  (source files only — the pin domain)
+  const leaks = [];
+  const advisories = []; // { path, label, sample } — non-fatal (brand/IP that ships verbatim)
+  let docCount = 0;
+  let funcCount = 0;
+  let stubCount = 0; // agent docs (CLAUDE.md/AGENTS.md) replaced with the brand-free stub (task 2121)
+  for (const e of publishable) {
+    let raw;
+    try { raw = readBlob(e); }
+    catch (err) { leaks.push({ path: e.path, label: `read-failed:${err.message}` }); continue; }
+    const { buf, leaks: fileLeaks, advisories: fileAdvisories, kind } =
+      processCoreFile({ pathRel: e.path, raw, rules, sensitiveLiterals, envSecrets, knownDocNames });
+    for (const l of fileLeaks) leaks.push({ path: e.path, label: l.label, sample: l.sample });
+    for (const a of fileAdvisories) advisories.push({ path: e.path, label: a.label, sample: a.sample });
+    if (kind === 'doc') docCount++; else if (kind === 'stub') stubCount++; else funcCount++;
+    filesMeta.push({ path: e.path, mode: e.mode, sha256: sha256hex(buf) });
+    staged.push({ name: TAR_ROOT + e.path, mode: parseInt(normalizeMode(e.mode), 8), buf });
+  }
+  funcCount += 2; // the two synthesized files below, staged outside the leak-gated loop
+
+  // The two synthesized files (2b above) carry no source content — no OTB brand,
+  // no secrets — so they need no redaction/leak scan; stage them directly into
+  // the same filesMeta/staged arrays the pin + tarball are built from.
+  for (const [relPath, obj] of [['package.json', corePkgJson], ['package-lock.json', corePkgLock]]) {
+    const buf = Buffer.from(`${JSON.stringify(obj, null, 2)}\n`, 'utf8');
+    filesMeta.push({ path: relPath, mode: '100644', sha256: sha256hex(buf) });
+    staged.push({ name: TAR_ROOT + relPath, mode: 0o644, buf });
+  }
+
+  // 4b. The release notes (task 1004218): what each release brought in, generated from this
+  //     ref's history, redacted as a doc, and staged into the same arrays so the pin covers
+  //     them. A worktree build or a shallow clone has no history to read, so it ships without
+  //     — and an upgrade onto it says its notes are unavailable rather than listing nothing.
+  const notesGen = fromWorktree
+    ? { skipped: 'built from the working tree, which carries no history' }
+    : generateReleaseNotes({ git, ref: sha, version });
+  let notesStaged = false;
+  if (notesGen.skipped) {
+    console.error(`[package-core] ! ${RELEASE_NOTES_FILE} not generated — ${notesGen.skipped}.`);
+  } else {
+    const art = releaseNotesArtifact(notesGen.notes, { rules, sensitiveLiterals, envSecrets, knownDocNames });
+    for (const l of art.leaks) leaks.push({ path: RELEASE_NOTES_FILE, label: l.label, sample: l.sample });
+    filesMeta.push({ path: RELEASE_NOTES_FILE, mode: '100644', sha256: sha256hex(art.buf) });
+    staged.push({ name: TAR_ROOT + RELEASE_NOTES_FILE, mode: 0o644, buf: art.buf });
+    notesStaged = true;
+    const kept = Object.keys(art.notes);
+    const trimmed = art.dropped.length
+      ? ` — the ${art.dropped.length} oldest release(s) DROPPED to stay under ${RELEASE_NOTES_MAX_BYTES / 1024} KiB`
+      : '';
+    console.error(`[package-core] ${RELEASE_NOTES_FILE}: ${kept.length} release(s) ${kept[0]} → ${kept[kept.length - 1]}, ${art.summaries} summaries (${art.redacted} redacted), ${(art.buf.length / 1024).toFixed(1)} KiB${trimmed}.`);
+  }
+
+  if (leaks.length > 0) {
+    console.error(`\n[package-core] NO-LEAK GATE FAILED — ${leaks.length} real leak(s) (doc redaction residue or a live credential in a functional file). PRODUCING NOTHING (fail-closed):`);
+    for (const l of leaks.slice(0, 50)) {
+      // Never print a secret sample; a redaction-residue instance literal is safe to show.
+      const shown = (l.label === 'live-credential' || l.label === 'doc:secret-shape')
+        ? '' : (l.sample ? ` (“${String(l.sample).slice(0, 40)}”)` : '');
+      console.error(`   ${l.path}: ${l.label}${shown}`);
+    }
+    if (leaks.length > 50) console.error(`   … +${leaks.length - 50} more`);
+    console.error('\nFix: for a DOC leak, extend scripts/bongos/mirror-redact.js (rules) or scripts/bongos/publish-manifest.js (exclusions);');
+    console.error('     for a live-credential leak, remove the secret at SOURCE (it should never be committed). Then re-run. dist/ was NOT touched.');
+    process.exit(1);
+  }
+  console.error(`[package-core] no-leak gate PASSED — ${staged.length} files clean (${docCount} docs redacted, ${stubCount} agent-docs stubbed, ${funcCount} functional verbatim${notesStaged ? `, ${RELEASE_NOTES_FILE} generated` : ''}).`);
+
+  // Advisory: brand-identity + public-IP literals that ship VERBATIM inside functional
+  // files. Not a leak (these are public, not secrets; a downstream rebrands via config) —
+  // surfaced so a human can see what instance-specific strings the consumer core carries.
+  if (advisories.length > 0) {
+    const byLabel = {};
+    for (const a of advisories) { const k = a.sample || a.label; byLabel[k] = (byLabel[k] || 0) + 1; }
+    const summary = Object.entries(byLabel).sort((x, y) => y[1] - x[1]).map(([k, n]) => `${k}×${n}`).join(', ');
+    console.error(`[package-core] advisory — ${advisories.length} brand/topology string(s) ship verbatim in functional files (public, not secrets): ${summary}.`);
+  }
+
+  // 5. Build the pin manifest, then materialize dist/ (only reached when clean).
+  filesMeta.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  const treeHash = canonicalTreeHash(filesMeta);
+  const innerManifest = buildCoreManifest({
+    version, coreContract: contract, sourceCommit: sha, sourceRef: ref,
+    builtAtIso: new Date().toISOString(), files: filesMeta, treeHash,
+    redaction: {
+      model: 'docs-redacted+functional-verbatim', // task 1824
+      docs_redacted: docCount,
+      agent_docs_stubbed: stubCount, // CLAUDE.md/AGENTS.md → brand-free stub (task 2121)
+      functional_verbatim: funcCount,
+      rules: rules.length,
+      gate_literals: sensitiveLiterals.length,
+      gate: 'passed',
+    },
+  });
+
+  // The self-describing manifest travels INSIDE the artifact too (minus tarball.*).
+  const innerJson = Buffer.from(JSON.stringify(innerManifest, null, 2) + '\n', 'utf8');
+  staged.push({ name: INNER_MANIFEST, mode: 0o644, buf: innerJson });
+
+  const tgz = buildTar(staged);
+  const sidecar = withTarballInfo(innerManifest, {
+    name: tarballName(version), sha256: sha256hex(tgz), bytes: tgz.length,
+  });
+
+  // Write: a fresh versioned stage dir (inspectable tree) + the .tgz + the pin.
+  fs.mkdirSync(outDir, { recursive: true });
+  const stageDir = path.join(outDir, stageDirName(version));
+  fs.rmSync(stageDir, { recursive: true, force: true });
+  for (const f of staged) {
+    // strip the TAR_ROOT prefix for the on-disk tree
+    const rel = f.name.startsWith(TAR_ROOT) ? f.name.slice(TAR_ROOT.length) : f.name;
+    const dest = path.join(stageDir, rel);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, f.buf, { mode: f.mode });
+  }
+  const tgzPath = path.join(outDir, tarballName(version));
+  const manifestPath = path.join(outDir, manifestName(version));
+  fs.writeFileSync(tgzPath, tgz);
+  fs.writeFileSync(manifestPath, JSON.stringify(sidecar, null, 2) + '\n');
+
+  console.error('');
+  console.error(`[package-core] Cloud Bongos core v${version} packaged (contract ^${contract}).`);
+  console.error(`  source_commit  ${sha || '(none — built from the working tree)'}`);
+  console.error(`  file_count     ${filesMeta.length}`);
+  console.error(`  tree_sha256    ${treeHash}`);
+  console.error(`  tarball        ${path.relative(REPO_ROOT, tgzPath)}  (${(tgz.length / 1024).toFixed(1)} KiB, sha256 ${sidecar.tarball.sha256.slice(0, 12)}…)`);
+  console.error(`  manifest       ${path.relative(REPO_ROOT, manifestPath)}   ← the PIN a downstream repo records`);
+  console.error(`  tree           ${path.relative(REPO_ROOT, stageDir)}/`);
+
+  // Optional self-verify leg (task 1002218 / audit H3): prove the built artifact reproduces
+  // its pin (+ optionally installs & boots) BEFORE it can be trusted or published. Runs after
+  // the artifact is written; a failure exits non-zero so an unverified/broken artifact never
+  // reaches the publish leg below or a downstream consumer.
+  if (process.argv.includes('--self-verify')) {
+    selfVerify({ tgzPath, sidecar, outDir, boot: process.argv.includes('--self-verify-boot') });
+  }
+
+  // Post-build leak scan (task 1002220 / audit H6): independent verification that the BUILT
+  // artifact carries no prior-instance identity, + a warn-level secret-shape scan over functional
+  // files. Runs on every build and is FAIL-CLOSED: an un-allowlisted prior-instance literal aborts
+  // the build. The trunk sweep (task 1003869) cleared the residue those literals used to represent,
+  // so warning instead of failing would only let it creep back (task 1003870). --no-leak-scan is
+  // the sole escape. A secret-shape hit stays a non-fatal warning — those 14 files were each
+  // confirmed a test fixture (task 1003871) and the R88 functional-verbatim fix is preserved.
+  if (!process.argv.includes('--no-leak-scan')) {
+    const scanFiles = staged.map((s) => ({ path: s.name.startsWith(TAR_ROOT) ? s.name.slice(TAR_ROOT.length) : s.name, content: s.buf }));
+    const scan = scanArtifactForLeaks(scanFiles);
+    // Named, reasoned exceptions (task 1003869). A detector must carry the pattern it
+    // detects and a "public IPs are flagged" test must be handed a public IP, so those
+    // hits are real but not leaks. Each is listed per (file, literal) with its reason in
+    // scripts/bongos/leak-scan-allowlist.js — never per bare file, which would let a NEW
+    // leak ride into an already-listed file unseen.
+    const { allowed, remaining } = partitionHits(scan.literalHits);
+    if (allowed.length) {
+      const byFile = [...new Set(allowed.map((h) => h.path))];
+      console.error(`[leak-scan] ${allowed.length} hit(s) across ${byFile.length} file(s) covered by a named exception (scripts/bongos/leak-scan-allowlist.js).`);
+    }
+    const stale = unusedEntries(scan.literalHits);
+    if (stale.length) {
+      console.error(`[leak-scan] ! ${stale.length} allowlist entr(ies) matched nothing — the trunk got cleaner, so prune them:`);
+      for (const e of stale) console.error(`   ${e.path}  [${e.literal}]`);
+    }
+    scan.literalHits = remaining;
+    const verdict = leakScanVerdict(scan.literalHits);
+    if (scan.literalHits.length) {
+      const byLit = {};
+      for (const h of scan.literalHits) byLit[h.sample] = (byLit[h.sample] || 0) + 1;
+      const summary = Object.entries(byLit).sort((a, b) => b[1] - a[1]).map(([k, n]) => `${k}×${n}`).join(', ');
+      const files = [...new Set(scan.literalHits.map((h) => h.path))];
+      console.error('');
+      console.error(`[leak-scan] FAILED — ${scan.literalHits.length} prior-instance literal hit(s) across ${files.length} shipped file(s): ${summary}`);
+      for (const p of files.slice(0, 30)) console.error(`   ${p}`);
+      if (files.length > 30) console.error(`   … +${files.length - 30} more file(s)`);
+      console.error('[leak-scan] refusing to certify a leaky artifact. Either remove the literal at SOURCE (check what');
+      console.error('[leak-scan] REGENERATES the file — a generator re-leaks on every run, task 1003911), or, if the hit is');
+      console.error('[leak-scan] a detector carrying its own pattern, add a named (path, class) reason to');
+      console.error('[leak-scan] scripts/bongos/leak-scan-allowlist.js. --no-leak-scan skips this gate entirely.');
+      if (verdict.fatal) process.exit(1);
+    } else {
+      console.error('[leak-scan] ✓ no prior-instance literals in the built artifact.');
+    }
+    if (scan.secretWarnings.length) {
+      console.error(`[leak-scan] ! ${scan.secretWarnings.length} functional file(s) carry a credential SHAPE (WARNING, not fatal — confirm none is a real credential; a real one must be removed at SOURCE):`);
+      for (const w of scan.secretWarnings.slice(0, 20)) console.error(`   ${w.path}  [${w.shapes.join(', ')}]`);
+      if (scan.secretWarnings.length > 20) console.error(`   … +${scan.secretWarnings.length - 20} more`);
+    } else {
+      console.error('[leak-scan] ✓ no committed-credential shapes in functional files.');
+    }
+  }
+
+  // Optional publish leg (task 2089): --publish runs `npm publish` on the built
+  // tarball. DRY-RUN by default; the real, permanent publish needs --publish --live
+  // (+ npm auth). Kept AFTER the artifact is written so a publish failure never
+  // costs the build; runs BEFORE the stdout pin so that pin stays the last line out.
+  if (process.argv.includes('--publish')) {
+    publishTarball({ tgzPath, live: process.argv.includes('--live') });
+  }
+
+  // stdout carries the machine-readable pin (so CI / R85 can capture it).
+  process.stdout.write(JSON.stringify({ core_version: version, source_commit: sha, tree_sha256: treeHash, tarball: sidecar.tarball }) + '\n');
+  process.exit(0);
+}
+
+module.exports = {
+  MANIFEST_SCHEMA, ARTIFACT_NAME, TAR_ROOT, INNER_MANIFEST,
+  coreVersion, sha256hex, canonicalTreeHash, normalizeMode,
+  buildCoreManifest, withTarballInfo, tarballName, manifestName, stageDirName,
+  octal, tarChecksum, ustarHeader, splitUstarName, buildTar,
+  // task 1824 — the consumer-core file-classification layer (pure; unit-tested)
+  isDocPath, functionalSecretLeaks, processCoreFile,
+  // idea 1000543 — npm-never-installed files dropped from the pin so vendored `bongos upgrade` pin-verify matches
+  isNpmStripped, NPM_STRIPPED_BASENAMES,
+  // task 1004866 — the gitignored API spec/reference/client, generated into every tarball
+  generateApiArtifacts,
+  // task 2121 — agent-doc (CLAUDE.md/AGENTS.md) stub so a consumer's node_modules can't auto-load core memory
+  isAgentDoc, CORE_AGENT_DOC_STUB,
+  // task 1882 (ADR 0108 §2) — the real installable npm package
+  CORE_DEP_NAMES, buildPackageJson, resolveLockDep, lockfileClosure, prunePackageLock,
+  // task 2089 (ADR 0134) — the npm publish argv; PUBLIC since task 1003872 / ADR 0283
+  publishArgs,
+  // task 1002218 (audit H3) — build-time self-verify (reproduce pin + optional bare-install boot)
+  selfVerify, reproducePinFromTree,
+  // task 1002220 (audit H6) — post-build leak scan (prior-instance literals + functional secret shapes)
+  scanArtifactForLeaks, PRIOR_INSTANCE_LITERALS,
+  // task 1003870 — the fail-closed verdict the build acts on (pure, so a test can plant a literal)
+  leakScanVerdict,
+  // task 1002217 (audit H4) — the fixed neutral floor injected into the doc-redaction + fail-closed gate
+  PRIOR_INSTANCE_FLOOR,
+  // task 1003995 — --from-worktree's enumerator, for a core checkout with no git history
+  walkWorktreeEntries,
+  // task 1004218 — release-notes.json: the history-derived file, redacted as a doc and bounded
+  releaseNotesArtifact,
+};
+
+if (require.main === module) main();