@bongos/core 1.19.492 → 1.19.494

package/modules/hall-ui/public/copy-desk.js

@@ -34,6 +34,10 @@
   let queue = null;
   // The composer's current target, set when a "Flag" button is pressed.
   let target = null;
+  // The proposal composer's target (task 1003114 / R03), set from a "Propose
+  // wording" button. Kept apart from `target` because the two dialogs can carry
+  // different things: a flag can name a whole surface, a proposal never can.
+  let proposing = null;
   let closing = null;
   let dupePager = null;
 
@@ -123,8 +127,22 @@
     const note = f.status !== 'open' && f.resolution_note
       ? `<p class="cd-closed"><b>${escapeHtml(f.status)}</b> — ${escapeHtml(f.resolution_note)}</p>`
       : '';
-    const actions = f.status === 'open' && canClose(f)
-      ? `<div class="ov-row__actions"><button class="btn-ghost cd-close-btn" data-flag="${escapeHtml(String(f.id))}">Close…</button></div>`
+    // The queue is where the artist actually works, so the answer to a flag is
+    // offered right on it — but only for an open flag whose target is still
+    // there. A flag whose string has since been reworded (target_state 'gone')
+    // gets no propose button: there is nothing to patch, and the honest next
+    // step is a person deciding whether the flag is still live.
+    const proposable = f.status === 'open' && f.scope === 'string' && f.current
+      ? proposeButton({
+        id: f.string_id, surface: f.surface, text: f.current.text,
+        file: f.current.file, line: f.current.line, flag: f.id,
+      })
+      : '';
+    const closeable = f.status === 'open' && canClose(f)
+      ? `<button class="btn-ghost cd-close-btn" data-flag="${escapeHtml(String(f.id))}">Close…</button>`
+      : '';
+    const actions = proposable || closeable
+      ? `<div class="ov-row__actions">${proposable}${closeable}</div>`
       : '';
 
     return `<li class="ov-row" data-flag="${escapeHtml(String(f.id))}">
@@ -147,6 +165,20 @@
       data-id="${escapeHtml(d.id)}" data-surface="${escapeHtml(d.surface)}" data-text="${escapeHtml(d.text)}">Flag this…</button></div>`;
   }
 
+  // The propose button (task 1003114 / R03), offered ONLY where the row names one
+  // occurrence — file and line. That is not a UI shortcut: a proposal patches a
+  // specific place in a specific file, and a row that cannot say which place
+  // would be asking the artist to write a change nobody can land. The duplicates
+  // list is exactly that case, and it keeps just "Flag this…" — a sentence said
+  // in seven places usually wants saying once, not rewording seven times.
+  function proposeButton(d) {
+    if (!d.id || !d.file || !Number.isInteger(d.line)) return '';
+    return `<button class="btn-ghost cd-propose-btn"
+      data-id="${escapeHtml(d.id)}" data-surface="${escapeHtml(d.surface)}" data-text="${escapeHtml(d.text)}"
+      data-file="${escapeHtml(d.file)}" data-line="${escapeHtml(String(d.line))}"
+      ${d.flag ? `data-flag="${escapeHtml(String(d.flag))}"` : ''}>Propose wording…</button>`;
+  }
+
   // The duplicate's state. Colour marks the EXCEPTION here, the inverse of the
   // queue: most of this list is untouched work, so the untouched row is the
   // plain pill and colour goes to the few already in the queue or looked at.
@@ -182,7 +214,13 @@
           ${e.origin ? `<span class="ov-fact">${escapeHtml(e.origin)}</span>` : ''}
         </div>
       </div>
