@bongos/core 1.17.0 → 1.17.2

package/modules/lifecycle/routes/goals.js

@@ -376,6 +376,32 @@ function authorizeJoinRequestResponse({ goal, actorId, actorRank, actorMembershi
   return { ok: true };
 }
 
+// authorizeWithdrawJoinRequest — the gate for POST /goals/:id/requests/:reqId/withdraw
+// (task 1953): ONLY the requester may withdraw their OWN pending join-request — a
+// symmetric mirror of authorizeInvitationResponse (the invitee resolves their own
+// invite; here the requester resolves their own request, self-served instead of
+// waiting on an owner/manager deny). Ordering: request_not_found → wrong_goal →
+// not_a_join_request → not_pending → not_your_request. PURE + exported.
+function authorizeWithdrawJoinRequest({ request, goalId, actorId }) {
+  if (!request) return { ok: false, status: 404, body: { error: 'request_not_found' } };
+  if (String(request.goal_id) !== String(goalId)) {
+    return { ok: false, status: 404, body: { error: 'request_not_found', message: 'No such request on this goal.' } };
+  }
+  if (request.kind !== 'request') {
+    return { ok: false, status: 400, body: { error: 'not_a_join_request', message: 'That row is an invitation, not a join-request.' } };
+  }
+  if (request.status !== 'pending') {
+    return { ok: false, status: 409, body: { error: 'not_pending', status: request.status } };
+  }
+  if (String(request.builder_id) !== String(actorId)) {
+    return { ok: false, status: 403, body: {
+      error: 'not_your_request',
+      message: 'Only the requester may withdraw their own join-request.',
+    } };
+  }
+  return { ok: true };
+}
+
 module.exports = function buildGoalsRouter() {
   const router = express.Router();
 
@@ -798,6 +824,57 @@ module.exports = function buildGoalsRouter() {
     }
   });
 
