clearotron 0.4.1 → 0.5.0-beta.1

package/driver/record-carry.mjs

@@ -702,6 +702,61 @@ export function mintRecordCarryDoubts(artifact, { max = 25 } = {}) {
   return { doubts, minted: doubts.length, omitted: Math.max(0, all.length - doubts.length) };
 }
 
+/**
+ * THE RECORD-CARRY DOUBTS AGAIN, FROM A TRACE WRITTEN AGAIN after a repair. A doubt of this family names one record
+ * under a POSITIONAL id, and the closure step's verdicts are applied by id, so a closure recorded against an id must
+ * never move onto another record:
+ *   - a record still unreasoned keeps its doubt exactly as it stands: id, status and ending;
+ *   - a record newly unreasoned gets a new doubt, under an id past every one this family gave, stitched by `stitch` as
+ *     a fresh doubt is (in code; nothing is dispatched);
+ *   - a record the new trace POSITIVELY reasons, a row for it that is not unreasoned, loses its doubt;
+ *   - a record the new trace does not list at all keeps its doubt as it stands: an absence is not a ground.
+ * A trace that is missing or could not be computed (no readable band, among other causes) says nothing about any
+ * record, so it removes nothing and adds nothing: every doubt stands as the pass raised it (`unavailable: true`).
+ * Every other family's doubts stay exactly where they stood. The cap (`max`) limits only the new doubts: a record that
+ * keeps its doubt keeps it wherever the new trace lists it, or where it does not. Returns { doubts, fresh, dropped,
+ * minted, omitted, unavailable }: the ids of the new and the dropped doubts, the family's size, the records without a
+ * ground the cap left out, and whether the trace could be read at all. PURE.
+ */
+export function recordCarryDoubtsAgain(doubts, trace, { stitch = (ds) => ds, max = 25 } = {}) {
+  const FAMILY = /^doubt:record-carry:unreasoned:(\d+)$/;
+  const all = Array.isArray(doubts) ? doubts : [];
+  const inFamily = (d) => FAMILY.test(String(d?.id ?? ""));
+  const uriOf = (d) => String(d?.subject?.uris?.[0] ?? "").toLowerCase();
+  const old = all.filter(inFamily);
+  if (trace?.computable !== true) return { doubts: all, fresh: [], dropped: [], minted: old.length, omitted: 0, unavailable: true };
+  const oldByUri = new Map(old.filter((d) => uriOf(d)).map((d) => [uriOf(d), d]));
+  // Minted whole, then capped: a record that keeps its doubt keeps it wherever the new trace lists it, and the cap
+  // limits only the new doubts, filled in the trace's order up to what the kept ones leave.
+  const mint = mintRecordCarryDoubts(trace, { max: Infinity });
+  const unreasonedUris = new Set(mint.doubts.map(uriOf));
+  const listed = new Set((Array.isArray(trace?.rows) ? trace.rows : []).map((r) => String(r?.uri ?? "").toLowerCase()).filter(Boolean));
+  const reasoned = (uri) => listed.has(uri) && !unreasonedUris.has(uri);
+  const carried = old.filter((d) => !unreasonedUris.has(uriOf(d)) && !reasoned(uriOf(d)));   // not listed: kept as it stands
+  const keptCount = mint.doubts.filter((d) => oldByUri.has(uriOf(d))).length + carried.length;
+  let room = Math.max(0, max - keptCount);
+  let next = old.reduce((n, d) => Math.max(n, Number(FAMILY.exec(d.id)[1])), 0);
+  const family = [], fresh = [];
+  for (const d of mint.doubts) {
+    const prior = oldByUri.get(uriOf(d));
+    if (prior) family.push(prior);
+    else if (room > 0) { room--; const f = { ...d, id: `doubt:record-carry:unreasoned:${++next}` }; fresh.push(f); family.push(f); }
+  }
+  family.push(...carried);
+  const stitched = fresh.length ? new Map(stitch(fresh).map((d) => [d.id, d])) : new Map();
+  const members = family.map((d) => stitched.get(d.id) ?? d);
+  const keptIds = new Set(members.map((d) => d.id));
+  const out = [];
+  let placed = false;
+  for (const d of all) {
+    if (!inFamily(d)) { out.push(d); continue; }
+    if (!placed) { out.push(...members); placed = true; }
+  }
+  if (!placed) out.push(...members);
+  return { doubts: out, fresh: fresh.map((d) => d.id), dropped: old.filter((d) => !keptIds.has(d.id)).map((d) => d.id),
+    minted: members.length, omitted: Math.max(0, mint.doubts.length - (members.length - carried.length)), unavailable: false };
+}
+
 /**
  * The one-line reader answer to "where did this record stop, and why". Takes the artifact and a mark
  * text or uri; returns the matching rows. The acceptance question for — "does it say why 澜珀 did
@@ -915,12 +970,7 @@ export function statedDivergenceFindings({ reconciliation = null, carryRows = nu
   // So the carry rows are the population — they are where a stated drop is RECORDED — and the
   // reconciliation is demoted to optional corroboration. Measured on that delivery, the correct
   // population is 70 rows over 34 distinct marks, all `digest:reasoned-negative`, and it contains both.
-  const arrived = new Set(["finding", "findings-surface"]);
-  const population = carryRows.filter((r) => r?.uri
-    && r.reason_source === "step-stated"           // the sibling owns step-silent; step-structural is mechanical
-    && !arrived.has(r.reach));                     // arrived, or arrived somewhere visible, is not a divergence
-
-  // Kept for corroboration only. `ended` no longer gates anything; where the reconciliation DOES name a
+  // Kept for corroboration. `ended` gates nothing but one exclusion below; where the reconciliation DOES name a
   // position it agrees with, that is recorded on the row so a reader can weigh it.
   const ended = [];
   for (const bucket of ["top_slice", "residual"]) {
@@ -930,6 +980,20 @@ export function statedDivergenceFindings({ reconciliation = null, carryRows = nu
     }
   }
   const endedUris = new Set(ended.map((e) => e.uri));
+  const arrived = new Set(["finding", "findings-surface"]);
+  // PLACEMENT'S OWN SET-ASIDE IS NOT A LOST FINDING. A record placement set aside, by name or by its group's row,
+  // leaves the placement seam with the step's ground before the digest ever sees it: the ruled method's decision,
+  // recorded where it was made. Read as a stated drop it was listed as a divergence pointing at another artifact,
+  // and on a crowded band those rows buried the few this check is for. It stays in the population where the digest
+  // ended its position as a finding, because then the record did vanish: in the reconciliation, or in the finding
+  // rows the digest's own typed calls recorded, which the reconciliation's silence cannot erase.
+  const digestFound = new Set((Array.isArray(digestFindingUris) ? digestFindingUris : []).map(lc));
+  const placementSetAside = (r) => r.stopped_at === "placement" && r.reason === "placement:set-aside"
+    && !endedUris.has(lc(r.uri)) && !digestFound.has(lc(r.uri));
+  const population = carryRows.filter((r) => r?.uri
+    && r.reason_source === "step-stated"           // the sibling owns step-silent; step-structural is mechanical
+    && !arrived.has(r.reach)                       // arrived, or arrived somewhere visible, is not a divergence
+    && !placementSetAside(r));
   const byUri = new Map();
   for (const r of carryRows) if (r?.uri) byUri.set(lc(r.uri), r);
 

package/driver/record-discard.mjs

@@ -92,8 +92,13 @@ const clip = (s, n = 300) => {
  * not name cannot be distinguished between considered-and-not-selected and never reached at all. Those
  * rows carry `verdict: "discarded"` with `reason_source: "step-structural"` and a reason naming the
  * incompletion, so the fact survives; they are never silently folded into ordinary drops.
+ *
+ * A SKIPPED PASS DECIDED NOTHING. A resumed run skips a stage whose answer is on disk, and that answer is an
+ * earlier pass's. Where `prior` (the folded ledger) already holds that earlier pass's row for a record at this
+ * seam, the skipped pass writes none: under the winner rule an incompletion written over it erased every ground
+ * the step had given. A record no earlier pass spoke about is still recorded as not reached.
  */
