@bongos/core 1.19.250 → 1.19.251

package/modules/copy-desk/registry.js

@@ -0,0 +1,317 @@
+// modules/copy-desk/registry.js — the READ side of R01's committed copy registry
+// (task 1003113 / R02 of goal 1000074).
+//
+// R01 (scripts/gds/copy-inventory.js) walks the tree and writes
+// docs/copy-registry.json: every user-facing string, with a stable id, the file
+// and line it lives at, and the render path that puts it in front of a person.
+// This file READS that artifact and never writes it. The generator stays a
+// commit-it command in the gen-* family (deterministic, fs-only); the server
+// must not regenerate on request — that would make a GET depend on a tree walk
+// and let two replicas disagree about what the product says.
+//
+// CONSEQUENCE, AND IT IS THE HONEST ONE: the queue describes the registry AS
+// COMMITTED — the state of the deployed tree, not of anyone's working copy. The
+// failure mode is a queue that quietly describes a month-old tree, so the
+// payload names what it is reading (`registry.at`) and hands over the command
+// that proves freshness (`--check`). See composeQueue's note on why there is no
+// `generated_at` field to report.
+//
+// A MISSING REGISTRY IS A NAMED STATE, NOT A CRASH. A packaged core install may
+// not carry docs/, and a fresh instance has not run the generator yet. Both read
+// as `{ ok: false, code: 'registry_missing' }` with the command to fix it — never
+// an empty registry (which would read as "this product says nothing to anyone")
+// and never a 500.
+//
+// Everything below the loader is PURE — given a parsed registry and a list of
+// flag rows it computes the queue with no I/O — so the composition rules are
+// unit-testable without a DB or a tree (modules/copy-desk/tests/copy_queue.mjs).
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// The committed artifact, addressed the way R01 names it (REGISTRY_REL).
+// Resolved from THIS file so it works from any cwd.
+const REGISTRY_REL = 'docs/copy-registry.json';
+const REGISTRY_ABS = path.resolve(__dirname, '..', '..', REGISTRY_REL);
+// The command that produces it — quoted verbatim to the reader when it is
+// missing or stale, so the fix never has to be looked up.
+const GENERATOR_CMD = 'node scripts/gds/copy-inventory.js';
+
+// mtime+size cache. The registry is a committed file that changes at deploy, not
+// per request, so re-reading and re-parsing ~1300 rows on every queue load is
+// pure waste; keying on (mtimeMs, size) means a deploy invalidates it without a
+// restart and without a clock.
+//
+// THE READ IS SYNCHRONOUS, AND THAT IS THE CALL. statSync + readFileSync block
+// the event loop, which is normally the wrong thing to do inside a request. Here
+// the stat is ~microseconds and the parse (~400KB) runs only on a cache MISS —
+// once per deploy, not once per request. Making it async would buy a few
+// milliseconds on that one request and cost every caller an await plus a
+// concurrent-miss stampede guard, for a path that by construction runs once.
+// If the registry ever grows an order of magnitude, revisit this first.
+let _cache = null;
+
+function loadRegistry() {
+  let st;
+  try {
+    st = fs.statSync(REGISTRY_ABS);
+  } catch {
+    return { ok: false, code: 'registry_missing', detail: { expected_at: REGISTRY_REL, run: GENERATOR_CMD } };
+  }
+  const key = `${st.mtimeMs}:${st.size}`;
+  if (_cache && _cache.key === key) return _cache.value;
+
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(REGISTRY_ABS, 'utf8'));
+  } catch (err) {
+    // A corrupt registry is NOT a missing one — the fix is different (the file
+    // is there and wrong), so it gets its own code rather than being folded in.
+    return { ok: false, code: 'registry_unreadable', detail: { expected_at: REGISTRY_REL, reason: err.message } };
+  }
+  const value = { ok: true, registry: parsed, index: indexRegistry(parsed) };
+  _cache = { key, value };
+  return value;
+}
+
+// Test seam: drop the cache so a test can point at different registry content
+// in one process. Never called by the routes.
+function _resetCache() { _cache = null; }
+
+// ---------------------------------------------------------------------------
+// PURE below this line.
+// ---------------------------------------------------------------------------
+
+// Build the lookup structures the queue needs. The registry ships as ARRAYS
+// (deterministic byte-for-byte output is the generator's contract, and a map
+// would not order stably), so the index is built here rather than stored.
+//
+// ONE id can have MANY entries — that is exactly what a duplicate IS (the same
+// text, on the same surface, in seven places). So byId maps id → entry[], and a
+// caller that wants "the" occurrence takes the first. Mapping id → entry would
+// silently drop six of the seven settings.js copies of "Could not save."
+function indexRegistry(reg) {
+  const byId = new Map();
+  const entries = Array.isArray(reg && reg.entries) ? reg.entries : [];
+  for (const e of entries) {
+    if (!e || !e.id) continue;
+    const list = byId.get(e.id);
+    if (list) list.push(e); else byId.set(e.id, [e]);
+  }
+  const surfaces = new Set(Object.keys((reg && reg.surfaces) || {}));
+  return { byId, surfaces, schema: Number(reg && reg.schema) || null };
+}
+
+// Does this surface exist in the registry? The route validates against this
+// rather than a hardcoded list, so adding a surface to the generator is enough.
+function hasSurface(index, surface) {
+  return index.surfaces.has(String(surface || ''));
+}
+
+// The occurrences of one string id, or [] if the registry does not know it.
+function occurrencesOf(index, stringId) {
+  return index.byId.get(String(stringId || '')) || [];
+}
+
+// The snapshot a NEW flag stores: what this string reads as, right now. Taken
+// server-side from the registry rather than from the POST body, deliberately —
+// a client-supplied snapshot is a client-supplied claim about what the product
+// says, and the whole point of the snapshot is that it is trustworthy later.
+function snapshotFor(index, stringId) {
+  const [first] = occurrencesOf(index, stringId);
+  if (!first) return null;
+  return {
+    text: first.text ?? null,
+    file: first.file ?? null,
+    line: Number.isInteger(first.line) ? first.line : null,
+    surface: first.surface ?? null,
+    schema: index.schema,
+  };
+}
+
+// Search the inventory — the FIND half of filing a flag.
+//
+// Without this, the only strings a person could flag from a UI are the ones some
+// other signal already surfaced (the duplicates), which would make the queue
+// self-referential: it would only ever contain what a machine had already
+// noticed. The judgement this loop exists to capture is precisely the kind no
+// machine surfaces, so the person has to be able to go and find the sentence.
+//
+// Deliberately a plain case-insensitive substring over the text and the file
+// path — the same rule the module catalog's browse uses. Nothing here ranks or
+// scores: an artist is looking for a sentence they have already read somewhere,
+// not discovering one.
+//
+// PURE. `openFlagIds` marks rows that are already in the queue so the UI can
+// show it rather than letting someone file a duplicate flag and get a 409.
+function searchEntries(reg, { q = '', surface = null, limit = 50 } = {}, openFlagIds = new Set()) {
+  const needle = String(q || '').trim().toLowerCase();
+  const entries = Array.isArray(reg && reg.entries) ? reg.entries : [];
+  // A non-positive or non-numeric limit is nonsense input, not a request for
+  // one row — fall back to the default rather than clamping to 1, which would
+  // answer `?limit=-5` with a single result and look like an empty product.
+  const asked = Number(limit);
+  const cap = Math.min(Number.isFinite(asked) && asked > 0 ? Math.floor(asked) : 50, 200);
+
+  const out = [];
+  let matched = 0;
+  for (const e of entries) {
+    if (surface && e.surface !== surface) continue;
+    if (needle && !(
+      String(e.text || '').toLowerCase().includes(needle)
+      || String(e.file || '').toLowerCase().includes(needle)
+    )) continue;
+    matched++;
+    // Count every match but only carry `cap` of them, so the caller can be told
+    // how much it is NOT seeing. A silently truncated list reads as a complete
+    // one, and an artist would conclude a string simply is not in the product.
+    if (out.length < cap) {
+      out.push({ ...e, flagged: openFlagIds.has(e.id) });
+    }
+  }
+  return { entries: out, matched, truncated: matched > out.length, limit: cap };
+}
+
+// Attach live registry state to one stored flag row.
+//
+// The three states a string-scoped flag can be in, and why each is named:
+//   present  — the registry still has this id; the flag points at live copy.
+//   gone     — the id is absent. Either the string was EDITED (the id is a hash
+//              over its text, so an edit is a new id) or it was deleted. Both
+//              mean "the sentence this judgement was about no longer exists",
+//              which is a strong hint the flag is resolvable — but it is a HINT
+//              shown to a person, never an auto-resolve. Closing someone's
+//              judgement because a hash moved is exactly the kind of silent
+//              wrong this goal exists to stop.
+//   n/a      — surface-scoped flags have no string to be present or gone.
+function annotateFlag(index, flag) {
+  if (flag.scope !== 'string') {
+    return { ...flag, target_state: 'n/a', current: null, moved: false };
+  }
+  const occ = occurrencesOf(index, flag.string_id);
+  if (occ.length === 0) {
+    return { ...flag, target_state: 'gone', current: null, moved: false };
+  }
+  const first = occ[0];
+  // The file/line MOVED but the text did not (same id, different location) —
+  // worth showing so the artist opens the right file, not the one in the
+  // snapshot. Not a state of its own: the flag is still live.
+  const moved = Boolean(
+    flag.file_at_flag && (first.file !== flag.file_at_flag || first.line !== flag.line_at_flag)
+  );
+  return {
+    ...flag,
+    target_state: 'present',
+    current: { text: first.text, file: first.file, line: first.line, origin: first.origin, occurrences: occ.length },
+    moved,
+  };
+}
+
+// The DUPLICATE signal (the task's "ALSO": the queue must show copy that is
+// stale, duplicated or off-voice, and duplication is the one of the three a
+// machine can compute with no judgement layer at all).
+//
+// R01 already computes it — `registry.duplicates` is a deterministic list of
+// ids appearing in more than one place — so this does NOT recompute it. What it
+// adds is the only thing the raw list is missing for an artist: which of these
+// have already been dealt with. A duplicate someone flagged, or looked at and
+// dismissed, must not keep surfacing as untouched work; that is how a queue
+// becomes noise and stops being read.
+//
+// `openFlagIds` / `closedFlagIds` are Sets of string_id.
+function duplicateCandidates(reg, openFlagIds, closedFlagIds) {
+  const dups = Array.isArray(reg && reg.duplicates) ? reg.duplicates : [];
+  return dups.map((d) => ({
+    id: d.id,
+    surface: d.surface,
+    text: d.text,
+    occurrences: d.occurrences,
+    at: Array.isArray(d.at) ? d.at : [],
+    flagged: openFlagIds.has(d.id),
+    settled: !openFlagIds.has(d.id) && closedFlagIds.has(d.id),
+  }));
+}
+
+// Compose the whole artist queue from a loaded registry + the flag rows.
+//
+// TWO SETS OF ROWS, AND THE DISTINCTION IS LOAD-BEARING:
+//   `flags`    — what the caller asked to SEE (the status/surface filter).
+//   `allFlags` — every flag in the same surface scope, whatever its status.
+//
+// The COUNTS and the DUPLICATE annotations are computed from `allFlags`, never
+// from the filtered slice. Otherwise the summary lies whenever a filter is on:
+// switching the view to "resolved" would report "0 open flags" (there are none
+// IN THIS LIST) and would re-surface every already-dismissed duplicate as
+// untouched work. A stat panel that changes meaning when you change a filter is
+// worse than no stat panel. `allFlags` defaults to `flags` for the unfiltered
+// call, where the two are the same thing.
+//
+// `duplicates_untouched` is the number the surface leads with: duplicates nobody
+// has flagged AND nobody has settled. Leading with the raw total would be a
+// number that never moves however much work an artist does, which teaches them
+// the queue is decorative.
+function composeQueue({ registry, index, flags, allFlags }) {
+  const rows = Array.isArray(flags) ? flags : [];
+  const every = Array.isArray(allFlags) ? allFlags : rows;
+
+  // ONE pass over `every` for the id sets AND the counts. Four independent
+  // .filter() walks read more nicely but say the same predicate twice (once to
+  // build the set, once to count it), which is exactly how the two drift apart.
+  const openFlagIds = new Set();
+  const closedFlagIds = new Set();
+  let flagsOpen = 0;
+  let flagsTargetGone = 0;
+  for (const f of every) {
+    const isOpen = f.status === 'open';
+    if (isOpen) flagsOpen++;
+    if (f.string_id) (isOpen ? openFlagIds : closedFlagIds).add(f.string_id);
+    if (isOpen && f.scope === 'string' && occurrencesOf(index, f.string_id).length === 0) flagsTargetGone++;
+  }
+
+  const duplicates = duplicateCandidates(registry, openFlagIds, closedFlagIds);
+  return {
+    flags: rows.map((f) => annotateFlag(index, f)),
+    duplicates,
+    counts: {
+      // From `every`, not `rows` — see the header. flags_shown is the only count
+      // that describes the filtered list, and it is named so.
+      flags_open: flagsOpen,
+      flags_shown: rows.length,
+      // Flags whose string has vanished from the registry — surfaced as its own
+      // number because it is the queue's "probably already fixed, confirm it"
+      // pile, and it is the one an artist can clear fastest.
+      flags_target_gone: flagsTargetGone,
+      duplicates_total: duplicates.length,
+      duplicates_untouched: duplicates.filter((d) => !d.flagged && !d.settled).length,
+    },
+    // What this queue is describing (see the header). Always reported.
+    //
+    // NOTE ON FRESHNESS, stated rather than faked: there is deliberately no
+    // `generated_at` here, because the registry HAS no timestamp. R01 is in the
+    // gen-* family and its contract is determinism — same tree, byte-identical
+    // output — so a clock is exactly the field it cannot carry. The file's mtime
+    // is the checkout's, not the generation's, and reporting it as "generated"
+    // would be a plausible lie. The honest freshness answer is the generator's
+    // own `--check` (exit 1 if the artifacts are stale against the tree), so the
+    // command is handed to the reader instead of a number that looks like proof.
+    registry: {
+      schema: index.schema,
+      generator: (registry && registry.generator) || null,
+      goal: (registry && registry.goal) || null,
+      counts: (registry && registry.counts) || null,
+      surfaces: (registry && registry.surfaces) || null,
+      blind_spots: (registry && registry.blind_spots) || null,
+      at: REGISTRY_REL,
+      freshness_check: `${GENERATOR_CMD} --check`,
+    },
+  };
+}
+
+module.exports = {
+  REGISTRY_REL, REGISTRY_ABS, GENERATOR_CMD,
+  loadRegistry, _resetCache,
+  indexRegistry, hasSurface, occurrencesOf, snapshotFor, searchEntries,
+  annotateFlag, duplicateCandidates, composeQueue,
+};

