@thebattlearena/corner 0.9.0 → 0.10.0

package/ring/scripts/judges-card.mjs

@@ -8,6 +8,28 @@
 //                              «sin equipo» (no-team) was marked
 //   node judges-card.mjs summary <pr>        everything a new session needs to resume
 //   node judges-card.mjs log <pr> decision|rebound <text>
+//   node judges-card.mjs log <pr> escalation <file> [--context <file>]
+//                                            right after sending an escalation to the judge: its
+//                                            text as sent, stamped (interview.jsonl, E<n>), and the
+//                                            context of each question («## Contexto <n> · …»)
+//   node judges-card.mjs log <pr> escalation-context E<n> <file>
+//                                            adds (or replaces) the context of a logged escalation
+//   node judges-card.mjs log <pr> answer [E<n>] <the judge's words>
+//                                            when the judge answers («1. a, 2. b»), stamped; to the
+//                                            last escalation unless E<n> names one; --attach
+//                                            <asset id,…> cites the judge's images
+//   node judges-card.mjs page-answers <pr> <file>
+//                                            the answers the judge saved from the chronicle page
+//                                            (ArtifactData listing of `respuestas`), each at its
+//                                            saved time; the ones already logged are skipped
+//   node judges-card.mjs plan <pr> <n|title> <state> [--ref <sha|round-bell>]
+//                                            a point of plan-tecnico.md changes state (pendiente ·
+//                                            espera al juez · en curso · hecho), stamped in plan.jsonl;
+//                                            `plan <pr> add "<group>" "<title>" …` and `plan <pr> list`
+//   node judges-card.mjs page-verdicts <pr> <file>
+//                                            the judge's verdicts on the endpoints (listing of
+//                                            `veredictos`): each «se mejora» becomes a contract
+//                                            finding; says when approve-contract can run
 //   node judges-card.mjs did <pr> <text>    a "What I did" line in the judges card, stamped by the clock
 //   node judges-card.mjs list                bouts of this repo
 //   node judges-card.mjs path <pr>
@@ -28,10 +50,12 @@
 // State lives in ~/.claude/ring/<owner>/<repo>/<pr>/ (RING_HOME overrides the root), never in the
 // session scratchpad: that one is wiped when the session restarts. state.json stays minimal (worktree, branch, base, lastReviewed,
 // active, venue); a state without venue is a backend bout, from before venues existed; round-bells are read from GitHub and the tip from git, so they never go stale here.
