@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/rename-ledger-prose.js

@@ -0,0 +1,482 @@
+#!/usr/bin/env node
+'use strict';
+// rename-ledger-prose.js — criterion C4 of goal 1000073, "the live ledger reads
+// Bongos" (task 1003698).
+//
+// WHAT IS LEFT TO RENAME, AND WHY IT IS THE LEDGER. The code and the API were
+// renamed long ago (src/gds/ is src/bongos/, /api/bongos is canonical). What
+// still says the old name to a live reader is the PROSE INSIDE DB ROWS — goal
+// and task titles and descriptions, read every day in the hall and by every
+// agent that claims work.
+//
+// THE ONE RULE, inherited from the goal: rename what the project says about
+// itself GOING FORWARD; leave what it recorded about its PAST. Its enforcement
+// is its sibling scripts/gds/rename-history-check.js (criterion C5), which
+// fails the build if the frozen record is erased. This script is the other
+// direction, and it is deliberately narrow about what it will touch.
+//
+// THREE KINDS OF OCCURRENCE, and only ONE of them is this script's business.
+// Measured over all 3,369 task rows on 2026-09-07 — the goal's own estimate of
+// ~119 rows was taken before this split was understood and is low by ~2.4x:
+//
+//   1. FROZEN ARCHIVES (157 rows). Anything whose version_id is GDS-V3 or
+//      GDS-V4. Those versions shipped; their rows are the record. Skipped by
+//      version, not by heuristic.
+//
+//   2. IDENTIFIERS (77 rows carry nothing else). `GDS_TOKEN`, `GDS_API_BASE`,
+//      `GDS_BRANDING_FILE`, `MEDUSA_GDS_ONLY`, the `gds_session` cookie, the
+//      `scripts/gds/` path, and `/api/gds`. These are NOT vocabulary — they are
+//      the true names of things that still exist under those names. Renaming
+//      the prose would make the ledger LIE about what the code does. The env
+//      names and paths belong to criterion C3, which renames the THING and the
+//      prose together, behind a fallback release; `/api/gds` is a permanent
+//      alias and is never renamed at all. So every one of these is masked out
+//      before substitution and restored afterwards, byte for byte.
+//
+//   3. VOCABULARY — the acronym used as a word: "the GDS", "GDS tasks",
+//      "GDS-internal", "the GDS DB". This, and only this, is what C4 rewrites.
+//
+// WHY A REVIEWED PROPOSAL AND NOT A FIND-REPLACE. "the GDS exists to support
+// builders" must become "Bongos exists to support builders" — the article has
+// to go — while "the GDS database" keeps it. No regex settles that reliably, so
+// the rules below handle the shapes that recur and EXEMPT_ROWS/OVERRIDES carry
+// the ones a rule would get wrong. The default mode prints every proposed diff
+// and changes nothing; --apply is a separate, deliberate act.
+//
+// WRITES GO THROUGH THE API, NOT SQL. The builder box holds no DATABASE_URL and
+// no psql by design, and PATCH /tasks/:id and PATCH /goals/:id are permission-
+// checked and land every edit in audit_log. That is a better audit trail than
+// hand-run SQL, which was the shape this task was originally filed with.
+//
+// Usage:
+//   node scripts/gds/rename-ledger-prose.js              # dry run: every proposed diff
+//   node scripts/gds/rename-ledger-prose.js --summary    # counts only
+//   node scripts/gds/rename-ledger-prose.js --json
+//   node scripts/gds/rename-ledger-prose.js --apply      # write, one PATCH per row
+
+const { execFileSync } = require('node:child_process');
+const path = require('node:path');
+
+// ONE detector, shared with the C2 ratchet. GDS_VERSION_ID_RE is the rule that
+// says a version id is a row key rather than vocabulary; PINNED_VERSION_IDS in
+// rename-history-check.js is the list those keys are pinned to. Importing both
+// is what stops this pass and the two gates around it from disagreeing about
+// what counts as history — a second, divergent copy is the failure the task
+// named explicitly.
+const { GDS_VERSION_ID_RE } = require('./gds-literal-scan.js');
+const { PINNED_VERSION_IDS } = require('./rename-history-check.js');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+
+// Versions whose rows ARE the record. Not a heuristic — a list.
+// Derived from the C5 pin, not re-typed. If a version id is ever added to the
+// frozen record, it becomes frozen HERE in the same commit rather than a
+// release later.
+const FROZEN_VERSION_IDS = new Set(PINNED_VERSION_IDS);
+
+// Rows that STATE the rule, and so must keep naming what they retire. The
+// ledger's analogue of GDS_RULE_FILES in gds-literal-scan.js: a goal that says
+// "finish the GDS→Bongos rename" cannot be rewritten to say "finish the
+// Bongos→Bongos rename" without becoming nonsense.
+const EXEMPT_ROWS = new Set([
+  'goal:1000073',   // Finish the GDS→Bongos rename — this goal
+  'goal:1000010',   // "GDS core modularization (Config B)" — a shipped goal's own title
+  'task:1001933',   // Part B2: rename internal gds→bongos names
+  'task:1003698',   // this task
+]);
+
+// ---------- the identifier mask ----------
+
+// Longest / most specific first: GDS_API_BASE must be consumed before a bare
+// GDS could match inside it. Each is a REAL NAME that still exists, so it is
+// removed from the text before substitution and put back byte-for-byte after.
+const IDENTIFIER_PATTERNS = [
+  // IMPORTED, not re-declared. The version-id rule is the one exclusion this
+  // script genuinely shares with the C2 ratchet, and two copies of it would
+  // drift the moment either side learned about a new version id. The ratchet's
+  // other exclusions are PATH-based (docs/adr, migrations) and have no meaning
+  // for a database row, so they are deliberately not pulled in here.
+  GDS_VERSION_ID_RE,
+  /\/api\/gds\b/gi,               // the permanent alias (src/bongos/api-prefix.js)
+  /\bMEDUSA_GDS_[A-Z0-9_]+/g,
+  /\bGDS_[A-Z0-9_]+/g,            // env names — criterion C3, with a fallback release
+  /\bOTB_GDS_[A-Z0-9_]+/g,
+  /\bgds_session\b/gi,            // cookie name — C3
+  /\bgds-session(?:\.json)?\b/gi, // the CLI session file — C3
+  /\bscripts\/gds\b/gi,           // paths — C3
+  /\bsrc\/gds\b/gi,
+  /\bapi\/gds\b/gi,
+];
+
+const SENTINEL = '
MASK';
+
+// maskIdentifiers — replace every real name with an opaque token, returning the
+// masked text plus the list needed to restore it. Exported so the test can
+// assert the round trip is lossless: an identifier that came back changed would
+// be a silent corruption of the ledger, not a visible failure.
+function maskIdentifiers(text) {
+  const masks = [];
+  let out = text;
+  for (const re of IDENTIFIER_PATTERNS) {
+    out = out.replace(re, (m) => {
+      masks.push(m);
+      return `${SENTINEL}${masks.length - 1}`;
+    });
+  }
+  return { masked: out, masks };
+}
+
+function unmask(masked, masks) {
+  return masked.replace(/
MASK(\d+)/g, (_, i) => masks[Number(i)]);
+}
+
+// ---------- mention vs use ----------
+
+// THE FAILURE THIS PREVENTS, found by reading all 147 proposed diffs before
+// applying any of them. Some rows do not USE the acronym as a name, they MENTION
+// it as a token — and renaming a mention destroys the sentence:
+//
+//   "GDS is a legacy term inherited from Primea"  → "Bongos is a legacy term…"  (now false)
+//   "the primer still says GDS (should be Bongos)" → "…says Bongos (should be Bongos)"
+//   "fails the build on a NEW literal `GDS`"       → the gate's own rule, erased
+//   "records the bongos-as-GDS-successor intent"   → nonsense
+//   "Nightly pg_dump of Cloud Bongos GDS Postgres" → "Cloud Bongos Bongos Postgres"
+//
+// This is the same principle as GDS_RULE_FILES in gds-literal-scan.js, applied
+// to rows instead of files: text that STATES the rule has to be able to name
+// what it retires. The bias is deliberate — a match SKIPS the row and reports
+// it for a human, so the cost of a false positive is a row left alone and
+// listed, never a corrupted one. Acceptance criterion 4 of the task asks for
+// exactly that list.
+const MENTION_MARKERS = [
+  /["'`«]\s*GDS\s*["'`»]/,          // quoted or backticked: the token itself
+  /\bliteral\s+`?GDS/i,
+  /\bcalled\s+GDS\b/i,
+  /\bsays?\s+GDS\b/i,
+  /\bnamed?\s+GDS\b/i,
+  /\bterm\b[^.\n]{0,40}GDS/i,
+  /GDS[^.\n]{0,40}\blegacy\b/i,
+  /\blegacy\b[^.\n]{0,40}GDS/i,
+  /GDS\s*(?:→|->|to)\s*Bongos/i,     // the rename, written out
+  /(?:PMS|Medusa)\s*(?:→|->)\s*GDS/i, // the PREVIOUS rename, which is history
+  /GDS-successor/i,
+  /\brename\b[^.\n]{0,60}GDS|GDS[^.\n]{0,60}\brename\b/i,
+];
+
+// mentionsRatherThanUses — true when the row is talking ABOUT the word.
+function mentionsRatherThanUses(text) {
+  return MENTION_MARKERS.some((re) => re.test(text));
+}
+
+// ---------- the vocabulary rules ----------
+
+// THE ARTICLE PROBLEM, and why the default is to KEEP it.
+//
+// "the GDS router" must become "the Bongos router" — the acronym is modifying a
+// noun. "the GDS knows everything" must become "Bongos knows everything" — the
+// acronym IS the subject and the article has to go. Get it backwards in the
+// first case and you write "mounted outside Bongos router", which is broken
+// English; get it backwards in the second and you write "the Bongos knows
+// everything", which merely reads oddly.
+//
+// So the asymmetry decides the default: KEEP the article unless the very next
+// word is a finite verb. Dropping wrongly breaks a sentence; keeping wrongly
+// never does. The verb list is taken from the 41 distinct "<determiner> GDS
+// <word>" shapes actually present in the corpus, not invented.
+const ARTICLE_DROP_VERBS = [
+  'is', 'are', 'was', 'were', 'has', 'have', 'holds', 'knows', 'pushes', 'pulls',
+  'exists', 'builds', 'says', 'records', 'enforces', 'sits', 'lives', 'treats',
+  'expects', 'refuses', 'returns', 'becomes', 'remains', 'auto-posts',
+];
+// The same reasoning covers what follows a bare mention: a preposition, a
+// conjunction or an opening bracket all mean the acronym was the noun itself
+// ("poll the GDS for the next task", "its home is the GDS (goal + task rows)").
+const ARTICLE_DROP_FOLLOWERS = ['for', 'by', 'and', 'or', 'today', 'then', 'itself'];
+const ARTICLE_DROP_RE = new RegExp(
+  `\\b[Tt]he\\s+GDS\\b(?=\\s+(?:${ARTICLE_DROP_VERBS.join('|')}|${ARTICLE_DROP_FOLLOWERS.join('|')})\\b|\\s*[(,.;:])`,
+  'g',
+);
+
+// rewriteVocabulary — the substitution, on ALREADY-MASKED text. Pure, and
+// exported so every rule has a test that names its own input.
+function rewriteVocabulary(masked) {
+  let s = masked;
+  // 0. the product name already carries the word — "Cloud Bongos GDS Postgres"
+  //    must not become "Cloud Bongos Bongos Postgres".
+  s = s.replace(/\bCloud Bongos GDS\b/g, 'Cloud Bongos');
+  // 1. "the GDS <verb>" — the acronym is the subject, so the article goes with
+  //    the rename rather than being left stranded in front of it.
+  s = s.replace(ARTICLE_DROP_RE, 'Bongos');
+  // 2. everything else: the acronym as a name or a modifier. Any determiner in
+  //    front of it is left exactly where it was ("the Bongos router").
+  s = s.replace(/\bGDS\b/g, 'Bongos');
+  return s;
+}
+
+// rewrite — the whole pipeline for one string: mask the real names, rename the
+// vocabulary, restore the real names. Returns null when nothing changed.
+function rewrite(text) {
+  if (!text || !text.includes('GDS')) return null;
+  const { masked, masks } = maskIdentifiers(text);
+  if (!masked.includes('GDS')) return null; // identifiers only — not this script's business
+  const out = unmask(rewriteVocabulary(masked), masks);
+  return out === text ? null : out;
+}
+
+// ---------- row selection ----------
+
+// EDITABLE tells each kind which prose columns the API will accept, so the
+// script cannot propose an edit the route would reject.
+const EDITABLE = {
+  task: ['title', 'description'],
+  goal: ['title', 'subtitle', 'description'],
+};
+
+// proposeForRow — the pure half of selection: given one row, what would change.
+function proposeForRow(kind, row) {
+  const key = `${kind}:${row.id}`;
+  if (EXEMPT_ROWS.has(key)) return { skipped: 'exempt', kind, id: String(row.id), key, title: row.title };
+  if (FROZEN_VERSION_IDS.has(row.version_id)) return null; // frozen archive — silent, it is the whole point
+
+  const whole = EDITABLE[kind].map((c) => row[c] || '').join('\n');
+  if (!whole.includes('GDS')) return null;
+
+  const patch = {};
+  for (const col of EDITABLE[kind]) {
+    const next = rewrite(row[col]);
+    if (next !== null) patch[col] = next;
+  }
+  if (!Object.keys(patch).length) return null; // identifiers only
+
+  // Both checks below run AFTER the patch is computed, so a row is only
+  // reported as needing a human when it would OTHERWISE have been rewritten.
+  // Order matters for honesty: testing the raw text first would flag rows whose
+  // only occurrences are protected identifiers, i.e. rows with nothing wrong.
+  if (mentionsRatherThanUses(whole)) {
+    return { skipped: 'mentions-the-word', kind, id: String(row.id), key, title: row.title };
+  }
+
+  // A goal that is no longer open is a completed record, and the server says so
+  // itself: PATCH /goals/:id answers 409 goal_not_open on anything but `open`.
+  // That rule and this goal's rule are the same rule — "leave what it recorded
+  // about its past" — so this is not an obstacle to be worked around by
+  // reopening the goal. Reported rather than skipped silently: those rows do
+  // still read the old way, and a human should know which ones.
+  if (kind === 'goal' && row.status && row.status !== 'open') {
+    return { skipped: `goal-${row.status}`, kind, id: String(row.id), key, title: row.title };
+  }
+  return { kind, id: String(row.id), key, title: row.title, patch, before: row };
+}
+
+// ---------- the API (collectors; kept out of the pure half) ----------
+
+function api(method, urlPath, body) {
+  const args = [path.join(ROOT, 'scripts', 'gds', 'api.js'), method, urlPath];
+  const opts = { cwd: ROOT, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 };
+  if (body !== undefined) {
+    args.push('--body-file', '-');
+    opts.input = JSON.stringify(body);
+  }
+  const out = execFileSync('node', args, opts);
+  const brace = out.indexOf('{');
+  return brace === -1 ? {} : JSON.parse(out.slice(brace));
+}
+
+// The list route caps at 1000 and orders oldest-first, so the newest rows are
+// on the LAST page. Paging is not optional here: stopping at one page would
+// silently skip everything filed recently, which is exactly the class of bug
+// filed as task 1003699 against sequence.js.
+function allTasks() {
+  const rows = [];
+  let offset = 0;
+  for (;;) {
+    const q = offset ? `/api/gds/tasks?limit=1000&offset=${offset}` : '/api/gds/tasks?limit=1000';
+    const page = api('GET', q).tasks || [];
+    rows.push(...page);
+    if (page.length < 1000) break;
+    offset += 1000;
+  }
+  return rows;
+}
+
+function allGoals() {
+  const out = [];
+  for (const version of ['BONGOS-V1', 'CB-V1']) {
+    const r = api('GET', `/api/gds/goals?version=${version}`);
+    for (const g of r.goals || []) out.push(g);
+  }
+  return out;
+}
+
+function collectProposals() {
+  const proposals = [];
+  const skipped = [];
+  const take = (p) => {
+    if (!p) return;
+    (p.skipped ? skipped : proposals).push(p);
+  };
+  for (const t of allTasks()) take(proposeForRow('task', t));
+  for (const g of allGoals()) take(proposeForRow('goal', g));
+  return { proposals, skipped };
+}
+
+// ---------- write pacing ----------
+
+// The server allows 30 writes per minute per IP (PER_IP_LIMIT in
+// src/bongos/middleware/rate-limit.js). Learned the expensive way: the first
+// --apply of this script fired 123 PATCHes flat out, landed the first ~60, and
+// took a 429 for every one after that — leaving the ledger half-renamed, which
+// is the one outcome worse than not starting. Pace under the limit and retry
+// what still bounces, so a run either finishes or says exactly what it missed.
+const WRITES_PER_MIN = 25;                                    // under 30, with headroom for the reads
+const WRITE_SPACING_MS = Math.ceil(60000 / WRITES_PER_MIN);
+const MAX_RETRIES = 4;
+
+// A synchronous sleep, because the whole script is execFileSync-shaped and one
+// async conversion would buy nothing here.
+function sleep(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+// patchWithRetry — one write, retried on 429 with a widening backoff. Any other
+// error is returned immediately: a validation failure will not fix itself, and
+// retrying it just burns the rate budget the remaining rows need.
+function patchWithRetry(url, body) {
+  let wait = WRITE_SPACING_MS * 2;
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt += 1) {
+    try {
+      api('PATCH', url, body);
+      return { ok: true };
+    } catch (e) {
+      // api.js prints the status line to STDOUT and exits non-zero, so the
+      // 429 is in e.stdout, not in e.message. Reading only the message would
+      // silently turn every rate-limit into a permanent failure.
+      const message = `${e.message || ''}\n${e.stdout || ''}\n${e.stderr || ''}`;
+      if (!message.includes('429') || attempt === MAX_RETRIES) {
+        return { ok: false, message: message.slice(0, 300) };
+      }
+      console.log(`      rate-limited, waiting ${Math.round(wait / 1000)}s`);
+      sleep(wait);
+      wait *= 2;
+    }
+  }
+  return { ok: false, message: 'unreachable' };
+}
+
+// ---------- reporting ----------
+
+// changedLines — only the lines that actually differ, so a 4,000-character task
+// description does not drown the one line under review.
+function changedLines(before, after) {
+  const b = String(before).split('\n');
+  const a = String(after).split('\n');
+  const out = [];
+  for (let i = 0; i < Math.max(b.length, a.length); i += 1) {
+    if (b[i] !== a[i]) out.push({ before: b[i], after: a[i] });
+  }
+  return out;
+}
+
+function printProposals(proposals) {
+  for (const p of proposals) {
+    console.log(`\n${p.kind} ${p.id} — ${String(p.title).slice(0, 76)}`);
+    for (const [col, next] of Object.entries(p.patch)) {
+      for (const line of changedLines(p.before[col], next)) {
+        console.log(`  ${col}`);
+        console.log(`    - ${String(line.before).trim().slice(0, 200)}`);
+        console.log(`    + ${String(line.after).trim().slice(0, 200)}`);
+      }
+    }
+  }
+}
+
+function summarize(proposals) {
+  const byKind = {};
+  let edits = 0;
+  for (const p of proposals) {
+    byKind[p.kind] = (byKind[p.kind] || 0) + 1;
+    edits += Object.keys(p.patch).length;
+  }
+  return { rows: proposals.length, edits, byKind };
+}
+
+// ---------- CLI ----------
+
+function printSkipped(skipped) {
+  if (!skipped.length) return;
+  console.log(`\nLEFT FOR A HUMAN — ${skipped.length} row(s) that would have been rewritten wrongly:`);
+  for (const s of skipped) {
+    console.log(`  ${s.key}  [${s.skipped}]  ${String(s.title).slice(0, 76)}`);
+  }
+  console.log('\n  mentions-the-word — the row talks ABOUT the acronym; renaming it breaks the sentence.');
+  console.log('  exempt            — the row states the rename rule and must keep naming what it retires.');
+  console.log('  goal-achieved/archived — a closed goal is a completed record; the server refuses the edit');
+  console.log('                      (409 goal_not_open), which is the same rule this goal is built on.');
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const { proposals, skipped } = collectProposals();
+  const stats = summarize(proposals);
+
+  if (argv.includes('--json')) {
+    process.stdout.write(`${JSON.stringify({
+      stats,
+      proposals: proposals.map((p) => ({ kind: p.kind, id: p.id, patch: p.patch })),
+      skipped: skipped.map((s) => ({ key: s.key, reason: s.skipped, title: s.title })),
+    }, null, 2)}\n`);
+    return;
+  }
+
+  if (!argv.includes('--apply')) {
+    if (!argv.includes('--summary')) printProposals(proposals);
+    printSkipped(skipped);
+    console.log(`\ndry run — nothing written.`);
+    console.log(`  ${stats.rows} row(s), ${stats.edits} column edit(s): ${JSON.stringify(stats.byKind)}`);
+    console.log(`  ${skipped.length} row(s) left for a human`);
+    console.log(`  frozen versions skipped entirely: ${[...FROZEN_VERSION_IDS].join(', ')}`);
+    console.log('\n  apply with: node scripts/gds/rename-ledger-prose.js --apply');
+    return;
+  }
+
+  console.log(`applying ${proposals.length} row(s) at ${WRITES_PER_MIN}/min — about ${Math.ceil(proposals.length / WRITES_PER_MIN)} minute(s).`);
+  let ok = 0;
+  const failed = [];
+  for (const [i, p] of proposals.entries()) {
+    const url = p.kind === 'task' ? `/api/gds/tasks/${p.id}` : `/api/gds/goals/${p.id}`;
+    if (i) sleep(WRITE_SPACING_MS);
+    const r = patchWithRetry(url, p.patch);
+    if (r.ok) {
+      ok += 1;
+      console.log(`  ok  ${String(i + 1).padStart(3)}/${proposals.length}  ${p.kind} ${p.id}`);
+    } else {
+      failed.push({ key: p.key, message: r.message });
+      console.log(`  FAIL      ${p.kind} ${p.id}`);
+    }
+  }
+  console.log(`\napplied ${ok}/${proposals.length} row(s).`);
+  if (failed.length) {
+    console.log('failed:');
+    for (const f of failed) console.log(`  ${f.key}: ${f.message}`);
+    process.exitCode = 1;
+  }
+  console.log('re-run without --apply to confirm 0 remaining (the idempotency check).');
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  FROZEN_VERSION_IDS,
+  EXEMPT_ROWS,
+  IDENTIFIER_PATTERNS,
+  EDITABLE,
+  MENTION_MARKERS,
+  mentionsRatherThanUses,
+  maskIdentifiers,
+  unmask,
+  rewriteVocabulary,
+  rewrite,
+  proposeForRow,
+  changedLines,
+  summarize,
+};

package/scripts/bongos/render-api.js

@@ -0,0 +1,197 @@
+// scripts/bongos/render-api.js — a thin Render API v1 client for the control plane, with
+// the workspace (ownerId) guard (task 1004183; ADR 0327).
+//
+// Control-plane code, like its model scripts/bongos/do-api.js: only the provisioning runner
+// uses it, never the web tier (ADR 0111 §2). Same skeleton (JsonHttpApi): injectable
+// transport, dry-run by default, and live mode refuses to start without a token.
+//
+// THE GUARD. A Render API key belongs to a USER, not a workspace, and carries that user's
+// rights in every workspace they belong to — measured 2026-09-22: one owner's key reached
+// three workspaces, one of them another builder's, holding live production services. So:
+//
+//   - the client is built for ONE workspace (`ownerId`) and refuses to exist without it —
+//     never defaulted, and never derived by taking the first of GET /owners;
+//   - every call that names an owner sends this one;
+//   - every response that carries an owner is ASSERTED to carry this one, and a missing
+//     or different owner is a hard error (RenderOwnerMismatch). Assert on the response,
+//     not the request: a request you got right says nothing about a response that came
+//     from somewhere else. A list is checked element by element.
+//
+// Render's own shapes decide where the owner sits: a service carries `ownerId`, a
+// Postgres carries `owner.id` (both measured by the pilot, task 1004142). A few calls
+// answer with no owner at all (a database's connection-info, an env-var PUT, a deploy
+// trigger). Those are only reachable through a method that first reads the parent
+// resource through the guard, so nothing is ever sent to or read from a resource whose
+// workspace was not checked.
+//
+// NO DELETE. The platform must not hold the ability to destroy infrastructure in an
+// account it does not own (ADR 0327 §3). There is no delete method, and _req refuses the
+// verb outright, so adding one later is a visible change to this file, not a one-liner.
+
+'use strict';
+
+const { JsonHttpApi, makeApiError } = require('./http-api-client');
+
+const RENDER_API_BASE = 'https://api.render.com/v1';
+
+const RenderApiError = makeApiError('RenderApiError', 'RENDER_API_ERROR');
+const RenderOwnerMismatch = makeApiError('RenderOwnerMismatch', 'RENDER_OWNER_MISMATCH');
+
+// The owner id a Render resource carries, in either of the two shapes Render uses.
+// null when it carries none.
+function ownerOf(resource) {
+  if (!resource || typeof resource !== 'object') return null;
+  if (typeof resource.ownerId === 'string' && resource.ownerId) return resource.ownerId;
+  if (resource.owner && typeof resource.owner.id === 'string' && resource.owner.id) return resource.owner.id;
+  return null;
+}
+
+// Env var values are the owner's secrets on their way to Render. A dry-run log is the one
+// place this client would otherwise print a request body, so it prints the names only.
+function redact(body) {
+  if (!body || typeof body !== 'object') return body;
+  const out = { ...body };
+  if (Array.isArray(out.envVars)) out.envVars = out.envVars.map((v) => ({ key: v && v.key, value: '[redacted]' }));
+  if ('value' in out) out.value = '[redacted]';
+  return out;
+}
+
+class RenderApi extends JsonHttpApi {
+  // opts: { token, ownerId, dryRun=true, fetchImpl=globalThis.fetch, base, log }
+  constructor(opts = {}) {
+    super(opts, { base: RENDER_API_BASE, logTag: 'Render', ErrorClass: RenderApiError });
+    if (typeof opts.ownerId !== 'string' || !opts.ownerId.trim()) {
+      throw new RenderApiError('a Render client needs the workspace it acts in (ownerId) — it is never defaulted');
+    }
+    this.ownerId = opts.ownerId.trim();
+    if (!this.dryRun && !this.token) {
+      throw new RenderApiError('live Render call requested with no API key');
+    }
+    if (!this.dryRun && typeof this.fetchImpl !== 'function') {
+      throw new RenderApiError('no fetch implementation available for live mode');
+    }
+  }
+
+  async _req(method, path, body, opts = {}) {
+    if (method === 'DELETE') throw new RenderApiError(`refusing ${method} ${path}: the platform never deletes in an account it does not own (ADR 0327 §3)`);
+    if (this.dryRun) {
+      this.log(`[dry-run] Render ${method} ${path}${body ? ' ' + JSON.stringify(redact(body)) : ''}`);
+      return { dryRun: true, ...(opts.dryRunResult || {}) };
+    }
+    return super._req(method, path, body, opts);
+  }
+
+  // Throws unless `resource` carries exactly this client's workspace.
+  assertOwned(resource, what) {
+    const got = ownerOf(resource);
+    if (got !== this.ownerId) {
+      throw new RenderOwnerMismatch(
+        got
+          ? `Render answered ${what} from workspace ${got}, not ${this.ownerId} — refusing to go on`
+          : `Render answered ${what} with no workspace on it — refusing to go on`,
+        { body: null });
+    }
+    return resource;
+  }
+
+  // ---- workspaces ------------------------------------------------------------
+
+  // The workspaces the key can reach, as [{ id, name, type }]. Used for MEMBERSHIP only —
+  // "is the workspace the owner named one this key can act in" — never to pick one.
+  async listOwners() {
+    const json = await this._req('GET', '/owners?limit=100', null, {
+      dryRunResult: { items: [{ owner: { id: this.ownerId, name: '(dry-run)', type: 'team' } }] },
+    });
+    const items = Array.isArray(json) ? json : (json && json.items) || [];
+    return items.map((e) => (e && e.owner) || e).filter((o) => o && typeof o.id === 'string');
+  }
+
+  // ---- services --------------------------------------------------------------
+
+  async getService(serviceId) {
+    const json = await this._req('GET', `/services/${encodeURIComponent(serviceId)}`, null, {
+      dryRunResult: { id: serviceId, ownerId: this.ownerId, serviceDetails: { url: null } },
+    });
+    return this.assertOwned(json && json.service ? json.service : json, `service ${serviceId}`);
+  }
+
+  // payload: the POST /services body (render-payload.js). Its ownerId must be ours — the
+  // payload builder takes it as an argument, so this is checked, not overwritten.
+  async createService(payload) {
+    if (!payload || payload.ownerId !== this.ownerId) throw new RenderApiError('a service payload must name this client\'s workspace');
+    const json = await this._req('POST', '/services', payload, {
+      dryRunResult: { deployId: null, service: { id: `dryrun-srv-${payload.name}`, ownerId: this.ownerId, serviceDetails: { url: null } } },
+    });
+    return { deployId: (json && json.deployId) || null, service: this.assertOwned(json && json.service, 'the new service') };
+  }
+
+  // Set one env var on a service this workspace owns. The PUT answers with no owner, so
+  // the service is read through the guard first.
+  async putEnvVar(serviceId, key, value) {
+    await this.getService(serviceId);
+    return this._req('PUT', `/services/${encodeURIComponent(serviceId)}/env-vars/${encodeURIComponent(key)}`, { value }, { dryRunResult: { key } });
+  }
+
+  async triggerDeploy(serviceId) {
+    await this.getService(serviceId);
+    return this._req('POST', `/services/${encodeURIComponent(serviceId)}/deploys`, {}, { dryRunResult: { id: null } });
+  }
+
+  // A service's deploys, newest first, as the bare deploy objects (Render wraps each in
+  // `{ deploy, cursor }`; both shapes are read). The list carries no owner, so the
+  // service is read through the guard first (the deploy hall's history, task 1004270).
+  async listDeploys(serviceId, { limit = 30 } = {}) {
+    await this.getService(serviceId);
+    const n = Math.max(1, Math.min(100, Number.parseInt(limit, 10) || 30));
+    const json = await this._req('GET', `/services/${encodeURIComponent(serviceId)}/deploys?limit=${n}`, null, { dryRunResult: { items: [] } });
+    const items = Array.isArray(json) ? json : (json && json.items) || [];
+    return items.map((e) => (e && e.deploy) || e).filter((d) => d && typeof d.id === 'string');
+  }
+
+  // Roll the service back to one of its earlier deploys. The answer carries no owner, so
+  // the service is read through the guard first. This is a write on the owner's account;
+  // the caller (the deploy hall) asks the owner twice before it reaches here.
+  async rollbackTo(serviceId, deployId) {
+    await this.getService(serviceId);
+    return this._req('POST', `/services/${encodeURIComponent(serviceId)}/rollback`, { deployId }, { dryRunResult: { id: null } });
+  }
+
+  // ---- Postgres --------------------------------------------------------------
+
+  async createPostgres(payload) {
+    if (!payload || payload.ownerId !== this.ownerId) throw new RenderApiError('a Postgres payload must name this client\'s workspace');
+    const json = await this._req('POST', '/postgres', payload, {
+      dryRunResult: { id: `dryrun-pg-${payload.name}`, status: 'creating', owner: { id: this.ownerId } },
+    });
+    return this.assertOwned(json, 'the new database');
+  }
+
+  async getPostgres(postgresId) {
+    const json = await this._req('GET', `/postgres/${encodeURIComponent(postgresId)}`, null, {
+      dryRunResult: { id: postgresId, status: 'available', owner: { id: this.ownerId } },
+    });
+    return this.assertOwned(json, `database ${postgresId}`);
+  }
+
+  // The database's connection strings. The answer carries no owner, so the database is
+  // read through the guard first.
+  async postgresConnectionInfo(postgresId) {
+    await this.getPostgres(postgresId);
+    return this._req('GET', `/postgres/${encodeURIComponent(postgresId)}/connection-info`, null, {
+      dryRunResult: { internalConnectionString: 'postgres://dry-run' },
+    });
+  }
+
+  // Poll until a new database is 'available'. `sleepFn` lets tests drive it with no clock.
+  async settlePostgres(postgresId, { tries = 60, sleepMs = 5000, sleepFn } = {}) {
+    const sleep = sleepFn || ((ms) => new Promise((r) => setTimeout(r, ms)));
+    for (let i = 0; i < tries; i++) {
+      const pg = await this.getPostgres(postgresId);
+      if (pg.status === 'available') return pg;
+      await sleep(sleepMs);
+    }
+    throw new RenderApiError(`database ${postgresId} did not become available in time`);
+  }
+}
+
+module.exports = { RenderApi, RenderApiError, RenderOwnerMismatch, RENDER_API_BASE, ownerOf, redact };