package/modules/copy-desk/routes/copy-desk.js

@@ -0,0 +1,272 @@
+// modules/copy-desk/routes/copy.js — the copy-flag surface (task 1003113 / R02 of
+// goal 1000074, the artist's loop).
+//
+// Three jobs:
+//   GET  /copy-desk/queue            — the artist's working list: open flags with
+//                                 live registry state attached, plus the
+//                                 deterministic duplicate candidates.
+//   POST /copy-desk/flags            — file a flag. ANY signed-in builder, any role.
+//   POST /copy-desk/flags/:id/close  — resolve or dismiss one, with a note.
+//
+// THE RANK SHAPE, AND WHY IT IS ASYMMETRIC:
+//
+//   FILING is open to every rank, deliberately. "Sourced by everyone else" is the
+//   task's own framing: the engineer who just wrote a toast, the newcomer who
+//   could not understand a button, and the ideator reading the landing page are
+//   the three people most likely to notice bad copy, and none of them is the
+//   artist. A rank floor on filing would leave the queue empty and the goal
+//   unmet. The reason floor is the quality gate; rank is not.
+//
+//   CLOSING is Metic+, OR the flag's own author. Closing is a triage act — it is
+//   the same shape as idea triage and blocker resolution, which are Metic+ — but
+//   an author withdrawing their own flag is not triage, it is a correction, and
+//   nobody should need a promotion to take back something they filed by mistake.
+//   The refusal names both paths rather than dead-ending on a bare 403.
+//
+// WHAT DOES NOT EXIST HERE, AND MUST NOT: any route that writes a user-facing
+// string. NO LIVE CMS is the goal's hard non-goal (task 1003114 / R03 makes the
+// editing affordance produce a TASK, not a write). A flag is a work request.
+// modules/copy-desk/tests/copy_no_cms.mjs pins that by asserting this router's write
+// surface stays exactly these two verbs.
+//
+// Same idioms as modules/security/routes/*.js: doorway-only requires, res.fail
+// codes, factory export mounted from module.json contributes.
+
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const flags = require('../flags');
+const registry = require('../registry');
+
+const { validateOrRespond } = api;
+
+// The write schemas (ADR 0118): strict by default, so an unknown or typo'd field
+// is REJECTED rather than silently dropped. Built once at module scope — the
+// [...flags.KINDS] spreads mean a renamed export crashes at boot with a named
+// stack instead of throwing per-request forever.
+//
+// These pin SHAPE only. The domain rules — the reason floor, the registry
+// lookups, the scope/string_id coupling — live in flags.normalize*, so the DB
+// constraint, the pure validator and this schema each say one thing once.
+const FLAG_BODY_SCHEMA = Object.freeze({
+  scope:       { type: 'string', enum: [...flags.SCOPES] },
+  surface:     { required: true, type: 'string', maxLength: 128, minLength: 1 },
+  string_id:   { type: 'string', maxLength: 64 },
+  reason:      { required: true, type: 'string', maxLength: flags.MAX_REASON_CHARS, minLength: 1 },
+  kind:        { type: 'string', enum: [...flags.KINDS] },
+});
+const CLOSE_BODY_SCHEMA = Object.freeze({
+  status:           { required: true, type: 'string', enum: [...flags.CLOSING_STATUSES] },
+  resolution_note:  { required: true, type: 'string', maxLength: flags.MAX_NOTE_CHARS, minLength: 1 },
+  resolved_task_id: { type: 'integer', min: 1 },
+});
+
+// Load the registry or answer the named "no registry" state. Returns null when
+// it has already responded, so every handler is `if (!reg) return;`.
+//
+// A missing registry is a 503, not a 404: the surface EXISTS and is temporarily
+// unable to answer, and the payload carries the command that fixes it. A 404
+// would tell an artist the feature is not there.
+function registryOrFail(res) {
+  const loaded = registry.loadRegistry();
+  if (!loaded.ok) {
+    res.fail(loaded.code, 503, {
+      ...loaded.detail,
+      what_this_means: 'The copy queue reads the committed registry generated by R01. Without it there is no inventory to flag against.',
+    });
+    return null;
+  }
+  return loaded;
+}
+
+module.exports = function buildCopyDeskRouter() {
+  const router = express.Router();
+
+  // -------------------------------------------------------------------------
+  // GET /copy-desk/queue — the artist's working list.
+  //
+  // ?status=open (default) | resolved | dismissed | all
+  // ?surface=<registry surface id>
+  //
+  // rank: any signed-in builder. The queue is a work list, not a privilege —
+  // and an artist is a craft, not a rank (builders.preferred_disciplines), so
+  // gating this by rank would hide the artist's own queue from the artist.
+  // -------------------------------------------------------------------------
+  router.get('/copy-desk/queue', api.requireBuilder, async (req, res) => {
+    try {
+      const loaded = registryOrFail(res);
+      if (!loaded) return;
+
+      const status = String(req.query.status || 'open');
+      if (!['open', 'resolved', 'dismissed', 'all'].includes(status)) {
+        return res.fail('bad_status_filter', 400, { allowed: ['open', 'resolved', 'dismissed', 'all'] });
+      }
+      const surface = req.query.surface ? String(req.query.surface) : null;
+      if (surface && !registry.hasSurface(loaded.index, surface)) {
+        return res.fail('unknown_surface', 400, { surface, known: [...loaded.index.surfaces] });
+      }
+
+      // TWO reads, deliberately. The summary counts and the duplicate
+      // annotations must describe EVERY flag in scope, not the filtered slice —
+      // otherwise switching the view to "resolved" reports "0 open flags" and
+      // re-surfaces every already-dismissed duplicate as untouched work.
+      // composeQueue owns that rule; this just feeds it both sets. When the
+      // caller asked for everything the two are the same query, so it runs once.
+      const shown = await flags.listFlags({ status, surface });
+      const allFlags = status === 'all' ? shown : await flags.listFlags({ status: 'all', surface });
+
+      const queue = registry.composeQueue({
+        registry: loaded.registry,
+        index: loaded.index,
+        flags: shown,
+        allFlags,
+      });
+
+      queue.filter = { status, surface };
+      res.set('Cache-Control', 'no-store');
+      res.json(queue);
+    } catch (err) {
+      console.error('[gds] GET /copy-desk/queue', err);
+      if (!res.headersSent) res.fail('copy_queue_failed', 500);
+    }
+  });
+
+  // -------------------------------------------------------------------------
+  // GET /copy-desk/strings — search the inventory, to find something to flag.
+  //
+  // ?q= substring over text or file path · ?surface= · ?limit= (max 200)
+  //
+  // Read-only over the committed registry — no DB, no tree walk. rank: any
+  // signed-in builder, same reasoning as the queue.
+  // -------------------------------------------------------------------------
+  router.get('/copy-desk/strings', api.requireBuilder, async (req, res) => {
+    try {
+      const loaded = registryOrFail(res);
+      if (!loaded) return;
+
+      const surface = req.query.surface ? String(req.query.surface) : null;
+      if (surface && !registry.hasSurface(loaded.index, surface)) {
+        return res.fail('unknown_surface', 400, { surface, known: [...loaded.index.surfaces] });
+      }
+
+      // Mark what is already flagged so the UI can say so up front, instead of
+      // letting someone write a reason and then collect a 409.
+      const open = await flags.listFlags({ status: 'open', surface });
+      const openIds = new Set(open.filter((f) => f.string_id).map((f) => f.string_id));
+
+      const result = registry.searchEntries(
+        loaded.registry,
+        { q: req.query.q, surface, limit: req.query.limit },
+        openIds
+      );
+      res.set('Cache-Control', 'no-store');
+      res.json(result);
+    } catch (err) {
+      console.error('[gds] GET /copy-desk/strings', err);
+      if (!res.headersSent) res.fail('copy_search_failed', 500);
+    }
+  });
+
+  // -------------------------------------------------------------------------
+  // POST /copy-desk/flags — file a flag.
+  //
+  // Body: { scope, surface, string_id?, reason, kind? }
+  // rank: any signed-in builder (see the header).
+  // -------------------------------------------------------------------------
+  router.post('/copy-desk/flags', api.requireBuilder, async (req, res) => {
+    try {
+      if (validateOrRespond(req, res, FLAG_BODY_SCHEMA)) return;
+
+      const loaded = registryOrFail(res);
+      if (!loaded) return;
+
+      const norm = flags.normalizeFlagPayload(req.body, loaded.index, registry);
+      if (!norm.ok) return res.fail(norm.code, 400, norm.detail);
+
+      let flag;
+      try {
+        flag = await flags.insertFlag(norm.value, req.builder.id);
+      } catch (err) {
+        // 23505 = the one-open-flag-per-(builder,target) partial unique index.
+        // A named 409 rather than a 500: this is almost always a double-submit
+        // or a forgotten flag, and the person deserves to be told which.
+        if (err && err.code === '23505') {
+          return res.fail('already_flagged_by_you', 409, {
+            what_this_means: 'You already have an OPEN flag on this target. Another builder flagging it too is fine and is kept as signal; the same person twice is not.',
+          });
+        }
+        throw err;
+      }
+      res.status(201).json({ ok: true, flag });
+    } catch (err) {
+      console.error('[gds] POST /copy-desk/flags', err);
+      if (!res.headersSent) res.fail('copy_flag_failed', 500);
+    }
+  });
+
+  // -------------------------------------------------------------------------
+  // POST /copy-desk/flags/:id/close — resolve or dismiss.
+  //
+  // Body: { status: 'resolved'|'dismissed', resolution_note, resolved_task_id? }
+  // rank: metic+archon, OR the flag's author (see the header).
+  // -------------------------------------------------------------------------
+  router.post('/copy-desk/flags/:id/close', api.requireBuilder, async (req, res) => {
+    try {
+      if (validateOrRespond(req, res, CLOSE_BODY_SCHEMA)) return;
+
+      const id = api.parseId(req.params.id);
+      if (!id) return res.fail('bad_flag_id', 400);
+
+      const existing = await flags.getFlag(id);
+      if (!existing) return res.fail('flag_not_found', 404);
+
+      const isAuthor = String(existing.flagged_by) === String(req.builder.id);
+      if (!isAuthor && !api.rankMeetsThreshold(req.builder.rank, 'metic')) {
+        return res.fail('close_requires_metic_or_author', 403, {
+          what_this_means: 'Closing someone else\'s flag is a triage act, at the same floor as idea triage and blocker resolution. Your own flag you may always withdraw.',
+          your_options: ['Ask any Metic+ builder to close it', 'Add a comment to the task that fixes it and let the fixer close it'],
+        });
+      }
+
+      // Closed already — a named 409 rather than silently re-closing, so the
+      // second person sees the first person's verdict instead of overwriting it.
+      if (existing.status !== 'open') {
+        return res.fail('flag_already_closed', 409, {
+          status: existing.status,
+          resolution_note: existing.resolution_note,
+          resolved_at: existing.resolved_at,
+        });
+      }
+
+      const norm = flags.normalizeResolution(req.body);
+      if (!norm.ok) return res.fail(norm.code, 400, norm.detail);
+
+      let flag;
+      try {
+        flag = await flags.closeFlag(id, norm.value, req.builder.id);
+      } catch (err) {
+        // 23503 = the resolved_task_id FK. A typo'd task number is a user error,
+        // not a server one — answer it as such rather than letting the ledger
+        // link fail as an opaque 500 and leaving the flag open with no clue why.
+        if (err && err.code === '23503') {
+          return res.fail('resolved_task_not_found', 400, {
+            resolved_task_id: norm.value.resolved_task_id,
+            what_this_means: 'That task id does not exist. Leave it blank if the fix has no task yet — the close is still recorded, and the missing link is visible rather than wrong.',
+          });
+        }
+        throw err;
+      }
+      // Lost the race against a concurrent close (the UPDATE is guarded on
+      // status='open'). Same answer as the pre-check above.
+      if (!flag) return res.fail('flag_already_closed', 409);
+
+      res.json({ ok: true, flag });
+    } catch (err) {
+      console.error('[gds] POST /copy-desk/flags/:id/close', err);
+      if (!res.headersSent) res.fail('copy_flag_close_failed', 500);
+    }
+  });
+
+  return router;
+};