-export function seamRows({ seam, stage, trigger = null, pass = 1, completed = true,
+export function seamRows({ seam, stage, trigger = null, pass = 1, completed = true, skipped = false, prior = null,
   saw = [], carried = [], reasonFor = null, evidence = "" } = {}) {
   if (!DISCARD_SEAMS.includes(seam)) return [];
   const carriedSet = new Set();
@@ -112,6 +117,7 @@ export function seamRows({ seam, stage, trigger = null, pass = 1, completed = tr
       continue;
     }
     if (!completed) {
+      if (skipped && prior?.byUri?.get?.(uri)?.[seam]) continue;
       rows.push({
         seam, stage, trigger, pass, uri, verdict: "discarded",
         reason: `${seam}:stage-incomplete`, reason_source: "step-structural",

package/driver/record-fold.mjs

@@ -153,6 +153,20 @@ export function modelRecordPath(runDir, findingsPath) {
   return readFold(runDir)?.map && existsSync(at) ? at : findingsPath;
 }
 
+/**
+ * The model's ordinal behind a finding of findings.json as it stands, given the fold state `readFold` returns.
+ * With no fold in force the file is the model's record, so the ordinal is its own. Under a fold a folded finding
+ * IS the object of the member the fold kept, so that member is the answer. Null when a fold is in force and its
+ * map does not name the finding: a caller then leaves it alone rather than guessing. PURE.
+ */
+export function keptModelOrdinal(state, ordinal) {
+  if (!state?.map) return ordinal;
+  const members = state.map.foldedToModel?.[String(ordinal)];
+  if (!Array.isArray(members) || !members.length) return null;
+  if (members.length === 1) return members[0];
+  return (state.merges ?? []).find((m) => members.includes(m?.kept))?.kept ?? null;
+}
+
 /** The fold as it stands, to put back if a pass that changed it is rolled back. Never throws. */
 export function snapshotFold(runDir) {
   const state = readFold(runDir);

package/driver/record-goods.mjs

@@ -77,12 +77,25 @@ export function recordGoods(body, { english = true } = {}) {
     }
   }
   if (out.length === 0 && Array.isArray(b?._raw?.classifications)) {
-    for (const c of b._raw.classifications) push([c?.nice_class], c?.goods_services_text, null, isEnglish(c?.goods_services_language) || (!tagged(c?.goods_services_language) && english));
+    for (const c of b._raw.classifications) {
+      const at = out.length;
+      push([c?.nice_class], c?.goods_services_text, null, isEnglish(c?.goods_services_language) || (!tagged(c?.goods_services_language) && english));
+      // The register's own flag, on the full record it serves (Signa, Retrieve Trademark, the classification
+      // object's `goods_services_text_truncated`): true is a cut, false is whole, and no flag establishes nothing.
+      if (out.length > at) {
+        if (c?.goods_services_text_truncated === true) out[at].cut = true;
+        else if (c?.goods_services_text_truncated !== false) out[at].unknown = true;
+      }
+    }
   }
   if (out.length === 0 && b.goodsAndServices != null) {
     const gs = b.goodsAndServices;
+    // One string is the register's own statement as this install's US index holds it, whole (uspto-local). A list
+    // is a register whose full-record operation this tree documents nowhere (EUIPO and the free tier): its goods
+    // are read, and their completeness is not established.
     if (typeof gs === "string") push([], gs, null, english);
     else if (Array.isArray(gs)) {
+      const from = out.length;
       for (const g of gs) {
         if (typeof g === "string") { push([], g, null, english); continue; }
         const d = g?.description;
@@ -91,11 +104,35 @@ export function recordGoods(body, { english = true } = {}) {
         push([g?.classNumber ?? g?.class ?? g?.niceClass ?? g?.nice_class], textOf(chosen ?? g?.text ?? g?.goods), null,
           Boolean(en) || (Array.isArray(d) ? !tagged(d[0]?.language) && english : english));
       }
+      for (let i = from; i < out.length; i++) out[i].unknown = true;
     }
   }
   return out;
 }
 
+/**
+ * WHAT A HELD RECORD'S GOODS REST ON: the operation its body came from, and whether that body supplies the goods
+ * field at all. PURE. `operation` is read off the body's shape, as `recordGoods` reads it:
+ *   · `record-text` — Clarivate's record text, the full record (its statements are whole: the accepted provenance);
+ *   · `retrieve` — Signa's Retrieve Trademark, the full record, each statement with the register's own flag;
+ *   · `bulk-register` — the register's own statement as this install's US index holds it, whole;
+ *   · `undocumented` — any other shape: its completeness is not established.
+ * `field` is `listed` (the field is there with goods), `empty` (there, listing none) or `none` (not there at
+ * all): a body whose goods field is missing, or that will not parse, is not one that lists no goods.
+ */
+export function recordGoodsProvenance(body) {
+  const b = Array.isArray(body) ? body[0] : body;
+  if (!b || typeof b !== "object") return { operation: "undocumented", field: "none" };
+  const said = (v) => String(textOf(v) ?? "").trim() !== "";
+  if (Array.isArray(b.goodsServices))
+    return { operation: "record-text", field: b.goodsServices.some((g) => said(g?.description) || said(g?.translation)) ? "listed" : "empty" };
+  if (Array.isArray(b?._raw?.classifications))
+    return { operation: "retrieve", field: b._raw.classifications.some((c) => said(c?.goods_services_text)) ? "listed" : "empty" };
+  if (typeof b.goodsAndServices === "string") return { operation: "bulk-register", field: b.goodsAndServices.trim() ? "listed" : "empty" };
+  if (b.goodsAndServices != null) return { operation: "undocumented", field: recordGoods(b).length ? "listed" : "empty" };
+  return { operation: "undocumented", field: "none" };
+}
+
 // THE RAW GOODS LIST SAYS NOTHING THE NORMALISED ONE DOES NOT. A Clarivate record holds its goods twice: as the
 // register wrote them (`_raw.goodsServices.intClassDescriptions`) and as the provider maps them, item for item,
 // into `goodsServices` beside it (providers/clarivate/src/core.js `normalizeGoodsServices`). On a crowded test
@@ -163,6 +200,59 @@ export function bandGoodsIndex(runDir) {
 /** The goods of one band row from an index, or null when the run holds none for it. PURE. */
 export const goodsFor = (index, record) => index?.get(normalizeRecordUri(record?.record_id)) ?? null;
 
+/**
+ * The goods a band row holds itself, where the register's search answer carries them: Signa sends each record's
+ * class statements on the search row (`raw.classifications`) and flags a statement it cut. Each statement is read as
+ * a held body's is (`recordGoods`) and marked `cut: true` where the register cut it, so a statement that stops early
+ * is never read as the whole of its class. null when the row holds none. PURE.
+ *
+ * WHOLE ONLY WHERE THE ANSWER SAYS SO. The search answer our request asks for is the register's default, which it
+ * documents as "the first 280 characters" of each statement (docs.signa.so, Search Trademarks, "Response options",
+ * `include`: "`full_goods_services` returns the full goods and services text instead of the first 280
+ * characters"); the request never asks for the full text. So a statement shorter than 280 characters is whole, a
+ * flagged one is cut, and an unflagged one of 280 characters or more is marked `unknown: true`: its completeness is
+ * not established, and missing words in it establish nothing.
+ */
+export const DEFAULT_ANSWER_CUT = 280;
+export function rowGoods(row) {
+  const classes = Array.isArray(row?.raw?.classifications) ? row.raw.classifications : null;
+  if (!classes) return null;
+  const english = untaggedIsEnglish(normalizeRecordUri(row?.record_id));
+  const out = [];
+  for (const c of classes) {
+    const [g] = recordGoods({ _raw: { classifications: [c] } }, { english });
+    if (!g) continue;
+    const { cut: _cut, unknown: _unknown, ...whole } = g;   // the row's own rule below, not the full record's
+    if (c?.goods_services_text_truncated === true) out.push({ ...whole, cut: true });
+    else if ([...String(c?.goods_services_text ?? "")].length >= DEFAULT_ANSWER_CUT) out.push({ ...whole, unknown: true });
+    else out.push(whole);
+  }
+  return out.length ? out : null;
+}
+
+/**
+ * Was a statement of these goods cut short by the register? A record whose statements match no word, while one of
+ * them stops where the register cut it, is unknown to the goods test, not a mismatch: the words cut off may be the
+ * client's. Only goods read off a band row carry the mark (`rowGoods`); a held body's statements are whole. PURE.
+ */
+export const statementCut = (goods) => (goods ?? []).some((g) => g?.cut === true);
+
+/** Is a statement of these goods one whose completeness is not established (`rowGoods`, `recordGoods`)? PURE. */
+export const completenessUnknown = (goods) => (goods ?? []).some((g) => g?.unknown === true);
+/** Could words cut off, or not shown, from these goods be the client's? Then a statement matching none is unknown. PURE. */
+const notWhole = (goods) => statementCut(goods) || completenessUnknown(goods);
+
+/** How many records rest on each kind of goods evidence: a held body, a row's whole statements, a row's statements cut short or not established whole, or none. PURE. */
+export function goodsEvidence(records, goods) {
+  const out = { held: 0, complete: 0, cut: 0, unknown: 0, none: 0 };
+  for (const r of Array.isArray(records) ? records : []) {
+    if (goods?.held?.(r)) { out.held++; continue; }
+    const g = goods ? goods.of(r) : null;
+    if (!g) out.none++; else if (statementCut(g)) out.cut++; else if (completenessUnknown(g)) out.unknown++; else out.complete++;
+  }
+  return out;
+}
+
 const fold = (s) => foldDiacritics(String(s ?? "")).toLowerCase();
 const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 
@@ -206,7 +296,7 @@ export function goodsWordCounter(words, { stems = false } = {}) {
     if (!res.length || !readable.length) return null;
     const text = fold(readable.map((g) => (g.alt ? `${g.text}\n${g.alt}` : g.text)).join("\n"));
     const n = res.filter((re) => re.test(text)).length;
-    return n === 0 && classUnread(goods) ? null : n;
+    return n === 0 && (classUnread(goods) || notWhole(goods)) ? null : n;
   };
 }
 
@@ -238,7 +328,7 @@ export function goodsWordsMatched(words, { stems = false } = {}) {
   return (goods) => {
     if (!list.length || !(goods ?? []).some((g) => g.en !== false)) return null;
     const hit = tests.filter(([, t]) => t(goods) === 1).map(([w]) => w);
-    return hit.length === 0 && classUnread(goods) ? null : hit;
+    return hit.length === 0 && (classUnread(goods) || notWhole(goods)) ? null : hit;
   };
 }
 
@@ -269,8 +359,12 @@ export function instructedOrder(P, job = null) {
  * search asked for beside the one the variants stage named. The client's markets come from the caller:
  * this module is loaded by the band tool server, which reads no account settings. IMPURE (reads the run).
  * Any part that cannot be read is simply absent, and the shape sorts without it.
+ *
+ * A record's goods are its held body's, and where the run holds no body, the statements its band row carries
+ * (`rowGoods`). `held` says which: a line's goods are "on file" only where a body is held, because that is the
+ * record `band_record` can open. `records` are the band's, so the shape tests goods whenever either is held.
  */
-export function bandShapeGoods(P) {
+export function bandShapeGoods(P, records = []) {
   let model = null;
   try { if (existsSync(P.variantManifestModel)) model = parseVariantManifestModel(readFileSync(P.variantManifestModel, "utf8")); } catch { model = null; }
   let searched = "";
@@ -285,7 +379,9 @@ export function bandShapeGoods(P) {
   const words = product ? model.product_words : Array.isArray(model?.goods_words) ? model.goods_words : [];
   const stems = true;   // the word list the shape groups on is matched as stems, whichever source it came from
   const hits = goodsWordCounter(words, { stems });
-  const goods = index.size ? { of: (r) => goodsFor(index, r), hits, matched: goodsWordsMatched(words, { stems }) } : null;
+  const held = (r) => goodsFor(index, r);
+  const rowsHold = Array.isArray(records) && records.some((r) => r && typeof r === "object" && rowGoods(r));
+  const goods = index.size || rowsHold ? { of: (r) => held(r) ?? rowGoods(r), held: (r) => held(r) != null, hits, matched: goodsWordsMatched(words, { stems }) } : null;
   const goodsTest = { source: product ? "product_words" : words.length ? "goods_words" : "none", words };
   return { goods, goodsTest, goodsWordCount: words.length, dominantTerm: searched || manifestDominant, manifestDominant };
 }

package/driver/register-plan.mjs

@@ -59,6 +59,8 @@ import { normalizeTerritory } from "../providers/_shared/territory-codes.mjs";
 import { bindingLayersFor, layerCoverageFor } from "./binding-layers.mjs";
 import { entryTermIssues, goodsTermsList, stripGoodsReservedWords, hasAnchoredWildcard, termAnnotationIssue, termMarkupIssue, termShapeIssue, termSubstanceIssue } from "../providers/_shared/term-shape.mjs";
 import { AWAITS_READING_TURN, awaitsReadingTurn, guardParentQid } from "../providers/_shared/plan-guards.mjs";
+import { asksIdenticalMark, identicalMarkTerms } from "../providers/_shared/follow-up-searches.mjs";
+import { territoryKey } from "./territory-tiers.mjs";
 import { formKey, romanizationSpellings, isNonLatinTerm } from "../providers/_shared/script-form.mjs"; import { marketsFilingScriptOf } from "./registration-scripts.mjs";
 
 export const PLAN_SCHEMA_VERSION = 1;
@@ -2155,6 +2157,95 @@ export function foldSupplementalEntries(plan, entries) {
   };
 }
 
+/**
+ * THE WAITING FAMILIES THE READING TURN WITHHELD, keyed by the question each one asks.
+ *
+ * A wider family waits in the plan until the reading turn asks for it, and the turn records each family it
+ * leaves unasked as withheld-by-judgment, with its reason (withheld-families.mjs). The fold above lets a
+ * question through when it matches a waiting family, because the turn's own ask of that question is what the
+ * family waits for. That rule cannot tell the turn's ask from anyone else's, and the blind frame comparison's
+ * re-sweep turns its requests into questions by code: its contains question on the mark is such a family, so
+ * it asked families the turn had withheld. This map is what lets the re-sweep tell them apart.
+ *
+ * A family is in it only when all of these hold, because each one missing is a way a question could inherit
+ * a judgment nobody made:
+ *   · it waits for the reading turn in this plan: a required row has no withholding to inherit;
+ *   · the turn's record names it, on its own axis, with a reason: a family nobody judged is still open;
+ *   · it is not released: a release replaces the withholding;
+ *   · no plan row that does not wait asks the same question: that row is the one that answers it, and the
+ *     fold's duplicate rule names it as the twin.
+ * `withheld` is the record as readWithheldFamilies returns it, `{ [qid]: { axis, reason } }`, and `released`
+ * the set releasedFamilyQids returns. The caller reads both, so this stays PURE.
+ * @returns {Map<string, {qid: string, reason: string}>} question key → the withheld family and its reason
+ */
+export function withheldFamilyTwins(plan, withheld = {}, released = new Set()) {
+  const entries = Array.isArray(plan?.entries) ? plan.entries : [];
+  const asked = new Set(entries.filter((e) => e && e.unsupported !== true && !awaitsReadingTurn(e.when))
+    .map((e) => entryQuestionKey(e, plan)).filter(Boolean));
+  const twins = new Map();
+  for (const e of entries) {
+    if (!e?.qid || e.unsupported === true || !awaitsReadingTurn(e.when) || released?.has?.(e.qid)) continue;
+    const w = withheld?.[e.qid];
+    const reason = String(w?.reason ?? "").trim();
+    if (!reason || (w?.axis != null && String(w.axis) !== String(e.axis ?? ""))) continue;
+    const key = entryQuestionKey(e, plan);
+    if (key && !asked.has(key) && !twins.has(key)) twins.set(key, { qid: e.qid, reason });
+  }
+  return twins;
+}
+
+/**
+ * WHAT A RE-SWEEP THAT ADDS NOTHING STILL OWES ITS AXIS: the axis's entries that have not landed. The executor reads
+ * an empty question list as every entry on the axis, so a fold that added nothing used to repeat every landed
+ * question and, with them, retry the ones still unanswered. These are that retry without the repeats: every entry
+ * on the axis the provider can express (`unsupported` is never sent), a family waiting for the reading turn only once
+ * the turn released it, less every entry the join of these bands counts as executed, a released family's block
+ * included. So it sends a required search that did not land, and also what the old re-send retried among the
+ * unlanded: an entry whose provider error spent its retry ladder (a real call, as before), a capability refusal not
+ * yet accepted as a gap (refused again without a call), and a fringe entry whose guard the executor still holds
+ * (no call). The dispatcher drops the capability gaps the run has already accepted. PURE.
+ * @param {object} plan  the frozen register plan
+ * @param {string} axis  the axis the re-sweep ran on
+ * @param {object} bandsByAxis  the run's register bands, as readRegisterBands returns them
+ * @param {Set<string>} released  the families the reading turn released (releasedFamilyQids)
+ */
+export function pendingRequiredQids(plan, axis, bandsByAxis = {}, released = new Set()) {
+  const landed = new Set(joinPlanToBands(plan, bandsByAxis, { released }).executed.map((x) => x.qid));
+  return (Array.isArray(plan?.entries) ? plan.entries : [])
+    .filter((e) => e?.qid && e.axis === axis && e.unsupported !== true && (!awaitsReadingTurn(e.when) || released?.has?.(e.qid))
+      && !landed.has(e.qid))
+    .map((e) => e.qid);
+}
+
+/**
+ * Refuse the minted entries that repeat a withheld family exactly, before they reach the fold. "Exactly" is
+ * the fold's own question identity (entryQuestionKey: offices resolved, classes, goods, owner, term form), so
+ * the same term asked in other classes, other offices or narrowed by goods is a different question and is
+ * kept. Each refusal is `withheld-by-judgment`, its twin is the family, and it carries the reason on the
+ * family's record, so the closure rule (close-verify.mjs, withheldAs) settles the slice by that judgment:
+ * the slice is never frozen into the plan and never runs, and the family stays waiting, so the reading turn
+ * can still release it.
+ *
+ * NOT A SCREEN IN THE FOLD ITSELF, deliberately. The fold is the funnel for the reading turn's own proposals
+ * as well, and the turn's ask of a family it once withheld is that turn reconsidering, which the waiting rule
+ * exists to let through. Only the re-sweep, which asks on nobody's judgment, calls this.
+ *
+ * Every other entry is KEPT for the fold, which screens it as before. An entry whose qid the plan already
+ * holds is kept too: the fold reads it as a re-proposal of a row that is already there. PURE.
+ * @returns {{ kept: object[], refused: {qid: string, term: string, kind: "withheld-by-judgment", twin: string, reason: string}[] }}
+ */
+export function refuseWithheldFamilies(entries, twins, plan) {
+  const inPlan = new Set((plan?.entries ?? []).map((e) => e?.qid));
+  const kept = [], refused = [];
+  for (const e of Array.isArray(entries) ? entries : []) {
+    const key = e?.qid && !inPlan.has(e.qid) ? entryQuestionKey(e, plan) : null;
+    const twin = key ? twins?.get?.(key) : undefined;
+    if (!twin) { kept.push(e); continue; }
+    refused.push({ qid: e.qid, term: String(e.term ?? e.terms?.[0] ?? ""), kind: "withheld-by-judgment", twin: twin.qid, reason: twin.reason });
+  }
+  return { kept, refused };
+}
+
 /**
  * The store decision (pure — the attach step does only IO around this): given the slug store's
  * latest plan (or null) and a fresh compile, decide reuse / extend / mint.
@@ -2319,6 +2410,110 @@ export function parseRegisterPlan(raw) {
   return { ...p };
 }
 
+// ── WHAT THE RUN RETRIEVED UNDER EACH CROWD ──────────────────────────────────────────────────────────
+//
+// A crowd is a question that ran and counted more than it read. This records, from the run's own blocks and plan,
+// what was retrieved under it, and nothing more: whether the reading happened, and whether a crowd is set aside, are
+// the reading step's and the write-up's judgments, recorded in their own places. Retrieving a list is not reading it.
+//
+// A NARROWING ASKS THE SAME QUESTION WITH TIGHTER LIMITS: the same predicate and the same terms, classes and markets
+// within the parent's, and the parent's goods words or fewer of them (a parent with none takes the client's goods
+// words, as the plan holds them), with the same owner. A list counts when its block is `enumerated`: complete, with no
+// error. Only lists reached through such narrowings count, at any depth.
+//   list-retrieved          a wider question with at least one narrowed list retrieved in full (named in `lists`).
+//   no-list                 a wider question with none: the reading step decides it, with its count on the record.
+//   required-covered        the identical mark's own question, with a retrieved list in every class it asks, in
+//                           every main market (the order's countries, else the customer's priority markets, else the
+//                           major markets), or worldwide where the run names none.
+//   required-not-covered    the identical mark's own question without that: the class and market cells no retrieved
+//                           list covers are named in `not_covered`.
+// A refused or failed question is not a crowd: the join keeps those as `outstanding` and `missing`. Each reader (the
+// receipt, the coverage form, the band shape) works this out from the blocks it reads itself. It changes no row's
+// state and no sentence. PURE.
+const WORLDWIDE = "worldwide";
+export function crowdNarrowing(plan, byQid, { mainMarkets = [] } = {}) {
+  const entries = Array.isArray(plan?.entries) ? plan.entries : [];
+  const identicalTerms = identicalMarkTerms(plan);
+  const childrenOf = new Map();
+  for (const e of entries) {
+    const parent = typeof e?.narrows === "string" ? e.narrows.trim() : "";
+    if (!parent || !e?.qid) continue;
+    if (!childrenOf.has(parent)) childrenOf.set(parent, []);
+    childrenOf.get(parent).push(e);
+  }
+  const strs = (v) => (Array.isArray(v) ? v.map((x) => String(x).trim()).filter(Boolean) : []);
+  const fold = (s) => String(s ?? "").normalize("NFKC").trim().toLowerCase().replace(/\s+/g, " ");
+  const marketsOf = (v) => [...new Set(strs(v).map((t) => territoryKey(t) || t.toUpperCase()))];
+  const regionsOf = (e) => (strs(e?.regions).length ? marketsOf(e.regions) : marketsOf(plan?.regions));
+  const classesOf = (e) => [...new Set(strs(e?.nice_classes))];
+  const termsOf = (e) => [...new Set((Array.isArray(e?.terms) && e.terms.length ? e.terms : [e?.term]).map(fold).filter(Boolean))].sort();
+  const goodsOf = (e) => [...new Set(goodsTermsList(e).map(fold).filter(Boolean))];
+  // the client's goods words, as the plan's own goods questions carry them
+  const clientGoods = new Set(entries.filter((e) => e?.provenance === "mark").flatMap(goodsOf));
+  const within = (inner, outer) => !outer.length || (inner.length > 0 && inner.every((x) => outer.includes(x)));
+  const sameTerms = (a, b) => a.length === b.length && a.every((t, i) => t === b[i]);
+  const narrows = (parent, child) => {
+    if (String(child.predicate ?? "") !== String(parent.predicate ?? "") || !sameTerms(termsOf(child), termsOf(parent))) return false;
+    if (!within(classesOf(child), classesOf(parent)) || !within(regionsOf(child), regionsOf(parent))) return false;
+    if (String(parent.owner ?? "").trim() !== String(child.owner ?? "").trim()) return false;
+    const pg = goodsOf(parent), cg = goodsOf(child);
+    if (pg.length) return cg.length > 0 && cg.every((g) => pg.includes(g));
+    return !cg.length || !clientGoods.size || cg.every((g) => clientGoods.has(g));
+  };
+  const stateOf = (qid) => { const b = byQid.get(qid); return b && b.error !== true ? String(b.state ?? "").toLowerCase() : null; };
+  const retrievedUnder = (e, seen) => {
+    const out = [];
+    for (const c of childrenOf.get(e.qid) ?? []) {
+      if (seen.has(c.qid) || !narrows(e, c)) continue;
+      seen.add(c.qid);
+      if (stateOf(c.qid) === "enumerated") out.push(c);
+      out.push(...retrievedUnder(c, seen));
+    }
+    return out;
+  };
+  const main = marketsOf(mainMarkets);
+  const rows = [];
+  for (const e of entries) {
+    if (!e?.qid || e.expected_kind === "count" || stateOf(e.qid) !== "incomplete") continue;
+    const lists = retrievedUnder(e, new Set([e.qid]));
+    const total = byQid.get(e.qid)?.total_hits;
+    const row = { qid: e.qid, axis: e.axis ?? null, ...(Number.isFinite(Number(total)) && total != null ? { total_hits: Number(total) } : {}) };
+    const named = lists.length ? { lists: lists.map((c) => c.qid).slice(0, 12) } : {};
+    if (!asksIdenticalMark(e, identicalTerms)) {
+      rows.push({ ...row, narrowing: lists.length ? "list-retrieved" : "no-list", ...named });
+      continue;
+    }
+    // THE REQUIRED READ, CELL BY CELL: every class the question asks, in every main market inside its scope, or the
+    // whole scope where the run names no main market. A worldwide scope is one cell per class, and only a worldwide
+    // list covers it: an empty market list is never read as "every market covered".
+    const scope = regionsOf(e);
+    const inScope = main.length ? (scope.length ? main.filter((m) => scope.includes(m)) : main) : [];
+    const cellMarkets = inScope.length ? inScope : (scope.length ? scope : [WORLDWIDE]);
+    const cellClasses = classesOf(e).length ? classesOf(e) : ["*"];
+    const covers = (c, m) => lists.some((d) => {
+      const dc = classesOf(d), dr = regionsOf(d);
+      const classOk = c === "*" ? !dc.length : (!dc.length || dc.includes(c));
+      const marketOk = m === WORLDWIDE ? !dr.length : (!dr.length || dr.includes(m));
+      return classOk && marketOk;
+    });
+    const notCovered = [];
+    for (const c of cellClasses) for (const m of cellMarkets) if (!covers(c, m)) notCovered.push(c === "*" ? m : `${c}/${m}`);
+    rows.push(notCovered.length
+      ? { ...row, narrowing: "required-not-covered", ...named, not_covered: notCovered.slice(0, 40) }
+      : { ...row, narrowing: "required-covered", ...named });
+  }
+  const count = (k) => rows.filter((r) => r.narrowing === k).length;
+  return { list_retrieved: count("list-retrieved"), no_list: count("no-list"), required_covered: count("required-covered"),
+    required_not_covered: count("required-not-covered"), rows };
+}
+
+/** Every band block with a qid, by qid, across the axes: the blocks a crowd's ending is read from. PURE. */
+export function blocksByQidOf(bandBlocksByAxis) {
+  const byQid = new Map();
+  for (const arr of Object.values(bandBlocksByAxis ?? {})) for (const b of arr ?? []) if (b && typeof b.qid === "string" && b.qid) byQid.set(b.qid, b);
+  return byQid;
+}
+
 // ── fan-in: identity join plan ⇄ band blocks ────────────────────────────────────────────────────
 
 /**
@@ -2334,7 +2529,7 @@ export function parseRegisterPlan(raw) {
  * An entry whose `when` guard resolves FALSE (parent crowd/absent) is `skipped`, never `missing`.
  * Blocks with no qid join nothing (legacy bands) and surface as unplanned only when they carry one.
  */
-export function joinPlanToBands(plan, bandBlocksByAxis, { released = new Set() } = {}) {
+export function joinPlanToBands(plan, bandBlocksByAxis, { released = new Set(), outstanding = new Set(), mainMarkets = [] } = {}) {
   const blocks = [];
   for (const [axis, arr] of Object.entries(bandBlocksByAxis ?? {})) {
     for (const b of arr ?? []) if (b && typeof b === "object") blocks.push({ ...b, _axis: axis });
@@ -2343,6 +2538,11 @@ export function joinPlanToBands(plan, bandBlocksByAxis, { released = new Set() }
   for (const b of blocks) if (typeof b.qid === "string" && b.qid) byQid.set(b.qid, b);
 
   const executed = [], missing = [], skipped = [], deferred = [], awaiting = [], asked = [];
+  // A FOLLOW-UP THE RUN'S SAFETY NET DID NOT SEND (providers/_shared/follow-up-searches.mjs) that holds no answer is a
+  // question not asked, never one that went missing: missing sends a question back to be run, and the net would hold
+  // it again. Only a follow-up can be refused; the plan's own questions never are.
+  const notAsked = [];
+  const refusedFollowUp = (e) => outstanding.has(e?.qid) && e?.origin === "supplemental";
   // A WAITING FAMILY THE READING TURN ASKED IS NOT WAITING. Its ask arrives as an ordinary entry — a
   // supplemental with the same question — and the family's own row stays guarded forever, so without this
   // link every family asked read as never asked. Matched on the question (entryQuestionKey), against
@@ -2352,6 +2552,12 @@ export function joinPlanToBands(plan, bandBlocksByAxis, { released = new Set() }
     if (e?.unsupported === true || awaitsReadingTurn(e?.when)) continue;
     const k = entryQuestionKey(e, plan);
     if (k && !askedBy.has(k)) askedBy.set(k, e.qid);
+    // A LIST ASKS EACH OF ITS SPELLINGS, with the list's own scope: a family asked inside a batch that went to the
+    // register as one list is asked by that list.
+    if (Array.isArray(e?.terms) && e.terms.length > 1) for (const t of e.terms) {
+      const kt = entryQuestionKey({ ...e, terms: undefined, term: t }, plan);
+      if (kt && !askedBy.has(kt)) askedBy.set(kt, e.qid);
+    }
   }
   for (const e of plan.entries) {
     if (e.when) {
@@ -2391,7 +2597,7 @@ export function joinPlanToBands(plan, bandBlocksByAxis, { released = new Set() }
       }
     }
     const b = byQid.get(e.qid);
-    if (!b) { missing.push(e.qid); continue; }
+    if (!b) { if (refusedFollowUp(e)) { notAsked.push({ qid: e.qid, axis: e.axis }); continue; } missing.push(e.qid); continue; }
     // A DETERMINISTIC CAPABILITY GAP (providers/_shared/execute-plan.mjs stamps `deferred:true` next to
     // `error:true`): the active provider genuinely cannot express this slice — a predicate it lacks, an
     // office outside its vocabulary, a term its query language cannot state. Retrying is pointless: the
@@ -2405,7 +2611,7 @@ export function joinPlanToBands(plan, bandBlocksByAxis, { released = new Set() }
     // incomplete shape — the dictated slice never really ran. It joins as MISSING (→ the warm
     // followup re-invokes the executor; exhaustion is an honest StageFailure), never as an
     // "executed" crowd — a transient must not ship indistinguishable from a sanctioned descriptor.
-    if (b.error === true) { missing.push(e.qid); continue; }
+    if (b.error === true) { if (refusedFollowUp(e)) { notAsked.push({ qid: e.qid, axis: e.axis }); continue; } missing.push(e.qid); continue; }
     // — WHAT THE SLICE RETURNED RIDES WITH THE FACT THAT IT RAN.
     //
     // "executed" answers "did the query run". It has never answered "did anything come back", and the
@@ -2447,7 +2653,10 @@ export function joinPlanToBands(plan, bandBlocksByAxis, { released = new Set() }
   const planQids = new Set(plan.entries.map((e) => e.qid));
   const unplanned = blocks.filter((b) => typeof b.qid === "string" && b.qid && !planQids.has(b.qid))
     .map((b) => ({ qid: b.qid, query: String(b.query ?? "").slice(0, 80) }));
-  return { executed, missing, skipped, deferred, awaiting, asked, unplanned };
+  // what was retrieved under each crowd, worked out from the same blocks (crowdNarrowing, above): on the receipt only when there is a crowd
+  const crowds = crowdNarrowing(plan, byQid, { mainMarkets });
+  return { executed, missing, skipped, deferred, awaiting, asked, unplanned, ...(notAsked.length ? { outstanding: notAsked } : {}),
+    ...(crowds.rows.length ? { crowd_narrowing: crowds } : {}) };
 }
 
 // ──: the slice the provider ACCEPTED and then hard-errored at RUN time ──────────────────────────
@@ -2650,6 +2859,7 @@ export function deriveCoverageSkeleton(plan, join) {
   const skippedQids = new Set(join.skipped.map((x) => x.qid));
   const deferredQids = new Set((join.deferred ?? []).map((x) => x.qid));
   const awaitingQids = new Set((join.awaiting ?? []).map((x) => x.qid));
+  const outstandingQids = new Set((join.outstanding ?? []).map((x) => x.qid));
   const askedQids = new Set((join.asked ?? []).map((x) => x.qid));
   // ── A COUNT THE PLAN ALSO READ IN FULL IS NOT A CROWD ──────────────────────────────────────────
   // A count-only descriptor (the saturation probe's shape) sizes a question and reads none of its
@@ -2674,7 +2884,7 @@ export function deriveCoverageSkeleton(plan, join) {
     && readInFull.get(question(e)) === totalByQid.get(e.qid);
   const axes = new Map();
   for (const e of plan.entries) {
-    if (!axes.has(e.axis)) axes.set(e.axis, { axis: e.axis, entries: 0, executed: 0, crowds: 0, missing: [], skipped: 0, deferred: [], awaiting: 0, asked: 0, readElsewhere: 0 });
+    if (!axes.has(e.axis)) axes.set(e.axis, { axis: e.axis, entries: 0, executed: 0, crowds: 0, missing: [], skipped: 0, deferred: [], awaiting: 0, asked: 0, readElsewhere: 0, outstanding: 0 });
     const a = axes.get(e.axis);
     a.entries++;
     // COUNTED BEFORE `skipped`, and separately from it. With the families waiting on every matter this is the ordinary state of
@@ -2686,6 +2896,8 @@ export function deriveCoverageSkeleton(plan, join) {
     // where it ran; counting the family as executed too would count one question twice.
     if (askedQids.has(e.qid)) { a.asked++; continue; }
     if (skippedQids.has(e.qid)) { a.skipped++; continue; }
+    // a follow-up the run's safety net did not send: not asked, so neither run nor missing
+    if (outstandingQids.has(e.qid)) { a.outstanding++; continue; }
     if (missing.has(e.qid)) { a.missing.push(e.qid); continue; }
     // a capability gap is NOT executed — it is a disclosed hole in the axis
     if (deferredQids.has(e.qid)) { a.deferred.push(e.qid); continue; }
@@ -2713,9 +2925,12 @@ export function deriveCoverageSkeleton(plan, join) {
       : (a.deferred.length ? "deferred"
         : (a.crowds ? "incomplete"
           : (a.executed === 0 && a.skipped > 0 ? "skipped"
-            : (a.executed === 0 && a.awaiting > 0 ? "awaiting-judgment" : "executed")))),
+            : (a.executed === 0 && a.awaiting > 0 ? "awaiting-judgment"
+              // nothing ran but follow-ups the safety net did not send: no answer to rest a clean on, as when they joined missing
+              : (a.executed === 0 && a.outstanding > 0 ? "unexecuted" : "executed"))))),
     entries: a.entries, executed: a.executed, crowds: a.crowds, skipped: a.skipped, missing: a.missing,
     ...(a.awaiting ? { awaiting: a.awaiting } : {}),
+    ...(a.outstanding ? { outstanding: a.outstanding } : {}),
     ...(a.asked ? { asked: a.asked } : {}),
     ...(a.readElsewhere ? { read_elsewhere: a.readElsewhere } : {}),
     ...(a.deferred.length ? { deferred: a.deferred } : {}),