@bongos/core 1.21.112 → 1.21.114

package/modules/builder-settings/law-locks.js

@@ -0,0 +1,202 @@
+'use strict';
+
+// modules/builder-settings/law-locks.js — a project LAW's lock on a builder's
+// personal setting, ENFORCED (task 1004707, goal 1000111 "government is how a
+// project steers its AI").
+//
+// A law (modules/government/laws.js) may lock personal settings it overrides: a
+// lock names a setting and either FIXES its value ({ setting, value }) or CAPS it
+// ({ setting, max }). This file is where such a lock bites. It is enforced in two
+// places, and the read is the one that cannot be dodged:
+//
+//   1. ON EVERY READ of the effective value. lockedPrefs() rewrites the builder's
+//      behavior_prefs so the effective profile obeys every lock, and describe()
+//      shapes the /me slices (interaction, wandering, model_allocation) from that.
+//      So a value stored BEFORE the law passed, or one written while the laws
+//      could not be read, still resolves to what the law says.
+//   2. ON EVERY WRITE. checkPatch() refuses a PATCH that would set a locked
+//      setting to anything the law does not allow (409 locked_by_law), so the
+//      settings page cannot quietly store a choice that will never take effect.
+//      Clearing a setting back to its default (null) is always allowed: the read
+//      clamps the default too.
+//
+// WHICH SETTINGS. The personal settings a table really holds, spelled as the
+// hall and laws.js spell them:
+//   technical_level, toolchain_familiarity, verbosity, machinery  (interaction)
+//   wandering                                                     (rank-clamped)
+//   model.main, model.subagentDefault, model.subagentRoutine      (model allocation)
+// A lock naming any other setting (on_stuck, ask_format …) has nothing to bite on
+// yet: it is reported `enforced: false, reason: 'not_a_personal_setting'`, and
+// the law's own words still reach every session (the laws block).
+//
+// ORDER FOR A CAP. `max` reads along each setting's own ordered list: the
+// interaction values in their declared order, wandering's four levels (or the
+// level number), the model tiers cheap→capable. A value past the cap is pulled
+// back to it; a value under it stands.
+//
+// The RANK still has the last word on wandering: a law can fix or cap it inside
+// the rank's ceiling, never lift a builder past it (ADR 0016 — a law is a project
+// rule, not a grant of authority).
+//
+// PURE: no db, no requires beyond the sibling pref libs. The routes and /me hand
+// the laws in (the government port's lawsForSession), read per request.
+
+const interactionPrefs = require('./interaction-prefs');
+const wanderingPrefs = require('./wandering-prefs');
+const modelAllocPrefs = require('./model-alloc-prefs');
+
+const MODEL_PREFIX = 'model.';
+
+// Each lockable setting: its ordered values, how to read its effective value off
+// a prefs blob, and how to write one into a prefs blob (returning a new blob).
+function settingSpec(setting) {
+  if (interactionPrefs.FIELD_KEYS.includes(setting)) {
+    return {
+      route: 'interaction',
+      order: Object.keys(interactionPrefs.FIELDS[setting].values),
+      read: (prefs) => interactionPrefs.effectiveProfile(prefs)[setting],
+      write: (prefs, v) => ({ ...(prefs || {}), [interactionPrefs.RESERVED_KEY]: { ...interactionPrefs.storedProfile(prefs), [setting]: v } }),
+      normalize: (v) => v,
+    };
+  }
+  if (setting === wanderingPrefs.RESERVED_KEY) {
+    return {
+      route: 'wandering',
+      order: wanderingPrefs.LEVELS.slice(),
+      read: (prefs, ctx) => wanderingPrefs.levelKey(wanderingPrefs.effectiveLevel(prefs, ctx.rank)),
+      write: (prefs, v) => ({ ...(prefs || {}), [wanderingPrefs.RESERVED_KEY]: wanderingPrefs.levelIndex(v) }),
+      // a level may be written as its key ('focused') or its number (1)
+      normalize: (v) => (wanderingPrefs.isLevelInt(v) ? wanderingPrefs.levelKey(v) : v),
+    };
+  }
+  if (setting.startsWith(MODEL_PREFIX)) {
+    const slot = setting.slice(MODEL_PREFIX.length);
+    if (!Object.prototype.hasOwnProperty.call(modelAllocPrefs.SLOTS, slot)) return null;
+    return {
+      route: 'model_allocation',
+      order: modelAllocPrefs.ALLOWED_TIERS.slice(),
+      read: (prefs, ctx) => modelAllocPrefs.effectiveAllocation(prefs, ctx.instanceModels)[slot],
+      write: (prefs, v) => ({ ...(prefs || {}), [modelAllocPrefs.RESERVED_KEY]: { ...modelAllocPrefs.storedOverride(prefs), [slot]: v } }),
+      normalize: (v) => v,
+    };
+  }
+  return null;
+}
+
+// Every lock the laws in force carry, flattened: { setting, value|max, law_id,
+// law_no, law_text }. `laws`: the government port's lawsForSession().laws.
+// laws.js refuses a setting locked by two laws at once, so the first wins here
+// only as a belt.
+function locksOf(laws) {
+  const out = [];
+  const seen = new Set();
+  (Array.isArray(laws) ? laws : []).forEach((law, i) => {
+    (law && Array.isArray(law.locks) ? law.locks : []).forEach((l) => {
+      if (!l || typeof l.setting !== 'string' || seen.has(l.setting)) return;
+      seen.add(l.setting);
+      const lock = { setting: l.setting, law_id: law.id == null ? null : String(law.id), law_no: law.no || i + 1, law_text: law.text || '' };
+      if (Object.prototype.hasOwnProperty.call(l, 'value')) lock.value = l.value;
+      else lock.max = l.max;
+      out.push(lock);
+    });
+  });
+  return out;
+}
+
+// What a lock allows for a value: the fixed value, or the cap applied.
+// Returns { ok: true, value } or { ok: false, reason }.
+function lockTarget(spec, lock, current) {
+  if (Object.prototype.hasOwnProperty.call(lock, 'value')) {
+    const v = spec.normalize(lock.value);
+    return spec.order.includes(v) ? { ok: true, value: v } : { ok: false, reason: 'value_not_allowed' };
+  }
+  const cap = spec.normalize(lock.max);
+  const j = spec.order.indexOf(cap);
+  if (j < 0) return { ok: false, reason: 'value_not_allowed' };
+  const i = spec.order.indexOf(current);
+  return { ok: true, value: i > j ? cap : current };
+}
+
+// Every value a lock lets a builder choose, in the setting's own order: the one
+// fixed value, or every value up to and including the cap (task 1004714 — so a
+// surface can offer the values under a cap instead of locking the whole row).
+function allowedFor(spec, lock) {
+  if (Object.prototype.hasOwnProperty.call(lock, 'value')) {
+    const v = spec.normalize(lock.value);
+    return spec.order.includes(v) ? [v] : null;
+  }
+  const j = spec.order.indexOf(spec.normalize(lock.max));
+  return j < 0 ? null : spec.order.slice(0, j + 1);
+}
+
+// The builder's prefs with every lock applied, and what each lock did.
+//   ctx: { rank, instanceModels }
+// Returns { prefs, locks: [{ setting, value|max, law_id, law_no, law_text,
+//   enforced, reason?, route?, from?, to?, allowed? }] } — `from` is what the
+// builder's own setting resolves to without the laws, `to` what it resolves to
+// under them, `allowed` every value the lock still lets them pick.
+function lockedPrefs(behaviorPrefs, laws, ctx = {}) {
+  let prefs = behaviorPrefs && typeof behaviorPrefs === 'object' ? behaviorPrefs : {};
+  const report = [];
+  for (const lock of locksOf(laws)) {
+    const spec = settingSpec(lock.setting);
+    if (!spec) { report.push({ ...lock, enforced: false, reason: 'not_a_personal_setting' }); continue; }
+    const from = spec.read(behaviorPrefs || {}, ctx);
+    const target = lockTarget(spec, lock, spec.read(prefs, ctx));
+    if (!target.ok) { report.push({ ...lock, route: spec.route, enforced: false, reason: target.reason, from }); continue; }
+    prefs = spec.write(prefs, target.value);
+    report.push({ ...lock, route: spec.route, enforced: true, from, to: spec.read(prefs, ctx), allowed: allowedFor(spec, lock) });
+  }
+  return { prefs, locks: report };
+}
+
+// A PATCH, checked against the locks. `patch` maps setting → value (null clears,
+// always allowed). Returns null when every key is allowed, else the first
+// refusal: { setting, law_id, law_no, law_text, allowed }.
+function checkPatch(patch, laws) {
+  const locks = locksOf(laws);
+  for (const [setting, raw] of Object.entries(patch || {})) {
+    if (raw === null || raw === undefined) continue;
+    const lock = locks.find((l) => l.setting === setting);
+    if (!lock) continue;
+    const spec = settingSpec(setting);
+    if (!spec) continue;
+    const v = spec.normalize(raw);
+    const target = lockTarget(spec, lock, v);
+    if (!target.ok) continue; // a lock naming no real value has nothing to enforce
+    if (target.value !== v) {
+      return { setting, law_id: lock.law_id, law_no: lock.law_no, law_text: lock.law_text, allowed: allowedFor(spec, lock) };
+    }
+  }
+  return null;
+}
+
+// The /me slices with the laws applied. The EFFECTIVE values and the injected
+// contracts come from the locked prefs; what the builder has STORED is still
+// reported as theirs, so a surface can say "yours: X, the law: Y".
+//   ctx: { rank, instanceModels }
+function describe(behaviorPrefs, laws, ctx = {}) {
+  const raw = behaviorPrefs && typeof behaviorPrefs === 'object' ? behaviorPrefs : {};
+  const { prefs, locks } = lockedPrefs(raw, laws, ctx);
+  const interaction = interactionPrefs.describeForApi(prefs);
+  interaction.stored = interactionPrefs.storedProfile(raw);
+  const wandering = wanderingPrefs.describeForApi(prefs, ctx.rank);
+  wandering.override_level = wanderingPrefs.overrideLevel(raw);
+  const modelAllocation = modelAllocPrefs.describeForApi(prefs, ctx.instanceModels || {});
+  modelAllocation.override = modelAllocPrefs.storedOverride(raw);
+  return { interaction, wandering, model_allocation: modelAllocation, locks };
+}
+
+// The slice of a describe() a single settings route answers, with its locks.
+function locksFor(route, locks) {
+  return (Array.isArray(locks) ? locks : []).filter((l) => l.route === route);
+}
+
+module.exports = {
+  settingSpec,
+  locksOf,
+  lockedPrefs,
+  checkPatch,
+  describe,
+  locksFor,
+};

