@bongos/core 1.17.0

package/modules/memory/search.js

@@ -0,0 +1,320 @@
+// GDS retrieval layer — lexical hybrid search over search_chunks (task 949,
+// V4.R11 / ADR 0060 §5–§6). Two retrievers fused with Reciprocal Rank Fusion:
+//   1. FTS leg     — websearch_to_tsquery against the generated tsvector,
+//                    ranked by ts_rank_cd.
+//   2. Trigram leg — pg_trgm word_similarity (the `<%` operator, GIN-accelerated
+//                    by idx_search_chunks_body_trgm), which catches typos /
+//                    partial tokens / identifier fragments FTS stems away.
+// RRF (score = Σ 1/(k + rank_i), k=60) fuses them by RANK, so the two legs'
+// incomparable score scales never need normalizing and a chunk strong in EITHER
+// leg surfaces. Done in ONE SQL round-trip (CTE per leg + a fused aggregate).
+//
+// SCOPING (ADR 0060 §6 / ADR 0016) is applied INSIDE the SQL WHERE of BOTH legs,
+// never as a post-filter — an unauthorized chunk is never selected in the first
+// place. The route passes the caller's LIVE, server-resolved rank + authenticated
+// id (never input). See ranksAtOrBelow (fail-closed on an unknown rank) and the
+// owner predicate. The isolation suite (#950) is the regression guard.
+//
+// The pool is injectable (deps.pool) so a future test seam can drive it; the
+// live route uses the shared src/db.js pool (same Postgres).
+
+// Carved into modules/memory/ (BV1.R72 / ADR 0091 §2): pool via the doorway.
+const { pool } = require('../../src/module-api');
+// Reuse the chunker's ~chars/4 token estimate so recall's progressive-disclosure
+// cost labels match how chunks are sized (ADR 0095 C1 / task 1658). Intra-module
+// require — same module, allowed by the boundary.
+const { estTokens } = require('./search-chunker');
+
+// The rank ladder (xenos < thetes < metic < archon), mirrored from
+// src/bongos/boxes.js RANK_ORDER. A query may see a chunk whose min_rank is at or
+// below the caller's rank.
+const RANK_LADDER = ['xenos', 'thetes', 'metic', 'archon'];
+
+// The set of min_rank values a caller of the given rank may see. FAIL-CLOSED: an
+// unknown/absent rank resolves to the LEAST privilege (['xenos'] only) — a chunk
+// is never exposed to an unrecognized rank, and never to nothing-at-all.
+function ranksAtOrBelow(rank) {
+  const i = RANK_LADDER.indexOf(rank);
+  if (i < 0) return ['xenos'];
+  return RANK_LADDER.slice(0, i + 1);
+}
+
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 50;
+// Per-leg candidate pool feeding the fusion. Generous vs the final limit so a
+// chunk ranked well by one leg isn't truncated before fusion.
+const LEG_CANDIDATES = 50;
+const RRF_K = 60;
+// Usefulness-signal ranking (ADR 0095 C3, task 1660). After RRF fuses the two
+// retrieval legs by rank, the fused score is scaled by a bounded multiplier
+// derived from the chunk's net usefulness votes (useful_count - not_useful_count):
+//   factor = 1 + USEFULNESS_WEIGHT * tanh(net / USEFULNESS_SCALE)
+// tanh keeps the factor in (1 - W, 1 + W) no matter how lopsided the votes get,
+// so a single popular chunk can never dominate the ranking and a heavily
+// down-voted chunk fades but is never fully suppressed (recall stays fail-open).
+// With W=0.25 a well-liked chunk rises ~up to 25%, a dead-end fades ~down to 25%.
+const USEFULNESS_WEIGHT = 0.25;
+// Net-vote count at which the boost reaches ~tanh(1)=76% of its cap. Small, so a
+// few honest votes already move the needle without needing dozens.
+const USEFULNESS_SCALE = 3;
+// Trigram word-similarity floor for the fuzzy leg. pg_trgm's default
+// (word_similarity_threshold = 0.6) is too strict for ordinary typos — e.g.
+// word_similarity('trigam','…trigram…') = 0.571, which the default REJECTS
+// (measured on prod). 0.3 catches typos + partial-token / identifier-fragment
+// matches while staying well clear of noise. Set per-query via SET LOCAL inside
+// the search transaction (so the `<%` operator — GIN-accelerated by
+// idx_search_chunks_body_trgm — uses it), never globally. It's a fixed numeric
+// constant we control, so interpolating it into the SET is safe (no user input).
+const TRGM_THRESHOLD = 0.3;
+
+// Clamp + sanitize the requested result count.
+function clampLimit(limit) {
+  const n = parseInt(limit, 10);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_LIMIT;
+  return Math.min(n, MAX_LIMIT);
+}
+
+// searchChunks — run the fused, scoped query. Returns [] for an empty query (no
+// throw). Results: { id, source_kind, source_ref, heading_path, title, snippet,
+// score, fts_rank, trgm_rank }.
+//
+// REQUIRED scoping inputs (the route supplies these from the authenticated
+// session, NEVER from request input):
+//   builderId   — the caller's builder id (owner scoping).
+//   builderRank — the caller's LIVE rank (min_rank scoping).
+// Optional: limit (clamped 1..50), sourceKind ('doc' | 'db' | null = both).
+async function searchChunks(
+  { q, limit = DEFAULT_LIMIT, sourceKind = null, builderId, builderRank } = {},
+  { pool: p = pool, client = null } = {}
+) {
+  const query = typeof q === 'string' ? q.trim() : '';
+  if (!query) return [];
+  const lim = clampLimit(limit);
+  const allowedRanks = ranksAtOrBelow(builderRank);
+  const ownerId = Number.isInteger(builderId) ? builderId : (Number(builderId) || null);
+  const kind = sourceKind === 'doc' || sourceKind === 'db' ? sourceKind : null;
+
+  // $1 q · $2 allowedRanks[] · $3 ownerId · $4 sourceKind|null · $5 legCandidates · $6 finalLimit
+  // · $7 RRF_K · $8 usefulnessWeight · $9 usefulnessScale (ADR 0095 C3)
+  // The scope predicate is shared by both legs (built once as a SQL fragment).
+  // websearch_to_tsquery tolerates arbitrary user input (no tsquery syntax to
+  // escape); the `<%` operator uses pg_trgm.word_similarity_threshold.
+  const sql = `
+    WITH scoped AS (
+      SELECT id, source_kind, source_ref, heading_path, title, body, tsv
+        FROM search_chunks
+       WHERE min_rank = ANY($2::text[])
+         AND (owner_builder_id IS NULL OR owner_builder_id = $3::bigint)
+         AND ($4::text IS NULL OR source_kind = $4::text)
+    ),
+    fts AS (
+      SELECT id,
+             row_number() OVER (ORDER BY ts_rank_cd(tsv, websearch_to_tsquery('english', $1)) DESC, id) AS rnk
+        FROM scoped
+       WHERE tsv @@ websearch_to_tsquery('english', $1)
+       ORDER BY ts_rank_cd(tsv, websearch_to_tsquery('english', $1)) DESC, id
+       LIMIT $5
+    ),
+    trgm AS (
+      SELECT id,
+             row_number() OVER (ORDER BY word_similarity($1, body) DESC, id) AS rnk
+        FROM scoped
+       WHERE $1 <% body
+       ORDER BY word_similarity($1, body) DESC, id
+       LIMIT $5
+    ),
+    fused AS (
+      SELECT id,
+             SUM(1.0 / ($7 + rnk)) AS rrf,
+             MAX(CASE WHEN leg = 'fts'  THEN rnk END) AS fts_rank,
+             MAX(CASE WHEN leg = 'trgm' THEN rnk END) AS trgm_rank
+        FROM (
+          SELECT id, rnk, 'fts'  AS leg FROM fts
+          UNION ALL
+          SELECT id, rnk, 'trgm' AS leg FROM trgm
+        ) legs
+       GROUP BY id
+    )
+    SELECT c.id, c.source_kind, c.source_ref, c.heading_path, c.title,
+           left(c.body, 400) AS snippet,
+           length(c.body) AS body_chars,
+           f.rrf::float8 AS base_score,
+           -- Usefulness boost (ADR 0095 C3): scale the fused RRF score by a
+           -- bounded factor of the chunk's net votes. tanh caps the factor in
+           -- (1-$8, 1+$8) so no chunk can run away or be fully buried.
+           (f.rrf * (1 + $8::float8 * tanh((c.useful_count - c.not_useful_count)::float8 / $9::float8)))::float8 AS score,
+           c.useful_count, c.not_useful_count,
+           f.fts_rank, f.trgm_rank
+      FROM fused f
+      JOIN search_chunks c ON c.id = f.id
+     ORDER BY score DESC, c.id
+     LIMIT $6;
+  `;
+  const params = [query, allowedRanks, ownerId, kind, LEG_CANDIDATES, lim, RRF_K, USEFULNESS_WEIGHT, USEFULNESS_SCALE];
+  let rows;
+  if (client) {
+    // Test seam (#950 isolation suite): the caller owns the transaction AND the
+    // pg_trgm threshold (set its own SET LOCAL), so we just run the query on
+    // their client. Lets the suite seed + search + ROLLBACK on one connection.
+    ({ rows } = await client.query(sql, params));
+  } else {
+    // One connection + transaction so SET LOCAL applies to THIS query (a bare
+    // pool.query for the SET could land on a different pooled connection than the
+    // search). SET LOCAL is scoped to the transaction and auto-reverts on COMMIT.
+    const c = await p.connect();
+    try {
+      await c.query('BEGIN');
+      await c.query(`SET LOCAL pg_trgm.word_similarity_threshold = ${TRGM_THRESHOLD}`);
+      ({ rows } = await c.query(sql, params));
+      await c.query('COMMIT');
+    } catch (e) {
+      await c.query('ROLLBACK').catch(() => {});
+      throw e;
+    } finally {
+      c.release();
+    }
+  }
+  return rows.map((r) => {
+    const snippet = r.snippet;
+    const bodyChars = r.body_chars == null ? (snippet ? snippet.length : 0) : Number(r.body_chars);
+    // Progressive-disclosure cost labels (ADR 0095 C1 / task 1658): what the
+    // caller already sees vs. what a full expansion would COST, so an agent
+    // decides whether the deeper read is worth the tokens before fetching it.
+    const snippetTokens = estTokens(snippet);
+    const fullTokens = Math.ceil(bodyChars / 4); // estTokens(body) without shipping the body
+    return {
+      id: Number(r.id),
+      source_kind: r.source_kind,
+      source_ref: r.source_ref,
+      heading_path: r.heading_path,
+      title: r.title,
+      snippet,
+      snippet_tokens: snippetTokens,
+      full_tokens: fullTokens,
+      truncated: bodyChars > (snippet ? snippet.length : 0),
+      score: Number(r.score),
+      // The pre-usefulness fused RRF score, exposed so a caller can see how much
+      // the usefulness signal moved a result (ADR 0095 C3).
+      base_score: r.base_score == null ? null : Number(r.base_score),
+      useful_count: r.useful_count == null ? 0 : Number(r.useful_count),
+      not_useful_count: r.not_useful_count == null ? 0 : Number(r.not_useful_count),
+      fts_rank: r.fts_rank == null ? null : Number(r.fts_rank),
+      trgm_rank: r.trgm_rank == null ? null : Number(r.trgm_rank),
+    };
+  });
+}
+
+// fetchChunkBody — the EXPAND half of progressive disclosure (ADR 0095 C1 / task
+// 1658). Given a chunk id, return its FULL body — but scoped exactly like
+// searchChunks (same min_rank + owner predicate built from the authenticated
+// session, never input), so expand can never widen visibility past what search
+// would have returned. Returns null when the id doesn't exist OR the caller may
+// not see it (the two are indistinguishable on purpose — no existence oracle).
+async function fetchChunkBody(
+  { id, builderId, builderRank } = {},
+  { pool: p = pool, client = null } = {}
+) {
+  const chunkId = Number.isInteger(id) ? id : (Number(id) || null);
+  if (!chunkId) return null;
+  const allowedRanks = ranksAtOrBelow(builderRank);
+  const ownerId = Number.isInteger(builderId) ? builderId : (Number(builderId) || null);
+  const sql = `
+    SELECT id, source_kind, source_ref, heading_path, title, body
+      FROM search_chunks
+     WHERE id = $1::bigint
+       AND min_rank = ANY($2::text[])
+       AND (owner_builder_id IS NULL OR owner_builder_id = $3::bigint)
+     LIMIT 1;
+  `;
+  const params = [chunkId, allowedRanks, ownerId];
+  let rows;
+  if (client) {
+    ({ rows } = await client.query(sql, params));
+  } else {
+    ({ rows } = await p.query(sql, params));
+  }
+  if (!rows.length) return null;
+  const r = rows[0];
+  const body = r.body || '';
+  return {
+    id: Number(r.id),
+    source_kind: r.source_kind,
+    source_ref: r.source_ref,
+    heading_path: r.heading_path,
+    title: r.title,
+    body,
+    body_tokens: estTokens(body),
+  };
+}
+
+// markChunkUsefulness — record whether a recalled chunk actually helped (ADR 0095
+// C3, task 1660). This is the write half of the feedback loop: recall returns
+// chunk ids, and the caller marks one used/not so the ranker (above) can lift the
+// useful and fade the dead-end.
+//
+// SCOPING (ADR 0016 / ADR 0060 §6): a caller may only mark a chunk they could
+// have SEEN — the same min_rank + owner predicate the search uses. The id is the
+// only request-supplied field; rank + owner come ONLY from the authenticated
+// session (the route passes them, never the body). The UPDATE's WHERE re-applies
+// the scope, so a chunk the caller can't read can't be voted on (and the affected
+// row count is 0, surfaced as { updated: false }).
+//
+// `useful` true → bump useful_count + stamp last_useful_at; false → bump
+// not_useful_count. Counters are monotonic (claude-mem's save-result shape:
+// useful vs dead_end); there is no un-vote, by design — the signal is cumulative.
+async function markChunkUsefulness(
+  { chunkId, useful, builderId, builderRank } = {},
+  { pool: p = pool, client = null } = {}
+) {
+  const id = Number(chunkId);
+  if (!Number.isInteger(id) || id <= 0) {
+    const e = new Error('markChunkUsefulness: a positive integer chunkId is required');
+    e.code = 'BAD_CHUNK_ID';
+    throw e;
+  }
+  const allowedRanks = ranksAtOrBelow(builderRank);
+  const ownerId = Number.isInteger(builderId) ? builderId : (Number(builderId) || null);
+  const isUseful = useful === true || useful === 'true' || useful === 1 || useful === '1';
+
+  // The scope predicate mirrors searchChunks' scoped CTE exactly: a caller can
+  // only vote on a chunk their rank + ownership lets them see.
+  const sql = `
+    UPDATE search_chunks
+       SET useful_count     = useful_count     + CASE WHEN $4 THEN 1 ELSE 0 END,
+           not_useful_count = not_useful_count + CASE WHEN $4 THEN 0 ELSE 1 END,
+           last_useful_at   = CASE WHEN $4 THEN now() ELSE last_useful_at END,
+           updated_at       = now()
+     WHERE id = $1
+       AND min_rank = ANY($2::text[])
+       AND (owner_builder_id IS NULL OR owner_builder_id = $3::bigint)
+    RETURNING id, useful_count, not_useful_count, last_useful_at;
+  `;
+  const params = [id, allowedRanks, ownerId, isUseful];
+  const runner = client || p;
+  const { rows } = await runner.query(sql, params);
+  if (rows.length === 0) return { updated: false };
+  const r = rows[0];
+  return {
+    updated: true,
+    id: Number(r.id),
+    useful: isUseful,
+    useful_count: Number(r.useful_count),
+    not_useful_count: Number(r.not_useful_count),
+    last_useful_at: r.last_useful_at,
+  };
+}
+
+module.exports = {
+  searchChunks,
+  fetchChunkBody,
+  markChunkUsefulness,
+  ranksAtOrBelow,
+  clampLimit,
+  RANK_LADDER,
+  DEFAULT_LIMIT,
+  MAX_LIMIT,
+  RRF_K,
+  TRGM_THRESHOLD,
+  USEFULNESS_WEIGHT,
+  USEFULNESS_SCALE,
+};