-      <div class="ov-row__right">${e.flagged ? pill('fact-pill--open', 'already flagged') : flagButton(e)}</div>
+      <div class="ov-row__right">
+        <div class="ov-row__actions">
+          ${e.flagged ? pill('fact-pill--open', 'already flagged') : `<button class="btn-ghost cd-flag-btn"
+            data-id="${escapeHtml(e.id)}" data-surface="${escapeHtml(e.surface)}" data-text="${escapeHtml(e.text)}">Flag this…</button>`}
+          ${proposeButton(e)}
+        </div>
+      </div>
     </li>`;
   }
 
@@ -355,6 +393,85 @@
     if ($('#cd-search').value.trim()) await runSearch();
   }
 
+  // ---------------------------------------------------------------------------
+  // the proposal composer (task 1003114 / R03)
+  //
+  // The affordance the goal asked for, shaped so it does not become the thing
+  // the goal forbids. Nothing here writes a string: it fills in a change, the
+  // server turns it into a task, and the wording reaches a reader only after
+  // somebody claims that task and ships the diff.
+  // ---------------------------------------------------------------------------
+
+  const HOLE = '{…}';
+  const holes = (s) => String(s || '').split(HOLE).length - 1;
+
+  function openProposer(t) {
+    proposing = t;
+    $('#cd-propose-target').innerHTML = `${quote(t.text)}<br>${where(t.file, t.line)}`;
+    // PREFILLED with the current wording. An artist is editing a sentence, not
+    // composing one from nothing, and retyping it from the quote above is how a
+    // proposal accidentally changes a word nobody meant to change.
+    $('#cd-propose-text').value = t.text;
+    $('#cd-propose-why').value = '';
+    $('#cd-propose-err').textContent = '';
+
+    const n = holes(t.text);
+    const hint = $('#cd-propose-holes');
+    hint.hidden = n === 0;
+    if (n > 0) {
+      hint.textContent = `This sentence has ${n} ${HOLE} where a value is dropped in when it is shown. `
+        + `Keep all ${n} — move them if the new sentence needs them elsewhere, but do not remove one: `
+        + 'the values come from the code, and dropping one is a code change.';
+    }
+    $('#cd-propose-dialog').showModal();
+  }
+
+  async function submitProposal() {
+    const proposed = $('#cd-propose-text').value.replace(/\s+/g, ' ').trim();
+    const why = $('#cd-propose-why').value.trim();
+    const err = $('#cd-propose-err');
+
+    // The server and its floors are the real gates; these mirror them so the
+    // common mistakes answer instantly instead of costing a round trip.
+    if (!proposed) { err.textContent = 'Write the wording you want instead.'; return; }
+    if (proposed === String(proposing.text).replace(/\s+/g, ' ').trim()) {
+      err.textContent = 'That is the wording it already has. Change something, or file a flag instead if you only want to mark it.';
+      return;
+    }
+    if (holes(proposed) !== holes(proposing.text)) {
+      err.textContent = `Keep all ${holes(proposing.text)} ${HOLE} — they are the values the code drops in, and the change cannot land without them.`;
+      return;
+    }
+    if (why.replace(/\s+/g, ' ').length < 10) {
+      err.textContent = 'Say why it is better. Whoever reviews this decides it from your reason, without asking you.';
+      return;
+    }
+
+    const body = {
+      string_id: proposing.string_id,
+      proposed_text: proposed,
+      why,
+      file: proposing.file,
+      line: proposing.line,
+    };
+    if (proposing.flag_id) body.flag_id = Number(proposing.flag_id);
+
+    const res = await api.request('POST', `${API}/copy-desk/proposals`, { body });
+    if (!res.ok) {
+      const e = (res.data && res.data.error) || {};
+      const d = e.details || {};
+      err.textContent = d.what_this_means || d.why || e.message || 'Could not file the change.';
+      return;
+    }
+    $('#cd-propose-dialog').close();
+    const task = (res.data && res.data.task) || {};
+    toast(res.data && res.data.created === false
+      ? `Already filed — task #${task.id} carries this exact change.`
+      : `Filed as task #${task.id}. It lands when someone claims it.`);
+    await loadQueue();
+    if ($('#cd-search').value.trim()) await runSearch();
+  }
+
   function openCloser(id) {
     closing = queue.flags.find((f) => String(f.id) === String(id));
     if (!closing) return;
@@ -427,12 +544,26 @@
       });
       return;
     }
+    const proposeBtn = ev.target.closest('.cd-propose-btn');
+    if (proposeBtn) {
+      openProposer({
+        string_id: proposeBtn.dataset.id,
+        surface: proposeBtn.dataset.surface,
+        text: proposeBtn.dataset.text,
+        file: proposeBtn.dataset.file,
+        line: Number(proposeBtn.dataset.line),
+        flag_id: proposeBtn.dataset.flag || null,
+      });
+      return;
+    }
     const closeBtn = ev.target.closest('.cd-close-btn');
     if (closeBtn) openCloser(closeBtn.dataset.flag);
   });
 
   $('#cd-cancel').addEventListener('click', () => $('#cd-dialog').close());
   $('#cd-submit').addEventListener('click', submitFlag);
