@bongos/core 1.19.126 → 1.19.127

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.126",
-  "core_contract": "1.19.126",
-  "source_commit": "b56cedc2da8ef6691bd7990c6e3219896694e540",
+  "core_version": "1.19.127",
+  "core_contract": "1.19.127",
+  "source_commit": "f4b67a76dc2ad911a7c9257ba4280de4ac7904c7",
   "source_ref": "HEAD",
-  "built_at": "2026-08-15T00:16:09.571Z",
+  "built_at": "2026-08-15T00:49:23.419Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 303,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 1569,
-  "tree_sha256": "5703791569f4c26556ad21f0bbcf605faf1b42cfd3631a1ce5f25a05269fd4b4",
+  "tree_sha256": "deedfbf01298656cc039a9d567722f3689778d62d8aacc97a230ac4490a39c7a",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -2367,7 +2367,7 @@
     {
       "path": "modules/builder-settings/builder-needs.js",
       "mode": "0000644",
-      "sha256": "0b40afc38f91ad053d5ecca380eb35d314a3f104fbe8096d51efeb3de131fc98"
+      "sha256": "3cb7478d9e347147e331f0954a9178a1770918067a678efdb8caef96241dfb5a"
     },
     {
       "path": "modules/builder-settings/db.js",
@@ -4167,12 +4167,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "64edc372bb49cd5c30eb5a1d46f54361293de787d1717d2e116f52568ff93f2c"
+      "sha256": "ecb64df7be6949adcb0d88b5f21ca3014724b598fa1a6d939a3a50d8f9696aa6"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "c652ffaf3901e4ccc8f64ff9340f7f4f6c418ab738fc52f2b71450083d2a4e97"
+      "sha256": "5be9320e605a4b67ba2d63fa4ab831b99bda91a847c11338fd5e0ed6a65d0779"
     },
     {
       "path": "public-docs/index.html",
@@ -5527,12 +5527,12 @@
     {
       "path": "src/bongos/db-kernel.js",
       "mode": "0000644",
-      "sha256": "fa80ba2c0bb742b83d637280e65965f450bc0387063e65dd06f6bd9171283f23"
+      "sha256": "f31dd847ed641bf49013c345b1f08f9e2794a875dad777de10daeda2a4ae1cf3"
     },
     {
       "path": "src/bongos/db.js",
       "mode": "0000644",
-      "sha256": "64b0efa7c0a251266a8dbc00d43373fb1516fa5c88ba737220c969ec97a2e98b"
+      "sha256": "d3dd606664855a94788751d13ab7fc62ccdc4a8df48f331ec97a5a81a8a6fa96"
     },
     {
       "path": "src/bongos/github-repos.js",
@@ -5687,7 +5687,7 @@
     {
       "path": "src/bongos/routes/me.js",
       "mode": "0000644",
-      "sha256": "e6c9e19a4b644f35da665cc48df21085d9a187e3b694a73af01f3d1b83c620b8"
+      "sha256": "83657d8a2f8e1d81a80324350ddd983baf5346da3f88ce1f41c2211275f34440"
     },
     {
       "path": "src/bongos/routes/modules.js",
@@ -5757,7 +5757,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "c64972eb393e195b4f24de3459036423077430a5cf643fd2e3a8da525ab3af56"
+      "sha256": "80e087f2181512cfdf51030c27aeb7aaa4235421c4e06c9d7c4a000d418b0d0a"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -6147,7 +6147,7 @@
     {
       "path": "tests/builder_needs.mjs",
       "mode": "0000644",
-      "sha256": "e3d8c5ac45d59f5d566547e2c406cf44ffa60f1b243afcb222b09eee68f5ee0d"
+      "sha256": "49a8146cbb0ec5def5b48130ed61fdec6e9855f22fe5ad3a09b39ae2cb218ca8"
     },
     {
       "path": "tests/bump_version.mjs",

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

@@ -90,13 +90,68 @@ function artKeyNeed(ctx) {
 // pure (ctx) => need|null function here — every renderer picks it up for free.
 const NEEDS = [artKeyNeed];
 
+// ---- founding grace (task 1002739 / direction §5.6, idea 1000701) -----------
+//
+// A freshly-provisioned instance used to greet its founding owner with "your
+// free art coverage has ended" — a demand as the payoff moment of the whole
+// create flow. While the founding owner's first days are running, the roster
+// leads with a welcome and every action_needed item is held at 'covered'
+// (listed, honest, but not demanding). First-run is a time window, not a
+// visit-counter: counting the first hall visit would end the grace on the very
+// request that renders it.
+//
+// ctx.isFoundingOwner   — is this builder the instance's first admitted builder?
+// ctx.founderCreatedAt  — that first builder's created_at (≈ the instance's
+//                         birth on a newborn); the window anchors here.
+// ctx.projectName       — branding identity.productName, for the greeting.
+// ctx.nowMs             — injectable clock for tests; defaults to Date.now().
+const FOUNDING_GRACE_DAYS = 7;
+const FOUNDING_GRACE_MS = FOUNDING_GRACE_DAYS * 24 * 60 * 60 * 1000;
+
+function foundingGraceActive(ctx = {}) {
+  if (!ctx.isFoundingOwner || !ctx.founderCreatedAt) return false;
+  const born = new Date(ctx.founderCreatedAt).getTime();
+  if (!Number.isFinite(born)) return false;
+  const now = typeof ctx.nowMs === 'number' ? ctx.nowMs : Date.now();
+  return now - born < FOUNDING_GRACE_MS;
+}
+
+function foundingWelcomeNeed(ctx) {
+  const name = ctx.projectName || 'your project';
+  return {
+    id: 'founding_welcome',
+    title: `Welcome to ${name}`,
+    what: 'Your project is standing, and this hall is where it gets built.',
+    learn_more_url: null,
+    state: 'covered',
+    severity: 'info',
+    message: `You made it — ${name} is up, and this hall is its workshop. ` +
+      'Look around at your own pace; if the platform ever needs something from you, ' +
+      'it will say so here once your first days are behind you.',
+    action: null,
+  };
+}
+
 // Compute the live list for a builder. `ctx` carries everything the need
 // functions read (see each need's doc). Returns:
 //   { items: Need[], action_needed_count, has_action_needed }
 // items is ordered: action_needed first (loudest), then covered, then satisfied,
-// so any renderer that takes "the first one" gets the most urgent.
+// so any renderer that takes "the first one" gets the most urgent. During the
+// founding grace nothing is action_needed, so the welcome (prepended before the
+// stable sort) is what that renderer shows.
 function computeNeeds(ctx = {}) {
-  const items = NEEDS.map((fn) => fn(ctx)).filter(Boolean);
+  const grace = foundingGraceActive(ctx);
+  let items = NEEDS.map((fn) => fn(ctx)).filter(Boolean);
+  if (grace) {
+    items = items.map((n) => n.state !== 'action_needed' ? n : {
+      ...n,
+      state: 'covered',
+      severity: 'info',
+      message: 'Nothing needed from you today — we’ll bring this up once your first days are behind you.',
+      action: null,
+    });
+    items.unshift(foundingWelcomeNeed(ctx));
+  }
   const order = { action_needed: 0, covered: 1, satisfied: 2 };
   items.sort((a, b) => (order[a.state] ?? 9) - (order[b.state] ?? 9));
   const actionNeeded = items.filter((n) => n.state === 'action_needed');
@@ -111,5 +166,7 @@ module.exports = {
   computeNeeds,
   // exported for tests / direct reuse
   artKeyNeed,
+  foundingGraceActive,
+  FOUNDING_GRACE_DAYS,
   SETTINGS_PATH,
 };

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.126",
+  "version": "1.19.127",
   "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",

package/src/bongos/db-kernel.js

@@ -62,6 +62,20 @@ async function getBuilderById(id) {
   return rows[0] ?? null;
 }
 
+// getFoundingBuilder — the instance's first admitted HUMAN builder (task
+// 1002739): the founding owner a newborn instance greets, and the anchor of
+// the builder-needs founding-grace window. system_role IS NULL is load-bearing:
+// core migrations 065/067 seed the BFG + Discord-bot system principals into
+// builders on EVERY instance before anyone can sign in, so the lowest ids on a
+// newborn DB are not the founder. First human row by id, regardless of status —
+// the founder stays the founder even if later deactivated.
+async function getFoundingBuilder() {
+  const { rows } = await pool.query(
+    `SELECT id, created_at FROM builders WHERE system_role IS NULL ORDER BY id ASC LIMIT 1`
+  );
+  return rows[0] ?? null;
+}
+
 // listActiveBuilders — the minimal, any-builder-readable roster (task 1877): an
 // invite-picker needs a real name of every builder to invite, not just the
 // leaderboard's top-100-by-credits window. Deliberately narrow columns — no
@@ -337,6 +351,7 @@ module.exports = {
   withTx,
   sessionPermsSelect,
   getBuilderById,
+  getFoundingBuilder,
   listActiveBuilders,
   insertAuditLog,
   LIVE_RANK_LADDER,

package/src/bongos/db.js

@@ -38,7 +38,7 @@ const seams = require('../module-seams');
 // published doorway resolves through. Re-exported below so every caller is
 // byte-identical; db-kernel depends only on ./pool, never ./db (one-way).
 const {
-  withTx, getBuilderById, listActiveBuilders, insertAuditLog, LIVE_RANK_LADDER,
+  withTx, getBuilderById, getFoundingBuilder, listActiveBuilders, insertAuditLog, LIVE_RANK_LADDER,
   // Auth/identity/admission + the rank vocabulary carved to db-kernel (ADR 0102,
   // finishing ADR 0091 §1). Re-exported below so db.js's other importers + its own
   // internal uses (setBuilderRank's RANKS.indexOf, etc.) stay byte-identical.
@@ -978,6 +978,7 @@ module.exports = {
   upsertBuilder,
   seatFirstAdminIfUnclaimed,
   getBuilderById,
+  getFoundingBuilder,
   listActiveBuilders,
   linkAnthropicAccount,
   getBuilderByGithubId,

package/src/bongos/routes/me.js

@@ -83,7 +83,7 @@ module.exports = function buildMeRouter() {
     const [
       builder, activeClaims, estVsActual, unlocked, lockedWithProgress, streakInfo,
       recentGrades, builderAvg, onboardingRow, shipCount, recentKarma, karma30d, discordLink, boxConnected, cliAuthed,
-      behaviorPrefs, geminiKeyRow, needsRebaseTasks,
+      behaviorPrefs, geminiKeyRow, needsRebaseTasks, foundingBuilder,
     ] = await Promise.all([
       db.getBuilderById(req.builder.id),
       lc().getActiveClaimsForBuilder(req.builder.id),
@@ -144,6 +144,10 @@ module.exports = function buildMeRouter() {
       // without a follow-up call. Through the `lifecycle` port; [] on a
       // lifecycle-less instance (guarded — the port is resolveOptional).
       lc() ? lc().needsRebaseTasksForBuilder(req.builder.id) : [],
+      // task 1002739: the instance's first admitted builder — anchors the
+      // builder-needs founding-grace window (a newborn instance's founder gets a
+      // welcome, not a nag). Best-effort: null just means no grace.
+      db.getFoundingBuilder().catch(() => null),
     ]);
     // V3.R84 (#302), criterion C3: the builder's month-to-date spend vs their
     // monthly budget. Surfaced here so the CLI (session-start ping) and the hall
@@ -274,6 +278,12 @@ module.exports = function buildMeRouter() {
         rank: builder?.rank,
         ownKeySet: !!(geminiKeyRow && geminiKeyRow.enc),
         sharedKeyConfigured: artSharedKeyConfigured(),
+        // founding grace (task 1002739 / direction §5.6): a newborn instance's
+        // founder gets a welcome roster, not a coverage nag. The module owns the
+        // policy (window length, copy); we pass the raw facts.
+        isFoundingOwner: !!(foundingBuilder && String(foundingBuilder.id) === String(req.builder.id)),
+        founderCreatedAt: foundingBuilder ? foundingBuilder.created_at : null,
+        projectName: (() => { try { return branding().identity?.productName || null; } catch { return null; } })(),
       }) : [],
     };
     // Module→core contribution seam (BV1.R42, ADR 0083). Let each enabled module

package/src/module-api.js

@@ -679,8 +679,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.124 with no explicit bump. run 31849445746. (task 1002620)
 //   1.19.126 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.125 with no explicit bump. run 31853055269. (task 1002620)
+//   1.19.127 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.126 with no explicit bump. run 31854730552. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.126'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.127'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/builder_needs.mjs

@@ -95,5 +95,119 @@ t('missing rank fails safe — not action_needed without an explicit rank', () =
   assert.ok(['covered', 'action_needed', 'satisfied'].includes(n.state));
 });
 
+console.log('founding grace (task 1002739, direction §5.6):');
+
+const DAY = 24 * 60 * 60 * 1000;
+const bornNow = new Date().toISOString();
+
+t('newborn founder: welcome item first, greeting by project name', () => {
+  const r = needs.computeNeeds({
+    rank: 'archon', ownKeySet: false,
+    isFoundingOwner: true, founderCreatedAt: bornNow, projectName: 'Mercury',
+  });
+  assert.equal(r.items[0].id, 'founding_welcome');
+  assert.match(r.items[0].title, /Mercury/);
+  assert.equal(r.items[0].state, 'covered');
+  assert.equal(r.items[0].action, null);
+});
+
+t('newborn founder: zero action_needed — every nag is suppressed', () => {
+  const r = needs.computeNeeds({
+    rank: 'archon', ownKeySet: false, isFoundingOwner: true, founderCreatedAt: bornNow,
+  });
+  assert.equal(r.has_action_needed, false);
+  assert.equal(r.action_needed_count, 0);
+  for (const n of r.items) assert.notEqual(n.state, 'action_needed');
+});
+
+t('a suppressed nag keeps its identity but loses the demand', () => {
+  const r = needs.computeNeeds({
+    rank: 'archon', ownKeySet: false, isFoundingOwner: true, founderCreatedAt: bornNow,
+  });
+  const artItem = r.items.find((n) => n.id === 'art_key');
+  assert.ok(artItem, 'the art_key item must still be listed, not hidden');
+  assert.equal(artItem.state, 'covered');
+  assert.equal(artItem.action, null);
+  assert.doesNotMatch(artItem.message, /coverage has ended/i);
+});
+
+t('the grace window is seven days — the policy number is pinned, not self-referential', () => {
+  // A fixed injected clock, and 7 written as a literal on both sides: mutating
+  // FOUNDING_GRACE_DAYS (a "tune", a bad merge) must fail here, not slide.
+  assert.equal(needs.FOUNDING_GRACE_DAYS, 7);
+  const born = Date.parse('2026-01-01T00:00:00Z');
+  const ctx = { rank: 'archon', ownKeySet: false, isFoundingOwner: true, founderCreatedAt: '2026-01-01T00:00:00Z' };
+  const inWindow = needs.computeNeeds({ ...ctx, nowMs: born + 7 * DAY - 60_000 });
+  assert.equal(inWindow.has_action_needed, false);
+  assert.equal(inWindow.items[0].id, 'founding_welcome');
+  const expired = needs.computeNeeds({ ...ctx, nowMs: born + 7 * DAY + 60_000 });
+  assert.equal(expired.has_action_needed, true);
+  assert.ok(!expired.items.find((n) => n.id === 'founding_welcome'));
+});
+
+t('grace expires: past FOUNDING_GRACE_DAYS the founder is nagged like anyone (real clock)', () => {
+  const old = new Date(Date.now() - (needs.FOUNDING_GRACE_DAYS * DAY + 60_000)).toISOString();
+  const r = needs.computeNeeds({
+    rank: 'archon', ownKeySet: false, isFoundingOwner: true, founderCreatedAt: old,
+  });
+  assert.equal(r.has_action_needed, true);
+  assert.ok(!r.items.find((n) => n.id === 'founding_welcome'));
+});
+
+t('a non-founder on a newborn instance is not suppressed', () => {
+  const r = needs.computeNeeds({
+    rank: 'thetes', ownKeySet: false, isFoundingOwner: false, founderCreatedAt: bornNow,
+  });
+  assert.equal(r.has_action_needed, true);
+  assert.ok(!r.items.find((n) => n.id === 'founding_welcome'));
+});
+
+t('satisfied stays satisfied during grace — no fake downgrades', () => {
+  const r = needs.computeNeeds({
+    rank: 'archon', ownKeySet: true, isFoundingOwner: true, founderCreatedAt: bornNow,
+  });
+  assert.equal(r.items.find((n) => n.id === 'art_key').state, 'satisfied');
+});
+
+t('no founder facts at all → no grace, no welcome (vanilla ctx unchanged)', () => {
+  const r = needs.computeNeeds({ rank: 'thetes', ownKeySet: false });
+  assert.equal(r.has_action_needed, true);
+  assert.ok(!r.items.find((n) => n.id === 'founding_welcome'));
+});
+
+console.log('the producing side (DB-free source pins — the policy is only as real as its facts):');
+
+// The seven policy cases above hand computeNeeds its ctx. These pin the two
+// places that PRODUCE that ctx, because both were wrong-or-unverified once:
+// the founder query returned the migration-seeded BFG system principal (ids 1-2
+// on every newborn DB — review panel, 2026-08-15), and a key rename in me.js
+// would silently disable the grace while every policy case stayed green. A
+// DB-backed newborn-instance test can't run in the unit gate, so the source is
+// the checkable artifact.
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+t('getFoundingBuilder skips the seeded system principals (system_role IS NULL)', () => {
+  const src = readFileSync(path.join(ROOT, 'src/bongos/db-kernel.js'), 'utf8');
+  const fn = src.slice(src.indexOf('function getFoundingBuilder'));
+  const sql = fn.slice(0, fn.indexOf('return'));
+  assert.match(sql, /FROM builders/);
+  assert.match(sql, /system_role IS NULL/,
+    'the founder query must exclude system principals — migrations 065/067 seed them at the lowest ids on every instance');
+  assert.match(sql, /ORDER BY id ASC/);
+});
+
+t('the /me aggregator feeds computeNeeds the founder facts under their contract names', () => {
+  const src = readFileSync(path.join(ROOT, 'src/bongos/routes/me.js'), 'utf8');
+  const call = src.slice(src.indexOf('computeNeeds({'), src.indexOf('}) : []'));
+  for (const key of ['isFoundingOwner', 'founderCreatedAt', 'projectName']) {
+    assert.match(call, new RegExp(`${key}\\s*:`),
+      `me.js must pass ${key} into computeNeeds — a rename silently disables the founding grace`);
+  }
+  assert.match(src, /getFoundingBuilder\(\)/, 'me.js must resolve the founder row');
+});
+
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);