@bongos/core 1.19.1073 → 1.19.1075

package/scripts/gds/module-artifact.js

@@ -0,0 +1,212 @@
+// scripts/gds/module-artifact.js — pack and verify ONE module version for the
+// Bongos-hosted module store (task 1004271, ADR 0338 D1).
+//
+// ADR 0338 settled "no second packaging format": a module version is a tarball plus a
+// hash manifest in exactly the shape package-core.js emits for the core — per-file
+// sha256, a compression-independent tree_sha256, a deterministic ustar+gzip — so the
+// tar writer, reader and tree pin all come from artifact-format.js, the file the core
+// release builds with. What differs is only WHAT is packed and what the manifest names:
+//
+//   tarball   package/<path inside modules/<key>/>   (module.json at package/module.json)
+//             package/.bongos-module.json            the inner manifest (below)
+//   manifest  { artifact: 'bongos-module', manifest_schema, generator, module_key,
+//               module_version, core_version, built_at, file_count, tree_sha256,
+//               files: [{ path, mode, sha256 }] }
+//   side-car  the same manifest + { tarball: { name, sha256, bytes } } (withTarballInfo)
+//
+// THE GATE. The core's isPublishable() is default-deny: a path ships only if the
+// allowlist names it and the denylist does not. The allowlist names the CORE's own
+// modules, so for a store module the allow side is "inside this module's own
+// modules/<key>/ directory" and the deny side is the SAME repo-wide denylist
+// (matchesDeny — game content, pixel art, copyrighted references, instance topology,
+// secrets), plus credential-named files anywhere in the module (SECRET_FILE_RE). Anything the denylist catches refuses the whole publish rather than being
+// silently dropped: a module that ships without a file it expected is a broken module.
+//
+// Both halves live here so the CLI (packModule) and the store route
+// (verifyModuleArtifact) cannot disagree about the format. Pure apart from reading the
+// module directory in packModule; never touches the network or the database.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { sha256hex, canonicalTreeHash, normalizeMode, buildTar, readTarAsync } = require('./artifact-format');
+const { matchesDeny } = require('./publish-manifest');
+const { validateManifest } = require('../../src/module-loader/manifest-schema');
+
+const ARTIFACT_NAME = 'bongos-module';
+const MANIFEST_SCHEMA = 1;
+const TAR_ROOT = 'package/';
+const INNER_MANIFEST_PATH = '.bongos-module.json';
+const INNER_MANIFEST = TAR_ROOT + INNER_MANIFEST_PATH;
+// Local-only files a module dir may hold that are never part of the module itself.
+const NEVER_PACKED = new Set(['.upstream-signoff.json', INNER_MANIFEST_PATH]);
+// The store's caps. A real feature module is tens of KB (the biggest bundled one packs
+// to ~90 KB), so these are generous headroom — and deliberately small, because the
+// store verifies an upload inside the web process: every byte is inflated and hashed
+// there. 5 MB on the wire matches the upstreaming queue's SUBMISSION_MAX_BYTES; the
+// unpacked cap bounds a gzip bomb.
+const MAX_TARBALL_BYTES = 5 * 1024 * 1024;
+const READ_LIMITS = { maxUnpackedBytes: 16 * 1024 * 1024, maxFiles: 2000 };
+
+function tarballName(key, version) { return `${ARTIFACT_NAME}-${key}-${version}.tgz`; }
+
+// Every file under dir, as module-relative forward-slash paths, sorted. Skips
+// VCS/dependency noise the way listModuleFiles (module.js) does.
+function listFiles(dir, rel = '') {
+  const out = [];
+  for (const entry of fs.readdirSync(path.join(dir, rel), { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name === '.git') continue;
+    const r = rel ? `${rel}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) out.push(...listFiles(dir, r));
+    else if (entry.isFile()) out.push(r);
+  }
+  return out.sort();
+}
+
+// A module-relative path is safe to unpack only if it stays inside the module.
+function isSafeRelPath(p) {
+  return typeof p === 'string' && p.length > 0 && !p.startsWith('/') && !p.includes('\\')
+    && !/^[A-Za-z]:/.test(p) && !p.split('/').some((seg) => seg === '' || seg === '.' || seg === '..');
+}
+
+// The repo denylist anchors its secret entries at the root (`.env`, not
+// `modules/x/.env`), which is right for the core tree and wrong for a module that
+// travels on its own. So a store module is also refused any file whose NAME marks it
+// as a credential, wherever it sits in the module.
+const SECRET_FILE_RE = /^(?:\.env(?:\..*)?|\.npmrc|\.netrc|\.pgpass|id_(?:rsa|dsa|ecdsa|ed25519)(?:\.pub)?|.*\.(?:pem|key|p12|pfx|jks|keystore))$/i;
+
+// The files the gate refuses, named at their canonical modules/<key>/ path.
+function deniedFiles(key, relPaths) {
+  return relPaths
+    .filter((p) => matchesDeny(`modules/${key}/${p}`) || SECRET_FILE_RE.test(p.split('/').pop()))
+    .map((p) => `modules/${key}/${p}`);
+}
+
+function buildModuleManifest({ key, version, coreVersion, builtAtIso, files, treeHash }) {
+  return {
+    artifact: ARTIFACT_NAME,
+    manifest_schema: MANIFEST_SCHEMA,
+    generator: 'scripts/gds/module-artifact.js',
+    module_key: key,
+    module_version: version,
+    core_version: coreVersion,
+    built_at: builtAtIso,
+    file_count: files.length,
+    tree_sha256: treeHash,
+    files: files.map((f) => ({ path: f.path, mode: normalizeMode(f.mode), sha256: f.sha256 })),
+  };
+}
+
+// Pack modules/<key>/ into { tgz, manifest, sidecar } or throw with a plain reason.
+// `modeOf` is injectable because Windows reports no executable bit.
+function packModule(key, { modulesDir, now = () => new Date(), modeOf } = {}) {
+  const dir = path.join(modulesDir, key);
+  if (!fs.existsSync(dir)) throw new Error(`modules/${key} does not exist`);
+  let moduleJson;
+  try { moduleJson = JSON.parse(fs.readFileSync(path.join(dir, 'module.json'), 'utf8')); }
+  catch { throw new Error(`modules/${key}/module.json is missing or is not valid JSON`); }
+  const { valid, errors } = validateManifest(moduleJson);
+  if (!valid) throw new Error(`modules/${key}/module.json is invalid: ${errors.join('; ')}`);
+  if (moduleJson.key !== key) throw new Error(`modules/${key}/module.json names key "${moduleJson.key}"`);
+
+  const rel = listFiles(dir).filter((p) => !NEVER_PACKED.has(p));
+  const denied = deniedFiles(key, rel);
+  if (denied.length) {
+    throw new Error(`the publish denylist refuses: ${denied.join(', ')} — remove them from the module (ADR 0098)`);
+  }
+  const unsafe = rel.filter((p) => !isSafeRelPath(p));
+  if (unsafe.length) throw new Error(`unpackable file name(s): ${unsafe.join(', ')}`);
+
+  const files = [];
+  const entries = [];
+  for (const p of rel) {
+    const abs = path.join(dir, ...p.split('/'));
+    const buf = fs.readFileSync(abs);
+    const mode = normalizeMode(modeOf ? modeOf(abs) : (fs.statSync(abs).mode & 0o777).toString(8));
+    files.push({ path: p, mode, sha256: sha256hex(buf) });
+    entries.push({ name: TAR_ROOT + p, mode: parseInt(mode, 8), buf });
+  }
+  const manifest = buildModuleManifest({
+    key, version: moduleJson.version, coreVersion: moduleJson.coreVersion,
+    builtAtIso: now().toISOString(), files, treeHash: canonicalTreeHash(files),
+  });
+  entries.push({ name: INNER_MANIFEST, mode: 0o644, buf: Buffer.from(JSON.stringify(manifest, null, 2) + '\n') });
+  const tgz = buildTar(entries);
+  const sidecar = { ...manifest, tarball: { name: tarballName(key, manifest.module_version), sha256: sha256hex(tgz), bytes: tgz.length } };
+  return { tgz, manifest, sidecar, moduleJson };
+}
+
+// The store's check on an upload. Trusts NOTHING the client says beyond the bytes:
+// every hash is recomputed, the inner manifest must describe exactly the files the
+// tarball holds, module.json must validate and name the route's key, and the
+// denylist runs again. Resolves { ok: true, ... } or { ok: false, code, message }.
+// Async so the inflate runs off the event loop (readTarAsync); the rest is one pass
+// over at most READ_LIMITS.maxUnpackedBytes.
+async function verifyModuleArtifact(tgz, { key, maxBytes = MAX_TARBALL_BYTES } = {}) {
+  const fail = (code, message) => ({ ok: false, code, message });
+  if (!Buffer.isBuffer(tgz) || tgz.length === 0) return fail('empty_artifact', 'the upload is empty');
+  if (tgz.length > maxBytes) return fail('artifact_too_large', `the tarball is over ${maxBytes} bytes`);
+
+  let entries;
+  try { entries = await readTarAsync(tgz, READ_LIMITS); }
+  catch (e) { return fail('bad_tarball', e.message); }
+
+  const byName = new Map();
+  for (const e of entries) {
+    if (!e.name.startsWith(TAR_ROOT)) return fail('bad_tarball', `"${e.name}" is outside ${TAR_ROOT}`);
+    const rel = e.name.slice(TAR_ROOT.length);
+    if (!isSafeRelPath(rel)) return fail('bad_tarball', `"${e.name}" is not a safe path`);
+    if (byName.has(rel)) return fail('bad_tarball', `"${e.name}" appears twice`);
+    byName.set(rel, e);
+  }
+  const inner = byName.get(INNER_MANIFEST_PATH);
+  if (!inner) return fail('no_manifest', `the tarball carries no ${INNER_MANIFEST}`);
+  let manifest;
+  try { manifest = JSON.parse(inner.buf.toString('utf8')); }
+  catch { return fail('no_manifest', `${INNER_MANIFEST} is not valid JSON`); }
+  if (manifest.artifact !== ARTIFACT_NAME || manifest.manifest_schema !== MANIFEST_SCHEMA || !Array.isArray(manifest.files)) {
+    return fail('bad_manifest', `${INNER_MANIFEST} is not a ${ARTIFACT_NAME} schema ${MANIFEST_SCHEMA} manifest`);
+  }
+
+  // Recompute the pin from the bytes and hold the manifest to it, file by file.
+  byName.delete(INNER_MANIFEST_PATH);
+  const actual = [...byName.entries()]
+    .map(([p, e]) => ({ path: p, mode: normalizeMode(e.mode.toString(8)), sha256: sha256hex(e.buf) }))
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  const declared = [...manifest.files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  if (declared.length !== actual.length || manifest.file_count !== actual.length) {
+    return fail('hash_mismatch', `the manifest lists ${declared.length} file(s) but the tarball holds ${actual.length}`);
+  }
+  for (let i = 0; i < actual.length; i++) {
+    const a = actual[i]; const d = declared[i];
+    if (d.path !== a.path || normalizeMode(d.mode) !== a.mode || d.sha256 !== a.sha256) {
+      return fail('hash_mismatch', `"${a.path}" does not match its manifest entry`);
+    }
+  }
+  const treeSha = canonicalTreeHash(actual);
+  if (manifest.tree_sha256 !== treeSha) return fail('hash_mismatch', 'tree_sha256 does not match the files');
+
+  const denied = deniedFiles(key, actual.map((f) => f.path));
+  if (denied.length) return fail('denied_content', `the publish denylist refuses: ${denied.join(', ')}`);
+
+  const mj = byName.get('module.json');
+  if (!mj) return fail('bad_module', 'the tarball has no module.json');
+  let moduleJson;
+  try { moduleJson = JSON.parse(mj.buf.toString('utf8')); }
+  catch { return fail('bad_module', 'module.json is not valid JSON'); }
+  const v = validateManifest(moduleJson);
+  if (!v.valid) return fail('bad_module', `module.json is invalid: ${v.errors.join('; ')}`);
+  if (moduleJson.key !== key || manifest.module_key !== key) {
+    return fail('key_mismatch', `the tarball is module "${moduleJson.key}", not "${key}"`);
+  }
+  if (manifest.module_version !== moduleJson.version || manifest.core_version !== moduleJson.coreVersion) {
+    return fail('bad_manifest', 'the manifest version does not match module.json');
+  }
+
+  return {
+    ok: true, manifest, moduleJson,
+    version: moduleJson.version, coreVersion: moduleJson.coreVersion,
+    treeSha256: treeSha, tarballSha256: sha256hex(tgz), bytes: tgz.length,
+  };
+}
+
+module.exports = { MAX_TARBALL_BYTES, packModule, verifyModuleArtifact };

package/scripts/gds/module.js

@@ -102,12 +102,12 @@ function envPrefix() {
 // Pure builders (exported for tests — no I/O, no network)
 // ---------------------------------------------------------------------------
 
-// dev-box -> "Dev Box"; economy -> "Economy". A readable default title.
+// art-pipeline -> "Art Pipeline"; economy -> "Economy". A readable default title.
 function titleize(key) {
   return String(key).split(/[-_]+/).filter(Boolean)
     .map((w) => w[0].toUpperCase() + w.slice(1)).join(' ');
 }
-// dev-box -> devBox (for the generated route-factory function name).
+// art-pipeline -> artPipeline (for the generated route-factory function name).
 function camel(key) {
   return String(key).replace(/[-_]+(.)/g, (_, c) => c.toUpperCase());
 }
@@ -125,6 +125,8 @@ function buildManifest(key, { core = coreVersion() } = {}) {
     key,
     title: titleize(key),
     description: `TODO: one sentence describing the ${key} module.`,
+    // The module's own version (task 1003781). A fresh scaffold is pre-release.
+    version: '0.1.0',
     coreVersion: `^${core}`,
     default: false,
     author: 'TODO: your name or builder handle',
@@ -265,7 +267,7 @@ function evaluateUpgrade({ rows = [], errors = [], core } = {}) {
 
 function scaffoldModule({ key, modulesDir = MODULES_DIR, core = coreVersion(), force = false } = {}) {
   if (!key || !KEY_RE.test(key)) {
-    throw new Error(`invalid module key "${key}" — must match ${KEY_RE} (lowercase kebab-case, e.g. "dev-box")`);
+    throw new Error(`invalid module key "${key}" — must match ${KEY_RE} (lowercase kebab-case, e.g. "art-pipeline")`);
   }
   const dir = path.join(modulesDir, key);
   if (fs.existsSync(dir) && !force) {
@@ -411,14 +413,14 @@ function formatCatalog(rows, { catalogOnly = false, query = '', core = null } =
     return out.join('\n');
   }
 
-  out.push(`  ${pad('', 5)}${pad('KEY', 20)}${pad('SOURCE', 10)}${pad('AUTHOR', 20)}${pad('ORIGIN', 26)}${pad('LICENSE', 12)}UPKEEP`);
+  out.push(`  ${pad('', 5)}${pad('KEY', 20)}${pad('VERSION', 9)}${pad('SOURCE', 10)}${pad('AUTHOR', 20)}${pad('ORIGIN', 26)}${pad('LICENSE', 12)}UPKEEP`);
   for (const r of shown) {
     const mark = r.enabled ? '[x]' : '[ ]';
     // An inferred credit is marked so it never reads as something the author
     // typed — the catalog's whole job is honest attribution (ADR 0107 §2).
     const suffix = r.credit.inferred ? '*' : '';
     const upkeep = (r.maintenance && r.maintenance.status) || 'undeclared';
-    out.push(`  ${pad(mark, 5)}${pad(clip(r.key, 19), 20)}${pad(r.source, 10)}${pad(clip((r.credit.author || '—') + suffix, 19), 20)}${pad(clip((r.credit.origin || '—') + suffix, 25), 26)}${pad(clip(r.license || '—', 11), 12)}${upkeep}`);
+    out.push(`  ${pad(mark, 5)}${pad(clip(r.key, 19), 20)}${pad(clip(r.version || '—', 8), 9)}${pad(r.source, 10)}${pad(clip((r.credit.author || '—') + suffix, 19), 20)}${pad(clip((r.credit.origin || '—') + suffix, 25), 26)}${pad(clip(r.license || '—', 11), 12)}${upkeep}`);
   }
   out.push('');
   out.push('  [x] enabled here · [ ] available, not enabled');
@@ -776,6 +778,90 @@ async function cmdSubmit(args, {
   return 0;
 }
 
+// ---------------------------------------------------------------------------
+// bongos module publish <key> — put a module version in the store (ADR 0338 D1)
+// ---------------------------------------------------------------------------
+
+// `bongos module publish <key>` — task 1004271. Packs modules/<key>/ into the
+// store's tarball + hash manifest (scripts/gds/module-artifact.js — the core
+// release's own format, through the publish denylist), then uploads it to
+// POST /store/modules/:key/versions, which re-verifies every hash itself and
+// records the version. `--dry-run` packs and reports without uploading;
+// `--out <dir>` also writes the tarball and its side-car manifest there.
+// Distinct from `submit`, which proposes a module INTO core (ADR 0135).
+async function cmdPublish(args, {
+  log = console.log, errlog = console.error,
+  modulesDir = MODULES_DIR, pack, upload, writeFile = fs.writeFileSync,
+} = {}) {
+  const key = args.find((a, i) => !a.startsWith('-') && args[i - 1] !== '--out');
+  if (!key) {
+    errlog('usage: bongos module publish <key> [--dry-run] [--out <dir>]');
+    return 2;
+  }
+  const dryRun = args.includes('--dry-run');
+  const outIdx = args.indexOf('--out');
+  const outDir = outIdx !== -1 ? args[outIdx + 1] : null;
+  if (outIdx !== -1 && (!outDir || outDir.startsWith('--'))) {
+    errlog('usage: bongos module publish <key> [--dry-run] [--out <dir>]');
+    return 2;
+  }
+
+  const artifact = require('./module-artifact');
+  let packed;
+  try { packed = (pack || ((k) => artifact.packModule(k, { modulesDir })))(key); }
+  catch (e) { errlog(`REFUSING: ${e.message}`); return 1; }
+  const { tgz, sidecar } = packed;
+  log(`bongos module publish — "${key}" ${sidecar.module_version} (needs core ${sidecar.core_version})`);
+  log(`  ✓ packed ${sidecar.file_count} file(s), ${tgz.length} bytes — tree ${sidecar.tree_sha256.slice(0, 12)}…`);
+  if (tgz.length > artifact.MAX_TARBALL_BYTES) {
+    errlog(`REFUSING: the tarball is ${tgz.length} bytes, over the store's ${artifact.MAX_TARBALL_BYTES}-byte cap.`);
+    return 1;
+  }
+
+  if (outDir) {
+    fs.mkdirSync(outDir, { recursive: true });
+    const tgzPath = path.join(outDir, sidecar.tarball.name);
+    writeFile(tgzPath, tgz);
+    writeFile(tgzPath.replace(/\.tgz$/, '.manifest.json'), JSON.stringify(sidecar, null, 2) + '\n');
+    log(`  ✓ wrote ${tgzPath} (+ .manifest.json)`);
+  }
+  if (dryRun) {
+    log('\n--dry-run: nothing uploaded.');
+    return 0;
+  }
+
+  const doUpload = upload || (async (k, body) => {
+    // Lazy require — the same reason cmdSubmit gives: this file loads in the server
+    // process too, and cli-lib's session/fetch plumbing must never come with it.
+    const { readSessionToken, dispatchedFetch, noKeepAliveDispatcher, CLI_USER_AGENT } = require('./cli-lib');
+    const session = readSessionToken();
+    if (!session) throw new Error('no Bongos session — run `bongos setup` first');
+    const res = await dispatchedFetch(`${session.apiBase}/api/bongos/store/modules/${encodeURIComponent(k)}/versions`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/gzip', Authorization: `Bearer ${session.token}`, 'User-Agent': CLI_USER_AGENT },
+      body,
+      dispatcher: noKeepAliveDispatcher(),
+    });
+    const text = await res.text();
+    let data;
+    try { data = text ? JSON.parse(text) : null; } catch { data = { raw: text }; }
+    return { status: res.status, ok: res.ok, data };
+  });
+
+  let res;
+  try { res = await doUpload(key, tgz); }
+  catch (e) { errlog(`bongos module publish: upload failed — ${e.message}`); return 1; }
+  if (!res.ok) {
+    const err = res.data && (res.data.error || res.data);
+    const detail = (err && (err.message || err.code)) || JSON.stringify(res.data);
+    errlog(`\nREFUSING: the store rejected "${key}" ${sidecar.module_version} (HTTP ${res.status}): ${detail}`);
+    return 1;
+  }
+  const row = res.data && res.data.version;
+  log(`\n✓ Published "${key}" ${row ? row.version : sidecar.module_version} to the store${res.data && res.data.created_module ? ' — its first version, so you are its author' : ''}.`);
+  return 0;
+}
+
 function printHelp(out = console.log) {
   out('bongos module — scaffold + manage Cloud Bongos modules\n');
   out('Usage:');
@@ -787,6 +873,8 @@ function printHelp(out = console.log) {
   out('                              AGPL/publish pre-check before upstreaming + record a DCO-style sign-off');
   out('  bongos module submit <key> [--sign-off "Name <email>"]');
   out('                              Pre-check + sign-off, then file into the rank-gated upstreaming review queue');
+  out('  bongos module publish <key> [--dry-run] [--out <dir>]');
+  out('                              Pack a module version (tarball + hash manifest) and upload it to the module store');
 }
 
 async function main(argv) {
@@ -797,6 +885,7 @@ async function main(argv) {
   if (sub === 'upgrade') return cmdUpgrade(args.slice(1));
   if (sub === 'check') return cmdCheck(args.slice(1));
   if (sub === 'submit') return cmdSubmit(args.slice(1));
+  if (sub === 'publish') return cmdPublish(args.slice(1));
   if (!sub || sub === 'help' || sub === '--help' || sub === '-h') {
     printHelp();
     return sub ? 0 : 2;
@@ -807,7 +896,7 @@ async function main(argv) {
 }
 
 module.exports = {
-  main, cmdNew, cmdList, cmdUpgrade, cmdCheck, cmdSubmit, printHelp,
+  main, cmdNew, cmdList, cmdUpgrade, cmdCheck, cmdSubmit, cmdPublish, printHelp,
   gatherCatalog, formatCatalog, ownProjectName,
   scaffoldModule, gatherUpgrade, evaluateUpgrade, buildManifest,
   formatMaintenanceHint, isPastRemoveAfter,

package/scripts/gds/package-core.js

@@ -103,6 +103,7 @@ 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/gds/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/gds/mirror-redact.js'));
@@ -144,9 +145,6 @@ function coreVersion() {
 // 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.
@@ -418,31 +416,8 @@ function prunePackageLock(sourceLock, { name, version, rootRanges, rootDepNames
   };
 }
 
-// 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 (canonicalTreeHash) and normalizeMode live in scripts/gds/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({
@@ -478,94 +453,8 @@ 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 });
-}
+// The ustar+gzip writer (buildTar and its header helpers) lives in
+// scripts/gds/artifact-format.js (task 1004271), shared with the module store.
 
 // ---- the git-LESS source: enumerate the working tree (task 1003995) --------
 //

package/scripts/gds/plain-cards.js

@@ -8,7 +8,7 @@
 // what happened, what the agent will do next, whether a PERSON is needed (and who), and
 // whether this is a rule rather than a fault. That last one is the expensive mistake:
 // an agent that reads a deliberate restriction as breakage goes looking for a way round
-// it (the box session that asked the owner for a personal access token).
+// it (the agent that asked the owner for a personal access token).
 //
 // STATIC TEXT ONLY. A card interpolates nothing — no task title, no server message — so
 // printing it adds no prompt-injection surface (the strand-watch / push-path-brief rule).

package/scripts/gds/provision-config.js

@@ -83,7 +83,7 @@ const CONFIG = {
   tag: process.env.PROVISION_TAG || 'cloudbongos-instance',
   doToken: process.env.DO_API_TOKEN || null,
   sshKeyIds: (process.env.BOX_SSH_KEY_IDS || '').split(',').map((s) => s.trim()).filter(Boolean),
-  // The Cloudflare DNS hook (the SAME infra/box-dns-cloudflare.sh box.js uses).
+  // The Cloudflare DNS hook (the instance's infra/box-dns-cloudflare.sh).
   // P4 (#1945) formalizes the UPSERT: point the instance's domain at the target
   // public IP (below), in the domain's OWN Cloudflare zone, proxied=false (see
   // dnsUpsertEnv). No hook configured → DNS is skipped (a co-tenant instance is
@@ -179,7 +179,7 @@ const MANIFEST_VERIFY_TRIES = numEnv('PROVISION_MANIFEST_VERIFY_TRIES', 90);
 const MANIFEST_VERIFY_INTERVAL_MS = numEnv('PROVISION_MANIFEST_VERIFY_INTERVAL_MS', 2000);
 
 // ---------------------------------------------------------------------------
-// Lazy dep load (so --help / arg errors need no Postgres) — the box.js pattern.
+// Lazy dep load (so --help / arg errors need no Postgres).
 // ---------------------------------------------------------------------------
 let _deps;
 function loadDeps() {

package/scripts/gds/provision-net.js

@@ -130,8 +130,7 @@ function dnsUpsertEnv(inst, { publicIp, zone, proxied = false } = {}) {
 }
 
 // The RFC 5737 TEST-NET-1 sentinel a released hostname is parked at (task
-// 1003237) — the shape scripts/gds/box-infra.js proved for a torn-down box
-// (idea 309 / task 1234). 192.0.2.1 is reserved for documentation and is
+// 1003237, first proven in task 1234). 192.0.2.1 is reserved for documentation and is
 // GUARANTEED never routable, so a name parked here can never dial platform
 // infra or a recycled address.
 const DNS_BLACKHOLE_IP = '192.0.2.1';
@@ -141,7 +140,7 @@ const DNS_BLACKHOLE_IP = '192.0.2.1';
 // address UPSERTed at the platform's IP for a project that no longer answers
 // there — the ADR 0181 §2 leak — and this is how the runner lets it go.
 //
-// REPOINT, not delete, for the reason box-infra.js records: deleting a name
+// REPOINT, not delete (task 1234): deleting a name
 // opens an NXDOMAIN window that resolvers negative-cache for the zone's SOA
 // neg-TTL (~30 min, not editable), so a client that queried mid-gap stays
 // broken long after. A name that always resolves — to a guaranteed-dead host —

package/scripts/gds/provision.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 // scripts/gds/provision.js — the INSTANCE-provisioning control-plane runner
-// (ADR 0111 §2/§3, BONGOS-V1 goal 32, task #1944). A sibling of box.js.
+// (ADR 0111 §2/§3, BONGOS-V1 goal 32, task #1944).
 //
 // WHAT IT IS. The trust-boundary-safe executor for the `provisioning` module.
 // The internet-facing web tier can only ENQUEUE a provision/teardown intent into
@@ -20,7 +20,7 @@
 //     → Caddy site block + reload
 //     → /healthz
 //
-// DESIGN — inherited from box.js / do-api.js:
+// DESIGN — shared with do-api.js:
 //   • DRY-RUN by DEFAULT. Without --apply, every step only PRINTS the command it
 //     WOULD run and mutates nothing (no DB writes, no shell, no cloud call). The
 //     LIVE leg is an explicit operator/timer `--apply`.
@@ -37,8 +37,8 @@
 //   • The step-command generators are PURE functions (exported) → the SAME command
 //     strings drive local exec (co-tenant) AND the dedicated droplet's cloud-init.
 //
-// This is control-plane ops tooling (scripts/), so — like box.js — it may require
-// the core + a module's data slice directly (a module may not, but a CLI may). It
+// This is control-plane ops tooling (scripts/), so it may require the core + a
+// module's data slice directly (a module may not, but a CLI may). It
 // reuses modules/provisioning/provisioning.js (the intent queue + state) and
 // scripts/gds/do-api.js (the shared DO client extracted in task #1943).
 
@@ -336,7 +336,7 @@ async function provisionInstance(inst, deps) {
   if (inst.hosting_shape === 'dedicated') {
     // Dedicated droplet: create it + settle its public IP via the shared DO client
     // (do-api, dry-run-default). The on-droplet app standup rides cloud-init
-    // user-data built from the SAME step commands below (mirrors box.js). For the
+    // user-data built from the SAME step commands below. For the
     // dry-run plan we surface the intent; --apply creates the droplet.
     const doApi = deps.doApi;
     log('  [server] dedicated droplet');
@@ -1249,8 +1249,8 @@ async function drainOAuthManifests(deps) {
 }
 
 // ---------------------------------------------------------------------------
-// run-intents — drain provisioning_intents (the systemd-timer entry point). The
-// box.js cmdRunIntents shape: dry-run lists the pending queue; --apply claims +
+// run-intents — drain provisioning_intents (the systemd-timer entry point).
+// Dry-run lists the pending queue; --apply claims +
 // executes each, with a poison-attempt cap. FOR UPDATE SKIP LOCKED (in
 // provisioning.claimNextIntent) makes overlapping ticks safe. It ALSO drains the
 // GitHub-App-Manifest conversion queue on the same tick (task 2080).
@@ -1324,8 +1324,8 @@ async function cmdRunIntents(deps) {
 
 // A light drift reconcile: surface instances stuck mid-flight (provisioning /
 // tearing_down) with no open intent — a runner died mid-op. Reports; --apply
-// re-enqueues a fresh intent so the next tick retries. (Full droplet-vs-DB drift,
-// the box.js reconcile-drift analogue, is a later hardening.)
+// re-enqueues a fresh intent so the next tick retries. (Full droplet-vs-DB drift
+// is a later hardening.)
 async function cmdReconcile(deps) {
   const { db, provisioning, log, apply } = deps;
   const { rows } = await db.query(

package/scripts/gds/publish-manifest.js

@@ -68,9 +68,8 @@ const PUBLISH_ALLOWLIST = [
   'modules/hall-ui/',
   'modules/status-ui/',
   'modules/public-landing/', // the front door (task 1003322, ADR 0218) — the repo-root public-landing/ entry this replaces was always here, and for the same reason: default:true, and it is the only thing an instance serves at its apex root. Omit it and a released core answers the game-less 404 tail on its own home page.
-  'modules/dev-box/',
   'modules/discord/',
-  'modules/provisioning/',   // instance-hosting control plane — CORE like its sibling dev-box (same do-api/cf-tunnel toolchain, all core). Reclassified IN so the core CLI scripts/gds/provision.js resolves it from the core package post-split, not a MODULE_NOT_FOUND (task 2135). default:false — shipped ≠ enabled.
+  'modules/provisioning/',   // instance-hosting control plane — CORE (its do-api toolchain is core). Reclassified IN so the core CLI scripts/gds/provision.js resolves it from the core package post-split, not a MODULE_NOT_FOUND (task 2135). default:false — shipped ≠ enabled.
   'modules/agents/',         // the declarative agent registry + spawn seam (goal 1000038) — CORE: its own manifest declares maintenance.status 'core-maintained', and it consumes the core `grade` port, so a released core without it cannot run the MAS machinery the methodology describes. default:false — shipped is not enabled (ADR 0083), exactly like provisioning + platform-identity below. Omitted at module-creation time (tasks 1002485/1002486): the omission was invisible until tests/agents_spawn.mjs became the first PUBLISHABLE file to import it and the R89 boundary guard caught it (task 1002489).
   'modules/npm-release/',    // the deploy page's "where is the work" + version history (task 1002622). default:false — on only in the hall that publishes the core. MUST be here: modules/hall-ui/ ships as one subtree, so a released core without this carries deploy.js's loader and the #nr-work mounts with no routes behind them — the copy-desk asymmetry above.
   'modules/platform-identity/', // hub identity provider (ADR 0141) — ships in core, enabled ONLY on the hub (cloudbongos.com). MUST be here or the hub's enabledModules() throws "unknown module" and provision.js's federation load MODULE_NOT_FOUNDs (task 1002235, same rationale as provisioning above). default:false — shipped ≠ enabled; a vanilla/self-hosted instance never turns it on.