+  $('#cd-propose-cancel').addEventListener('click', () => $('#cd-propose-dialog').close());
+  $('#cd-propose-submit').addEventListener('click', submitProposal);
   $('#cd-close-cancel').addEventListener('click', () => $('#cd-close-dialog').close());
   $('#cd-close-submit').addEventListener('click', submitClose);
 

package/modules/hall-ui/public/copy-desk.states.json

@@ -1,5 +1,5 @@
 {
-  "_": "Copy desk — the one-voice review queue. Its two dialogs are real <dialog>s, so their ::backdrop is the sheet's single sanctioned literal (black with alpha as a scrim). Written with the re-skin (task 1003307) so this page is MEASURED at three widths in both modes rather than looked at once; the redesign (task 1003471) put a queue, ten duplicates and a search's hits in the harness so the rows and both dialogs can be looked at.",
+  "_": "Copy desk — the one-voice review queue. Its three dialogs are real <dialog>s, so their ::backdrop is the sheet's single sanctioned literal (black with alpha as a scrim). Written with the re-skin (task 1003307) so this page is MEASURED at three widths in both modes rather than looked at once; the redesign (task 1003471) put a queue, ten duplicates and a search's hits in the harness so the rows and the dialogs can be looked at; task 1003114 (R03) added the proposal composer and the `proposer` state that opens it.",
   "page": "/builders/copy-desk",
   "surface": "hall-ui",
   "stub": {
@@ -102,6 +102,23 @@
           250
         ]
       ]
