@bongos/core 1.19.1078 → 1.19.1080

package/docs/modules-contract.md

@@ -357,6 +357,22 @@ Run `bongos upgrade` to confirm coreVersion compatibility, then `node scripts/gd
 - The publish denylist applies (ADR 0098), plus a refusal of credential-named files (`.env*`, `*.pem`, `*.key`, `id_rsa`, …) anywhere in the module. The store re-checks every hash and the denylist itself.
 - Gate: Metic+ (`module.submit`) for now. This is not `bongos module submit`, which proposes a module *into* core.
 
+### 7. Install from the store
+
+`bongos module install <key> [--version X.Y.Z]` acquires a module from the store and places it under the instance's `modules/`. Three calls: `POST /store/modules/:key/acquire` takes your entitlement and names the version (the newest unless you pick one), `GET /store/modules/:key/versions/:version/tarball` downloads it, and once the files are placed, `POST /store/modules/:key/acquired` records the exact version.
+
+- The download is checked with `verifyModuleArtifact`, the same checker the store runs on publish, and must match the version and hashes the store described. A failed check places nothing.
+- A module with no price, or a zero price, is free and granted on the spot. A priced one answers 402 until buying exists (area 8). An entitlement is kept for good, even if a price is added later (ADR 0338 D2).
+- Install never enables. Switch the module on from the hall's Modules tab.
+- A module already on disk, in the instance's `modules/` or bundled with the core, is refused; moving one to a newer version is `update`. A module this core cannot mount is refused before download.
+- A delisted module cannot be acquired or downloaded. Channels are not checked yet: every version is general until the channel tasks land.
+
+`bongos module update <key> [--version X.Y.Z]` moves an installed store module forward through the same three calls, so a paid module and a free one take one identical path, and a module you already hold is never charged again (`tests/module_update.mjs` fails if a price-conditional branch appears).
+
+- With no `--version` it takes the newest, and says "up to date" without downloading when that isn't newer. An older `--version` is refused: update only moves forward.
+- The new version is written beside the old one and swapped in; any failure leaves the installed version in place. Files the new version dropped are gone afterwards.
+- The on/off switch is untouched. A module bundled with the core is refused; it updates with the core (`bongos upgrade`).
+
 ## Carving an existing core domain (the `db.js` per-domain pattern)
 
 Most BONGOS-V1 module work is not scaffolding a *new* module — it's **carving an existing core domain out of the monolith** (ADR 0091, criterion C7). The reference carve is the kernel slice `src/bongos/db-kernel.js` (BV1.R69); the feature precedents are `modules/discord/db.js` + `modules/game/db.js`. Every later carve (memory R72, grading R73, …) copies this recipe. The invariant is **OTB byte-identical** at every step — you are *moving* code, not changing behavior.

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1078",
+  "version": "1.19.1080",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.1078",
+      "version": "1.19.1080",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1078",
+  "version": "1.19.1080",
   "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",
@@ -29,6 +29,6 @@
     "pino": "^9.14.0"
   },
   "overrides": {
-    "undici": "^6.28.0"
+    "undici": "^6.28.1"
   }
 }

package/release-notes.json

@@ -7861,5 +7861,17 @@
       "id": "1003813",
       "text": "The store now has a durable record of who owns which module and at which version, so install and update can check it. Free and bundled modules use the same record; nothing charges money yet."
     }
+  ],
+  "1.19.1079": [
+    {
+      "id": "1003785",
+      "text": "You can now install a module from the store with one command. It checks the download is exactly what was published and never switches the module on by itself. Modules without a price are free."
+    }
+  ],
+  "1.19.1080": [
+    {
+      "id": "1003786",
+      "text": "Installed modules can now be updated with one command. Paid and free modules update the exact same way, you are never charged twice, and a failed update leaves your working version in place."
+    }
   ]
 }

package/scripts/gds/module-artifact.js

@@ -141,7 +141,10 @@ function packModule(key, { modulesDir, now = () => new Date(), modeOf } = {}) {
 // 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 } = {}) {
+// `includeFiles: true` (install, task 1003785) also returns `files`: the module's own
+// files — [{ path, mode, buf }], the inner manifest left out — from the SAME parse the
+// hashes were checked against, so a caller that places them never re-reads the bytes.
+async function verifyModuleArtifact(tgz, { key, maxBytes = MAX_TARBALL_BYTES, includeFiles = false } = {}) {
   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`);
