@bongos/core 1.19.485 → 1.19.486

package/src/bongos/project-settings.js

@@ -0,0 +1,193 @@
+'use strict';
+
+// src/bongos/project-settings.js — the instance's live, DB-backed knobs, and the
+// typed accessor every reader goes through (task 1003279, goal 1000072).
+//
+// WHY THIS FILE EXISTS. Goal 1000072's rotting half needs a number — "untouched
+// for how long?" — and task 1003280 states where it must live: "STALE TIMER —
+// live, DB-backed", followed by "do not fork a second store". A knob an owner can
+// change from a page cannot be an env var that needs a redeploy, and it must not
+// become a THIRD place staleness is configured. So there is one table
+// (project_settings, migration core_231) and one accessor, here.
+//
+// HOW THIS RELATES TO src/stale-timer.js — READ THIS BEFORE ADDING A THIRD TIMER.
+// ADR 0226 collapsed four disagreeing answers to "how long may a CLAIM go silent"
+// into one resolver. This file does not reopen that. The two timers measure
+// different things, are owned by different surfaces, and have different
+// consequences:
+//
+//   src/stale-timer.js   a CLAIM goes silent      hours   env    the sweep RELEASES it
+//   this file            work goes UNTOUCHED      days    DB     a human is ASKED
+//
+// The distinction that keeps them from collapsing into each other: the claim timer
+// is about a builder who stopped responding, and the machine acts alone. The rot
+// timer is about work nobody picked up, and the machine only ever raises a
+// question. One enforces, one reports — which is exactly the asymmetry ADR 0226's
+// header names, applied one level up.
+//
+// This is why the rot read deliberately EXCLUDES tasks at 'active': a claimed task
+// that has gone quiet is the claim timer's question, and reporting it here too
+// would put the same rot in two inboxes with two different numbers — the precise
+// failure ADR 0226 exists to prevent.
+//
+// FAIL POSTURE: REPORTING, SO IT DEGRADES. Every caller of this file is a read
+// surface (the needs-attention inbox, the settings page). A knob typed wrong shows
+// up ON the screen of the person who can fix it, labelled, instead of 500-ing the
+// inbox they were using to find the problem. Nothing here throws on a bad value;
+// it reports one. (An enforcing caller would have to refuse instead — see the
+// stale-timer header. There is no enforcing caller of the rot timer, by design.)
+
+const { pool } = require('./pool');
+// The structured logger rather than console.* — both are kernel files (this one is on
+// fitness.js's KERNEL_FILES roster), a structured line is attributable and rides
+// ADR 0022's redaction, and the quality ratchet counts bare console calls.
+const { logger } = require('./logger');
+
+// The knob names. Namespaced by the surface that owns them so a settings page can
+// group rows without a second column, and so a future knob from another surface
+// cannot collide with this one.
+const SETTING_KEYS = {
+  ROT_DAYS: 'attention.rot_days',
+};
+
+// The last-resort rot timer, in days. 30 because that is the shortest window in
+// which "nobody has touched this" is evidence of rot rather than evidence of a
+// normal week — a fortnight would fire on every ordinary holiday, and a quarter is
+// long enough that the backlog has already stopped being read.
+const DEFAULT_ROT_DAYS = 30;
+
+// The accepted range, in days. 1 because "yesterday" is the shortest question worth
+// asking. 365 because past a year the timer is an off switch, and an off switch
+// should be asked for out loud rather than typed as a big number — the same
+// reasoning, and the same sentence, as the 720h bound in src/stale-timer.js.
+const MIN_ROT_DAYS = 1;
+const MAX_ROT_DAYS = 365;
+
+// Parse one candidate into whole days, or say why it is unusable. Pure, never
+// throws: both the DB tier and the override tier want to decide for themselves what
+// an unusable value means. Mirrors parseHours in src/stale-timer.js deliberately —
+// two timers with two different range checks would drift into two different ideas
+// of what "valid" means.
+function parseDays(raw) {
+  if (raw == null || raw === '') return { reason: 'empty' };
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return { reason: 'not a number' };
+  if (!Number.isInteger(n)) return { reason: 'must be a whole number of days' };
+  if (n <= 0) return { reason: 'must be positive' };
+  if (n < MIN_ROT_DAYS || n > MAX_ROT_DAYS) {
+    return { reason: `out of range (${MIN_ROT_DAYS}..${MAX_ROT_DAYS})` };
+  }
+  return { days: n };
+}
+
+// getSetting(key) — the raw row, or null when the key has never been set.
+// NULL IS MEANINGFUL: absence means "never configured, use the code default", which
+// is what lets a fresh instance boot with an empty table and what lets the settings
+// page tell "never touched" apart from "deliberately set to the default value".
+// Never seed a default row to avoid the null.
+async function getSetting(key) {
+  const { rows } = await pool.query(
+    'SELECT key, value, updated_at, updated_by FROM project_settings WHERE key = $1',
+    [key]
+  );
+  return rows[0] || null;
+}
+
+// setSetting(key, value, builderId) — upsert one knob, returning the stored row.
+// The value is stored verbatim as text and validated by the typed resolver at READ
+// time, not here, so a value that was valid when written and later fell outside a
+// tightened range degrades on the screen rather than becoming unreadable.
+// builderId may be null for a system path with no builder in the request.
+async function setSetting(key, value, builderId = null) {
+  const { rows } = await pool.query(
+    `INSERT INTO project_settings (key, value, updated_by, updated_at)
+          VALUES ($1, $2, $3, now())
+     ON CONFLICT (key) DO UPDATE
+            SET value = EXCLUDED.value,
+                updated_by = EXCLUDED.updated_by,
+                updated_at = now()
+      RETURNING key, value, updated_at, updated_by`,
+    [key, String(value), builderId]
+  );
+  return rows[0];
+}
+
+// resolveRotDays({ override }) — the project's rot timer and where the number came
+// from, for any surface that reports staleness.
+//
+// Precedence, widest-scope last (the same shape as resolveStaleClaimHours):
+//   1. override — a per-request lens (?rot_days=). Someone asking "what would 7
+//                 days show me?" is not reconfiguring the project, so this never
+//                 becomes the project's answer and is never written back.
+//   2. the DB   — project_settings['attention.rot_days']. THIS is the project's
+//                 configured timer, the row task 1003280's page writes.
+//   3. default  — DEFAULT_ROT_DAYS.
+//
+// Returns { days, source, invalid }:
+//   days    — always a usable positive integer, whatever went wrong
+//   source  — 'override' | 'project_settings' | 'default'
+//   invalid — null, or { where, raw, reason }: something was SET and unusable.
+//             `days` has already fallen through to the next tier; a reporting
+//             caller should say so on screen.
+//
+// A DB that is unreachable is NOT an invalid value — it is a failure to read, and
+// this returns the default with source 'default' rather than taking the inbox down.
+// The inbox is how someone would notice the database is unhappy.
+async function resolveRotDays({ override } = {}) {
+  if (override != null && override !== '') {
+    const got = parseDays(override);
+    if (got.days != null) return { days: got.days, source: 'override', invalid: null };
+    return {
+      days: DEFAULT_ROT_DAYS,
+      source: 'default',
+      invalid: { where: 'override', raw: String(override), reason: got.reason },
+    };
+  }
+
+  let row = null;
+  try {
+    row = await getSetting(SETTING_KEYS.ROT_DAYS);
+  } catch (err) {
+    logger.error(`project_settings read failed; falling back to the default rot timer: ${err && err.message}`);
+    return { days: DEFAULT_ROT_DAYS, source: 'default', invalid: null };
+  }
+
+  if (row && row.value != null && row.value !== '') {
+    const got = parseDays(row.value);
+    if (got.days != null) return { days: got.days, source: 'project_settings', invalid: null };
+    return {
+      days: DEFAULT_ROT_DAYS,
+      source: 'default',
+      invalid: { where: `project_settings['${SETTING_KEYS.ROT_DAYS}']`, raw: String(row.value), reason: got.reason },
+    };
+  }
+
+  return { days: DEFAULT_ROT_DAYS, source: 'default', invalid: null };
+}
+
+// describeRotTimer(resolved) — one sentence naming the timer and its provenance, for
+// an API receipt or a settings row. A number with no provenance is what let a 6h and
+// a 24h coexist unnoticed for months (ADR 0226); every surface that prints the rot
+// timer prints this instead of printing the bare number.
+function describeRotTimer(resolved) {
+  const r = resolved || {};
+  const base = `${r.days}d (${r.source})`;
+  if (!r.invalid) return base;
+  return `${base} — ignoring ${r.invalid.where}="${r.invalid.raw}" (${r.invalid.reason})`;
+}
+
+// parseDays is exported for the tests only — the range check and the default are
+// asserted against the SAME constants the resolver reads, because a test that
+// re-typed 30 or 365 would be the second copy of the number this file exists to
+// keep singular.
+module.exports = {
+  SETTING_KEYS,
+  DEFAULT_ROT_DAYS,
+  MIN_ROT_DAYS,
+  MAX_ROT_DAYS,
+  parseDays,
+  getSetting,
+  setSetting,
+  resolveRotDays,
+  describeRotTimer,
+};