+    },
+    "proposer": {
+      "auth": true,
+      "actions": [
+        [
+          "wait",
+          700
+        ],
+        [
+          "clickIfVisible",
+          ".cd-propose-btn"
+        ],
+        [
+          "wait",
+          250
+        ]
+      ]
     }
   },
   "reducedMotion": {

package/modules/lifecycle/lifecycle.js

@@ -53,6 +53,12 @@ module.exports = {
   // nobody surfaces is merely stored.
   openTaskRecommendationsFor: (...a) => taskRecommendations.countOpenForRecipient(...a),
   getTask: (...a) => db.getTask(...a),
+  // findTaskBySourceRef: the create-vector idempotency read (task 1003114 / R03
+  // of goal 1000074). copy-desk turns an artist's copy proposal into a task and
+  // needs the same "this (source, source_ref) already minted a task" check the
+  // core POST /tasks vector does, so a double-submitted proposal resolves to the
+  // task it already made instead of littering the board with twins.
+  findTaskBySourceRef: (...a) => db.findTaskBySourceRef(...a),
   listVersions: (...a) => db.listVersions(...a),
   versionProgress: (...a) => db.versionProgress(...a),
   recentShippedTasks: (...a) => db.recentShippedTasks(...a),

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.492",
+  "version": "1.19.494",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/copy-apply.js

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/gds/copy-apply.js — land a copy proposal as a real diff (R03 of goal
+// 1000074, the artist's loop; task 1003114).
+//
+// WHAT IT IS FOR. R03's done-when is that "an artist with no terminal can propose
+// a copy change that reaches main through a claim". The copy desk gives them the
+// first half: a proposal becomes a GDS task carrying a patch
+// (modules/copy-desk/proposals.js). This command is the second half — the thing
+// whoever claims that task runs. It is the direct analogue of `adapter.export()`
+// in the design half (ADR 0081, modules/ui-design/adapters/*): tool output lands
+// in the repo as a committed diff under a claim, with a path guard, and the repo
+// stays the source of truth. Nothing about the copy path bypasses the ledger,
+// because this command IS the ledger's hands.
+//
+// WHY IT RE-DERIVES INSTEAD OF TRUSTING THE PATCH. The patch names a file and a
+// line, but a line number is stale the moment anything above it changes, and the
+// registry's committed rows deliberately carry no character offsets (see the
+// note in copy-inventory.js's buildRegistry). So this re-runs R01's OWN
+// extractor over the working tree and finds the occurrence there. One set of
+// matching rules, in one file, used by both the inventory and the applier —
+// which is what stops this command from editing a byte the inventory would never
+// have called copy.
+//
+// THE REFUSALS ARE THE FEATURE. A copy change that lands on the wrong characters
+// is worse than one that does not land, so every ambiguity is a named refusal
+// with the reason on one line: the string is gone, it moved and is no longer
+// unique, its literal is escaped so no exact span exists, the placeholder
+// arithmetic does not hold, or the file is outside a registry surface. None of
+// them means the wording was wrong — they mean a person should look.
+//
+// Run:  node scripts/gds/copy-apply.js                    (the task you are HOLDING — the normal call)
+//       node scripts/gds/copy-apply.js --dry-run          (say what would change, write nothing)
+//       node scripts/gds/copy-apply.js --task 1234        (a named task, when you hold more than one)
+//       node scripts/gds/copy-apply.js --patch-file p.json  (a local patch — used by the tests)
+//
+// WHY THE BARE FORM DEFAULTS TO YOUR CLAIM rather than taking an id. The task a
+// proposal creates has to print the exact line that lands it, and it cannot know
+// its own id at the moment its description is written. Every workaround for that
+// is worse than the rule it would paper over: this command may only be run under
+// a claim (that is the whole point of the feature), and a claim already names a
+// task. So the bare call reads the claim, and holding no claim is a refusal that
+// says to go and claim the task — the methodology's own rule, enforced by the
+// command instead of restated in its output.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ci = require('./copy-inventory.js');
+const proposals = require('../../modules/copy-desk/proposals.js');
+const { apiCall, arg, hasFlag, cliExit } = require('./cli-lib.js');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const PLACEHOLDER = proposals.PLACEHOLDER;
+
+// ---------------------------------------------------------------------------
+// PURE below this line, down to `main`. The tests drive these directly with
+// string sources — no fs, no network, no task.
+// ---------------------------------------------------------------------------
+
+// THE PATH GUARD, and it is the same rule the design adapter enforces: an export
+// may only write inside the surfaces the contract knows about. Here the surface
+// roots come from R01's own SURFACES table, so a patch can only ever touch a
+// directory the inventory actually walks. A patch naming anything else — a
+// traversal, a config file, a migration — is refused before a single byte is
+// read, not after.
+function surfaceRootFor(surfaceId) {
+  const surface = ci.SURFACES.find((s) => s.id === surfaceId);
+  return surface ? surface.at : null;
+}
+
+function checkPatchPath(patch) {
+  const root = surfaceRootFor(patch.surface);
+  if (!root) return { ok: false, code: 'unknown_surface', detail: { surface: patch.surface, known: ci.SURFACES.map((s) => s.id) } };
+  // Compare normalized, repo-relative, forward-slash paths — the same form the
+  // registry stores — and require the file to sit under its surface's root.
+  const rel = String(patch.file).replace(/\\/g, '/');
+  const abs = path.resolve(REPO_ROOT, rel);
+  const rootAbs = path.resolve(REPO_ROOT, root);
+  if (!abs.startsWith(rootAbs + path.sep)) {
+    return {
+      ok: false,
+      code: 'path_outside_surface',
+      detail: { file: rel, surface: patch.surface, must_be_under: root },
+    };
+  }
+  return { ok: true, rel, abs };
+}
+
+// Find the one occurrence this patch is about, in the tree as it stands now.
+//
+// Matching is on (origin, current text) within the file, NOT on the line: a line
+// number is the first thing to go stale, and the registry id is explicitly
+// designed to survive a string moving. The line is used only to disambiguate
+// when the same sentence appears at several sites in one file — which is the
+// duplicate case R01 already reports, and where guessing would be indefensible.
+function locateOccurrence(source, rel, patch) {
+  const rows = (path.extname(rel) === '.html'
+    ? ci.fromHtml({ source, rel })
+    : ci.fromJs({ source, rel }))
+    .filter((r) => r.origin === patch.origin && r.text === patch.current);
+
+  if (!rows.length) {
+    return {
+      ok: false,
+      code: 'target_gone',
+      detail: {
+        file: rel,
+        looked_for: patch.current,
+        what_this_means: 'That exact wording is no longer in this file — it has already been edited, or the proposal was written against an older tree. Nothing was changed. Re-read the string on the copy desk and propose again if it still needs work.',
+      },
+    };
+  }
+  let row = rows[0];
+  if (rows.length > 1) {
+    const onLine = rows.filter((r) => r.line === patch.line);
+    if (onLine.length !== 1) {
+      return {
+        ok: false,
+        code: 'ambiguous_target',
+        detail: {
+          file: rel,
+          occurrences: rows.length,
+          lines: rows.map((r) => r.line),
+          what_this_means: 'This sentence appears more than once in this file and the proposal cannot say which one it meant. That is the duplicate case the copy desk reports — decide whether they should all change, and land it as an ordinary edit under this claim.',
+        },
+      };
+    }
+    row = onLine[0];
+  }
+  if (row.start === undefined) {
+    return {
+      ok: false,
+      code: 'no_exact_span',
+      detail: {
+        file: rel,
+        line: row.line,
+        what_this_means: 'This string lives inside an escaped quoted literal, so the inventory cannot point at its exact characters and this command will not guess. Edit it by hand under this claim.',
+      },
+    };
+  }
+  return { ok: true, row };
+}
+
+// Rebuild the replacement text, re-injecting the source's own interpolations.
+//
+// The registry writes `{…}` where the source has `${expr}`, so the artist edits a
+// readable sentence with holes in it. Landing it means putting the ORIGINAL
+// expressions back, in order — the k-th hole takes the k-th expression. The
+// count was already checked when the proposal was made; it is checked again here
+// against the real source, because the source is what is about to be written.
+function reinjectInterpolations(rawSpan, proposedText) {
+  const expressions = String(rawSpan).match(/\$\{[^{}]*\}/g) || [];
+  const holes = proposals.placeholderCount(proposedText);
+  if (holes !== expressions.length) {
+    return {
+      ok: false,
+      code: 'placeholder_mismatch',
+      detail: {
+        expected: expressions.length,
+        got: holes,
+        placeholder: PLACEHOLDER,
+        what_this_means: 'The values this sentence drops in at render time do not line up with the proposed wording. Nothing was changed.',
+      },
+    };
+  }
+  let out = '';
+  let rest = String(proposedText);
+  for (const expr of expressions) {
+    const at = rest.indexOf(PLACEHOLDER);
+    out += rest.slice(0, at) + expr;
+    rest = rest.slice(at + PLACEHOLDER.length);
+  }
+  return { ok: true, text: out + rest };
+}
+
+// The whole edit, as a pure function of the file's current contents and a patch.
+// Returns the new source — or a named refusal. Writes nothing.
+function applyPatchToSource(source, rel, patch) {
+  const located = locateOccurrence(source, rel, patch);
+  if (!located.ok) return located;
+  const { row } = located;
+  const rawSpan = source.slice(row.start, row.end);
+  const rebuilt = reinjectInterpolations(rawSpan, patch.proposed);
+  if (!rebuilt.ok) return rebuilt;
+  return {
+    ok: true,
+    line: row.line,
+    before: rawSpan,
+    after: rebuilt.text,
+    source: source.slice(0, row.start) + rebuilt.text + source.slice(row.end),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The command.
+// ---------------------------------------------------------------------------
+
+function refuse(result) {
+  const detail = result.detail || {};
+  console.error(`copy-apply: REFUSED (${result.code})`);
+  if (detail.what_this_means) console.error(`  ${detail.what_this_means}`);
+  for (const [k, v] of Object.entries(detail)) {
+    if (k === 'what_this_means') continue;
+    console.error(`  ${k}: ${typeof v === 'object' ? JSON.stringify(v) : v}`);
+  }
+  return 2;
+}
+
+// The task this session is holding. Returns a named refusal rather than an id
+// when there is nothing to act under — "claim it first" is the correct answer,
+// not an inconvenience to route around.
+async function claimedTaskId() {
+  const me = await apiCall('GET', '/api/gds/me');
+  if (!me.ok) return { ok: false, code: 'no_session', detail: { status: me.status, run: 'node scripts/gds/setup.js' } };
+  const claims = me.data.active_claims || (me.data.active_claim ? [me.data.active_claim] : []);
+  if (!claims.length) {
+    return {
+      ok: false,
+      code: 'no_active_claim',
+      detail: {
+        what_this_means: 'A copy change lands under a claim like every other change. Claim the proposal task first (node scripts/gds/claim.js <id>), then run this again — or name one with --task <id>.',
+      },
+    };
+  }
+  if (claims.length > 1) {
+    return {
+      ok: false,
+      code: 'several_active_claims',
+      detail: {
+        held: claims.map((c) => c.task_id),
+        what_this_means: 'You hold more than one claim, so this command will not guess which proposal you meant. Name it with --task <id>.',
+      },
+    };
+  }
+  return { ok: true, taskId: claims[0].task_id };
+}
+
+async function loadPatch({ taskId, patchFile }) {
+  if (patchFile) {
+    let raw;
+    try {
+      raw = fs.readFileSync(path.resolve(process.cwd(), patchFile), 'utf8');
+    } catch (err) {
+      return { ok: false, code: 'patch_file_unreadable', detail: { reason: err.message } };
+    }
+    // A bare patch file is still parsed through the SAME reader the task path
+    // uses, so the local shortcut can never accept a shape the real path rejects.
+    return proposals.parseProposalBlock(raw.trim().startsWith('{')
+      ? ['```' + proposals.FENCE, raw.trim(), '```'].join('\n')
+      : raw);
+  }
+  const res = await apiCall('GET', `/api/gds/tasks/${taskId}`);
+  if (!res.ok) {
+    return { ok: false, code: 'task_unreadable', detail: { task: taskId, status: res.status } };
+  }
+  const task = (res.data && res.data.task) || {};
+  const parsed = proposals.parseProposalBlock(task.description || '');
+  if (!parsed.ok) return parsed;
+  return { ok: true, patch: parsed.patch, task };
+}
+
+async function main() {
+  let taskId = arg('--task');
+  const patchFile = arg('--patch-file');
+  const dryRun = hasFlag('--dry-run');
+
+  if (!taskId && !patchFile) {
+    const held = await claimedTaskId();
+    if (!held.ok) return cliExit(refuse(held));
+    taskId = held.taskId;
+    console.log(`copy-apply: the task you are holding — #${taskId}`);
+  }
+
+  const loaded = await loadPatch({ taskId, patchFile });
+  if (!loaded.ok) return cliExit(refuse(loaded));
+  const { patch } = loaded;
+
+  const guard = checkPatchPath(patch);
+  if (!guard.ok) return cliExit(refuse(guard));
+
+  let source;
+  try {
+    source = fs.readFileSync(guard.abs, 'utf8');
+  } catch (err) {
+    return cliExit(refuse({ code: 'file_unreadable', detail: { file: guard.rel, reason: err.message } }));
+  }
+
+  const applied = applyPatchToSource(source, guard.rel, patch);
+  if (!applied.ok) return cliExit(refuse(applied));
+
+  console.log(`copy-apply: ${guard.rel}:${applied.line} (${patch.origin})`);
+  console.log(`  -  ${applied.before}`);
+  console.log(`  +  ${applied.after}`);
+
+  if (dryRun) {
+    console.log('copy-apply: --dry-run, nothing written.');
+    return cliExit(0);
+  }
+
+  fs.writeFileSync(guard.abs, applied.source);
+
+  // Regenerate the inventory in the same breath. The registry is a committed
+  // artifact whose CI check fails on drift, so an applier that edited a surface
+  // and left the registry describing the old tree would hand the builder a
+  // red build and a puzzle. It also gives us the verification below.
+  const { reg } = ci.write();
+
+  // VERIFY OUR OWN WORK, because a copy change that lands on the wrong characters
+  // is the failure this whole command is shaped to avoid — and the registry we
+  // just rebuilt is an independent read of the file we just wrote.
+  const nowThere = reg.entries.some((e) => e.file === guard.rel && e.text === patch.proposed);
+  if (!nowThere) {
+    console.error('copy-apply: WROTE THE FILE, but the regenerated registry does not contain the new wording at that path.');
+    console.error('  The edit landed somewhere the inventory does not read as copy. Review `git diff` before doing anything else.');
+    return cliExit(3);
+  }
+
+  console.log(`copy-apply: applied, registry regenerated (${reg.counts.strings} strings).`);
+  console.log('  Review with `git diff`, then ship this task the normal way.');
+  return cliExit(0);
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(`copy-apply: ${err && err.message ? err.message : err}`);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = {
+  surfaceRootFor,
+  checkPatchPath,
+  locateOccurrence,
+  reinjectInterpolations,
+  applyPatchToSource,
+};