package/modules/builder-settings/routes/settings.js

@@ -27,6 +27,7 @@ const eventSoundPrefs = require('../event-sound-prefs');
 const wanderingPrefs = require('../wandering-prefs');
 const interactionPrefs = require('../interaction-prefs');
 const modelAllocPrefs = require('../model-alloc-prefs');
+const lawLocks = require('../law-locks');
 const renderPrefs = require('../render-prefs');
 const profileNudgePrefs = require('../profile-nudge-prefs');
 const displayName = require('../display-name');
@@ -214,6 +215,58 @@ module.exports = function buildBuilderSettingsRouter() {
     }
   });
 
+  // ---- the project's LAWS on these settings (task 1004707) ----
+  //
+  // A law passed by the project's government may LOCK a personal setting (fix it,
+  // or cap it). The lock is enforced here and in GET /me, never only shown:
+  //   * every read below resolves the EFFECTIVE value with the locks applied
+  //     (law-locks.js), and reports them as `law_locks` — so a value stored before
+  //     the law passed still resolves to what the law says;
+  //   * every write refuses a value a lock does not allow (409 locked_by_law).
+  // The laws are read per request through the government PORT (this module never
+  // requires another); with the government module off there are no laws.
+  async function lawsInForce() {
+    const gov = api.resolveOptional('government');
+    if (!gov || typeof gov.lawsForSession !== 'function') return [];
+    const out = await gov.lawsForSession();
+    return out && Array.isArray(out.laws) ? out.laws : [];
+  }
+  // A READ fails soft: the laws unreadable → the builder's own settings, said so
+  // (laws_read:false), rather than a broken settings page. A WRITE fails closed
+  // (lawsAllowingWrite): it is never let through on a guess.
+  async function lawsForRead() {
+    try { return { laws: await lawsInForce(), read: true }; } catch (err) {
+      log.warn('[gds] laws unreadable for a settings read', err);
+      return { laws: [], read: false };
+    }
+  }
+  // `known`: the laws this request already read (a write's check), so one
+  // request reads the book once.
+  async function lockedSlice(slice, stored, rank, known) {
+    const { laws, read } = known ? { laws: known, read: true } : await lawsForRead();
+    const d = lawLocks.describe(stored, laws, { rank, instanceModels: instanceModels() });
+    return { ...d[slice], law_locks: lawLocks.locksFor(slice, d.locks), laws_read: read };
+  }
+  // The write's check. Answers the refusal and returns null when a law forbids
+  // `settingPatch` (setting → value, the names laws use) or the laws cannot be
+  // read; otherwise returns the laws it read, for the response to reuse.
+  async function lawsAllowingWrite(res, settingPatch) {
+    let laws;
+    try { laws = await lawsInForce(); } catch (err) {
+      log.error('[gds] laws unreadable for a settings write', err);
+      res.fail('laws_unreadable', { status: 503, message: 'The project\'s laws could not be read just now, so nothing was saved. Try again.' });
+      return null;
+    }
+    const hit = lawLocks.checkPatch(settingPatch, laws);
+    if (!hit) return laws;
+    res.fail('locked_by_law', {
+      status: 409,
+      message: `Law ${hit.law_no} sets ${hit.setting} ("${hit.law_text}"); allowed: ${hit.allowed.join(', ')}`,
+      details: { setting: hit.setting, law_id: hit.law_id, law_no: hit.law_no, law: hit.law_text, allowed: hit.allowed },
+    });
+    return null;
+  }
+
   // Per-builder "wandering" level (task 1268, migration 119). Governs how
   // readily the agent opens a NEW THREAD of work (tangent / investigation /
   // unsolicited suggestion) vs. staying on the claimed task — off-task only,