+  // GET /goals/:id/requests — the goal's own pending invite/join-request queue
+  // (task 1953): every pending row on THIS goal, both kinds — outstanding invites
+  // the goal has sent (awaiting the invitee) and join-requests awaiting approval.
+  // db.listPendingRequestsForGoal was built for this route in task 1952's landing
+  // but never wired to HTTP; this is the goals-page manager view alongside the
+  // cross-goal GET /goals/inbox.
+  // rank: any-builder (requireBuilder) + the in-handler owner|manager|Archon gate
+  // (authorizeGoalManagement) — same wall as visibility/invite/request-respond.
+  router.get('/goals/:id/requests', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_goal_id' });
+    if (id === null) return;
+    try {
+      const goal = await db.getGoal(id);
+      const actorMembership = goal
+        ? await db.getGoalMember({ goalId: id, builderId: req.builder.id })
+        : null;
+      const decision = authorizeGoalManagement({
+        goal, actorId: req.builder.id, actorRank: req.builder.rank, actorMembership,
+      });
+      if (!decision.ok) return res.status(decision.status).json(decision.body);
+      const requests = await db.listPendingRequestsForGoal(id);
+      return res.json({ requests });
+    } catch (err) {
+      console.error('[gds] GET /goals/:id/requests', err);
+      return res.fail('fetch_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /goals/:id/requests/:reqId/withdraw — the requester cancels their OWN
+  // pending join-request (task 1953): the symmetric self-served mirror of a
+  // manager's deny. Sets status='cancelled' (kept as the audit trail, like a
+  // deny's 'rejected'); never touches an invitation row.
+  // rank: any-builder (requireBuilder) + the in-handler authorizeWithdrawJoinRequest.
+  router.post('/goals/:id/requests/:reqId/withdraw', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_goal_id' });
+    if (id === null) return;
+    const reqId = parseId(req, res, { param: 'reqId', code: 'bad_request_id', positiveInt: true });
+    if (reqId === null) return;
+    try {
+      const request = await db.getMembershipRequest(reqId);
+      const decision = authorizeWithdrawJoinRequest({ request, goalId: id, actorId: req.builder.id });
+      if (!decision.ok) return res.status(decision.status).json(decision.body);
+      const resolved = await db.resolveMembershipRequest({ id: reqId, status: 'cancelled', resolvedBy: req.builder.id });
+      if (!resolved) return res.fail('not_pending', { status: 409, message: 'The request changed underneath this withdrawal — re-read and retry.' });
+      return res.json({ ok: true, request: resolved });
+    } catch (err) {
+      console.error('[gds] POST /goals/:id/requests/:reqId/withdraw', err);
+      return res.fail('withdraw_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // POST /goals/:id/members — the goal's own authority (owner | manager | Archon)
   // invites a builder to the goal (task 1762: widened from Archon-only so a
   // manager doesn't need an Archon in the loop for a normal goal). This stays the
@@ -1417,3 +1494,6 @@ module.exports.protectedScopeAdmissionBlock = protectedScopeAdmissionBlock;
 module.exports.authorizeCreateJoinRequest = authorizeCreateJoinRequest;
 module.exports.authorizeInvitationResponse = authorizeInvitationResponse;
 module.exports.authorizeJoinRequestResponse = authorizeJoinRequestResponse;
+// task 1953: the withdraw gate — exported for tests/goal_membership_requests.mjs,
+// same precedent as its siblings above.
+module.exports.authorizeWithdrawJoinRequest = authorizeWithdrawJoinRequest;

package/modules/memory/CLAUDE.md

@@ -1,40 +1,15 @@
-# `memory` module — builder memory, recall/search, learnings
+# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
 
-> The **first CORE-domain** carved into a module (BV1.R72, [ADR 0091](../../docs/adr/<redacted>.md) §2) — not an optional feature like dev-box/discord/art/game, but a core methodology domain extracted to prove the kernel↔core-domain boundary. It is the reference every later core-domain carve (grading R73, …) copies.
+This file is a placeholder shipped inside the **@bongos/core** package. The core's own
+internal agent notes are intentionally omitted from the published artifact so they cannot
+load into your instance's context.
 
-Owns per-builder session **memory** (the BFG-scoped store the hall syncs), the lexical **recall/search** retrieval layer ([ADR 0060](../../docs/adr/0060-gds-retrieval-layer.md): Postgres FTS + trigram/RRF), and durable **learnings**. `default: true` in `module.json` — the build system's memory ships to **every** instance (unlike the default-off feature modules), so it mounts unconditionally unless an instance explicitly disables it.
+**It does not govern this repository.** Your own root `CLAUDE.md`, your `.claude/`
+directory, and the live Bongos database are the source of truth for how work happens here
+and who may do what.
 
-## The boundary (the one rule)
+You are seeing this only because an agent opened a file under `node_modules/@bongos/core/`.
+Nothing in here needs to be read to use the platform — run `bongos help` for commands.
 
-This module reaches core **only** through the published doorway `../../src/module-api.js` (`coreVersion ^1.5.0`). It must **never** `require()` a core internal (`../../src/bongos/db`, `../../src/bongos/auth`, `../../src/bongos/pool`, …) directly, and never another module. Core, in turn, must never `require()` a file in here — the route mounts left `src/bongos/routes.js`; `moduleLoader.mountModuleRoutes` discovers + mounts them now. Both directions are enforced by the BV1.R44/R45 fitness checks; R70's `kernel-imports-no-domain` check additionally keeps the kernel from reaching back in.
-
-## Files
-
-| File | What |
-|---|---|
-| `memory.js` | per-builder memory store (quotas, BFG namespace, store/fetch/list). Manages its own transactions via the doorway `pool`. |
-| `search.js` | the recall query engine — FTS + trigram, RRF fusion, rank-scoped (ADR 0060). |
-| `search-chunker.js` | pure markdown→chunk splitter (no DB). Also used by the `search-ingest-*` CLIs (memory-owned scripts). |
-| `learnings.js` | durable paid-once knowledge capture (the `learnings` table). |
-| `routes/memory.js` | `/memory/*` — sync/read/forensic. Carries its own larger `express.json` for `/memory/sync` (1 MB batches); core `routes.js` still skips the global parser for that path. |
-| `routes/search.js` | `/search` (recall) + `/search/mark` (the ADR 0095 C3 usefulness vote — `POST {chunk_id, useful?}`, session-scoped). |
-| `routes/learnings.js` | `/learnings` (POST capture + GET). |
-
-All four lib files reach Postgres through the doorway `pool`; the routes reach auth gates + the kernel db helpers (`getBuilderById`, `insertAuditLog`) + the shared request validators (`validateOrRespond`/`LIMITS`) off the doorway `api`, and the lib files via intra-module relative requires.
-
-## Tables (owned, not moved)
-
-`builder_memory`, `memory_search_chunks`, `learnings` (+ their migrations) were created before the module system and stay in core `migrations/` (the schema-migrations stem-key makes a later relocation a no-op). The module owns the *queries*; any **new** memory migration belongs in `modules/memory/migrations/` namespaced `memory_*` (the additive rule).
-
-## Seams
-
-None yet — memory neither provides nor consumes a port/event. Core reads memory only through its HTTP routes (the hall's sync/recall), never a direct import.
-
-## NOT in this module
-
-- **`bfg.js`** — the BFG memory-hygiene evaluator stays core (it scores memory quality across builders); it touches memory through the routes/store contract, not a sibling import.
-- **`migrations/`** — the memory tables' creating migrations stay in core `migrations/` (pre-module-system; see Tables above).
-
-## Tests
-
-`tests/memory_isolation.mjs`, `tests/bfg*.mjs`, `tests/search_*.mjs`, `tests/search_chunker.mjs`, `tests/diff_derived_signals.mjs`, `tests/recall_*.mjs` import from `modules/memory/…`. The ADR 0095 C3 mark/rank loop's DB-backed cases live in the `tests/search_isolation.mjs` Layer C class (integration gate); the pure ranker-factor + scope logic is exercised by the in-module assertions in `markChunkUsefulness`.
+_To work ON the platform core itself, use the standalone @bongos/core source repository,
+not this vendored copy._

package/modules/onboarding/CLAUDE.md

@@ -1,55 +1,15 @@
-# `onboarding` module — admission · onboarding state machine · newcomer floor + the `onboarding` kernel port
+# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
 
-> 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.
+This file is a placeholder shipped inside the **@bongos/core** package. The core's own
+internal agent notes are intentionally omitted from the published artifact so they cannot
+load into your instance's context.
 
-Owns the **newcomer ADMISSION + ORIENTATION domain**:
+**It does not govern this repository.** Your own root `CLAUDE.md`, your `.claude/`
+directory, and the live Bongos database are the source of truth for how work happens here
+and who may do what.
 
-- **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.
+You are seeing this only because an agent opened a file under `node_modules/@bongos/core/`.
+Nothing in here needs to be read to use the platform — run `bongos help` for commands.
 
-## 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).
+_To work ON the platform core itself, use the standalone @bongos/core source repository,
+not this vendored copy._

package/modules/provisioning/CLAUDE.md

@@ -0,0 +1,15 @@
+# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
+
+This file is a placeholder shipped inside the **@bongos/core** package. The core's own
+internal agent notes are intentionally omitted from the published artifact so they cannot
+load into your instance's context.
+
+**It does not govern this repository.** Your own root `CLAUDE.md`, your `.claude/`
+directory, and the live Bongos database are the source of truth for how work happens here
+and who may do what.
+
+You are seeing this only because an agent opened a file under `node_modules/@bongos/core/`.
+Nothing in here needs to be read to use the platform — run `bongos help` for commands.
+
+_To work ON the platform core itself, use the standalone @bongos/core source repository,
+not this vendored copy._

package/modules/provisioning/migrations/provisioning_001_tables.sql

@@ -0,0 +1,160 @@
+-- provisioning_001_tables.sql — the `provisioning` module's DB slice (ADR 0111 §1,
+-- task #1942 / BONGOS-V1 goal 32). Instance hosting + domains: the web-tier REQUEST
+-- + STATE surface for standing up + operating a Cloud Bongos instance's own infra.
+--
+-- These three tables mirror the dev-box lifecycle ledger (migrations 067/070), one
+-- layer up — a whole INSTANCE instead of a builder's box:
+--   • provisioning_instances — one row per instance being provisioned/operated.
+--   • provisioning_intents    — the trust-boundary-safe request queue (the box_intents
+--                               analogue): the web tier only ENQUEUES; the control-plane
+--                               runner (scripts/gds/provision.js, task P3) drains it. The
+--                               web process holds NO cloud tokens (ADR 0111 §2 / ADR 0016).
+--   • provisioning_events     — an append-only audit ledger of provisioning actions
+--                               (direct control-plane infra mutations are project-state
+--                               changes too — CLAUDE.md hard rule — so they get a row).
+--
+-- Module migrations are ADDITIVE and NAMESPACED: every object lives under the
+-- provisioning_ prefix, there is no down-migration, and the file itself is
+-- provisioning_-prefixed (ADR 0108 §5) so its stem can never collide with a core /
+-- instance / other-module migration across repos. `scripts/migrate.sh` discovers +
+-- applies this ONLY when the provisioning module is enabled in config/modules.json.
+--
+-- Idempotent: safe to re-run.
+
+-- ---------------------------------------------------------------------------
+-- provisioning_instances — one row per instance an owner is provisioning/operating.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS provisioning_instances (
+  id                bigserial PRIMARY KEY,
+
+  -- The owner (a builder in THIS GDS) who requested + operates this instance.
+  owner_builder_id  bigint NOT NULL REFERENCES builders(id) ON DELETE CASCADE,
+
+  -- A DNS/db-safe slug naming the instance (e.g. 'mercury'). The stable key an
+  -- owner + the port reference it by; also the base for its DB name + hostname.
+  slug              text NOT NULL UNIQUE,
+
+  -- The target repo/ref this instance runs (e.g. 'owner/repo'). Advisory metadata
+  -- the runner reads; NULL until supplied.
+  target_ref        text,
+
+  -- Hosting shape (ADR 0111 §3/§6). Cheapest-first DNA:
+  --   co-tenant  — a process + DB on an EXISTING box (the cloudbongos.com model, $0 extra)
+  --   dedicated  — its own DigitalOcean droplet (only when justified)
+  hosting_shape     text NOT NULL DEFAULT 'co-tenant'
+    CHECK (hosting_shape IN ('co-tenant', 'dedicated')),
+
+  -- Bring-your-own-domain first (ADR 0111 §4): the apex/host the owner already owns
+  -- (or a delegated zone). NULL until supplied. Registrar PURCHASE is deferred.
+  domain            text,
+
+  -- The instance's own database name (createdb <db_name>; GDS-only migrate).
+  db_name           text,
+
+  -- Allocated port for a co-tenant process (NULL for a dedicated droplet / unallocated).
+  port              int,
+
+  -- The droplet size tier for a dedicated shape (a SIZE_CATALOG slug); NULL co-tenant.
+  tier              text,
+
+  -- Lifecycle state machine (mirrored in modules/provisioning/provisioning.js
+  -- INSTANCE_STATES):
+  --   requested    — the owner asked; a 'provision' intent is (or will be) enqueued
+  --   provisioning — the control-plane runner is standing it up
+  --   active        — running + serving
+  --   tearing_down  — a 'teardown' intent is being executed
+  --   torn_down     — fully de-provisioned
+  --   error         — a provisioning op failed; needs operator attention
+  status            text NOT NULL DEFAULT 'requested'
+    CHECK (status IN ('requested', 'provisioning', 'active',
+                      'tearing_down', 'torn_down', 'error')),
+
+  -- Monthly cost estimate (USD) for visibility (ADR 0111 §6). Co-tenant = 0;
+  -- dedicated = the tier's SIZE_CATALOG monthly rate. NOT a bill — just visibility.
+  cost_estimate_usd numeric(10,4) NOT NULL DEFAULT 0,
+
+  error_note        text,
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  updated_at        timestamptz NOT NULL DEFAULT now(),
+  provisioned_at    timestamptz,
+  torn_down_at      timestamptz
+);
+CREATE INDEX IF NOT EXISTS idx_provisioning_instances_owner
+  ON provisioning_instances (owner_builder_id);
+CREATE INDEX IF NOT EXISTS idx_provisioning_instances_status
+  ON provisioning_instances (status);
+
+-- ---------------------------------------------------------------------------
+-- provisioning_intents — the provision / teardown request queue (the
+-- trust-boundary-safe bridge between the web process and the control plane).
+-- The web side only ever RECORDS a request here; scripts/gds/provision.js (task
+-- P3, the sole holder of the DO/Cloudflare tokens) drains it. The web process
+-- stays powerless over infra — it can ask, never act (ADR 0111 §2 / ADR 0016).
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS provisioning_intents (
+  id            bigserial PRIMARY KEY,
+  instance_id   bigint NOT NULL REFERENCES provisioning_instances(id) ON DELETE CASCADE,
+
+  -- Only the two SAFE, owner/Archon-initiated ops are queueable from the web:
+  -- 'provision' (stand up) and 'teardown' (an explicit tear-down the owner/Archon
+  -- asked for). No implicit destructive op is ever queued.
+  action        text NOT NULL CHECK (action IN ('provision', 'teardown')),
+
+  -- pending  → waiting for the runner to pick it up
+  -- running  → the runner claimed it and is doing the control-plane work
+  -- done     → the op succeeded
+  -- error    → the op failed (last_error carries why); the row is no longer "open"
+  --            so the partial unique index below lets a fresh intent (retry) through.
+  state         text NOT NULL DEFAULT 'pending'
+    CHECK (state IN ('pending', 'running', 'done', 'error')),
+
+  -- Who asked. 'api:self' for an owner's own request; 'api:archon:<id>' for an
+  -- Archon force action; a runner/control-plane tag otherwise. Audit only.
+  requested_by  text,
+
+  -- Retry accounting. The runner bumps attempts each claim; a small cap (enforced
+  -- in the runner, not here) stops a poison intent from looping forever.
+  attempts      int NOT NULL DEFAULT 0,
+  last_error    text,
+
+  created_at    timestamptz NOT NULL DEFAULT now(),
+  updated_at    timestamptz NOT NULL DEFAULT now(),
+  resolved_at   timestamptz
+);
+
+-- At most ONE open (pending|running) intent per instance — a repeated request
+-- collides here and the route returns the already-open intent instead of piling
+-- up a redundant queue. Resolved (done|error) rows are exempt, so a retry after a
+-- failure is always allowed (mirrors ux_box_intents_open).
+CREATE UNIQUE INDEX IF NOT EXISTS ux_provisioning_intents_open
+  ON provisioning_intents (instance_id)
+  WHERE state IN ('pending', 'running');
+
+-- The runner's hot path: "oldest pending intent". A partial index keeps it tiny
+-- (it only ever indexes the unresolved tail, not the full history).
+CREATE INDEX IF NOT EXISTS idx_provisioning_intents_pending
+  ON provisioning_intents (created_at)
+  WHERE state = 'pending';
+
+-- ---------------------------------------------------------------------------
+-- provisioning_events — append-only audit/log of provisioning actions. The HTTP
+-- audit_log captures only API mutations; the real provisioning ops run on the
+-- control-plane runner, so they record here (like box_events for the box lifecycle).
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS provisioning_events (
+  id                bigserial PRIMARY KEY,
+  instance_id       bigint NOT NULL REFERENCES provisioning_instances(id) ON DELETE CASCADE,
+  owner_builder_id  bigint REFERENCES builders(id) ON DELETE SET NULL,
+  -- request | provision | active | teardown | torn_down | cost | error | ...
+  event             text NOT NULL,
+  detail            text,
+  cost_usd          numeric(10,4),
+  -- Who/what triggered it: 'api:self' | 'api:archon:<id>' | 'runner' | ...
+  actor             text,
+  created_at        timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS idx_provisioning_events_instance
+  ON provisioning_events (instance_id, created_at DESC);
+
+INSERT INTO schema_migrations (version) VALUES ('provisioning_001_tables')
+  ON CONFLICT (version) DO NOTHING;

package/modules/provisioning/migrations/provisioning_002_standalone_shape.sql

@@ -0,0 +1,11 @@
+-- provisioning_002_standalone_shape.sql — widen provisioning_instances.hosting_shape
+-- to allow 'standalone' (ADR 0108 / ADR 0111, BONGOS-V1 goal 32/35, task 1978).
+--
+-- A standalone instance runs from its OWN repo checkout with a pinned @cloudbongos/core
+-- npm dep (the ADR 0108 destination model), distinct from the co-tenant shape (which
+-- shares the control-plane checkout) and dedicated (its own droplet). Widening a CHECK
+-- enum is ADDITIVE — it only permits MORE values; no existing row changes, no data is
+-- lost — so it is safe under the module-owned-migration rule (ADR 0083 §Decision #5).
+ALTER TABLE provisioning_instances DROP CONSTRAINT IF EXISTS provisioning_instances_hosting_shape_check;
+ALTER TABLE provisioning_instances ADD CONSTRAINT provisioning_instances_hosting_shape_check
+  CHECK (hosting_shape IN ('co-tenant', 'dedicated', 'standalone'));

package/modules/provisioning/migrations/provisioning_003_github_app_manifest.sql

@@ -0,0 +1,95 @@
+-- provisioning_003_github_app_manifest.sql — the GitHub App Manifest onboarding flow
+-- (ADR 0133, BONGOS-V1 goal 35 / criterion 165, task 2080).
+--
+-- WHY. The last human friction in greenfield onboarding was: the owner had to hand-
+-- create a GitHub OAuth App, generate a client secret, and hand it to the box
+-- (oauth-secret.js). GitHub has NO API to create an OAuth App — but it DOES have the
+-- GitHub App *Manifest* flow: the owner clicks ONE pre-filled link, approves on GitHub,
+-- and GitHub returns a temporary `code` we exchange (control-plane-side) for the
+-- client_id + client_secret automatically. The secret never touches the browser/chat.
+--
+-- The flow spans TWO processes across the trust boundary (ADR 0111 §2 / ADR 0016):
+--   • the web tier mints a one-time `state` token + stores the row (this table), and
+--     its public callback stores GitHub's `code` when the owner returns;
+--   • the control-plane runner (scripts/gds/provision.js — the sole token-holder)
+--     drains rows in status 'code_received', exchanges the code for creds, and places
+--     them in /etc/<slug>/web.env (the oauth-secret.js path), then verifies /healthz.
+-- Because the two processes don't share memory, the state/code lease is DB-backed (the
+-- merge_lease / builder_sessions expires_at pattern), NOT the in-memory deviceFlows map.
+--
+-- Additive + idempotent + namespaced (ADR 0108 §5). Applied only when the provisioning
+-- module is enabled (config/modules.json). Safe to re-run.
+
+-- ---------------------------------------------------------------------------
+-- (1) Widen provisioning_intents.action so the manifest conversion can ride the
+--     existing intent queue if ever needed. Today the runner drains manifests by
+--     scanning this table's status (drainOAuthManifests) — but widening the CHECK
+--     keeps a future intent-driven path open and keeps INTENT_ACTIONS in lockstep.
+--     Widening a CHECK enum is additive (permits MORE values; no row changes).
+-- ---------------------------------------------------------------------------
+ALTER TABLE provisioning_intents DROP CONSTRAINT IF EXISTS provisioning_intents_action_check;
+ALTER TABLE provisioning_intents ADD CONSTRAINT provisioning_intents_action_check
+  CHECK (action IN ('provision', 'teardown', 'oauth-manifest'));
+
+-- ---------------------------------------------------------------------------
+-- (2) provisioning_oauth_manifests — one row per GitHub-App-Manifest onboarding
+--     attempt for an instance. The `state` is the one-time CSRF token round-tripped
+--     through GitHub; `github_code` is GitHub's temporary conversion code (single-use,
+--     ~1h GitHub-side TTL) the control-plane runner exchanges for the client creds.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS provisioning_oauth_manifests (
+  id            bigserial PRIMARY KEY,
+  instance_id   bigint NOT NULL REFERENCES provisioning_instances(id) ON DELETE CASCADE,
+
+  -- The one-time CSRF `state` token minted by the web tier (crypto.randomBytes hex),
+  -- carried to GitHub in the manifest POST and returned on the callback. UNIQUE so a
+  -- callback maps to exactly one attempt. Unguessable (256-bit) — it is the callback's
+  -- only authorization (GitHub redirects the browser back unauthenticated).
+  state         text NOT NULL UNIQUE,
+
+  -- Lifecycle:
+  --   pending        — link minted; awaiting the owner's click + GitHub's redirect back
+  --   code_received  — GitHub redirected back with a `code`; awaiting the control-plane runner
+  --   converting     — the runner claimed the row and is exchanging the code with GitHub
+  --   done           — creds fetched + placed in web.env; /healthz auth_configured verified
+  --   error          — conversion or placement failed (last_error carries why)
+  --   expired        — the `state` TTL passed before the owner completed the round-trip
+  status        text NOT NULL DEFAULT 'pending'
+    CHECK (status IN ('pending', 'code_received', 'converting', 'done', 'error', 'expired')),
+
+  -- GitHub's temporary manifest-conversion code. Written by the web-tier callback;
+  -- consumed by the runner (POST /app-manifests/{code}/conversions). NEVER the secret
+  -- itself — only the short-lived code is web-tier-visible; the client_secret is fetched
+  -- by the control plane and written straight to web.env, never stored here.
+  github_code   text,
+
+  -- The GitHub App id + slug GitHub assigned once converted (audit; the App the owner
+  -- created for their instance's sign-in). Filled by the runner on success.
+  app_id        bigint,
+  app_slug      text,
+
+  -- The builder who initiated the attempt (the signed-in owner on the mothership).
+  requested_by  bigint REFERENCES builders(id) ON DELETE SET NULL,
+
+  -- Runner retry accounting (a poison conversion never loops forever) + last error.
+  attempts      int NOT NULL DEFAULT 0,
+  last_error    text,
+
+  -- The `state` token's TTL — the owner must complete the GitHub round-trip before this.
+  expires_at    timestamptz NOT NULL,
+  created_at    timestamptz NOT NULL DEFAULT now(),
+  updated_at    timestamptz NOT NULL DEFAULT now(),
+  resolved_at   timestamptz
+);
+
+-- The runner's hot path: "oldest manifest awaiting conversion" (status='code_received').
+-- A partial index keeps it tiny (only the unresolved tail).
+CREATE INDEX IF NOT EXISTS idx_provisioning_oauth_manifests_ready
+  ON provisioning_oauth_manifests (created_at)
+  WHERE status = 'code_received';
+
+CREATE INDEX IF NOT EXISTS idx_provisioning_oauth_manifests_instance
+  ON provisioning_oauth_manifests (instance_id, created_at DESC);
+
+INSERT INTO schema_migrations (version) VALUES ('provisioning_003_github_app_manifest')
+  ON CONFLICT (version) DO NOTHING;

package/modules/provisioning/module.json

@@ -0,0 +1,17 @@
+{
+  "key": "provisioning",
+  "title": "Instance provisioning",
+  "description": "Stand up + operate a Cloud Bongos instance's own infrastructure (server, database, domain, DNS, TLS) via the API, so an owner does not manage infra by hand (ADR 0111). Owns the web-tier REQUEST + STATE surface only: it enqueues provisioning intents + reads instance state — it holds NO cloud-provider tokens and calls NO cloud API. A separate control-plane runner (scripts/gds/provision.js, task P3) is the sole token-holder that drains the intents. Distinct from the `hosting` module (ADR 0092), which brokers compute WORKLOADS.",
+  "coreVersion": "^1.14.0",
+  "default": false,
+  "author": "Off the Boats",
+  "origin": "Off the Boats (the first Cloud Bongos instance, amazonprimea.com)",
+  "license": "AGPL-3.0",
+  "maintainer": "Off the Boats maintainers",
+  "contributes": {
+    "routes": ["provisioning"],
+    "migrations": true
+  },
+  "provides": ["provisioning.instanceState"],
+  "consumes": []
+}

package/modules/provisioning/onboard-plan.js

@@ -0,0 +1,37 @@
+// modules/provisioning/onboard-plan.js — the CANONICAL onboarding step sequence.
+//
+// Goal 35 / criterion 165 names the sequence as the source of truth: "The canonical
+// step sequence is the source of truth; skill/CLI/hall are forms over it." This file
+// is that ONE source. The CLI (`bongos onboard`, scripts/gds/onboard.js), the branded
+// /create landing page, and the hall's new-project wizard all read it — via a direct
+// require (the CLI) or the public GET /provisioning/onboard-plan route (the web) — so
+// the sequence can never drift between the forms (task 2085, anti-drift).
+//
+// PURE — no I/O, no core imports. Safe to require from a script, a route, or a test.
+//
+// Each step: { key, kind: 'auto' | 'human', label }. `kind: 'human'` marks the
+// irreducibly-manual owner actions (create the GitHub repo, wire GitHub sign-in, first
+// sign-in) that every form renders UI-first; `kind: 'auto'` steps the flow performs.
+// The sequence branches at exactly ONE leg — scaffold — into greenfield (`bongos init`,
+// a fresh empty repo) vs brownfield (`bongos init --adopt`, LAYER onto an existing repo;
+// ADR 0121 §Decision 1 / task 2046). Every other leg is identical, so `mode` only
+// relabels the github-repo / init / scaffold steps.
+function onboardPlan(mode = 'greenfield') {
+  const adopt = mode === 'adopt';
+  return [
+    { key: 'name-address', kind: 'auto', label: 'Decide name + address (interview)' },
+    { key: 'github-repo', kind: 'human', label: adopt ? 'Use your EXISTING GitHub repository' : 'Create the empty GitHub repository' },
+    { key: 'dns-preflight', kind: 'auto', label: 'DNS token preflight — before the address step (task 1980)' },
+    { key: 'init', kind: 'auto', label: adopt ? 'bongos init --adopt — LAYER onto the existing repo (pre-flight + accept)' : 'bongos init — scaffold the instance config' },
+    { key: 'scaffold', kind: 'auto', label: adopt ? 'Layer config + pinned @bongos/core onto the existing repo (no clobber)' : 'Scaffold the standalone repo (own repo + pinned @bongos/core)' },
+    { key: 'provision', kind: 'auto', label: 'Provision core + DB + address + service (standalone, task 1978)' },
+    { key: 'seed-version', kind: 'auto', label: 'Seed the first version (V1) so the instance can take tasks immediately (task 2119)' },
+    { key: 'oauth-app', kind: 'human', label: 'Wire GitHub sign-in — one-click GitHub App (task 2080), or a manual OAuth app' },
+    { key: 'oauth-place', kind: 'auto', label: 'Place the OAuth secret — auto via the Manifest flow, or verified manual (task 1979)' },
+    { key: 'first-sign-in', kind: 'human', label: 'First sign-in (seats the founding Archon)' },
+    { key: 'verify', kind: 'auto', label: 'Verify /healthz auth_configured' },
+    { key: 'brand', kind: 'auto', label: 'Brand the instance look' },
+  ];
+}
+
+module.exports = { onboardPlan };