@bongos/core 1.19.250 → 1.19.252

package/modules/copy-desk/tests/copy_flags.mjs

@@ -0,0 +1,246 @@
+// modules/copy-desk/tests/copy_flags.mjs — the pure validators behind the flag
+// write path (task 1003113 / R02 of goal 1000074).
+//
+// The criterion these pin: A FLAG CARRIES A JUDGEMENT, AND POINTS AT SOMETHING
+// REAL. Everything below is one of those two halves — the reason floor (and the
+// closing-note floor that mirrors it), or the registry lookups that stop a flag
+// being filed against a surface or string that does not exist.
+//
+// The snapshot tests are the load-bearing ones: the snapshot's whole value is
+// that it can be trusted a month later, which is only true if it comes from the
+// registry and never from the request body.
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const flags = require('../flags.js');
+const registry = require('../registry.js');
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.stack || err.message}`); }
+}
+
+// A miniature registry in the shape copy-inventory.js emits, so these tests
+// never depend on what the real tree happens to say today.
+const FAKE = {
+  schema: 1,
+  generator: 'scripts/gds/copy-inventory.js',
+  counts: { strings: 3, unique_ids: 2, certain: 3, heuristic: 0, duplicate_ids: 1 },
+  surfaces: {
+    'builders-hall': { at: 'modules/hall-ui/public', files: 2, strings: 2 },
+    landing: { at: 'public-landing', files: 1, strings: 1 },
+  },
+  duplicates: [
+    { id: 'dup1', surface: 'builders-hall', text: 'Could not save.', occurrences: 2,
+      at: ['modules/hall-ui/public/a.js:10', 'modules/hall-ui/public/b.js:20'] },
+  ],
+  entries: [
+    { id: 'dup1', surface: 'builders-hall', text: 'Could not save.', file: 'modules/hall-ui/public/a.js', line: 10, origin: 'js-notice', confidence: 'certain' },
+    { id: 'dup1', surface: 'builders-hall', text: 'Could not save.', file: 'modules/hall-ui/public/b.js', line: 20, origin: 'js-notice', confidence: 'certain' },
+    { id: 'solo', surface: 'landing', text: 'Enter the future.', file: 'public-landing/index.html', line: 4, origin: 'html-text', confidence: 'certain' },
+  ],
+};
+const INDEX = registry.indexRegistry(FAKE);
+const ok = (body) => flags.normalizeFlagPayload(body, INDEX, registry);
+
+const GOOD_REASON = 'Reads like a stack trace, not a sentence a person would say.';
+
+console.log('copy-desk: flag payload validation');
+
+// ---------------------------------------------------------------------------
+// The reason floor — the rule the whole queue's usefulness rests on.
+// ---------------------------------------------------------------------------
+
+await test('a flag with no reason is refused', () => {
+  const r = ok({ scope: 'string', surface: 'landing', string_id: 'solo' });
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'reason_too_thin');
+});
+
+await test('a one-word reason is refused', () => {
+  const r = ok({ scope: 'string', surface: 'landing', string_id: 'solo', reason: 'bad' });
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'reason_too_thin');
+});
+
+await test('the floor measures content, not whitespace', () => {
+  // 15 characters, 3 of content. A spacebar must not clear a content floor.
+  const r = ok({ scope: 'string', surface: 'landing', string_id: 'solo', reason: '  f   i   x  ' });
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'reason_too_thin');
+  assert.equal(r.detail.got, 5); // 'f i x' after collapsing
+});
+
+await test('the refusal explains WHY, not just that a rule fired', () => {
+  const r = ok({ scope: 'string', surface: 'landing', string_id: 'solo', reason: 'no' });
+  assert.equal(typeof r.detail.why, 'string');
+  assert.ok(r.detail.why.length > 40, 'the "why" must be a sentence, not a code');
+  assert.equal(r.detail.min_chars, flags.MIN_REASON_CHARS);
+});
+
+await test('a real reason passes and is stored tidied', () => {
+  const r = ok({ scope: 'string', surface: 'landing', string_id: 'solo', reason: `  ${GOOD_REASON}\n\n` });
+  assert.equal(r.ok, true);
+  assert.equal(r.value.reason, GOOD_REASON);
+});
+
+// ---------------------------------------------------------------------------
+// Pointing at something real.
+// ---------------------------------------------------------------------------
+
+await test('an unknown surface is refused, and the refusal lists the known ones', () => {
+  const r = ok({ scope: 'surface', surface: 'not-a-surface', reason: GOOD_REASON });
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'unknown_surface');
+  assert.deepEqual([...r.detail.known].sort(), ['builders-hall', 'landing']);
+});
+
+await test('an unknown string id is refused', () => {
+  const r = ok({ scope: 'string', surface: 'landing', string_id: 'nope', reason: GOOD_REASON });
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'unknown_string_id');
+});
+
+await test("scope 'string' with no string_id is refused", () => {
+  const r = ok({ scope: 'string', surface: 'landing', reason: GOOD_REASON });
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'string_id_required');
+});
+
+await test("scope 'surface' stores no string_id and no snapshot", () => {
+  const r = ok({ scope: 'surface', surface: 'landing', reason: GOOD_REASON });
+  assert.equal(r.ok, true);
+  assert.equal(r.value.string_id, null);
+  assert.equal(r.value.text_at_flag, null);
+  // The DB constraint copy_desk_flags_target_chk enforces the same coupling; this
+  // is the half that produces a readable error instead of a 500.
+});
+
+await test('a body naming a different surface than the registry is REFUSED, not silently corrected', () => {
+  // Silently filing it under the registry's surface would send the flag somewhere
+  // the reporter never chose, and they would never find out.
+  const r = ok({ scope: 'string', surface: 'builders-hall', string_id: 'solo', reason: GOOD_REASON });
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'surface_mismatch');
+  assert.equal(r.detail.registry_surface, 'landing');
+});
+
+// ---------------------------------------------------------------------------
+// The snapshot comes from the registry, never from the caller.
+// ---------------------------------------------------------------------------
+
+await test('the snapshot is taken from the registry', () => {
+  const r = ok({ scope: 'string', surface: 'landing', string_id: 'solo', reason: GOOD_REASON });
+  assert.equal(r.ok, true);
+  assert.equal(r.value.text_at_flag, 'Enter the future.');
+  assert.equal(r.value.file_at_flag, 'public-landing/index.html');
+  assert.equal(r.value.line_at_flag, 4);
+  assert.equal(r.value.registry_schema, 1);
+});
+
+await test('a caller-supplied snapshot is IGNORED', () => {
+  // The snapshot's entire value is that it is trustworthy later. A body that can
+  // set it turns it into a claim by whoever filed the flag.
+  const r = ok({
+    scope: 'string', surface: 'landing', string_id: 'solo', reason: GOOD_REASON,
+    text_at_flag: 'something the reporter made up',
+    file_at_flag: 'somewhere/else.js',
+    line_at_flag: 999,
+  });
+  assert.equal(r.ok, true);
+  assert.equal(r.value.text_at_flag, 'Enter the future.');
+  assert.equal(r.value.file_at_flag, 'public-landing/index.html');
+  assert.equal(r.value.line_at_flag, 4);
+});
+
+await test('a duplicated string snapshots its first occurrence, and the id resolves to all of them', () => {
+  const r = ok({ scope: 'string', surface: 'builders-hall', string_id: 'dup1', reason: GOOD_REASON });
+  assert.equal(r.ok, true);
+  assert.equal(r.value.file_at_flag, 'modules/hall-ui/public/a.js');
+  assert.equal(registry.occurrencesOf(INDEX, 'dup1').length, 2,
+    'one id maps to MANY entries — mapping id→entry would drop every duplicate but the first');
+});
+
+// ---------------------------------------------------------------------------
+// Kind + scope enums mirror the DB CHECKs.
+// ---------------------------------------------------------------------------
+
+await test('an unknown kind is refused with the allowed list', () => {
+  const r = ok({ scope: 'string', surface: 'landing', string_id: 'solo', reason: GOOD_REASON, kind: 'vibes' });
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'bad_kind');
+  assert.deepEqual(r.detail.allowed, flags.KINDS);
+});
+
+await test('kind defaults to other', () => {
+  const r = ok({ scope: 'string', surface: 'landing', string_id: 'solo', reason: GOOD_REASON });
+  assert.equal(r.value.kind, 'other');
+});
+
+await test('the JS enums match the migration CHECK constraints exactly', async () => {
+  // Two lists that drift is the failure mode this pins: the route would accept a
+  // value the DB then rejects as a 500.
+  const fs = await import('node:fs');
+  const url = await import('node:url');
+  const path = await import('node:path');
+  const here = path.dirname(url.fileURLToPath(import.meta.url));
+  const sql = fs.readFileSync(path.join(here, '..', 'migrations', 'copy_desk_001_flags.sql'), 'utf8');
+  for (const [name, list] of [['kind', flags.KINDS], ['scope', flags.SCOPES], ['status', flags.STATUSES]]) {
+    const m = new RegExp(`CHECK \\(${name} IN \\(([^)]*)\\)\\)`).exec(sql);
+    assert.ok(m, `migration has no CHECK for ${name}`);
+    const inSql = m[1].split(',').map((s) => s.trim().replace(/'/g, ''));
+    assert.deepEqual(inSql.sort(), [...list].sort(), `${name} enum drifted between flags.js and the migration`);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Closing a flag.
+// ---------------------------------------------------------------------------
+
+console.log('copy-desk: closing a flag');
+
+await test('closing to a non-closing status is refused', () => {
+  const r = flags.normalizeResolution({ status: 'open', resolution_note: 'changed the wording' });
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'bad_status');
+});
+
+await test('closing with no note is refused — the symmetry with opening is the point', () => {
+  const r = flags.normalizeResolution({ status: 'dismissed' });
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'resolution_note_too_thin');
+  assert.ok(r.detail.why.length > 40);
+});
+
+await test('dismissed is a first-class close, not a soft delete', () => {
+  const r = flags.normalizeResolution({ status: 'dismissed', resolution_note: 'Deliberate house style; leaving as is.' });
+  assert.equal(r.ok, true);
+  assert.equal(r.value.status, 'dismissed');
+});
+
+await test('resolved may name the task that carried the fix', () => {
+  const r = flags.normalizeResolution({ status: 'resolved', resolution_note: 'Rewritten in the ship below.', resolved_task_id: 1003113 });
+  assert.equal(r.ok, true);
+  assert.equal(r.value.resolved_task_id, 1003113);
+});
+
+await test('resolved WITHOUT a task id is allowed, and records the absence', () => {
+  // A string can legitimately be fixed by a task filed before the flag existed.
+  // Refusing the close would leave a false open flag standing.
+  const r = flags.normalizeResolution({ status: 'resolved', resolution_note: 'Already fixed by an earlier ship.' });
+  assert.equal(r.ok, true);
+  assert.equal(r.value.resolved_task_id, null);
+});
+
+await test('a non-numeric task id is refused', () => {
+  const r = flags.normalizeResolution({ status: 'resolved', resolution_note: 'Fixed in the ship below.', resolved_task_id: 'abc' });
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'bad_resolved_task_id');
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/modules/copy-desk/tests/copy_no_cms.mjs

@@ -0,0 +1,104 @@
+// modules/copy-desk/tests/copy_no_cms.mjs — the goal's hard NON-GOAL, made
+// testable (task 1003113 / R02 of goal 1000074).
+//
+// Goal 1000074, verbatim: "NO LIVE CMS. Every copy change is a claimed, graded,
+// shipped GDS task (the methodology's hard rule). The registry is an inventory
+// plus a work queue plus an editing affordance — never a write path that
+// bypasses the ledger."
+//
+// A constraint that lives only in prose is a constraint that erodes. The way
+// this one erodes is not a dramatic "add a CMS" commit — it is one plausible
+// column ("just store the suggested wording so the artist doesn't lose it"),
+// then one plausible read of that column, and the ledger rule is dead with
+// nobody having decided to kill it. So the shape is pinned here:
+//
+//   * the write surface is EXACTLY the two verbs R02 defines,
+//   * no column on copy_desk_flags could hold replacement text, and
+//   * nothing in this module ever hands a renderer a string as authoritative copy.
+//
+// R03 (task 1003114) builds the editing affordance, and its own done-when asks
+// for the full version of this test. This is the R02-scoped seed of it: when R03
+// adds a proposal path, the expected route list below changes DELIBERATELY, in a
+// diff a reviewer can see, rather than drifting.
+
+import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+
+const HERE = path.dirname(url.fileURLToPath(import.meta.url));
+const MODULE_DIR = path.join(HERE, '..');
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.stack || err.message}`); }
+}
+
+const read = (rel) => fs.readFileSync(path.join(MODULE_DIR, rel), 'utf8');
+
+// Strip comments so the prose ABOUT the rule (which necessarily names the
+// forbidden things — the migration header says in so many words that a flag
+// must never carry replacement text) is not mistaken for the rule being broken.
+// Both comment dialects, because this scans JS and SQL.
+const stripComments = (src) => src
+  .replace(/\/\*[\s\S]*?\*\//g, ' ')
+  .replace(/^\s*\/\/.*$/gm, ' ')
+  .replace(/--[^\n]*/g, ' ');
+
+console.log('copy-desk: NO LIVE CMS');
+
+await test('the write surface is exactly the two verbs R02 defines', () => {
+  const src = stripComments(read('routes/copy-desk.js'));
+  const found = [...src.matchAll(/router\.(post|put|patch|delete)\(\s*'([^']+)'/g)]
+    .map((m) => `${m[1].toUpperCase()} ${m[2]}`)
+    .sort();
+  assert.deepEqual(found, [
+    'POST /copy-desk/flags',
+    'POST /copy-desk/flags/:id/close',
+  ], 'a new write route on this module must be a deliberate, reviewed change to this list');
+});
+
+await test('no column on copy_desk_flags could hold replacement text', () => {
+  const sql = stripComments(read('migrations/copy_desk_001_flags.sql'));
+  // The names a "just store the suggested wording" column would plausibly take.
+  const forbidden = /\b(new_text|proposed_text|suggested_text|replacement|replacement_text|new_copy|proposed_copy|override_text|value_text)\b/i;
+  const hit = forbidden.exec(sql);
+  assert.equal(hit ? hit[0] : null, null,
+    `copy_desk_flags must carry a judgement and a pointer, never replacement copy (found "${hit && hit[0]}")`);
+});
+
+await test('the only text column is the historical snapshot, and it is never the live source', () => {
+  const sql = stripComments(read('migrations/copy_desk_001_flags.sql'));
+  const textish = [...sql.matchAll(/^\s{2}(\w+)\s+text\b/gm)].map((m) => m[1]);
+  assert.deepEqual(textish.sort(), [
+    'file_at_flag', 'kind', 'reason', 'resolution_note', 'scope', 'status', 'string_id', 'surface', 'text_at_flag',
+  ], 'a new text column here needs a deliberate look at whether it is copy');
+
+  // And the live read path is the registry, not the row: annotateFlag fills
+  // `current` from the registry index every time.
+  const reg = stripComments(read('registry.js'));
+  assert.ok(/current: \{ text: first\.text/.test(reg),
+    'the live text an artist sees must come from the registry entry, not from text_at_flag');
+});
+
+await test('this module never writes to the surfaces it inventories', () => {
+  // The registry is generated by R01 and committed. If this module ever gained a
+  // write to docs/copy-registry.json — or to any surface file — the inventory
+  // would stop describing the tree and start describing itself.
+  for (const rel of ['registry.js', 'flags.js', 'routes/copy-desk.js']) {
+    const src = stripComments(read(rel));
+    assert.equal(/fs\.(writeFile|writeFileSync|appendFile|appendFileSync|rm|unlink|mkdir)/.test(src), false,
+      `${rel} performs a filesystem WRITE — this module reads the registry and never writes it`);
+  }
+});
+
+await test('the module manifest declares no seam another module could write copy through', () => {
+  const manifest = JSON.parse(read('module.json'));
+  assert.deepEqual(manifest.provides, [], 'a provided port here would be a copy write path for every other module');
+  assert.deepEqual(manifest.consumes, []);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/modules/copy-desk/tests/copy_queue.mjs

@@ -0,0 +1,257 @@
+// modules/copy-desk/tests/copy_queue.mjs — the queue composition (task 1003113 /
+// R02 of goal 1000074).
+//
+// The criterion these pin: THE QUEUE TELLS AN ARTIST THE TRUTH ABOUT ITS OWN
+// STATE. Three ways it could lie, one test group each:
+//
+//   1. A flag whose string has since been edited or deleted must READ as such
+//      ('gone'), not silently vanish and not auto-close. The id is a hash over
+//      the text, so an edit produces a new id — which means "target gone" is a
+//      routine, expected state, not an error.
+//   2. A flag whose string MOVED file or line must show where it is now, or the
+//      artist opens the wrong file.
+//   3. The duplicate signal must subtract what has already been dealt with. A
+//      count that never moves however much work you do teaches you the queue is
+//      decorative.
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const registry = require('../registry.js');
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.stack || err.message}`); }
+}
+
+const REG = {
+  schema: 1,
+  generator: 'scripts/gds/copy-inventory.js',
+  goal: 1000074,
+  counts: { strings: 3, unique_ids: 2, duplicate_ids: 1 },
+  surfaces: { 'builders-hall': { at: 'modules/hall-ui/public', files: 2, strings: 3 } },
+  blind_spots: ['server-side messages'],
+  duplicates: [
+    { id: 'dupA', surface: 'builders-hall', text: 'Could not save.', occurrences: 2, at: ['a.js:1', 'b.js:2'] },
+    { id: 'dupB', surface: 'builders-hall', text: 'Archons only.', occurrences: 3, at: ['c.js:1', 'd.js:2', 'e.js:3'] },
+    { id: 'dupC', surface: 'builders-hall', text: 'Loading…', occurrences: 2, at: ['f.js:1', 'g.js:2'] },
+  ],
+  entries: [
+    { id: 'dupA', surface: 'builders-hall', text: 'Could not save.', file: 'a.js', line: 1, origin: 'js-notice' },
+    { id: 'dupA', surface: 'builders-hall', text: 'Could not save.', file: 'b.js', line: 2, origin: 'js-notice' },
+    { id: 'live', surface: 'builders-hall', text: 'Enter.', file: 'h.js', line: 42, origin: 'html-text' },
+  ],
+};
+const INDEX = registry.indexRegistry(REG);
+
+const flag = (o) => ({
+  id: 1, scope: 'string', surface: 'builders-hall', string_id: 'live',
+  reason: 'x', kind: 'other', status: 'open',
+  text_at_flag: 'Enter.', file_at_flag: 'h.js', line_at_flag: 42, ...o,
+});
+
+console.log('copy-desk: what the queue says about a flag');
+
+await test('a flag whose string is still there reads present, with the live text', () => {
+  const a = registry.annotateFlag(INDEX, flag({}));
+  assert.equal(a.target_state, 'present');
+  assert.equal(a.current.text, 'Enter.');
+  assert.equal(a.current.occurrences, 1);
+  assert.equal(a.moved, false);
+});
+
+await test('a flag whose string was edited or deleted reads GONE, and is not auto-closed', () => {
+  const a = registry.annotateFlag(INDEX, flag({ string_id: 'was-edited-away' }));
+  assert.equal(a.target_state, 'gone');
+  assert.equal(a.current, null);
+  // The status is untouched. Closing someone's judgement because a hash moved is
+  // exactly the silent wrong this goal exists to stop — 'gone' is a HINT to a
+  // person, never a verdict.
+  assert.equal(a.status, 'open');
+});
+
+await test('a flag whose string moved file or line shows where it is NOW', () => {
+  const a = registry.annotateFlag(INDEX, flag({ file_at_flag: 'old.js', line_at_flag: 7 }));
+  assert.equal(a.target_state, 'present');
+  assert.equal(a.moved, true);
+  assert.equal(a.current.file, 'h.js');
+  assert.equal(a.current.line, 42);
+  // The snapshot is preserved beside it — the artist can see both.
+  assert.equal(a.file_at_flag, 'old.js');
+});
+
+await test('a surface-scoped flag has no target state to report', () => {
+  const a = registry.annotateFlag(INDEX, flag({ scope: 'surface', string_id: null }));
+  assert.equal(a.target_state, 'n/a');
+  assert.equal(a.current, null);
+});
+
+console.log('copy-desk: the duplicate signal');
+
+await test('duplicates come from the registry, not recomputed here', () => {
+  const d = registry.duplicateCandidates(REG, new Set(), new Set());
+  assert.equal(d.length, 3);
+  assert.deepEqual(d.map((x) => x.id), ['dupA', 'dupB', 'dupC']);
+  assert.equal(d[1].occurrences, 3);
+});
+
+await test('an already-flagged duplicate is marked flagged', () => {
+  const d = registry.duplicateCandidates(REG, new Set(['dupA']), new Set());
+  assert.equal(d.find((x) => x.id === 'dupA').flagged, true);
+  assert.equal(d.find((x) => x.id === 'dupB').flagged, false);
+});
+
+await test('a duplicate someone looked at and DISMISSED is settled, not untouched', () => {
+  // Otherwise a judgement call ("this repetition is deliberate") reappears as
+  // fresh work forever, and the queue trains people to ignore it.
+  const d = registry.duplicateCandidates(REG, new Set(), new Set(['dupB']));
+  assert.equal(d.find((x) => x.id === 'dupB').settled, true);
+  assert.equal(d.find((x) => x.id === 'dupB').flagged, false);
+});
+
+await test('an open flag wins over a closed one for the same string', () => {
+  // A string flagged, resolved, then flagged again is OPEN work.
+  const d = registry.duplicateCandidates(REG, new Set(['dupC']), new Set(['dupC']));
+  const c = d.find((x) => x.id === 'dupC');
+  assert.equal(c.flagged, true);
+  assert.equal(c.settled, false);
+});
+
+console.log('copy-desk: the counts the surface leads with');
+
+await test('untouched duplicates subtract both flagged and settled', () => {
+  const q = registry.composeQueue({
+    registry: REG,
+    index: INDEX,
+    flags: [
+      flag({ id: 1, string_id: 'dupA', status: 'open' }),
+      flag({ id: 2, string_id: 'dupB', status: 'dismissed' }),
+    ],
+  });
+  assert.equal(q.counts.duplicates_total, 3);
+  assert.equal(q.counts.duplicates_untouched, 1, 'only dupC is untouched');
+});
+
+await test('the "target gone" pile is counted separately — it is the fastest to clear', () => {
+  const q = registry.composeQueue({
+    registry: REG,
+    index: INDEX,
+    flags: [
+      flag({ id: 1, string_id: 'live', status: 'open' }),
+      flag({ id: 2, string_id: 'vanished', status: 'open' }),
+      flag({ id: 3, string_id: 'also-vanished', status: 'open' }),
+      // A CLOSED flag on a vanished string is not outstanding work.
+      flag({ id: 4, string_id: 'long-gone', status: 'resolved' }),
+    ],
+  });
+  assert.equal(q.counts.flags_open, 3);
+  assert.equal(q.counts.flags_target_gone, 2);
+});
+
+await test('the counts describe EVERY flag in scope, not the filtered slice', () => {
+  // The bug this pins: viewing "resolved" would report "0 open flags" and
+  // re-surface every dismissed duplicate as untouched work. A stat panel that
+  // changes meaning when you change a filter is worse than no stat panel.
+  const every = [
+    flag({ id: 1, string_id: 'dupA', status: 'open' }),
+    flag({ id: 2, string_id: 'dupB', status: 'dismissed' }),
+    flag({ id: 3, string_id: 'live', status: 'resolved' }),
+  ];
+  const q = registry.composeQueue({
+    registry: REG,
+    index: INDEX,
+    flags: every.filter((f) => f.status === 'resolved'), // the filtered view
+    allFlags: every,
+  });
+  assert.equal(q.counts.flags_shown, 1, 'flags_shown is the only count about the filtered list');
+  assert.equal(q.counts.flags_open, 1, 'there IS one open flag, even though the view is "resolved"');
+  assert.equal(q.counts.duplicates_untouched, 1, 'dupB stays settled while the view is filtered');
+  assert.equal(q.duplicates.find((d) => d.id === 'dupA').flagged, true);
+});
+
+await test('allFlags defaults to flags for the unfiltered call', () => {
+  const rows = [flag({ id: 1, string_id: 'dupA', status: 'open' })];
+  const q = registry.composeQueue({ registry: REG, index: INDEX, flags: rows });
+  assert.equal(q.counts.flags_open, 1);
+  assert.equal(q.duplicates.find((d) => d.id === 'dupA').flagged, true);
+});
+
+await test('the payload names the artifact it is describing and how to check it is fresh', () => {
+  const q = registry.composeQueue({ registry: REG, index: INDEX, flags: [] });
+  assert.equal(q.registry.at, 'docs/copy-registry.json');
+  assert.ok(q.registry.freshness_check.includes('--check'));
+  assert.equal(q.registry.schema, 1);
+  // Deliberately NO generated_at: the generator is deterministic and carries no
+  // clock, so a timestamp here could only be the checkout's, dressed up as the
+  // generation's. See composeQueue's note.
+  assert.equal(q.registry.generated_at, undefined);
+});
+
+await test('the blind spots R01 documented travel with the queue', () => {
+  // The registry knows what it cannot see (server-side messages, skill prose,
+  // runtime-composed strings). An artist reading a queue built from it needs to
+  // know the inventory is partial, or they will read "1279 strings" as "all of them".
+  const q = registry.composeQueue({ registry: REG, index: INDEX, flags: [] });
+  assert.deepEqual(q.registry.blind_spots, ['server-side messages']);
+});
+
+console.log('copy-desk: finding a string to flag');
+
+await test('search matches on the text', () => {
+  const r = registry.searchEntries(REG, { q: 'could not' });
+  assert.equal(r.matched, 2);
+  assert.equal(r.entries.length, 2);
+});
+
+await test('search matches on the file path too — an engineer looks by file', () => {
+  const r = registry.searchEntries(REG, { q: 'h.js' });
+  assert.equal(r.matched, 1);
+  assert.equal(r.entries[0].id, 'live');
+});
+
+await test('search is scoped by surface when asked', () => {
+  assert.equal(registry.searchEntries(REG, { q: '', surface: 'nope' }).matched, 0);
+  assert.equal(registry.searchEntries(REG, { q: '', surface: 'builders-hall' }).matched, 3);
+});
+
+await test('already-flagged strings are marked, so nobody writes a reason to earn a 409', () => {
+  const r = registry.searchEntries(REG, { q: 'Enter' }, new Set(['live']));
+  assert.equal(r.entries[0].flagged, true);
+});
+
+await test('a truncated result SAYS it is truncated, and how many it matched', () => {
+  // A silently capped list reads as a complete one — an artist would conclude a
+  // string simply is not in the product.
+  const r = registry.searchEntries(REG, { q: '', limit: 1 });
+  assert.equal(r.entries.length, 1);
+  assert.equal(r.matched, 3);
+  assert.equal(r.truncated, true);
+});
+
+await test('the limit is clamped, not trusted', () => {
+  assert.equal(registry.searchEntries(REG, { limit: 100000 }).limit, 200);
+  assert.equal(registry.searchEntries(REG, { limit: -5 }).limit, 50);
+});
+
+console.log('copy-desk: a missing registry is a named state, not a crash');
+
+await test('loadRegistry on an absent file returns a named code and the fix', () => {
+  // Simulated by pointing the loader at a path that cannot exist is not possible
+  // without touching module internals, so this asserts the SHAPE the routes rely
+  // on: either { ok:true, registry, index } or { ok:false, code, detail }.
+  const loaded = registry.loadRegistry();
+  assert.equal(typeof loaded.ok, 'boolean');
+  if (loaded.ok) {
+    assert.ok(loaded.registry && loaded.index, 'a loaded registry carries both halves');
+    assert.ok(loaded.index.surfaces.size > 0, 'the real committed registry has surfaces');
+  } else {
+    assert.ok(['registry_missing', 'registry_unreadable'].includes(loaded.code));
+    assert.ok(loaded.detail.expected_at, 'the refusal says where the file should be');
+  }
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);