+import { boutFormatGate } from './format-gate.mjs';
 import { execFileSync } from 'node:child_process';
 import {
   appendFileSync,
   existsSync,
+  readdirSync,
   readFileSync,
   statSync,
   writeFileSync,
@@ -65,7 +89,23 @@ import {
   recordSparringChronicle,
 } from './fight.mjs';
 import { record } from './live.mjs';
+import {
+  answerTarget,
+  INTERVIEW,
+  interviewOf,
+  missingContext,
+  nextInterviewId,
+  parseEscalation,
+  pageAnswerDocs,
+  pageAnswerEntries,
+  parseContext,
+  parseInterview,
+  unloggedEscalationNotice,
+} from './preparation.mjs';
 import { handOffWarning, withChronicleUrl } from './sparring-chronicle.mjs';
+import { parsePlan, PLAN } from './tech-plan.mjs';
+import { addPlanItem, setPlanState } from './tech-plan-log.mjs';
+import { logPageVerdicts } from './verdicts-log.mjs';
 import { DEFAULT_VENUE } from './venues.mjs';
 
 export const TEMPLATES = join(RING_ROOT, 'skills', 'referee', 'templates');
@@ -234,6 +274,9 @@ function summary([pr]) {
       '## Open rebounds',
       openRebounds(read('rebounds.md')).join('\n') || '(none)',
       '',
+      '## Questions the judge has not answered (interview.jsonl)',
+      unansweredLines(dir).join('\n') || '(none)',
+      '',
       '## Decisions',
       read('decisions.md').trim(),
       '',
@@ -242,10 +285,278 @@ function summary([pr]) {
   );
 }
 
+/**
+ * The interview entry `log <pr> escalation|answer …` appends, stamped by the clock. An escalation
+ * is the text as sent to the judge (a file, or the words); an answer is the judge's own words, to
+ * the escalation named (`E<n>` first) or the last one. PURE apart from `read`.
+ */
+export function interviewEntry(entries, kind, words, { at, judge, read }) {
+  if (kind === 'escalation-context') {
+    const [to, path] = words;
+    if (!/^E\d+$/.test(to ?? '') || !path)
+      throw new Error('usage: log <pr> escalation-context E<n> <file>');
+    answerTarget(entries, to);
+    const escalation = entries.find(
+      (entry) => entry.kind === 'escalation' && entry.id === to,
+    );
+    const body = read(path);
+    const missing = missingContext(escalation.body, body);
+    if (missing.length)
+      throw new Error(
+        `the context has no «## Contexto <n> · <question>» section for question(s) ${missing.join(', ')}: one per question, numbered like the escalation`,
+      );
+    return { kind: 'context', to, at, body };
+  }
+  if (kind === 'escalation') {
+    const contextAt = words.indexOf('--context');
+    const context = contextAt === -1 ? null : read(words[contextAt + 1]);
+    const rest =
+      contextAt === -1
+        ? words
+        : [...words.slice(0, contextAt), ...words.slice(contextAt + 2)];
+    const body = rest.length > 1 ? rest.join(' ') : read(rest[0]);
+    if (!parseEscalation(body).length)
+      throw new Error(
+        'the escalation has no numbered question with options «(a) … · (b) …» (templates/escalation.md)',
+      );
+    const missing = context === null ? [] : missingContext(body, context);
+    if (missing.length)
+      throw new Error(
+        `the context has no «## Contexto <n> · <question>» section for question(s) ${missing.join(', ')}: one per question, numbered like the escalation`,
+      );
+    return {
+      kind,
+      id: nextInterviewId(entries, kind),
+      at,
+      body,
+      ...(context ? { context } : {}),
+    };
+  }
+  const attachAt = words.indexOf('--attach');
+  const attachments =
+    attachAt === -1
+      ? []
+      : String(words[attachAt + 1] ?? '')
+          .split(',')
+          .map((id) => id.trim())
+          .filter(Boolean);
+  const plain =
+    attachAt === -1
+      ? words
+      : [...words.slice(0, attachAt), ...words.slice(attachAt + 2)];
+  const named = /^E\d+$/.test(plain[0] ?? '') ? plain[0] : null;
+  const said = (named ? plain.slice(1) : plain).join(' ').trim();
+  if (!said)
+    throw new Error('usage: log <pr> answer [E<n>] <the judge’s words>');
+  return {
+    kind,
+    id: nextInterviewId(entries, kind),
+    to: answerTarget(entries, named),
+    at,
+    judge,
+    said,
+    ...(attachments.length ? { attachments } : {}),
+  };
+}
+
+/** The judge's name for an answer: RING_JUDGE, else the git user of the host checkout. */
+function judgeName() {
+  if (process.env.RING_JUDGE) return process.env.RING_JUDGE;
+  try {
+    return git(projectDir(), ['config', 'user.name']) || null;
+  } catch {
+    return null;
+  }
+}
+
+/** `- E1 (asked <time>): 2, 5` for each escalation with questions still unanswered. */
+function unansweredLines(dir) {
+  const file = join(dir, INTERVIEW);
+  const entries = parseInterview(
+    existsSync(file) ? readFileSync(file, 'utf8') : '',
+  );
+  const notice = unloggedEscalationNotice(
+    readFileSync(join(dir, 'judges-card.md'), 'utf8'),
+    entries,
+  );
+  if (notice) return [`- warning: ${notice}`];
+  return interviewOf(entries, '', null)
+    .escalations.filter((escalation) => escalation.unanswered.length)
+    .map(
+      (escalation) =>
+        `- ${escalation.id} (asked ${localStamp(new Date(escalation.at))}): ${escalation.unanswered.join(', ')}`,
+    );
+}
+
+function logInterview(pr, kind, words) {
+  const dir = currentDir(pr);
+  const file = join(dir, INTERVIEW);
+  const entries = parseInterview(
+    existsSync(file) ? readFileSync(file, 'utf8') : '',
+  );
+  const entry = interviewEntry(entries, kind, words, {
+    at: new Date().toISOString(),
+    judge: judgeName(),
+    read: (path) => {
+      if (!existsSync(path))
+        throw new Error(
+          `usage: log <pr> escalation <file with the escalation as sent> (no file ${path})`,
+        );
+      return readFileSync(path, 'utf8');
+    },
+  });
+  appendFileSync(file, `${JSON.stringify(entry)}\n`);
+  if (entry.kind === 'context')
+    return void console.log(
+      `context of ${entry.to} logged at ${localStamp(new Date(entry.at))} (questions ${Object.keys(parseContext(entry.body)).join(', ')})`,
+    );
+  record(dir, {
+    actor: kind === 'escalation' ? 'arbitro' : 'juez',
+    state: 'done',
+    label: kind === 'escalation' ? 'escaló al juez' : 'respondió',
+    detail:
+      kind === 'escalation'
+        ? `${entry.id} · ${parseEscalation(entry.body).length} pregunta(s)`
+        : `${entry.to} · ${entry.said}`,
+  });
+  console.log(`${entry.id} logged at ${localStamp(new Date(entry.at))}`);
+}
+
+/**
+ * An ArtifactData listing as given: a JSON file, or the directory `out_dir` wrote (every JSON file
+ * in it, at any depth).
+ */
+function readListing(path) {
+  if (!statSync(path).isDirectory())
+    return JSON.parse(readFileSync(path, 'utf8'));
+  const walk = (dir) =>
+    readdirSync(dir, { withFileTypes: true }).flatMap((entry) =>
+      entry.isDirectory()
+        ? walk(join(dir, entry.name))
+        : entry.name.endsWith('.json')
+          ? [JSON.parse(readFileSync(join(dir, entry.name), 'utf8'))]
+          : [],
+    );
+  return walk(path);
+}
+
+/**
+ * `page-answers <pr> <file>`: logs the answers the judge saved from the chronicle page (the
+ * ArtifactData listing of `respuestas`, saved to a file), each at the time the judge saved it; an
+ * answer already logged is skipped.
+ */
+function pageAnswers([pr, file]) {
+  if (!pr || !file || !existsSync(file))
+    throw new Error(
+      'usage: page-answers <pr> <file with the ArtifactData listing of respuestas>',
+    );
+  const dir = currentDir(pr);
+  const ledger = join(dir, INTERVIEW);
+  const entries = parseInterview(
+    existsSync(ledger) ? readFileSync(ledger, 'utf8') : '',
+  );
+  const docs = pageAnswerDocs(readListing(file));
+  const fresh = pageAnswerEntries(entries, docs, { pr, judge: judgeName() });
+  for (const entry of fresh) {
+    appendFileSync(ledger, `${JSON.stringify(entry)}\n`);
+    record(dir, {
+      actor: 'juez',
+      state: 'done',
+      label: 'respondió',
+      detail: `${entry.to} · ${entry.said}`,
+    });
+  }
+  console.log(
+    `${fresh.length} answer(s) logged from the page (${docs.length} saved there)${fresh.length ? `: ${fresh.map((entry) => `${entry.id} → ${entry.to}`).join(', ')}` : ''}`,
+  );
+}
+
+/**
+ * `page-verdicts <pr> <file>`: logs the judge's verdicts on the endpoints, saved from the chronicle
+ * page (the ArtifactData listing of `veredictos`, saved to a file), and says whether every
+ * operation is approved with its current fingerprint.
+ */
+function pageVerdicts([pr, file]) {
+  if (!pr || !file || !existsSync(file))
+    throw new Error(
+      'usage: page-verdicts <pr> <file with the ArtifactData listing of veredictos>',
+    );
+  const result = logPageVerdicts(currentDir(pr), pr, readListing(file));
+  console.log(
+    `${result.logged} verdict(s) logged, ${result.findings} «se mejora» registered as contract findings (${result.planned} new in the technical plan). ${result.report}`,
+  );
+}
+
+/**
+ * `plan <pr> <n|title> <state> [--ref <sha|round-bell>]`: a point of the technical plan changes
+ * state, stamped; `plan <pr> add "<group>" "<title>" [--detail <t>] [--origin <ids>] [--state <s>]`
+ * adds one; `plan <pr> list` prints it.
+ */
+function plan([pr, target, ...rest]) {
+  const dir = currentDir(pr);
+  const value = (flag) => {
+    const at = rest.indexOf(flag);
+    return at === -1 ? null : (rest[at + 1] ?? null);
+  };
+  if (target === 'list') {
+    const markdown = existsSync(join(dir, PLAN))
+      ? readFileSync(join(dir, PLAN), 'utf8')
+      : '';
+    return void console.log(
+      parsePlan(markdown)
+        .groups.flatMap((group) => [
+          `## ${group.name}`,
+          ...group.items.map(
+            (item) => `${item.n}. [${item.state}] ${item.title}`,
+          ),
+        ])
+        .join('\n') || `no ${PLAN} in ${dir}`,
+    );
+  }
+  if (target === 'add') {
+    const [group, title] = rest;
+    if (!group || !title)
+      throw new Error(
+        'usage: plan <pr> add "<group>" "<title>" [--detail <t>] [--origin <ids>] [--state <s>]',
+      );
+    const added = addPlanItem(dir, {
+      group,
+      title,
+      detail: value('--detail') ?? '',
+      origins: (value('--origin') ?? '')
+        .split(',')
+        .map((id) => id.trim())
+        .filter(Boolean),
+      state: value('--state') ?? 'pendiente',
+    });
+    return void console.log(
+      added
+        ? `added to «${group}»: ${title}`
+        : 'a point with that origin is already in the plan',
+    );
+  }
+  const [state] = rest;
+  if (!target || !state)
+    throw new Error(
+      'usage: plan <pr> <n|title> <pendiente|espera al juez|en curso|hecho> [--ref <sha|round-bell>] | add … | list',
+    );
+  const changed = setPlanState(dir, target, state, value('--ref'));
+  console.log(
+    `${changed.n}. ${changed.title}: ${changed.from} → ${changed.to} at ${localStamp(new Date())}`,
+  );
+}
+
 function log([pr, kind, ...words]) {
+  if (
+    ['escalation', 'escalation-context', 'answer'].includes(kind) &&
+    words.length
+  )
+    return logInterview(pr, kind, words);
   const files = { decision: 'decisions.md', rebound: 'rebounds.md' };
   if (!files[kind] || !words.length)
-    throw new Error('usage: log <pr> decision|rebound <text>');
+    throw new Error(
+      'usage: log <pr> decision|rebound <text> | escalation <file> | answer [E<n>] <the judge’s words>',
+    );
   const stamp = new Date().toISOString();
   const box = kind === 'rebound' ? '[ ] ' : '';
   const dir = currentDir(pr);
@@ -298,7 +609,14 @@ function close([pr]) {
   const dir = currentDir(pr);
   const blocked = auditBlocks(readLedger(dir), { closing: true });
   if (blocked) throw new Error(`bout #${pr} does not close yet: ${blocked}`);
-  writeState(dir, { ...readState(dir), active: false });
+  const state = readState(dir);
+  const tip = state.lastApproved ?? state.lastReviewed;
+  if (tip) {
+    const format = boutFormatGate(dir, state, tip);
+    if (format.refusal)
+      throw new Error(`bout #${pr} does not close yet: ${format.refusal}`);
+  }
+  writeState(dir, { ...state, active: false });
   console.log(`bout #${pr} closed; its files stay in ${dir} as the record.`);
 }
 
@@ -544,6 +862,9 @@ function playByPlayUrl([pr, url]) {
 const COMMANDS = {
   open,
   'play-by-play-url': playByPlayUrl,
+  'page-answers': pageAnswers,
+  'page-verdicts': pageVerdicts,
+  plan,
   'approve-contract': approveContract,
   'title-defense': titleDefense,
   summary,
@@ -559,7 +880,7 @@ if (isMain(import.meta.url)) {
   const run = COMMANDS[command];
   if (!run) {
     console.error(
-      'Usage: node judges-card.mjs open|summary|log|did|list|path|close|approve-contract|title-defense|play-by-play-url …',
+      'Usage: node judges-card.mjs open|summary|log|did|list|path|close|approve-contract|title-defense|play-by-play-url|page-answers|page-verdicts|plan …',
     );
     process.exit(1);
   }

package/ring/scripts/lookout.mjs

@@ -5,6 +5,8 @@
 //   node lookout.mjs mark <boutDir> <sha-or-ref>              record what the referee reviewed
 //                                                             (its findings registered first)
 //   node lookout.mjs approve <boutDir> <sha-or-ref>           record what the cornerman approved
+//        [--format-unverified "<why>"]                         (refused while the range is not
+//                                                             formatted; see format-gate.mjs)
 //   node lookout.mjs backup <boutDir>                         push the worktree HEAD to the backup branch
 //
 // `watch` polls the wrestler's worktree and EXITS as soon as its HEAD differs from the last
@@ -25,6 +27,7 @@ import {
   writeState,
 } from './config.mjs';
 import { counts, readLedger, reviewDeclared } from './findings.mjs';
+import { acceptUnverified, boutFormatGate } from './format-gate.mjs';
 
 const FULL_SHA = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
 
@@ -292,7 +295,8 @@ export function approvalRefusal(state, sha, ancestor) {
  * Records what the cornerman approved: the PR branch may receive up to it (mask-guard checks every
  * push to it). An approval is also a review, so lastReviewed moves forward with it.
  */
-function approve(dir, ref) {
+function approve(dir, ref, { formatUnverified = null } = {}) {
+  if (formatUnverified !== null) acceptUnverified(dir, formatUnverified);
   const state = readState(dir);
   const sha = resolveSha(state, ref);
   const refusal = approvalRefusal(state, sha, (a, b) =>
@@ -308,6 +312,17 @@ function approve(dir, ref) {
     isFullSha(state.lastReviewed) &&
     isAncestor(state.worktree, sha, state.lastReviewed);
   if (!covered) requireDeclared(dir, state, sha);
+  // Nothing is approved for the PR branch without the repo's format (sort-imports + prettier).
+  const format = boutFormatGate(dir, state, sha);
+  if (format.refusal)
+    throw Object.assign(
+      new Error(`${sha.slice(0, 9)} is not approved: ${format.refusal}`),
+      // Same codes as format-gate check: 2 when the format could not be verified, 1 otherwise.
+      {
+        exitCode:
+          format.result.unclean.length || format.result.verified ? 1 : 2,
+      },
+    );
   writeState(dir, {
     ...state,
     lastApproved: sha,
@@ -322,13 +337,16 @@ if (isMain(import.meta.url)) {
   const interval = intervalIndex === -1 ? 60 : Number(rest[intervalIndex + 1]);
   const fail = (error) => {
     console.error(`lookout: ${error.message}`);
-    process.exit(1);
+    process.exit(error.exitCode ?? 1);
   };
   if (command === 'watch' && dir) watch(dir, interval).catch(fail);
   const once = { mark, approve };
   if (once[command] && dir && rest[0]) {
     try {
-      once[command](dir, rest[0]);
+      const at = rest.indexOf('--format-unverified');
+      once[command](dir, rest[0], {
+        formatUnverified: at === -1 ? null : (rest[at + 1] ?? ''),
+      });
     } catch (error) {
       fail(error);
     }
@@ -351,7 +369,7 @@ if (isMain(import.meta.url)) {
     (once[command] && dir && rest[0]);
   if (!valid) {
     console.error(
-      'Usage: node lookout.mjs watch <boutDir> [--interval <seconds>]\n       node lookout.mjs mark|approve <boutDir> <sha-or-ref>\n       node lookout.mjs backup <boutDir>',
+      'Usage: node lookout.mjs watch <boutDir> [--interval <seconds>]\n       node lookout.mjs mark <boutDir> <sha-or-ref>\n       node lookout.mjs approve <boutDir> <sha-or-ref> [--format-unverified "<why>"]\n       node lookout.mjs backup <boutDir>',
     );
     process.exit(1);
   }

package/ring/scripts/mask-guard.mjs

@@ -10,6 +10,7 @@
 //
 // Exit 2 with the reason blocks the command. If the guard itself fails while a bout may be active,
 // it blocks too: a guard that cannot evaluate must not let the command through.
+import { boutFormatGate } from './format-gate.mjs';
 import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -735,7 +736,7 @@ const sparringGitRules = [
     always: true,
     when: (git, ctx) => git.sub === 'push' && pushesSparringOut(git, ctx),
     reason: () =>
-      "A sparring branch is pushed only to `sparring/*`. Its code leaves only through a KO: `node \"$RING/scripts/sparring.mjs\" promote <slug>`, which refuses unless the verdict is ko.",
+      'A sparring branch is pushed only to `sparring/*`. Its code leaves only through a KO: `node "$RING/scripts/sparring.mjs" promote <slug>`, which refuses unless the verdict is ko.',
   },
 ];
 
@@ -868,6 +869,18 @@ const gitRules = [
       return `The PR branch ${branch} only receives what the cornerman approved: ${source} is not inside the approved tip ${approved ?? '(none yet)'}. Get the cornerman's verdict on the range, record it with lookout.mjs approve <bout dir> <sha>, then push up to that sha. Unreviewed work goes to the backup branch (lookout.mjs backup).`;
     },
   },
+  {
+    // Second line behind lookout approve: what goes up to the PR branch has the repo's format.
+    when: (git, ctx) =>
+      git.sub === 'push' && ctx.formatBeforePush(git, pushRefspecs(git, ctx)),
+    reason: (git, ctx) => {
+      const { branch, reason } = ctx.formatBeforePush(
+        git,
+        pushRefspecs(git, ctx),
+      );
+      return `The PR branch ${branch} only receives formatted work: ${reason}`;
+    },
+  },
   {
     when: (git, ctx) =>
       git.sub === 'push' && ctx.findingsBeforePush(git, pushRefspecs(git, ctx)),
@@ -1268,6 +1281,8 @@ function judgeSegment(segment, words, cwd, ctx) {
       ctx.pushBeyondApprovalAt(context.path(push.dir), refspecs),
     findingsBeforePush: (push, refspecs) =>
       ctx.findingsBeforePushAt(context.path(push.dir), refspecs),
+    formatBeforePush: (push, refspecs) =>
+      ctx.formatBeforePushAt(context.path(push.dir), refspecs),
     isBackupBranch: (push, target) =>
       ctx
         .backupBranchesAt(context.path(push.dir))
@@ -1541,6 +1556,24 @@ function realContext(cwd) {
       }
       return null;
     },
+    // The first push to a bout's PR branch whose range is not formatted (or could not be
+    // verified without the referee's override), or null. A check that throws blocks (fail closed).
+    formatBeforePushAt: (dir, refspecs) => {
+      const slug = insideGitRepo(dirOf(dir)) ? slugOf(dirOf(dir)) : null;
+      if (!slug) return null;
+      for (const { source, target } of refspecs) {
+        const bout = boutsOf(slug).find(({ state }) => state.branch === target);
+        if (!bout || source === null) continue;
+        const sha = git(dirOf(dir), [
+          'rev-parse',
+          '--verify',
+          `${source}^{commit}`,
+        ]);
+        const { refusal } = boutFormatGate(bout.dir, bout.state, sha);
+        if (refusal) return { branch: target, reason: refusal };
+      }
+      return null;
+    },
     contractApprovals: (where) => {
       const slug = slugWhere(where);
       if (!slug) return {};

package/ring/scripts/page-embed.mjs

@@ -0,0 +1,112 @@
+// What `play-by-play.mjs embed` puts inside a written chronicle page, so the one Artifact page
+// carries it without a server or a local file: each bout's database diagram (an iframe whose
+// `srcdoc` is the diagram page, escaped whole, so its own `</body>` never shows up in the page),
+// each bout's «Endpoints del contrato» (contract-endpoints.mjs) and the page's scripts (the
+// interview form, the endpoints view and «Qué necesita de ti ahora», from the skill's templates). Every block sits between a
+// begin and an end marker after its placeholder, so running it again replaces, never duplicates.
+// PURE and zero-dependency.
+
+/** Escapes text for a double-quoted attribute, `<` and `>` included. PURE. */
+export const escapeAttribute = (text) =>
+  String(text)
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+
+/**
+ * The page with each `<!-- ring:<kind> #<pr> -->` placeholder followed by `blocks[pr]`, between
+ * `<!-- ring:<kind> begin -->` and `<!-- ring:<kind> end -->`; a placeholder without a block stays
+ * as it is. PURE.
+ */
+export function embedBlocks(page, kind, blocks) {
+  const pattern = new RegExp(
+    `<!-- ring:${kind} #(\\d+) -->(?:\\s*<!-- ring:${kind} begin -->[^]*?<!-- ring:${kind} end -->)?`,
+    'g',
+  );
+  return String(page).replace(pattern, (whole, pr) => {
+    const html = blocks[pr];
+    if (html === undefined) return whole;
+    return [
+      `<!-- ring:${kind} #${pr} -->`,
+      `<!-- ring:${kind} begin -->`,
+      html,
+      `<!-- ring:${kind} end -->`,
+    ].join('\n');
+  });
+}
+
+/** Each bout's diagram as an iframe after its `ring:db-diagram #<pr>` placeholder. PURE. */
+export function embedDiagrams(page, diagrams) {
+  const blocks = Object.fromEntries(
+    Object.entries(diagrams).map(([pr, html]) => [
+      pr,
+      `<iframe class="diagram" sandbox="allow-same-origin" title="Diagrama de la base de datos #${pr}" loading="lazy" srcdoc="${escapeAttribute(html)}"></iframe>`,
+    ]),
+  );
+  return embedBlocks(page, 'db-diagram', blocks);
+}
+
+const SCRIPTS =
+  /<!-- ring:page-scripts begin -->[^]*?<!-- ring:page-scripts end -->/;
+
+/**
+ * The page with its scripts (and the styles of what embed puts in it, `blocks.css`) at the very
+ * end of the document, between the page-scripts markers:
+ * after `<!-- ring:page-scripts -->` when the page has it, else appended. Never placed by
+ * searching `</body>`: an embedded diagram carries its own. PURE.
+ */
+export function embedScripts(
+  page,
+  { form, endpoints, panel = null, css = null },
+) {
+  const text = String(page).replace(SCRIPTS, '').replace(/\s+$/, '');
+  const wantsEndpoints = /data-ring-(spec|routes|plan)="/.test(text);
+  const wantsPanel =
+    Boolean(panel) && /\bdata-ring-(now|open-all)\b/.test(text);
+  const block = [
+    '<!-- ring:page-scripts begin -->',
+    css ? `<style id="ring-blocks">\n${css.trim()}\n</style>` : null,
+    `<script>\n${form.trim()}\n</script>`,
+    wantsEndpoints
+      ? `<script type="module">\n${endpoints.trim()}\n</script>`
+      : null,
+    wantsPanel ? `<script>\n${panel.trim()}\n</script>` : null,
+    '<!-- ring:page-scripts end -->',
+  ]
+    .filter(Boolean)
+    .join('\n');
+  const placeholder = '<!-- ring:page-scripts -->';
+  if (text.includes(placeholder))
+    return text.replace(placeholder, `${placeholder}\n${block}`);
+  return `${text}\n${block}\n`;
+}
+
+const jsonInScript = (value) =>
+  JSON.stringify(value)
+    .replace(/</g, '\\u003c')
+    .split(String.fromCharCode(0x2028))
+    .join('\\u2028')
+    .split(String.fromCharCode(0x2029))
+    .join('\\u2029');
+
+/**
+ * Each escalation's question contexts (`{ "pr7-E1": { "1": "<Markdown>" } }`) as JSON right before
+ * its `<ol class="qa" data-escalation="pr7-E1">`, where the interview form reads them for «Ver más
+ * información». A previous block is replaced, never duplicated. PURE.
+ */
+export function embedContexts(page, contexts) {
+  let text = String(page);
+  for (const [escalation, byQuestion] of Object.entries(contexts)) {
+    const begin = `<!-- ring:context ${escalation} begin -->`;
+    const end = `<!-- ring:context ${escalation} end -->`;
+    const previous = new RegExp(`${begin}[^]*?${end}\\n?`, 'g');
+    text = text.replace(previous, '');
+    const list = new RegExp(`<ol\\b[^>]*data-escalation="${escalation}"[^>]*>`);
+    const match = list.exec(text);
+    if (!match) continue;
+    const block = `${begin}\n<script type="application/json" id="ring-context-${escalation}">${jsonInScript(byQuestion)}</script>\n${end}\n`;
+    text = text.slice(0, match.index) + block + text.slice(match.index);
+  }
+  return text;
+}