@bongos/core 1.19.1077 → 1.19.1079

package/scripts/gds/module.js

@@ -60,6 +60,7 @@
 //   bongos module list [--catalog]     browse the module catalog (author + origin credit)
 //   bongos upgrade                     pre-check enabled modules vs the core version
 //   bongos module check <key> [--sign-off "Name <email>"]   AGPL/publish pre-check + DCO sign-off
+//   bongos module install <key> [--version X.Y.Z]   acquire from the store, verify, place (not enabled)
 
 const fs = require('node:fs');
 const path = require('node:path');
@@ -862,6 +863,143 @@ async function cmdPublish(args, {
   return 0;
 }
 
+// ---------------------------------------------------------------------------
+// bongos module install <key> — acquire a module from the store (ADR 0338 D1)
+// ---------------------------------------------------------------------------
+
+// The store half of the CLI, over three calls (src/bongos/routes/modules.js):
+// acquire (take the entitlement, learn the version), download the tarball, and
+// once the files are placed, record the version acquired. Injected in tests.
+function storeRequest() {
+  // Lazy require — cli-lib's session/fetch plumbing must never load in the server
+  // process, which requires this file too (the same reason cmdPublish gives).
+  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');
+  return async (method, urlPath, { json, binary = false } = {}) => {
+    const res = await dispatchedFetch(`${session.apiBase}/api/bongos${urlPath}`, {
+      method,
+      headers: {
+        Authorization: `Bearer ${session.token}`, 'User-Agent': CLI_USER_AGENT,
+        ...(json ? { 'Content-Type': 'application/json' } : {}),
+      },
+      body: json ? JSON.stringify(json) : undefined,
+      dispatcher: noKeepAliveDispatcher(),
+    });
+    if (binary && res.ok) return { ok: true, status: res.status, buf: Buffer.from(await res.arrayBuffer()) };
+    const text = await res.text();
+    let data;
+    try { data = text ? JSON.parse(text) : null; } catch { data = { raw: text }; }
+    return { ok: res.ok, status: res.status, data };
+  };
+}
+
+function storeError(res) {
+  const err = res.data && (res.data.error || res.data);
+  return (err && (err.message || err.code)) || `HTTP ${res.status}`;
+}
+
+// Where install places a module: the INSTANCE's own modules/ root (ADR 0108 §1),
+// which the loader discovers. In a single checkout that is this repo's modules/.
+function instanceModulesDir() {
+  return path.join(require('../../src/instance-config').resolveInstanceRoot(), 'modules');
+}
+
+// Write the verified files into a private staging dir beside the target, then
+// rename it into place, so a crash leaves a staging dir to delete, never a
+// half-written module the loader would try to mount.
+function placeModule(files, target) {
+  const staging = `${target}.installing-${process.pid}-${Date.now()}`;
+  fs.mkdirSync(staging, { recursive: true });
+  try {
+    for (const f of files) {
+      const dest = path.join(staging, ...f.path.split('/'));
+      if (!dest.startsWith(staging + path.sep)) throw new Error(`"${f.path}" would land outside the module`);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, f.buf, { mode: parseInt(f.mode, 8) || 0o644 });
+    }
+    fs.renameSync(staging, target);
+  } catch (e) {
+    fs.rmSync(staging, { recursive: true, force: true });
+    throw e;
+  }
+}
+
+// `bongos module install <key> [--version X.Y.Z]` — task 1003785. Acquires the
+// module (a free one is granted on the spot; a priced one waits on the buy action,
+// area 8), downloads its tarball, verifies it with verifyModuleArtifact — the one
+// checker the store itself uses on publish — and places it under the instance's
+// modules/. It never enables: the loader discovers what is on disk and the hall's
+// Modules tab decides what mounts. A module already on disk is refused; moving an
+// installed module to a newer version is `update` (task 1003786).
+async function cmdInstall(args, {
+  log = console.log, errlog = console.error,
+  modulesDir, request, core,
+} = {}) {
+  const usage = 'usage: bongos module install <key> [--version X.Y.Z]';
+  const vIdx = args.indexOf('--version');
+  const wanted = vIdx !== -1 ? args[vIdx + 1] : null;
+  const key = args.find((a, i) => !a.startsWith('-') && args[i - 1] !== '--version');
+  if (!key || (vIdx !== -1 && (!wanted || wanted.startsWith('--')))) { errlog(usage); return 2; }
+  if (!KEY_RE.test(key)) { errlog(`REFUSING: "${key}" is not a module key (lowercase kebab-case).`); return 2; }
+  const { parseVersion, satisfies } = require('../../src/module-loader/semver');
+  if (wanted && !parseVersion(wanted)) { errlog(`REFUSING: --version must be exact X.Y.Z, not "${wanted}".`); return 2; }
+
+  const dir = modulesDir || instanceModulesDir();
+  const target = path.join(dir, key);
+  if (fs.existsSync(target)) {
+    errlog(`REFUSING: "${key}" is already on disk at ${target}. Install only adds a new module; updating one is a separate command.`);
+    return 1;
+  }
+
+  let call;
+  try { call = request || storeRequest(); }
+  catch (e) { errlog(`bongos module install: ${e.message}`); return 1; }
+
+  const enc = encodeURIComponent(key);
+  let acq;
+  try { acq = await call('POST', `/store/modules/${enc}/acquire`, { json: wanted ? { version: wanted } : {} }); }
+  catch (e) { errlog(`bongos module install: the store could not be reached — ${e.message}`); return 1; }
+  if (!acq.ok) { errlog(`REFUSING: the store would not hand over "${key}" (HTTP ${acq.status}): ${storeError(acq)}`); return 1; }
+  const a = acq.data;
+  log(`bongos module install — "${key}" ${a.version} (needs core ${a.core_version})`);
+
+  const coreV = core || require('../../src/module-api').CORE_VERSION;
+  if (!satisfies(coreV, a.core_version)) {
+    errlog(`REFUSING: "${key}" ${a.version} needs core ${a.core_version}; this core is ${coreV}, so it could not mount.`);
+    return 1;
+  }
+
+  let dl;
+  try { dl = await call('GET', `/store/modules/${enc}/versions/${encodeURIComponent(a.version)}/tarball`, { binary: true }); }
+  catch (e) { errlog(`bongos module install: download failed — ${e.message}`); return 1; }
+  if (!dl.ok) { errlog(`REFUSING: the download was refused (HTTP ${dl.status}): ${storeError(dl)}`); return 1; }
+
+  const artifact = require('./module-artifact');
+  const v = await artifact.verifyModuleArtifact(dl.buf, { key, includeFiles: true });
+  if (!v.ok) { errlog(`REFUSING: the downloaded tarball failed verification (${v.code}): ${v.message}`); return 1; }
+  if (v.version !== a.version || v.tarballSha256 !== a.tarball_sha256 || v.treeSha256 !== a.tree_sha256) {
+    errlog(`REFUSING: the download is not the ${a.version} the store described (version or hash differs).`);
+    return 1;
+  }
+  log(`  ✓ verified ${v.files.length} file(s), ${v.bytes} bytes — tree ${v.treeSha256.slice(0, 12)}…`);
+
+  try { placeModule(v.files, target); }
+  catch (e) { errlog(`bongos module install: could not place the module — ${e.message}`); return 1; }
+  log(`  ✓ placed at ${target}`);
+
+  let rec;
+  try { rec = await call('POST', `/store/modules/${enc}/acquired`, { json: { version: a.version } }); }
+  catch (e) { rec = { ok: false, status: 0, data: { error: { message: e.message } } }; }
+  if (!rec.ok) {
+    errlog(`WARNING: "${key}" is installed, but the store did not record the version (${storeError(rec)}). Nothing is lost; the next install or update records it.`);
+    return 1;
+  }
+
+  log(`\n✓ Installed "${key}" ${a.version}. It is not switched on: enable it from the hall's Modules tab when you want it.`);
+  return 0;
+}
+
 function printHelp(out = console.log) {
   out('bongos module — scaffold + manage Cloud Bongos modules\n');
   out('Usage:');
@@ -875,6 +1013,8 @@ function printHelp(out = console.log) {
   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');
+  out('  bongos module install <key> [--version X.Y.Z]');
+  out('                              Acquire a module from the store, verify it and place it under modules/ (not enabled)');
 }
 
 async function main(argv) {
@@ -886,6 +1026,7 @@ async function main(argv) {
   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 === 'install') return cmdInstall(args.slice(1));
   if (!sub || sub === 'help' || sub === '--help' || sub === '-h') {
     printHelp();
     return sub ? 0 : 2;
@@ -896,7 +1037,7 @@ async function main(argv) {
 }
 
 module.exports = {
-  main, cmdNew, cmdList, cmdUpgrade, cmdCheck, cmdSubmit, cmdPublish, printHelp,
+  main, cmdNew, cmdList, cmdUpgrade, cmdCheck, cmdSubmit, cmdPublish, cmdInstall, printHelp,
   gatherCatalog, formatCatalog, ownProjectName,
   scaffoldModule, gatherUpgrade, evaluateUpgrade, buildManifest,
   formatMaintenanceHint, isPastRemoveAfter,

package/src/bongos/module-entitlements.js

@@ -0,0 +1,127 @@
+// src/bongos/module-entitlements.js — the entitlement record: who holds which
+// module, at which version (task 1003813, ADR 0338 D1; table core_259).
+//
+// This is the ONE place install, update and the telemetry signals ask "does this
+// holder own this module?" — the store checks it before it serves a tarball. It is
+// the record of ownership, not of payment: a grant needs no money to have moved,
+// so free and core-bundled modules hold an entitlement through the same rows a
+// paid one will (area 8 writes source 'purchase' + payment_ref when it lands).
+//
+// Rules the functions enforce, from ADR 0338 D2:
+//   - ownership is per MODULE, the acquired version moves forward under it, so an
+//     update never asks for a second purchase;
+//   - a delist never reaches this table — only revokeEntitlement ends a hold (the
+//     refund path, task 1003789), and it keeps the row rather than deleting it.
+//
+// Every function takes { db } (a pg Pool or anything with query()) so tests run
+// against a fake client, the way module-store.js does.
+
+const { parseVersion, cmp } = require('../module-loader/semver');
+const { KEY_RE } = require('../module-loader/manifest-schema');
+
+const HOLDER_KINDS = ['builder', 'instance'];
+const SOURCES = ['free', 'core', 'grant', 'purchase'];
+
+const COLS = `id, module_key, holder_kind, holder_ref, source, payment_ref, version,
+  acquired_at, granted_by, granted_at, revoked_at, revoked_reason`;
+
+function poolOf(db) { return db || require('./pool').pool; }
+
+// A bad argument is a programming error in the caller, not a user error: throw.
+function assertHolder(moduleKey, holderKind, holderRef) {
+  if (!KEY_RE.test(String(moduleKey))) throw new Error('entitlement: a bad module key');
+  if (!HOLDER_KINDS.includes(holderKind)) throw new Error(`entitlement: holder_kind must be one of ${HOLDER_KINDS.join(', ')}`);
+  if (typeof holderRef !== 'string' || !holderRef.length) throw new Error('entitlement: holder_ref is required');
+}
+
+// Give a holder a module. Idempotent: granting a holder that already holds it is a
+// no-op that returns the existing row (an earlier source is never rewritten), and
+// granting one whose hold was revoked lifts the revocation on the same row.
+// `source: 'purchase'` is area 8's to use; nothing here checks a payment.
+async function grantEntitlement({ moduleKey, holderKind, holderRef, source, grantedBy = null, paymentRef = null }, { db } = {}) {
+  assertHolder(moduleKey, holderKind, holderRef);
+  if (!SOURCES.includes(source)) throw new Error(`entitlement: source must be one of ${SOURCES.join(', ')}`);
+  const pool = poolOf(db);
+  const { rows: [fresh] } = await pool.query(
+    `INSERT INTO module_entitlements (module_key, holder_kind, holder_ref, source, payment_ref, granted_by)
+     VALUES ($1, $2, $3, $4, $5, $6)
+     ON CONFLICT (module_key, holder_kind, holder_ref) DO NOTHING
+     RETURNING ${COLS}`,
+    [moduleKey, holderKind, holderRef, source, paymentRef, grantedBy]);
+  if (fresh) return { entitlement: fresh, created: true };
+  const { rows: [held] } = await pool.query(
+    `UPDATE module_entitlements
+        SET revoked_at = NULL, revoked_reason = NULL, source = $4, payment_ref = $5,
+            granted_by = $6, granted_at = now()
+      WHERE module_key = $1 AND holder_kind = $2 AND holder_ref = $3 AND revoked_at IS NOT NULL
+      RETURNING ${COLS}`,
+    [moduleKey, holderKind, holderRef, source, paymentRef, grantedBy]);
+  if (held) return { entitlement: held, created: false, reinstated: true };
+  const { rows: [same] } = await pool.query(
+    `SELECT ${COLS} FROM module_entitlements WHERE module_key = $1 AND holder_kind = $2 AND holder_ref = $3`,
+    [moduleKey, holderKind, holderRef]);
+  return { entitlement: same, created: false };
+}
+
+// Record the exact version a holder acquired. Refuses a holder with no live
+// entitlement (nothing is handed over without one) and a version older than the
+// one already held (an update moves forward; a rollback is a separate act, so it
+// must be asked for with allowDowngrade).
+async function recordAcquired({ moduleKey, holderKind, holderRef, version, allowDowngrade = false }, { db } = {}) {
+  assertHolder(moduleKey, holderKind, holderRef);
+  const wanted = parseVersion(String(version));
+  if (!wanted) throw new Error('entitlement: version must be exact X.Y.Z');
+  const pool = poolOf(db);
+  const { rows: [cur] } = await pool.query(
+    `SELECT ${COLS} FROM module_entitlements
+      WHERE module_key = $1 AND holder_kind = $2 AND holder_ref = $3`,
+    [moduleKey, holderKind, holderRef]);
+  if (!cur || cur.revoked_at) return { ok: false, code: 'not_entitled' };
+  const held = cur.version && parseVersion(cur.version);
+  if (held && !allowDowngrade && cmp(wanted, held) < 0) return { ok: false, code: 'version_older_than_held' };
+  const { rows: [row] } = await pool.query(
+    `UPDATE module_entitlements SET version = $2, acquired_at = now()
+      WHERE id = $1 AND revoked_at IS NULL
+      RETURNING ${COLS}`,
+    [cur.id, version]);
+  return row ? { ok: true, entitlement: row } : { ok: false, code: 'not_entitled' };
+}
+
+// End a hold. Only the refund path calls this (task 1003789); a delist must not.
+// The row stays, stamped with when and why.
+async function revokeEntitlement({ moduleKey, holderKind, holderRef, reason }, { db } = {}) {
+  assertHolder(moduleKey, holderKind, holderRef);
+  if (typeof reason !== 'string' || !reason.trim()) throw new Error('entitlement: a revocation needs a reason');
+  const { rows: [row] } = await poolOf(db).query(
+    `UPDATE module_entitlements SET revoked_at = now(), revoked_reason = $4
+      WHERE module_key = $1 AND holder_kind = $2 AND holder_ref = $3 AND revoked_at IS NULL
+      RETURNING ${COLS}`,
+    [moduleKey, holderKind, holderRef, reason.trim()]);
+  return row ? { ok: true, entitlement: row } : { ok: false, code: 'not_entitled' };
+}
+
+// The question the store asks before it serves: does this holder hold this module
+// right now? `entitled` is false for no row and for a revoked row; the row itself
+// comes back either way so the caller can say WHY.
+async function checkEntitlement({ moduleKey, holderKind, holderRef }, { db } = {}) {
+  assertHolder(moduleKey, holderKind, holderRef);
+  const { rows: [row] } = await poolOf(db).query(
+    `SELECT ${COLS} FROM module_entitlements
+      WHERE module_key = $1 AND holder_kind = $2 AND holder_ref = $3`,
+    [moduleKey, holderKind, holderRef]);
+  return { entitled: !!row && !row.revoked_at, entitlement: row || null };
+}
+
+// Everything one holder holds (live and revoked), newest grant first.
+async function listEntitlements({ holderKind, holderRef }, { db } = {}) {
+  assertHolder('x', holderKind, holderRef);
+  const { rows } = await poolOf(db).query(
+    `SELECT ${COLS} FROM module_entitlements
+      WHERE holder_kind = $1 AND holder_ref = $2 ORDER BY granted_at DESC, id DESC`,
+    [holderKind, holderRef]);
+  return rows;
+}
+
+module.exports = {
+  grantEntitlement, recordAcquired, revokeEntitlement, checkEntitlement, listEntitlements,
+};

package/src/bongos/module-store.js

@@ -136,6 +136,61 @@ async function publishVersion(input, { db, beforeCommit } = {}) {
   }
 }
 
+// ---- the read side: what install acquires (task 1003785) ----------------------
+//
+// A module with NO price row is free. The owner decided this (2026-09-29): nothing
+// sets a price yet and who may sell is still open, so an unpriced module is
+// acquirable at no cost, and an entitlement taken then is kept if a price is added
+// later (ADR 0338 D2). A priced module is free when either currency it is offered in
+// is zero (0 = free, NULL = not offered in that currency; core_257).
+function isFreePrice(priceRow) {
+  if (!priceRow) return true;
+  return priceRow.price_cents === 0 || priceRow.price_credits === 0;
+}
+
+// Resolve what an acquire of `key` (optionally at an exact `version`) would hand
+// over. Refuses an unknown or delisted module (ADR 0338 D2: a delisted module takes
+// no new acquisitions and serves no further versions) and an unknown version. With
+// no version asked for, the newest published version (semver order, not text).
+// Returns { ok: true, module, version, price, free } or { ok: false, status, code, message }.
+async function resolveAcquirable(key, { version = null, db } = {}) {
+  const pool = db || require('./pool').pool;
+  const refuse = (status, code, message) => ({ ok: false, status, code, message });
+  const { rows: [mod] } = await pool.query(
+    'SELECT module_key, title, author_id, status FROM store_modules WHERE module_key = $1', [key]);
+  if (!mod) return refuse(404, 'module_not_found', `The store has no module "${key}".`);
+  if (mod.status === 'delisted') return refuse(409, 'module_delisted', `"${key}" is delisted: it can no longer be acquired or downloaded (ADR 0338 D2).`);
+  const { rows: versions } = await pool.query(
+    `SELECT id, module_key, version, core_version, tree_sha256, tarball_sha256, tarball_bytes,
+            artifact_path, published_at
+       FROM store_module_versions WHERE module_key = $1`, [key]);
+  let row;
+  if (version) {
+    row = versions.find((r) => r.version === version);
+    if (!row) return refuse(404, 'version_not_found', `"${key}" has no published version ${version}.`);
+  } else {
+    row = versions.filter((r) => parseVersion(r.version))
+      .sort((a, b) => cmp(parseVersion(a.version), parseVersion(b.version))).pop();
+    if (!row) return refuse(404, 'no_versions', `"${key}" has no published version yet.`);
+  }
+  const { rows: [price] } = await pool.query(
+    `SELECT price_cents, price_credits, set_at FROM store_module_prices
+      WHERE module_key = $1 ORDER BY set_at DESC, id DESC LIMIT 1`, [key]);
+  return { ok: true, module: mod, version: row, price: price || null, free: isFreePrice(price) };
+}
+
+// The tarball on disk for a version row. artifact_path is relative to the store dir
+// (relativeArtifactPath), and artifactPath() re-validates key + version, so a row
+// can never point a read outside the store.
+function versionArtifactFile(row, { dir = storeDir() } = {}) {
+  const file = artifactPath(row.module_key, row.version, { dir });
+  if (relativeArtifactPath(file, { dir }) !== row.artifact_path) {
+    throw new Error(`store row for ${row.module_key} ${row.version} names an unexpected artifact path`);
+  }
+  return file;
+}
+
 module.exports = {
   stageArtifact, commitArtifact, removeArtifact, relativeArtifactPath, publishVersion,
+  isFreePrice, resolveAcquirable, versionArtifactFile,
 };

package/src/bongos/routes/modules.js

@@ -23,6 +23,15 @@
 //                               server end of `bongos module publish`. Not the
 //                               upstreaming door above: submit proposes a module
 //                               INTO core; publish puts a version in the store.
+//   GET  /store/entitlements   the modules the caller holds, and at which version
+//   GET  /store/modules/:key/entitlement
+//                               does the caller hold this module (task 1003813).
+//   POST /store/modules/:key/acquire
+//   GET  /store/modules/:key/versions/:version/tarball
+//   POST /store/modules/:key/acquired
+//                               the server end of `bongos module install` (task
+//                               1003785): take the entitlement, download the
+//                               checked tarball, record the version placed.
 //
 // Read is open to any signed-in builder (same gate as the atlas/primer pages);
 // every write (enable/disable, submit) is metic+archon, same rank as
@@ -50,6 +59,7 @@
 // cross-repo call to the extracted core repo): see
 // docs/adr/0135-module-upstream-submission-interim-queue.md.
 
+const fs = require('node:fs');
 const express = require('express');
 const auth = require('../auth');
 const { asyncHandler, validateOrRespond, LIMITS } = require('./_helpers');
@@ -65,8 +75,14 @@ const modulesLib = require('../../modules');
 const moduleCli = require('../../../scripts/gds/module');
 const moduleSubmissions = require('../module-submissions');
 const moduleArtifact = require('../../../scripts/gds/module-artifact');
-const { stageArtifact, commitArtifact, removeArtifact, relativeArtifactPath, publishVersion } = require('../module-store');
+const { checkEntitlement, listEntitlements, grantEntitlement, recordAcquired } = require('../module-entitlements');
+const {
+  stageArtifact, commitArtifact, removeArtifact, relativeArtifactPath, publishVersion,
+  resolveAcquirable, versionArtifactFile,
+} = require('../module-store');
 const { KEY_RE } = require('../../module-loader/manifest-schema');
+const { parseVersion } = require('../../module-loader/semver');
+const log = require('../logger').logger.child({ src: 'modules' });
 // Named imports, not a namespace object (task 1004052 strand walk): knip cannot follow
 // property access on a CommonJS namespace, so reaching these through one made them read
 // as unused exports and tripped the dead-code ratchet that held this branch out of main.
@@ -347,6 +363,136 @@ module.exports = function buildModulesRouter() {
       res.status(201).json({ ok: true, created_module: result.created, version: result.version });
     }));
 
+  // GET /api/bongos/store/entitlements and /store/modules/:key/entitlement — the
+  // read side of the entitlement record (task 1003813, ADR 0338 D1). Own-scoped
+  // like /me/sessions: the holder is ALWAYS the caller (holder_kind 'builder',
+  // holder_ref = req.builder.id), never named in the query or path, so requireBuilder
+  // alone is the gate and one builder cannot read another's holdings. Granting has no
+  // route yet: install (task 1003785) grants a free module, area 8's buy action
+  // grants a paid one — both through src/bongos/module-entitlements.js.
+  router.get('/store/entitlements', auth.requireBuilder,
+    asyncHandler('GET /store/entitlements', async (req, res) => {
+      const entitlements = await listEntitlements({ holderKind: 'builder', holderRef: String(req.builder.id) });
+      res.set('Cache-Control', 'no-store');
+      res.json({ entitlements });
+    }));
+
+  router.get('/store/modules/:key/entitlement', auth.requireBuilder,
+    asyncHandler('GET /store/modules/:key/entitlement', async (req, res) => {
+      const { key } = req.params;
+      if (!KEY_RE.test(key)) {
+        return res.fail('bad_module_key', { status: 400, message: 'A module key is lowercase kebab-case.' });
+      }
+      const held = await checkEntitlement({ moduleKey: key, holderKind: 'builder', holderRef: String(req.builder.id) });
+      res.set('Cache-Control', 'no-store');
+      res.json(held);
+    }));
+
+  // ---- install: acquire → download → record (task 1003785, ADR 0338 D1) ----
+  //
+  // The server end of `bongos module install`. Three steps, so the store never
+  // records a version as acquired that the caller did not verify and place:
+  //   1. POST acquire   — resolve the version, and take the entitlement: a free
+  //                       module (no price, or a zero price) is granted here with
+  //                       source 'free'; a priced one needs the buy action, which is
+  //                       area 8's (tasks 1003788/1003789) and answers 402 until then.
+  //   2. GET  tarball   — served only to a LIVE entitlement holder, never for a
+  //                       delisted module (ADR 0338 D2: no further versions served).
+  //   3. POST acquired  — the CLI has verified the bytes with verifyModuleArtifact and
+  //                       placed them; recordAcquired stamps the exact version.
+  // Own-scoped like the entitlement reads: the holder is always the caller
+  // (holder_kind 'builder'), never named in the request, so requireBuilder is the
+  // gate — any signed-in builder may take a free module for themselves, and nothing
+  // here changes what runs on this instance (install never enables; the CLI places
+  // files on the CALLER's checkout).
+  //
+  // Channels: every version is on the general channel until the channel table
+  // (task 1003815) and "install honours the channel" (task 1003805) land; those
+  // add the channel check to step 1 and step 2, beside the entitlement check.
+  router.post('/store/modules/:key/acquire', auth.requireBuilder,
+    asyncHandler('POST /store/modules/:key/acquire', async (req, res) => {
+      const { key } = req.params;
+      if (!KEY_RE.test(key)) {
+        return res.fail('bad_module_key', { status: 400, message: 'A module key is lowercase kebab-case.' });
+      }
+      if (validateOrRespond(req, res, { version: { type: 'string', maxLength: 32 } })) return;
+      const wanted = req.body && req.body.version;
+      if (wanted != null && !parseVersion(String(wanted))) {
+        return res.fail('bad_version', { status: 400, message: 'A version is exact X.Y.Z.' });
+      }
+      const r = await resolveAcquirable(key, { version: wanted || null });
+      if (!r.ok) return res.fail(r.code, { status: r.status, message: r.message });
+
+      const holder = { moduleKey: key, holderKind: 'builder', holderRef: String(req.builder.id) };
+      let held = await checkEntitlement(holder);
+      if (!held.entitled) {
+        if (!r.free) {
+          return res.fail('payment_required', {
+            status: 402,
+            message: `"${key}" is priced, and buying a module is not available yet (it arrives with the credit economy, area 8).`,
+          });
+        }
+        const g = await grantEntitlement({ ...holder, source: 'free', grantedBy: req.builder.id });
+        held = { entitled: true, entitlement: g.entitlement };
+      }
+      const v = r.version;
+      res.set('Cache-Control', 'no-store');
+      res.json({
+        ok: true,
+        module_key: key,
+        version: v.version,
+        core_version: v.core_version,
+        tarball_sha256: v.tarball_sha256,
+        tree_sha256: v.tree_sha256,
+        tarball_bytes: Number(v.tarball_bytes),
+        channel: 'general',
+        entitlement: held.entitlement,
+      });
+    }));
+
+  router.get('/store/modules/:key/versions/:version/tarball', auth.requireBuilder,
+    asyncHandler('GET /store/modules/:key/versions/:version/tarball', async (req, res) => {
+      const { key, version } = req.params;
+      if (!KEY_RE.test(key) || !parseVersion(version)) {
+        return res.fail('bad_request', { status: 400, message: 'A module key is lowercase kebab-case and a version is exact X.Y.Z.' });
+      }
+      const r = await resolveAcquirable(key, { version });
+      if (!r.ok) return res.fail(r.code, { status: r.status, message: r.message });
+      const held = await checkEntitlement({ moduleKey: key, holderKind: 'builder', holderRef: String(req.builder.id) });
+      if (!held.entitled) {
+        return res.fail('not_entitled', { status: 403, message: `You do not hold "${key}". Acquire it first.` });
+      }
+      let buf;
+      try { buf = await fs.promises.readFile(versionArtifactFile(r.version)); }
+      catch (e) {
+        log.error({ key, version, err: e.message }, 'store tarball missing');
+        return res.fail('artifact_missing', { status: 500, message: `The store has no file for ${key} ${version}.` });
+      }
+      res.set('Cache-Control', 'no-store');
+      res.set('Content-Type', 'application/gzip');
+      res.set('X-Tarball-Sha256', r.version.tarball_sha256);
+      res.send(buf);
+    }));
+
+  router.post('/store/modules/:key/acquired', auth.requireBuilder,
+    asyncHandler('POST /store/modules/:key/acquired', async (req, res) => {
+      const { key } = req.params;
+      if (!KEY_RE.test(key)) {
+        return res.fail('bad_module_key', { status: 400, message: 'A module key is lowercase kebab-case.' });
+      }
+      if (validateOrRespond(req, res, { version: { type: 'string', required: true, maxLength: 32 } })) return;
+      const { version } = req.body;
+      if (!parseVersion(version)) return res.fail('bad_version', { status: 400, message: 'A version is exact X.Y.Z.' });
+      const r = await resolveAcquirable(key, { version });
+      if (!r.ok) return res.fail(r.code, { status: r.status, message: r.message });
+      const out = await recordAcquired({ moduleKey: key, holderKind: 'builder', holderRef: String(req.builder.id), version });
+      if (!out.ok) {
+        const status = out.code === 'not_entitled' ? 403 : 409;
+        return res.fail(out.code, { status, message: out.code === 'not_entitled' ? `You do not hold "${key}".` : `You already hold a newer version of "${key}".` });
+      }
+      res.json({ ok: true, entitlement: out.entitlement });
+    }));
+
   return router;
 };
 

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.19.1077'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1079'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');