@@ -202,11 +205,15 @@ async function verifyModuleArtifact(tgz, { key, maxBytes = MAX_TARBALL_BYTES } =
     return fail('bad_manifest', 'the manifest version does not match module.json');
   }
 
-  return {
+  const out = {
     ok: true, manifest, moduleJson,
     version: moduleJson.version, coreVersion: moduleJson.coreVersion,
     treeSha256: treeSha, tarballSha256: sha256hex(tgz), bytes: tgz.length,
   };
+  if (includeFiles) {
+    out.files = [...byName.entries()].map(([p, e]) => ({ path: p, mode: normalizeMode(e.mode.toString(8)), buf: e.buf }));
+  }
+  return out;
 }
 
 module.exports = { MAX_TARBALL_BYTES, packModule, verifyModuleArtifact };

package/scripts/gds/module.js

@@ -60,6 +60,8 @@
 //   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)
+//   bongos module update <key> [--version X.Y.Z]    move an installed store module forward
 
 const fs = require('node:fs');
 const path = require('node:path');
@@ -862,6 +864,269 @@ 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;
+  }
+}
+
+// Every discovery root the loader scans (core + instance, ADR 0108 §1). A key on
+// disk in ANY of them is already taken: the loader treats a repeated key as a hard
+// error, so placing a second copy in the instance root would break boot.
+function discoveryRoots() {
+  return require('../../src/module-loader/loader').DEFAULT_ROOTS;
+}
+
+// Parse `<key> [--version X.Y.Z]` for install and update. Returns { key, wanted }
+// or { code } (2 = usage) after printing why.
+function parseStoreArgs(args, verb, errlog) {
+  const usage = `usage: bongos module ${verb} <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 { code: 2 }; }
+  if (!KEY_RE.test(key)) { errlog(`REFUSING: "${key}" is not a module key (lowercase kebab-case).`); return { code: 2 }; }
+  const { parseVersion } = require('../../src/module-loader/semver');
+  if (wanted && !parseVersion(wanted)) { errlog(`REFUSING: --version must be exact X.Y.Z, not "${wanted}".`); return { code: 2 }; }
+  return { key, wanted };
+}
+
+// The one acquisition path install AND update share (task 1003786): acquire, check
+// the version can mount on this core, download, verify with verifyModuleArtifact and
+// hold the bytes to what the store described. Nothing here reads a price or branches
+// on how the module was obtained — the store decides entitlement, and a holder it has
+// already granted (for any reason) is never asked again. tests/module_update.mjs
+// fails if a price-conditional branch appears in this path.
+//
+// `shouldDownload(described)` lets update stop before the download when the store's
+// version is not newer than what is installed. Resolves { ok, described, verified }
+// or { ok: false, code, upToDate? } after printing why.
+async function fetchVerified(key, { wanted, call, core, log, errlog, verb, shouldDownload = () => true }) {
+  const fail = (code, msg) => { if (msg) errlog(msg); return { ok: false, code }; };
+  const enc = encodeURIComponent(key);
+  let acq;
+  try { acq = await call('POST', `/store/modules/${enc}/acquire`, { json: wanted ? { version: wanted } : {} }); }
+  catch (e) { return fail(1, `bongos module ${verb}: the store could not be reached — ${e.message}`); }
+  if (!acq.ok) return fail(1, `REFUSING: the store would not hand over "${key}" (HTTP ${acq.status}): ${storeError(acq)}`);
+  const described = acq.data;
+  log(`bongos module ${verb} — "${key}" ${described.version} (needs core ${described.core_version})`);
+
+  const stop = shouldDownload(described);
+  if (stop !== true) return { ok: false, code: stop.code, upToDate: stop.upToDate };
+
+  const { satisfies } = require('../../src/module-loader/semver');
+  const coreV = core || require('../../src/module-api').CORE_VERSION;
+  if (!satisfies(coreV, described.core_version)) {
+    return fail(1, `REFUSING: "${key}" ${described.version} needs core ${described.core_version}; this core is ${coreV}, so it could not mount.`);
+  }
+
+  let dl;
+  try { dl = await call('GET', `/store/modules/${enc}/versions/${encodeURIComponent(described.version)}/tarball`, { binary: true }); }
+  catch (e) { return fail(1, `bongos module ${verb}: download failed — ${e.message}`); }
+  if (!dl.ok) return fail(1, `REFUSING: the download was refused (HTTP ${dl.status}): ${storeError(dl)}`);
+
+  const artifact = require('./module-artifact');
+  const verified = await artifact.verifyModuleArtifact(dl.buf, { key, includeFiles: true });
+  if (!verified.ok) return fail(1, `REFUSING: the downloaded tarball failed verification (${verified.code}): ${verified.message}`);
+  if (verified.version !== described.version || verified.tarballSha256 !== described.tarball_sha256 || verified.treeSha256 !== described.tree_sha256) {
+    return fail(1, `REFUSING: the download is not the ${described.version} the store described (version or hash differs).`);
+  }
+  log(`  ✓ verified ${verified.files.length} file(s), ${verified.bytes} bytes — tree ${verified.treeSha256.slice(0, 12)}…`);
+  return { ok: true, described, verified };
+}
+
+// Tell the store which exact version was placed. A failure here never undoes the
+// placement: the files are good, and the next install or update records it.
+async function recordPlaced(key, version, { call, errlog, verb }) {
+  let rec;
+  try { rec = await call('POST', `/store/modules/${encodeURIComponent(key)}/acquired`, { json: { version } }); }
+  catch (e) { rec = { ok: false, status: 0, data: { error: { message: e.message } } }; }
+  if (!rec.ok) {
+    errlog(`WARNING: "${key}" is ${verb === 'update' ? 'updated' : 'installed'}, but the store did not record the version (${storeError(rec)}). Nothing is lost; the next install or update records it.`);
+    return false;
+  }
+  return true;
+}
+
+// `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 key already on disk in ANY discovery root 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, roots, request, core,
+} = {}) {
+  const parsed = parseStoreArgs(args, 'install', errlog);
+  if (parsed.code) return parsed.code;
+  const { key, wanted } = parsed;
+
+  const dir = modulesDir || instanceModulesDir();
+  const target = path.join(dir, key);
+  const taken = [dir, ...(roots || discoveryRoots())].map((r) => path.join(r, key)).find((p) => fs.existsSync(p));
+  if (taken) {
+    errlog(`REFUSING: "${key}" is already on disk at ${taken}. Install only adds a new module; to move an installed one forward, run \`bongos module update ${key}\`.`);
+    return 1;
+  }
+
+  let call;
+  try { call = request || storeRequest(); }
+  catch (e) { errlog(`bongos module install: ${e.message}`); return 1; }
+
+  const got = await fetchVerified(key, { wanted, call, core, log, errlog, verb: 'install' });
+  if (!got.ok) return got.code;
+
+  try { placeModule(got.verified.files, target); }
+  catch (e) { errlog(`bongos module install: could not place the module — ${e.message}`); return 1; }
+  log(`  ✓ placed at ${target}`);
+
+  if (!(await recordPlaced(key, got.described.version, { call, errlog, verb: 'install' }))) return 1;
+  log(`\n✓ Installed "${key}" ${got.described.version}. It is not switched on: enable it from the hall's Modules tab when you want it.`);
+  return 0;
+}
+
+// Replace an installed module's directory with a verified new one. The new files
+// are written to a staging dir first; the old dir is moved aside, the new one moved
+// in, and only then is the old one removed — so a failure at any step leaves the
+// previous version in place, never a half-written or missing module.
+function replaceModule(files, target) {
+  const aside = `${target}.previous-${process.pid}-${Date.now()}`;
+  const staging = `${target}.installing-${process.pid}-${Date.now()}`;
+  placeModule(files, staging);
+  try {
+    fs.renameSync(target, aside);
+  } catch (e) {
+    fs.rmSync(staging, { recursive: true, force: true });
+    throw e;
+  }
+  try {
+    fs.renameSync(staging, target);
+  } catch (e) {
+    fs.renameSync(aside, target);
+    fs.rmSync(staging, { recursive: true, force: true });
+    throw e;
+  }
+  fs.rmSync(aside, { recursive: true, force: true });
+}
+
+// `bongos module update <key> [--version X.Y.Z]` — task 1003786. Moves an installed
+// store module forward, through exactly the acquisition path install uses
+// (fetchVerified): the same calls whether the module was free or paid, and a module
+// the caller already holds is never charged again (the store's acquire route only
+// looks at price for a caller with no entitlement). Only forward: with no --version
+// it takes the newest, and says so without downloading when that is not newer; an
+// older --version is refused, since rolling back is a different act. Like install it
+// never enables or disables — the module keeps whatever switch it had.
+async function cmdUpdate(args, {
+  log = console.log, errlog = console.error,
+  modulesDir, roots, request, core,
+} = {}) {
+  const parsed = parseStoreArgs(args, 'update', errlog);
+  if (parsed.code) return parsed.code;
+  const { key, wanted } = parsed;
+
+  const dir = modulesDir || instanceModulesDir();
+  const target = path.join(dir, key);
+  if (!fs.existsSync(path.join(target, 'module.json'))) {
+    const bundled = (roots || discoveryRoots()).map((r) => path.join(r, key)).find((p) => p !== target && fs.existsSync(p));
+    errlog(bundled
+      ? `REFUSING: "${key}" at ${bundled} comes with the core, not the store. It updates when the core does (\`bongos upgrade\`).`
+      : `REFUSING: "${key}" is not installed here. Run \`bongos module install ${key}\` first.`);
+    return 1;
+  }
+  const { parseVersion, cmp } = require('../../src/module-loader/semver');
+  let installed;
+  try { installed = JSON.parse(fs.readFileSync(path.join(target, 'module.json'), 'utf8')).version; }
+  catch (e) { errlog(`REFUSING: could not read the installed ${key}/module.json — ${e.message}`); return 1; }
+  const have = parseVersion(String(installed));
+  if (!have) { errlog(`REFUSING: the installed "${key}" has no exact version in module.json, so there is nothing to compare against.`); return 1; }
+  if (wanted && cmp(parseVersion(wanted), have) < 0) {
+    errlog(`REFUSING: ${wanted} is older than the installed ${installed}. Update only moves forward.`);
+    return 1;
+  }
+
+  let call;
+  try { call = request || storeRequest(); }
+  catch (e) { errlog(`bongos module update: ${e.message}`); return 1; }
+
+  const got = await fetchVerified(key, {
+    wanted, call, core, log, errlog, verb: 'update',
+    shouldDownload: (d) => {
+      const next = parseVersion(String(d.version));
+      if (next && cmp(next, have) > 0) return true;
+      log(`\n✓ "${key}" is up to date at ${installed}.`);
+      return { code: 0, upToDate: true };
+    },
+  });
+  if (!got.ok) return got.code;
+
+  try { replaceModule(got.verified.files, target); }
+  catch (e) { errlog(`bongos module update: could not replace the module, ${installed} is still in place — ${e.message}`); return 1; }
+  log(`  ✓ replaced ${installed} with ${got.described.version} at ${target}`);
+
+  if (!(await recordPlaced(key, got.described.version, { call, errlog, verb: 'update' }))) return 1;
+  log(`\n✓ Updated "${key}" ${installed} → ${got.described.version}. Its on/off switch is unchanged.`);
+  return 0;
+}
+
 function printHelp(out = console.log) {
   out('bongos module — scaffold + manage Cloud Bongos modules\n');
   out('Usage:');
@@ -875,6 +1140,10 @@ 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)');
+  out('  bongos module update <key> [--version X.Y.Z]');
+  out('                              Move an installed store module to a newer version (same path, paid or free)');
 }
 
 async function main(argv) {
@@ -886,6 +1155,8 @@ 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 === 'update') return cmdUpdate(args.slice(1));
   if (!sub || sub === 'help' || sub === '--help' || sub === '-h') {
     printHelp();
     return sub ? 0 : 2;
@@ -896,7 +1167,7 @@ async function main(argv) {
 }
 
 module.exports = {
-  main, cmdNew, cmdList, cmdUpgrade, cmdCheck, cmdSubmit, cmdPublish, printHelp,
+  main, cmdNew, cmdList, cmdUpgrade, cmdCheck, cmdSubmit, cmdPublish, cmdInstall, cmdUpdate, printHelp,
   gatherCatalog, formatCatalog, ownProjectName,
   scaffoldModule, gatherUpgrade, evaluateUpgrade, buildManifest,
   formatMaintenanceHint, isPastRemoveAfter,

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

@@ -26,6 +26,12 @@
 //   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
@@ -53,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');
@@ -68,9 +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 { checkEntitlement, listEntitlements } = require('../module-entitlements');
-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.
@@ -376,6 +388,111 @@ module.exports = function buildModulesRouter() {
       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.1078'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1080'; // 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');