@bongos/core 1.17.0

package/scripts/gds/package-core.js

@@ -0,0 +1,684 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/gds/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/gds/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).
+//   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/cloudbongos-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/gds/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/gds/package-core.js [--ref <git-ref>] [--out-dir dist]
+//        [--version <v>] [--droplet-ip <ip>] [--publish [--live]]
+//   Defaults: --ref HEAD, --out-dir dist, --version = platform CORE_VERSION.
+//   Outputs (nothing is committed — dist/ is gitignored):
+//     dist/cloudbongos-core-<version>/           the redacted core tree (inspectable)
+//     dist/cloudbongos-core-<version>.tgz        the installable unit
+//     dist/cloudbongos-core-<version>.manifest.json   the PIN (tree hash + per-file hashes)
+//   --publish        after building, `npm publish` the .tgz as a PRIVATE scoped
+//                    package (--access restricted). DRY-RUN unless --live is added
+//                    (task 2089 / ADR 0134). Private publish needs the cloudbongos
+//                    npm org on a paid plan + `npm login`; this script holds no token.
+
+const fs = require('node:fs');
+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 } = require(path.join(REPO_ROOT, 'scripts/gds/publish-manifest.js'));
+const {
+  buildRedactionRules, collectSensitiveLiterals, findLeaks,
+} = require(path.join(REPO_ROOT, 'scripts/gds/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 MANIFEST_SCHEMA = 1;
+const ARTIFACT_NAME = 'cloudbongos-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}.cloudbongos-core.json`;
+
+// ---------------------------------------------------------------------------
+// The platform version — read CORE_VERSION via the doorway, lazily + fail-soft,
+// mirroring scripts/gds/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)
+// ---------------------------------------------------------------------------
+
+function sha256hex(buf) {
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+// ---------------------------------------------------------------------------
+// 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 || '')); }
+
+// 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 }) {
+  if (isDocPath(pathRel)) {
+    const r = redactBlob({ buf: raw, rules, sensitiveLiterals, envSecrets });
+    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',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 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 @cloudbongos/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 (+ an undici pin) — ADR 0108 §Context. 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'];
+
+// 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: '@cloudbongos/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`): mountInternalSurfaces (the shared
+    // host-routing surface both server.js and platform-server.js call) and the
+    // module-api doorway a module's routes/seams are authored against.
+    exports: {
+      '.': './src/platform-server.js',
+      './serve-internal': './src/bongos/serve-internal.js',
+      './module-api': './src/module-api.js',
+    },
+    engines: { node: '>=22' },
+    // Pre-launch distribution posture (task 2089 / ADR 0134): publish PRIVATE by
+    // default. `access:"restricted"` makes a scoped package private on publish, so a
+    // paid npm org can ship it where only members can install — no accidental public
+    // leak if someone forgets the CLI flag. Going public at launch is one step:
+    // `npm access public @cloudbongos/core` (or flip this to "public"). The name must
+    // stay SCOPED to be private at all — unscoped npm names are always public.
+    publishConfig: { access: 'restricted' },
+    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. A canonical, compression-independent digest of the core tree: one
+// "path\0mode\0filesha256\n" line per file, byte-sorted by path. A consumer
+// recomputes this from the unpacked tree to prove an install matches the pin.
+// `files` = [{ path, mode, sha256 }]. Modes are normalized so the pin is stable
+// regardless of the checkout's umask.
+function canonicalTreeHash(files) {
+  const lines = (files || [])
+    .map((f) => `${f.path}\u0000${normalizeMode(f.mode)}\u0000${f.sha256}`)
+    .sort();
+  return sha256hex(Buffer.from(lines.join('\n') + '\n', 'utf8'));
+}
+
+// Collapse ANY mode form — git's 100644/100755, our canonical 0000644/0000755, or a
+// raw filesystem octal string like "755" — to two canonical tar modes, keyed only on
+// the executable bit. IDEMPOTENT (normalizeMode(normalizeMode(x)) === normalizeMode(x))
+// AND exec-aware, so the tree pin reproduces byte-identically whether a consumer
+// recomputes it from the manifest's files[] (already-canonical modes) or from the
+// unpacked tree's stat() modes. Expects a STRING (git mode / canonical mode / octal).
+function normalizeMode(mode) {
+  const s = String(mode);
+  if (s === '100755' || s === '0000755' || s === '755') return '0000755';
+  const n = parseInt(s, 8);
+  if (Number.isFinite(n) && (n & 0o111)) return '0000755';
+  return '0000644';
+}
+
+// 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/gds/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}`; }
+
+// ---- a minimal, correct, DETERMINISTIC ustar+gzip writer (node-only, #686) ----
+// Deterministic (fixed mtime/uid/gid, normalized mode, sorted entries) so the same
+// source yields byte-identical bytes — a bonus over the tree_sha256 pin. Long paths
+// use the ustar name/prefix split, falling back to a GNU 'L' longname entry (read
+// by GNU tar, bsdtar/macOS, and node-tar) for the rare path that won't split.
+
+function octal(n, width) {
+  // width-1 octal digits, zero-padded, then a NUL — the classic numeric field.
+  return Buffer.from(n.toString(8).padStart(width - 1, '0').slice(-(width - 1)) + '\0', 'ascii');
+}
+
+function tarChecksum(block) {
+  let sum = 0;
+  for (let i = 0; i < 512; i++) sum += (i >= 148 && i < 156) ? 0x20 : block[i];
+  return sum;
+}
+
+// Build one 512-byte ustar header. `name`/`prefix` must already fit (<=100 / <=155).
+function ustarHeader({ name, prefix = '', mode, size, typeflag }) {
+  const h = Buffer.alloc(512, 0);
+  h.write(name, 0, 100, 'utf8');
+  octal(mode, 8).copy(h, 100);
+  octal(0, 8).copy(h, 108);   // uid
+  octal(0, 8).copy(h, 116);   // gid
+  octal(size, 12).copy(h, 124);
+  octal(0, 12).copy(h, 136);  // mtime = 0 (determinism)
+  h.write(typeflag, 156, 1, 'ascii');
+  h.write('ustar\0', 257, 6, 'ascii');
+  h.write('00', 263, 2, 'ascii');
+  if (prefix) h.write(prefix, 345, 155, 'utf8');
+  // checksum field: 6 octal digits + NUL + space, computed with the field = spaces.
+  const cksum = tarChecksum(h);
+  h.write(cksum.toString(8).padStart(6, '0').slice(-6) + '\0 ', 148, 8, 'ascii');
+  return h;
+}
+
+// Split a >100-byte path into { name<=100, prefix<=155 } at a '/' boundary, or
+// return null if no split fits (→ caller uses the GNU longname fallback).
+function splitUstarName(fullPath) {
+  const bytes = Buffer.byteLength(fullPath, 'utf8');
+  if (bytes <= 100) return { name: fullPath, prefix: '' };
+  // Find the LAST '/' such that the tail (after it) is <=100 and the head <=155.
+  for (let i = fullPath.length - 1; i > 0; i--) {
+    if (fullPath[i] !== '/') continue;
+    const prefix = fullPath.slice(0, i);
+    const name = fullPath.slice(i + 1);
+    if (Buffer.byteLength(name, 'utf8') <= 100 && Buffer.byteLength(prefix, 'utf8') <= 155) {
+      return { name, prefix };
+    }
+  }
+  return null;
+}
+
+function padTo512(buf) {
+  const rem = buf.length % 512;
+  return rem === 0 ? buf : Buffer.concat([buf, Buffer.alloc(512 - rem, 0)]);
+}
+
+// GNU longname pseudo-entry: a header (typeflag 'L', name '././@LongLink') whose
+// BODY is the full path (incl. trailing NUL), immediately followed by the real
+// file entry. Read by GNU tar, bsdtar/macOS, and node-tar.
+function gnuLongName(fullPath) {
+  const payload = Buffer.from(fullPath + '\0', 'utf8');
+  const hdr = ustarHeader({ name: '././@LongLink', mode: 0o644, size: payload.length, typeflag: 'L' });
+  return Buffer.concat([hdr, padTo512(payload)]);
+}
+
+// entries: [{ name, mode, buf }] — `name` includes the TAR_ROOT prefix. Returns a
+// gzip'd tar Buffer. Pure + deterministic given sorted entries.
+function buildTar(entries) {
+  const sorted = [...entries].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  const chunks = [];
+  for (const e of sorted) {
+    const mode = e.mode & 0o7777;
+    const split = splitUstarName(e.name);
+    if (split) {
+      chunks.push(ustarHeader({ name: split.name, prefix: split.prefix, mode, size: e.buf.length, typeflag: '0' }));
+    } else {
+      chunks.push(gnuLongName(e.name));
+      chunks.push(ustarHeader({ name: e.name.slice(0, 100), mode, size: e.buf.length, typeflag: '0' }));
+    }
+    chunks.push(padTo512(e.buf));
+  }
+  // two zero blocks terminate the archive
+  chunks.push(Buffer.alloc(1024, 0));
+  const tar = Buffer.concat(chunks);
+  return zlib.gzipSync(tar, { level: 9 });
+}
+
+// ---- 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. Scoped packages
+// publish PRIVATE via publishConfig.access:"restricted" (buildPackageJson); we ALSO
+// pass `--access restricted` so a stray `publishConfig` edit can't silently make the
+// pre-launch artifact public. `--dry-run` unless `live` (the permanent owner step).
+function publishArgs(tgzPath, live) {
+  const a = ['publish', tgzPath, '--access', 'restricted'];
+  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`
+// (+ the cloudbongos org on a paid plan, for a PRIVATE scoped publish) provides it.
+// 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 requires `npm login` + the cloudbongos npm org on a paid plan');
+    console.error('  (private scoped publish needs one). Going public later: `npm access public @cloudbongos/core`.');
+  }
+  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`), the org isn’t on a paid plan (private scoped publish requires one), or 2FA.');
+    process.exit(r.status || 1);
+  }
+  console.error(`[package-core] npm publish ${live ? 'succeeded — @cloudbongos/core is live (private).' : 'dry-run OK — the tarball is publishable.'}`);
+}
+
+function main() {
+  const ref = 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;
+  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 = parseLsTree(git(['ls-tree', '-r', sha])).filter((e) => e.type === 'blob');
+  const publishable = entries.filter((e) => isPublishable(e.path) && !SYNTHESIZED_PATHS.has(e.path));
+  console.error(`[package-core] ${ref} = ${sha.slice(0, 12)} — ${entries.length} files, ${publishable.length} in the core (+2 synthesized), ${entries.length - publishable.length - 2} excluded.`);
+  if (publishable.length === 0) {
+    console.error('refusing: the core set is EMPTY — almost certainly a manifest/ref mismatch, not intentional. Aborting.');
+    process.exit(1);
+  }
+
+  // 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 @cloudbongos/core, version = the
+  //     platform version being packaged.
+  const pkgJsonBlob = entries.find((e) => e.path === 'package.json');
+  const pkgLockBlob = entries.find((e) => e.path === 'package-lock.json');
+  if (!pkgJsonBlob || !pkgLockBlob) {
+    console.error('refusing: source package.json/package-lock.json not found at this ref — cannot synthesize the core package.');
+    process.exit(1);
+  }
+  const sourcePkgJson = JSON.parse(gitBuf(['cat-file', 'blob', pkgJsonBlob.sha]).toString('utf8'));
+  const sourcePkgLock = JSON.parse(gitBuf(['cat-file', 'blob', pkgLockBlob.sha]).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);
+  const extra = { owners: ownerAliases, 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).`);
+
+  // 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.
+  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;
+  for (const e of publishable) {
+    let raw;
+    try { raw = gitBuf(['cat-file', 'blob', e.sha]); }
+    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 });
+    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 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 });
+  }
+
+  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/gds/mirror-redact.js (rules) or scripts/gds/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, ${funcCount} functional verbatim).`);
+
+  // 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,
+      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}`);
+  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 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,
+  // task 1882 (ADR 0108 §2) — the real installable npm package
+  CORE_DEP_NAMES, buildPackageJson, resolveLockDep, lockfileClosure, prunePackageLock,
+  // task 2089 (ADR 0134) — private-by-default npm publish
+  publishArgs,
+};
+
+if (require.main === module) main();