package/src/module-api.js

@@ -17,6 +17,17 @@ const { pool, instanceDbName } = require('./bongos/pool');
 const branding = require('./branding');
 const instanceConfig = require('./instance-config');
 const staleTimer = require('./stale-timer');
+// Destructured, not namespaced, deliberately — the same form src/bongos/routes/
+// builders.js uses for stale-timer.js. knip attributes a named export to a
+// destructured binding but not to a property read off a required namespace, so the
+// namespace form reports every export here as dead and regresses the ratchet.
+const {
+  resolveRotDays,
+  SETTING_KEYS: PROJECT_SETTING_KEYS,
+  getSetting: getProjectSetting,
+  setSetting: setProjectSetting,
+  describeRotTimer,
+} = require('./bongos/project-settings');
 const seams = require('./module-seams');
 const { buildInfo } = require('./build-info');
 const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePagination, pageMeta, PAGINATION } = require('./bongos/routes/_helpers');
@@ -34,7 +45,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.485'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.486'; // 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('dev-box'); log.info('mounted');
@@ -250,6 +261,23 @@ module.exports = {
   //     a direct require in scripts/ rather than joining the published surface.
   resolveStaleClaimHours: staleTimer.resolveStaleClaimHours,
   staleClaimMinutes: staleTimer.staleClaimMinutes,
+  // --- the project's ROT TIMER + the knob store behind it (task 1003279, goal
+  //     1000072) — how long a GOAL or TASK may go untouched before the hall's
+  //     needs-attention inbox raises a line about it. A DIFFERENT question from the
+  //     stale-claim timer directly above, and the two must not be confused: that one
+  //     counts hours, is read from the env, is about a builder who went quiet, and
+  //     the sweeper ACTS on it alone. This one counts days, is read from the DB
+  //     (task 1003280 puts it on a settings page, and "do not fork a second store"),
+  //     is about work nobody picked up, and it only ever ASKS a human. The rot read
+  //     deliberately skips tasks at 'active' so the two never report the same rot
+  //     with two different numbers. See src/bongos/project-settings.js.
+  resolveRotDays,
+  projectSettings: {
+    KEYS: PROJECT_SETTING_KEYS,
+    get: getProjectSetting,
+    set: setProjectSetting,
+    describeRotTimer,
+  },
   readConfigFileSync: instanceConfig.readConfigFileSync,
   configHome: instanceConfig.configHome,
   configPath: instanceConfig.configPath,

package/tests/module_api.mjs

@@ -34,6 +34,7 @@ const PUBLISHED_SURFACE = [
   'llmPricing', // BV1.R77: shared token→USD pricing (1.7.0; tracked domain leak — economy carve)
   'branding', 'clientBranding', 'userAgent', 'resolveEnv', 'readConfigFileSync', 'configHome', 'configPath', // userAgent added 1.12.0 (BV1.R86; github-push UA)
   'resolveStaleClaimHours', 'staleClaimMinutes', // added by task 1003476 (ADR 0226; goal 1000072): the PROJECT's stale-claim timer — the sweep that releases a silent claim and the Archon roster that reports one read the same number through here, after eighteen hours of disagreeing (6 vs 24)
+  'resolveRotDays', 'projectSettings', // added by task 1003279 (ADR 0232; goal 1000072): the ROT timer + the live knob store behind it. A DIFFERENT question from the stale-claim timer above — days not hours, DB not env, work nobody picked up rather than a builder who went quiet, and it only ever ASKS a human where that one ACTS. Both ride the doorway so no module hardcodes either.
   'joinabilityMode', // added by task 1003044 (ADR 0194; the carrier after 1.19.374): the project's membership door, one reader for the sign-in gate AND the onboarding module's public POST
   'enabledDisciplines', // BV1.R81: instance offered-disciplines (1.9.0; onboarding restock backstop)
   'registerProvider', 'hasProvider', 'resolve', 'resolveOptional', 'listPorts', 'verifyPortsSatisfied',