@@ -227,7 +280,7 @@ module.exports = function buildBuilderSettingsRouter() {
     try {
       const builder = await api.getBuilderById(req.builder.id);
       const stored = await db.getBuilderBehaviorPrefs(req.builder.id);
-      res.json(wanderingPrefs.describeForApi(stored, builder?.rank));
+      res.json(await lockedSlice('wandering', stored, builder?.rank));
     } catch (err) {
       log.error('[gds] GET /me/wandering', err);
       res.fail('read_failed', { status: 500, message: 'internal error' });
@@ -250,10 +303,12 @@ module.exports = function buildBuilderSettingsRouter() {
       if (!v.ok) {
         return res.fail('invalid_patch', 422, { errors: v.errors });
       }
+      const laws = await lawsAllowingWrite(res, v.patch);
+      if (!laws) return;
       const existing = await db.getBuilderBehaviorPrefs(req.builder.id);
       const next = wanderingPrefs.applyPatch(existing, v.patch);
       const saved = await db.setBuilderBehaviorPrefs(req.builder.id, next);
-      res.json(wanderingPrefs.describeForApi(saved, builder?.rank));
+      res.json(await lockedSlice('wandering', saved, builder?.rank, laws));
     } catch (err) {
       log.error('[gds] PATCH /me/wandering', err);
       res.fail('write_failed', { status: 500, message: 'internal error' });
@@ -271,7 +326,7 @@ module.exports = function buildBuilderSettingsRouter() {
   router.get('/me/interaction', api.requireBuilder, async (req, res) => {
     try {
       const stored = await db.getBuilderBehaviorPrefs(req.builder.id);
-      res.json(interactionPrefs.describeForApi(stored));
+      res.json(await lockedSlice('interaction', stored));
     } catch (err) {
       log.error('[gds] GET /me/interaction', err);
       res.fail('read_failed', { status: 500, message: 'internal error' });
@@ -287,11 +342,13 @@ module.exports = function buildBuilderSettingsRouter() {
       if (!v.ok) {
         return res.fail('invalid_patch', 422, { errors: v.errors });
       }
+      const laws = await lawsAllowingWrite(res, v.patch);
+      if (!laws) return;
       const existing = await db.getBuilderBehaviorPrefs(req.builder.id);
       const nextInteraction = interactionPrefs.applyPatch(interactionPrefs.storedProfile(existing), v.patch);
       const nextPrefs = { ...(existing || {}), [interactionPrefs.RESERVED_KEY]: nextInteraction };
       const saved = await db.setBuilderBehaviorPrefs(req.builder.id, nextPrefs);
-      res.json(interactionPrefs.describeForApi(saved));
+      res.json(await lockedSlice('interaction', saved, undefined, laws));
     } catch (err) {
       log.error('[gds] PATCH /me/interaction', err);
       res.fail('write_failed', { status: 500, message: 'internal error' });
@@ -311,7 +368,7 @@ module.exports = function buildBuilderSettingsRouter() {
   router.get('/me/model-allocation', api.requireBuilder, async (req, res) => {
     try {
       const stored = await db.getBuilderBehaviorPrefs(req.builder.id);
-      res.json(modelAllocPrefs.describeForApi(stored, instanceModels()));
+      res.json(await lockedSlice('model_allocation', stored));
     } catch (err) {
       log.error('[gds] GET /me/model-allocation', err);
       res.fail('read_failed', { status: 500, message: 'internal error' });
@@ -327,11 +384,14 @@ module.exports = function buildBuilderSettingsRouter() {
       if (!v.ok) {
         return res.fail('invalid_patch', 422, { errors: v.errors });
       }
+      // a slot is locked by its law name, model.<slot>
+      const laws = await lawsAllowingWrite(res, Object.fromEntries(Object.entries(v.patch).map(([k, t]) => [`model.${k}`, t])));
+      if (!laws) return;
       const existing = await db.getBuilderBehaviorPrefs(req.builder.id);
       const nextOverride = modelAllocPrefs.applyPatch(modelAllocPrefs.storedOverride(existing), v.patch);
       const nextPrefs = { ...(existing || {}), [modelAllocPrefs.RESERVED_KEY]: nextOverride };
       const saved = await db.setBuilderBehaviorPrefs(req.builder.id, nextPrefs);
-      res.json(modelAllocPrefs.describeForApi(saved, instanceModels()));
+      res.json(await lockedSlice('model_allocation', saved, undefined, laws));
     } catch (err) {
       log.error('[gds] PATCH /me/model-allocation', err);
       res.fail('write_failed', { status: 500, message: 'internal error' });

package/modules/builder-settings/settings.js

@@ -32,6 +32,7 @@ const interactionPrefs = require('./interaction-prefs');
 const modelAllocPrefs = require('./model-alloc-prefs');
 const renderPrefs = require('./render-prefs');
 const builderNeeds = require('./builder-needs');
+const lawLocks = require('./law-locks');
 
 module.exports = {
   // --- the raw behavior_prefs blob read (GET /me resolves this once, then shapes
@@ -45,6 +46,12 @@ module.exports = {
   describeModelAllocation: (...a) => modelAllocPrefs.describeForApi(...a),
   describeRender: (...a) => renderPrefs.describeForApi(...a),
   computeNeeds: (...a) => builderNeeds.computeNeeds(...a),
+  // task 1004707: the interaction / wandering / model-allocation slices with the
+  // project's laws' locks APPLIED (law-locks.js), plus what each lock did:
+  // (behaviorPrefs, laws, { rank, instanceModels }) → { interaction, wandering,
+  // model_allocation, locks }. GET /me uses this so a session reads the locked
+  // values, not the builder's own.
+  describeWithLaws: (...a) => lawLocks.describe(...a),
 
   // --- the per-builder model ceiling for a skill (cascade-dispatch clamps to it;
   //     never exceeds it). Mirrors the former `skillPrefs.getForBuilder` call.

package/modules/discord/ship-broadcast.js

@@ -21,15 +21,24 @@
 //     branch can NEVER return ship_news or ship_feed — a security fix must not
 //     advertise the shape of an exploit on a public/builder channel before it is
 //     live (the owner requirement behind task 990).
-//   - otherwise               → the builder #ship-feed only.
+//   - otherwise               → the builder #ship-feed, every ship; and, for a
+//     NEWS_KINDS task only, the owner-facing #ship-news too.
 // #ship-feed / #security-ship-feed lines are PREFIXED with `#<taskId>` so the
 // upvote bot can map a 👍 back to the task (discord-reaction.parseShipMarker).
 //
-// #ship-news is PAUSED (task 1749, owner ask 2026-07-03): per-ship broadcast was
-// too spammy (it posted to #ship-news AND #ship-feed, ×2 posters = 4 messages).
-// For now #ship-news gets nothing so exactly one #ship-feed message fires per
-// ship. The broader "make the two channels genuinely different + filter by task
-// type" work is idea 458 — un-pause by restoring the ship_news entry below.
+// THE TWO CHANNELS ARE EDITORIALLY DIFFERENT (task 1002846, idea 1000458; the
+// owner's pick 2026-10-12 — a kind filter, not a daily digest). #ship-feed is the
+// builders' ledger: every ship, `#<id>`-prefixed. #ship-news is the owner-facing
+// headline stream (CLAUDE.md §2: short, no jargon): only what a person using the
+// project would notice — a `feature` or a `bug` fix — as the plain value summary,
+// no id. Cleanup, infra, refactor, spike and the rest stay on #ship-feed. A task
+// whose kind is missing or unknown posts no headline: a quiet #ship-news is the
+// safe failure. The headline is the value summary verbatim, author-written like
+// the #ship-feed line; webhook.js posts every channel with allowed_mentions
+// {parse:[]}, so a summary can never ping anyone from either. This replaces task 1749's pause, which muted #ship-news entirely
+// because it then repeated every #ship-feed line (×2 posters = 4 messages a ship);
+// the one poster is now the server's (ship-finish.js defers), so a news ship is
+// two messages, in two channels that say different things.
 //
 // A PAGE TWEAK (task 1004439): an approved Tweak Mode round ships as a task, and
 // its line says what it is — a page approved, rewritten by its ARTIST (the round's
@@ -37,7 +46,8 @@
 // `pageArtist` is the artist's name already resolved, or null when it could not be
 // read; the line then says "page approved" and names nobody rather than the
 // applier. Still `#<id>`-prefixed, so applause on it reaches the round.
-function chooseBroadcastTargets({ securitySensitive, taskId, summary, pageTweak = false, pageArtist = null }) {
+const NEWS_KINDS = new Set(['feature', 'bug']);
+function chooseBroadcastTargets({ securitySensitive, taskId, summary, kind = null, pageTweak = false, pageArtist = null }) {
   if (!summary) return [];
   if (securitySensitive) {
     return [{ channel: 'security_ship_feed', line: `#${taskId} shipped (security) — ${summary}` }];
@@ -46,10 +56,9 @@ function chooseBroadcastTargets({ securitySensitive, taskId, summary, pageTweak
     const by = pageArtist ? ` — rewritten by ${plainName(pageArtist)}` : '';
     return [{ channel: 'ship_feed', line: `#${taskId} page approved${by}: ${summary}` }];
   }
-  return [
-    // { channel: 'ship_news', line: summary },  // PAUSED — task 1749 / idea 458
-    { channel: 'ship_feed', line: `#${taskId} shipped — ${summary}` },
-  ];
+  const targets = [{ channel: 'ship_feed', line: `#${taskId} shipped — ${summary}` }];
+  if (NEWS_KINDS.has(kind)) targets.push({ channel: 'ship_news', line: summary });
+  return targets;
 }
 
 // The page-tweak source string, and the artist's display name for a shipped
@@ -89,7 +98,7 @@ async function postShipBroadcast(task, deps = {}) {
   const log = deps.log || console.log;
   const pageTweak = task.source === PAGE_TWEAK_SOURCE;
   const pageArtist = pageTweak && sec === false ? await pageArtistName(task, deps) : null;
-  const targets = chooseBroadcastTargets({ securitySensitive: sec, taskId: task.id, summary, pageTweak, pageArtist });
+  const targets = chooseBroadcastTargets({ securitySensitive: sec, taskId: task.id, summary, kind: task.kind, pageTweak, pageArtist });
   for (const { channel, line } of targets) {
     try {
       await postWebhook(channel, line);
@@ -155,4 +164,4 @@ async function postStrandNotice(info, deps = {}) {
   return result;
 }
 
-module.exports = { chooseBroadcastTargets, postShipBroadcast, chooseStrandTargets, postStrandNotice };
+module.exports = { chooseBroadcastTargets, NEWS_KINDS, postShipBroadcast, chooseStrandTargets, postStrandNotice };

package/modules/government/asks-db.js

@@ -0,0 +1,54 @@
+'use strict';
+
+// modules/government/asks-db.js — where asks are stored and read (task 1004703).
+//
+// One row per docket matter in government_asks (government_028), keyed by the
+// matter's docket id (`blockers:12`). saveAsk replaces a matter's ask whole (an
+// agent rewriting its card after a refusal writes the new card, not a patch);
+// asksFor reads the asks of many matters in one query, for the docket and the
+// blockers list. The shape is checked in asks.js BEFORE anything reaches here,
+// and the table's own CHECKs refuse a hand-written slop row too.
+//
+// The pool comes through the published doorway (ADR 0091 §2). No caching: an ask
+// written a moment ago is in the next read.
+
+const { pool } = require('../../src/module-api');
+const asks = require('./asks');
+
+const MAX_READ = 500;
+
+// Store (or replace) one matter's ask. `ask` is checkAsk's stored form.
+async function saveAsk({ matterId, ask, builderId }) {
+  if (!asks.isMatterId(matterId)) throw Object.assign(new Error('bad matter id'), { code: 'BAD_MATTER_ID' });
+  const { rows } = await pool.query(
+    `INSERT INTO government_asks
+            (matter_id, question, options, recommend_key, recommend_why, waits_on, if_nobody_answers, detail, written_by, written_at)
+     VALUES ($1, $2, $3::jsonb, $4, $5, $6, $7, $8, $9, now())
+     ON CONFLICT (matter_id) DO UPDATE
+        SET question = EXCLUDED.question, options = EXCLUDED.options,
+            recommend_key = EXCLUDED.recommend_key, recommend_why = EXCLUDED.recommend_why,
+            waits_on = EXCLUDED.waits_on, if_nobody_answers = EXCLUDED.if_nobody_answers,
+            detail = EXCLUDED.detail, written_by = EXCLUDED.written_by, written_at = now()
+     RETURNING matter_id, question, options, recommend_key, recommend_why, waits_on, if_nobody_answers, detail, written_at`,
+    [matterId, ask.question, JSON.stringify(ask.options), ask.recommend.key, ask.recommend.why,
+      ask.waits_on, ask.if_nobody_answers, ask.detail || null, builderId == null ? null : builderId],
+  );
+  return asks.fromRow(rows[0]);
+}
+
+// The asks of these matters → Map(matter_id → ask). Ids that are not matter ids
+// are skipped; an empty list reads nothing.
+async function asksFor(matterIds) {
+  const ids = [...new Set((Array.isArray(matterIds) ? matterIds : []).filter(asks.isMatterId))].slice(0, MAX_READ);
+  const out = new Map();
+  if (!ids.length) return out;
+  const { rows } = await pool.query(
+    `SELECT matter_id, question, options, recommend_key, recommend_why, waits_on, if_nobody_answers, detail, written_at
+       FROM government_asks WHERE matter_id = ANY($1::text[])`,
+    [ids],
+  );
+  for (const r of rows) out.set(r.matter_id, asks.fromRow(r));
+  return out;
+}
+
+module.exports = { saveAsk, asksFor, MAX_READ };