package/modules/onboarding/CLAUDE.md

@@ -0,0 +1,55 @@
+# `onboarding` module — admission · onboarding state machine · newcomer floor + the `onboarding` kernel port
+
+> The **seventh CORE-domain** carved into a module (BV1.R81, [ADR 0093](../../docs/adr/<redacted>.md) §1) — after memory (R72), grading (R73), economy (R77), ideas (R78), security (R79), and builder-settings (R80). `default: true` in `module.json` — every instance onboards its own builders.
+
+Owns the **newcomer ADMISSION + ORIENTATION domain**:
+
+- **admission** ([`routes/access-requests.js`](routes/access-requests.js) + [`approval-broadcast.js`](approval-broadcast.js)) — the public `POST /access-requests` (the one unauthenticated GDS write) → the two Archon-only resolve endpoints. A pending request also posts a one-line approve/decline prompt to Discord `#member-approvals` (best-effort; the in-process bot's reaction handler closes the loop).
+- **the onboarding state machine** ([`onboarding-state.js`](onboarding-state.js)) — the server-ticked "Path into the City" checklist (`auth_complete → pick_disciplines → first_start → first_claim → ship_three → graduated`). The terminal `ship_three` stage clears at the same threshold that auto-promotes a Xenos to Thetes, so checklist-graduation coincides with the rank promotion. Backed by the `builder_onboarding_state` table (migration 045); the module reads/writes it directly with the client/pool its callers hand it.
+- **the friction analyzer** ([`onboarding.js`](onboarding.js)) — the *pure* half of "feedback without asking" (V3.R79 / C1): parse a consented onboarding transcript, compute deterministic friction signals, build the subagent prompt, validate its JSON, shape the `idea_inbox` payload. No FS/network/DB (those live in `scripts/gds/onboarding-analyze.js`).
+- **the evergreen newcomer-chore restock** ([`newcomer-restock.js`](newcomer-restock.js) + [`db.js`](db.js)) — a fresh first-builder task is always waiting: claiming a chore instance stamps a replacement synchronously, in the claim request. Template content lives in `scripts/gds/newcomer-floor.templates.json`; the supply read (`newcomerInstanceStats`) is the module's db slice.
+
+## The boundary (the one rule)
+
+This module reaches core **only** through the published doorway [`../../src/module-api.js`](../../src/module-api.js) (`coreVersion ^1.9.0`). It must **never** `require()` a core internal directly, and never another module. Core, in turn, must never `require()` a file in here — it reaches the state-machine + restock surface only through the `onboarding` port (below). Both directions are enforced by the BV1.R44/R45 fitness checks.
+
+## The `onboarding` kernel PORT
+
+The novel shape of this carve: it is the FIRST **core → module** port the LIFECYCLE drives (alongside the economy `reward` port). The onboarding state machine is ticked from inside core's claim/ship transactions, so the boundary can't be "module reaches into core" (the builder-settings pattern) — it's "core reaches the module's state machine through a kernel port."
+
+- **Provides — port `onboarding`** → the surface in [`port.js`](port.js): `{ getState, shapeForApi, safeMarkStage, markStage, broadcastGraduation, restockForClaim, restockAll, SOURCE_TAG }`. Registered in [`routes/onboarding.js`](routes/onboarding.js)'s factory (the loader runs it at boot, and again whenever a test rebuilds the GDS router — `hasProvider`-guarded). Mirrors `modules/economy/routes/reward.js`.
+- **The core consumers resolve it WITHOUT importing this module** (all via `seams.resolveOptional('onboarding')`):
+  - `src/bongos/db.js` — `claimTask`/`shipTask` tick `markStage` INSIDE their transaction (passing the txn `client`) and fire `broadcastGraduation` after COMMIT. The transaction-participant direction.
+  - `src/bongos/auth.js` — the Device-Flow + web auth callbacks mark `auth_complete` (`safeMarkStage`).
+  - `src/bongos/routes/me.js` — `GET /me` reads+shapes the checklist (`getState`/`shapeForApi`); `PATCH /me/disciplines` marks `pick_disciplines`.
+  - `src/bongos/routes/builders.js` — `GET /builders/:id/onboarding` reads+shapes the roster-visible checklist.
+  - `src/bongos/routes/tasks.js` — `GET /tasks/claimable` marks `first_start`; `POST /tasks/newcomer-restock` is the Archon backstop (`restockAll`).
+  - `src/bongos/routes/claims.js` — `POST /claims` restocks the chore shelf the instant one is claimed (`restockForClaim`/`SOURCE_TAG`).
+- All degrade gracefully when the module is off (a vanilla instance): the state-machine ticks become best-effort no-ops and the restock is skipped (the chore shelf simply isn't maintained), exactly as the surrounding try/catch already tolerated. The doorway gained one additive export (`enabledDisciplines`, CORE_VERSION → 1.9.0) the restock backstop needs; the onboarding capability itself is the port, not a doorway export.
+
+## Files
+
+| File | What |
+|---|---|
+| `onboarding-state.js` | the server-ticked onboarding state machine (markStage/getState/shapeForApi/safeMarkStage/broadcastGraduation/requireStageCleared + the displayed-checklist shaping). Pure of core `require()` — moved verbatim. |
+| `onboarding.js` | the *pure* friction analyzer (transcript parse → signals → prompt → validate → idea payload). Reads `branding().llmProjectName` through the doorway (de-branded in BV1.R76). |
+| `newcomer-restock.js` | the on-claim chore stamper — template load + per-template floor + monotonic-seq stamping. Reaches `createTask`/`newcomerInstanceStats` via the module `db.js`; `enabledDisciplines` via the doorway. |
+| `db.js` | the onboarding db slice — `newcomerInstanceStats` (the chore-supply read; pool via the doorway) + a `createTask` re-export off the doorway so the stamper's call site stays byte-identical. |
+| `approval-broadcast.js` | the `#member-approvals` outbound (the admission route's sole consumer; travels with it). Posts via `scripts/discord/lib` (a scripts/ require — outside the boundary). |
+| `port.js` | the `onboarding` port provider surface — DELEGATES (does not spread) to onboarding-state / newcomer-restock so test stubs bite at call time. |
+| `routes/onboarding.js` | the module route factory: registers the `onboarding` port + mounts the admission router. |
+| `routes/access-requests.js` | the admission cold-start endpoints (the public POST + the two Archon-only resolves). Auth/pool/validators via the doorway; approval-broadcast intra-module. |
+
+## NOT in this module (deliberately left in core)
+
+- **The admission GATE READS** — `db.hasInvitedAccessRequest` / `getBuilderByGithubId` stay core `db.js`: they are KERNEL identity/admission reads the trust boundary (`auth.js`) runs at first sign-in, not the onboarding state/restock domain (mirrors the Gemini-key staying core in the builder-settings carve).
+- **The `GET /me` + `GET /builders/:id/onboarding` AGGREGATORS** — `routes/me.js` / `routes/builders.js` stay core; they resolve this port for their onboarding slices (the facade precedent, 02-module-map §2).
+- **The onboarding-domain CLIs** — `scripts/gds/setup.js`, `onboarding-config.js`, `onboarding-analyze.js`, `newcomer-floor.js` travel with the domain but stay under `scripts/` and require the module directly (scripts are outside the kernel boundary — the grading/economy precedent).
+
+## Tables
+
+None owned. `builder_onboarding_state` (045) + `access_requests` live on the CORE schema and stay in core `migrations/`. This module owns the *onboarding-state queries* (inside `onboarding-state.js`) + the chore-supply read; any **new** onboarding migration belongs in `modules/onboarding/migrations/` namespaced `onboarding_*` (the additive rule).
+
+## Tests
+
+`tests/onboarding_state.mjs`, `tests/onboarding_gate.mjs`, `tests/onboarding_route_signals.mjs`, and `tests/newcomer_restock.mjs` import from `modules/onboarding/…` (the route-signal test registers the `onboarding` port). `tests/discord_approvals.mjs` imports the moved `approval-broadcast.js`. The doorway/boundary checks discover `onboarding` as a module. See [ADR 0093](../../docs/adr/<redacted>.md).

package/modules/onboarding/approval-broadcast.js

@@ -0,0 +1,59 @@
+// Server-side approval-request broadcast (task 1100).
+//
+// When a new-builder access request (access_requests, status='pending') needs an
+// Archon's go-ahead, the GDS posts a one-line request to the Archon-only
+// #member-approvals Discord channel so the Archon can approve it WITHOUT opening
+// the amazonprimea hall.
+//
+// The Archon then 👍 (approve) or 👎 (decline) the message; the in-process bot's
+// reaction handler (src/bongos/discord-approvals.js) re-derives the reactor's LIVE
+// rank and fires the existing approve/decline action. This module is ONLY the
+// outbound half — it posts the request line through the channel's webhook
+// (scripts/discord/lib), exactly like ship-broadcast.js posts ship lines.
+//
+// MARKER CONTRACT (mirrors ship-broadcast's `#<taskId>` prefix): each request
+// line LEADS with a `member-request #<id>` token the reaction handler anchors to,
+// so the bot maps a 👍 back to the right GDS record and a body that happens to
+// mention another "#5" cannot hijack the mapping. Keep this in lockstep with
+// discord-approvals.parseApprovalMarker.
+//
+// SECURITY: the only attacker-influenceable field is the requester's GitHub login
+// (validated to GITHUB_LOGIN_RE upstream) / a display name. postWebhook already
+// suppresses ALL mention pings (allowed_mentions:{parse:[]}, #871), so even a
+// crafted name can't @-ping the server. Best-effort + never throws — a Discord
+// hiccup must never break the access-request path.
+
+// PURE — the #member-approvals request line for a pending access request.
+// `request` is the access_requests row: { id, github_login, display_name, note }.
+function memberApprovalLine(request) {
+  const who = request.display_name
+    ? `${request.github_login} (${request.display_name})`
+    : request.github_login;
+  const note = request.note ? ` — “${String(request.note).slice(0, 200)}”` : '';
+  return `member-request #${request.id} — ${who} is asking to join the hall${note}\n`
+    + `React 👍 to invite them, 👎 to dismiss.`;
+}
+
+// Best-effort post to a channel. Swallows + logs all failure (an unconfigured
+// webhook on this host, a Discord outage) so the caller's path is never broken.
+async function postLine(channel, line, deps = {}) {
+  const postWebhook = deps.postWebhook || require('../../scripts/discord/lib').postWebhook;
+  const log = deps.log || console.log;
+  try {
+    await postWebhook(channel, line);
+    return { posted: true };
+  } catch (e) {
+    log(`[gds] approval broadcast: #${channel.replace(/_/g, '-')} post failed (non-blocking): ${e && e.message ? e.message : e}`);
+    return { posted: false, error: e && e.message ? e.message : String(e) };
+  }
+}
+
+async function postMemberApprovalRequest(request, deps = {}) {
+  if (!request || request.id == null) return { posted: false, skipped: 'no_request' };
+  return postLine('member_approvals', memberApprovalLine(request), deps);
+}
+
+module.exports = {
+  memberApprovalLine,
+  postMemberApprovalRequest,
+};

package/modules/onboarding/db.js

@@ -0,0 +1,54 @@
+'use strict';
+
+// modules/onboarding/db.js — the onboarding domain's data-layer slice
+// (BV1.R81 / ADR 0093 §1).
+//
+// Carved out of the GDS core src/bongos/db.js: `newcomerInstanceStats` (the
+// evergreen-chore SUPPLY read that backs newcomer-restock.js) left the monolith
+// verbatim — only the require() path changed (the shared pool reaches through the
+// published doorway, the memory/economy per-domain db-slice pattern, ADR 0091
+// §2). `createTask` is a LIFECYCLE write now owned by modules/lifecycle/ (the
+// `lifecycle` kernel PORT, BV1.R86 — the marked doorway seam retired). It's
+// re-exposed here as a delegating call that resolves the port at call time so
+// newcomer-restock's `db.createTask(...)` call site stays byte-identical without
+// reaching into core or a sibling module.
+//
+// onboarding-state's own table (`builder_onboarding_state`) is NOT queried here:
+// onboarding-state.js reads/writes that table directly with the client/pool its
+// callers hand it (it was always self-contained — no db.js function backed it),
+// so it travels as-is and needs no slice.
+
+const api = require('../../src/module-api');
+const { pool } = api;
+// createTask via the `lifecycle` port (resolved at call time — the port registers
+// at boot; a vanilla instance without lifecycle is impossible, it is default-on).
+function createTask(...a) {
+  const lifecycle = api.resolveOptional('lifecycle');
+  if (!lifecycle) throw new Error('lifecycle port unavailable (createTask)');
+  return lifecycle.createTask(...a);
+}
+
+// Restock support for the evergreen newcomer chores (task 1168). One read that
+// backs modules/onboarding/newcomer-restock.js (which owns template content + the
+// stamping); lives here because it needs the module pool. Returns the count of
+// READY instances of a chore plus EVERY existing source_ref for it (any status),
+// so the caller can compute the next monotonic seq without a second round-trip.
+async function newcomerInstanceStats(discipline, templateId) {
+  const { rows } = await pool.query(
+    `SELECT source_ref, status FROM tasks
+      WHERE source = 'newcomer-template' AND source_ref LIKE $1`,
+    [`tmpl:${discipline}:${templateId}:%`]
+  );
+  return {
+    readyCount: rows.filter((r) => r.status === 'ready').length,
+    refs: rows.map((r) => r.source_ref),
+  };
+}
+
+module.exports = {
+  newcomerInstanceStats,
+  // LIFECYCLE write the kernel owns — re-exported off the doorway so the chore
+  // stamper's `db.createTask(...)` stays byte-identical (the marked createTask
+  // seam, src/module-api.js).
+  createTask,
+};

package/modules/onboarding/module.json

@@ -0,0 +1,10 @@
+{
+  "key": "onboarding",
+  "title": "Onboarding (admission · setup · newcomer floor)",
+  "description": "The newcomer ADMISSION + ORIENTATION domain — the public access-request → Archon-approval gate, the server-ticked onboarding state machine (the 'Path into the City' checklist that graduates a Xenos to Thetes), the friction analyzer (feedback-without-asking on consented onboarding transcripts), and the evergreen newcomer-chore restock (a fresh first-builder task is always waiting). A core-domain module carved out of the GDS core in BV1.R81 (ADR 0093 §1); default-on because every instance onboards its own builders. The access-requests admission routes mount here; the core lifecycle (db.js claim/ship), auth callbacks, and the me/builders profile readers resolve the `onboarding` kernel PORT for the state-machine + restock surface they need — never importing the module.",
+  "coreVersion": "^1.9.0",
+  "default": true,
+  "contributes": { "routes": ["onboarding"] },
+  "provides": ["onboarding"],
+  "consumes": []
+}