clearotron 0.4.1 → 0.5.0-beta.0

package/driver/placement-decisions.mjs

@@ -0,0 +1,243 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+//
+// placement-decisions.mjs — PLACEMENT'S DECISIONS AS THEY STAND ON A RUN'S FILES, for every reader that is told them.
+//
+// Placement sets lines aside by name and under its groups' rows, each with a ground, and keeps them out of
+// placements.json. One check says which of them still stand (a group's row checked again on the shape now on disk; a
+// set-aside by name while the band still holds its record and no placement places its line), and every reader takes
+// them through it: the delivered Audit Trail, recall reconciliation, the review's list of floors, and the list the
+// reading step and the writer are given. Here rather than in the pipeline so that the MCP server's rebuild of a
+// missing audit, which loads no publishing code, delivers the same rows the driver's audit builder does. Reads the
+// run's files; never writes them.
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { createHash } from "node:crypto";
+import { buildSelectionIndex, setAsideGrounds, isSetAsideGroupRow, lineKey, groupName } from "./placement-form.mjs";
+import { unionPlacementForm } from "./placement-union.mjs";
+import { readPlacementForm, readPlacementFormInput } from "./placement-form-io.mjs";
+import { parsePlacementsJson } from "./placement-model.mjs";
+
+const safeReadJson = (p) => { try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; } };
+
+/** Every record uri a placements.json names. */
+export function placedUriRows(P) {
+  try {
+    const placements = parsePlacementsJson(readFileSync(P.placementModel, "utf8")).placements;
+    const out = [];
+    for (const p of Array.isArray(placements) ? placements : []) {
+      for (const r of Array.isArray(p?.records) ? p.records : []) out.push({ uri: r, tier: p?.tier ?? null });
+    }
+    return out;
+  } catch { return []; }
+}
+
+
+/**
+ * The form's set-aside entries as they stand on the shape now on disk, and on what placement placed. A ground by
+ * name stands while the band still holds its record and no placement places its line: a later pass that places
+ * the line reverses the set-aside, as the fate count already reads it, and a record the band no longer holds has
+ * no decision left to deliver. A group's row is checked again exactly as the union took it, on its count and on
+ * every line read, because the shape may have been derived again since: a resumed run derives it afresh, and a
+ * record body fetched after placement can move a line out of the list the goods test could not place and into a
+ * group. A row taken on the earlier shape then covers no line the later one added. `placedUris` are the records
+ * the placements carry, and `rows` the form's own rows, from which the union reads the lines placement placed.
+ * Nothing is written back. PURE.
+ */
+export function standingSetAside(entries, input, { placedUris = [], rows = [] } = {}) {
+  const all = Array.isArray(entries) ? entries : [];
+  const index = buildSelectionIndex(input);
+  const placedLines = new Set([...placedUris].map((u) => lineKey(index.resolve(u))).filter(Boolean));
+  const named = all.filter((e) => !isSetAsideGroupRow(e)).filter((e) => {
+    const line = lineKey(index.resolve(e?.set_aside));
+    return Boolean(line) && !placedLines.has(line);
+  }).map((e) => ({ ...e, key: lineKey(index.resolve(e.set_aside)) }));
+  const grouped = all.filter(isSetAsideGroupRow);
+  if (!grouped.length) return named;
+  // A group's row is taken again beside the lines placement placed (`rows`, the form's own) and the ones it named that
+  // still stand, so the lines it covers and the floors it leaves are counted as the fate count reads them: neither a
+  // placed line nor a named one is the row's, and a placed floor is not one it leaves. Each row carries the keys of
+  // the lines it covers (`covered_lines`), which the form itself never says back.
+  const { form, covered_lines: covered } = unionPlacementForm({ rows: Array.isArray(rows) ? rows : [], set_aside: [...named, ...grouped] }, null, input,
+    { covered: true });
+  return [...named, ...form.set_aside_groups.map((e) => ({ ...e, covered_lines: covered?.[e.set_aside_group] ?? [] }))];
+}
+
+/** The set-aside grounds the placement form holds, by name and by group, as uri → entry, through the form's own selection index. */
+export function placementSetAsideGrounds(P) {   // @internal — driven by its test with a run's own files
+  try {
+    const form = readPlacementForm(P.runDir);
+    if (!form.set_aside?.length) return () => null;
+    const input = readPlacementFormInput(P.runDir);
+    const placedUris = placedUriRows(P).map((r) => r.uri);
+    return setAsideGrounds(standingSetAside(form.set_aside, input, { placedUris, rows: form.rows }), buildSelectionIndex(input), input.groups, input.floors,
+      { placedUris });
+  } catch { return () => null; }
+}
+
+/**
+ * THE FLOORS PLACEMENT SET ASIDE, AS THE REVIEW IS TOLD THEM: one line per floor of the shape now on disk whose
+ * set-aside stands, by name on its status or its territory, or under a crowd's row, with placement's ground. Only
+ * decisions that stand on the current shape are listed (`placementSetAsideGrounds`, which checks a group's row
+ * again); a floor with no standing decision is not listed, so the review flags it as before. [] when nothing stands
+ * or nothing can be read. IMPURE (reads the run).
+ */
+export function placementFloorDecisionLines(P) {   // @internal — driven by its test with a run's own files
+  try {
+    const floors = safeReadJson(P.bandShape)?.floors?.in_class_identical_or_near;
+    if (!Array.isArray(floors) || !floors.length) return [];
+    const groundOf = placementSetAsideGrounds(P);
+    const out = [];
+    for (const f of floors) {
+      const g = f?.record_id ? groundOf(f.record_id) : null;
+      if (!g?.ground) continue;
+      const who = `${f.mark_text ?? "(unnamed)"}${f.owner_name ? ` — ${f.owner_name}` : ""} (${f.record_id})`;
+      if (g.by === "group") out.push(`- ${who}: covered by group (${g.group})'s row: ${g.ground}`);
+      else if (g.on === "status" || g.on === "territory") out.push(`- ${who}: set aside on its ${g.on}: ${g.ground}`);
+    }
+    return out;
+  } catch { return []; }
+}
+
+/**
+ * PLACEMENT'S ACCEPTED SET-ASIDES THAT STAND ON THE RUN'S FILES, as data: one entry per decision (`standingSetAside`: a
+ * group's row checked again on the shape beside what placement placed and named, a set-aside by name only while the
+ * band holds its record and no placement places its line). A name's entry gives the record the record tools open, its
+ * mark and owner, its ground and, for a floor, what the ground is on; a group's row its name, the records in the group,
+ * the lines it covers (the group's lines placement neither placed nor named) and its ground, with every floor it leaves
+ * to be placed or named. A group's row also carries a hash of the keys of the lines it covers, so a row that comes to
+ * cover other lines at the same count is a changed decision to every stage that reads it, while the file stays small
+ * enough for a stage to open. [] when nothing stands or nothing can be read. IMPURE (reads the run).
+ */
+export function standingPlacementDecisions(P) {   // @internal — driven by its test with a run's own files
+  try {
+    const form = readPlacementForm(P.runDir);
+    if (!form.set_aside?.length) return [];
+    const input = readPlacementFormInput(P.runDir);
+    const index = buildSelectionIndex(input);
+    return standingSetAside(form.set_aside, input, { placedUris: placedUriRows(P).map((r) => r.uri), rows: form.rows }).flatMap((e) => {
+      if (!e?.ground) return [];
+      if (isSetAsideGroupRow(e)) return [{ kind: "group", group: groupName(e.set_aside_group), records: Number(e.count ?? 0),
+        covers_lines: Number(e.covers_lines ?? 0), ground: e.ground, floors_not_covered: Array.isArray(e.floors_not_covered) ? e.floors_not_covered : [],
+        covered_lines_hash: createHash("sha256").update((e.covered_lines ?? []).join("\n")).digest("hex").slice(0, 16) }];
+      const c = index.resolve(e.set_aside);
+      return [{ kind: "name", record: e.set_aside, mark: c?.mark ?? null, owner: c?.owner ?? null, ground: e.ground,
+        ...(e.on === "status" || e.on === "territory" ? { on: e.on } : {}) }];
+    });
+  } catch { return []; }
+}
+
+/**
+ * WHERE EACH RECORD STANDS IN PLACEMENT'S ACCOUNT: a placed record by its tier, a record set aside by name by its ground,
+ * and each group's row as one entry with the records it holds, which it does not name. Read before and after a repeated
+ * placement pass, it says how many records the pass re-ranked. IMPURE (reads the run).
+ */
+export function rankingNow(P) {   // @internal — driven by its test with a run's own files
+  const records = new Map();
+  for (const r of placedUriRows(P)) records.set(String(r.uri).toLowerCase(), `placed:${r.tier ?? ""}`);
+  const groups = new Map();
+  for (const d of standingPlacementDecisions(P)) {
+    if (d.kind === "group") groups.set(d.group, { key: `${d.ground}|${d.covers_lines}|${d.covered_lines_hash}`, records: d.records });
+    else records.set(String(d.record).toLowerCase(), `set aside${d.on ? ` on its ${d.on}` : ""}: ${d.ground}`);
+  }
+  return { records, groups };
+}
+
+/** A ranking as it is kept on disk: its two maps as plain objects. PURE. */
+export function rankingToJson(ranking) {
+  return { records: Object.fromEntries(ranking?.records ?? []), groups: Object.fromEntries(ranking?.groups ?? []) };
+}
+
+/** A ranking kept on disk, read back into its two maps; null when there is none to read. PURE. */
+export function rankingFromJson(json) {
+  if (!json || typeof json !== "object" || typeof json.records !== "object" || typeof json.groups !== "object") return null;
+  return { records: new Map(Object.entries(json.records ?? {})), groups: new Map(Object.entries(json.groups ?? {})) };
+}
+
+/** How many records a ranking accounts for: each named record once, and every record a group's row holds. PURE. */
+export function rankedRecords(ranking) {
+  return (ranking?.records?.size ?? 0) + [...(ranking?.groups?.values() ?? [])].reduce((n, g) => n + (Number(g?.records) || 0), 0);
+}
+
+/**
+ * How many records stand differently in `after` than in `before`: a named record that moved, appeared or went counts
+ * once, and a group's row that changed counts every record it holds, as it names none of them. PURE.
+ */
+export function recordsReRanked(before, after) {
+  let n = 0;
+  for (const id of new Set([...(before?.records?.keys() ?? []), ...(after?.records?.keys() ?? [])]))
+    if (before?.records?.get(id) !== after?.records?.get(id)) n++;
+  for (const g of new Set([...(before?.groups?.keys() ?? []), ...(after?.groups?.keys() ?? [])])) {
+    const a = before?.groups?.get(g), b = after?.groups?.get(g);
+    if (a?.key !== b?.key || a?.records !== b?.records) n += Math.max(Number(a?.records) || 0, Number(b?.records) || 0);
+  }
+  return n;
+}
+
+/**
+ * THE SAME DECISIONS, AS THE READING STEP AND THE WRITER ARE TOLD THEM: one line each, under the approved introduction.
+ * A group's floors are listed up to twenty; beyond that the line says how many more there are and names the file that
+ * holds every one of them (`writePlacementDecisions`), so a shortened list never stands in for the whole. IMPURE.
+ */
+export function placementSetAsideLines(P, decisions = standingPlacementDecisions(P)) {   // @internal — driven by its test with a run's own files
+  const n = (x) => Number(x ?? 0).toLocaleString("en-US");
+  const listed = (ids) => (ids.length > 20 ? `${ids.slice(0, 20).join(", ")}, and ${n(ids.length - 20)} more, all listed in ${P.placementDecisions}` : ids.join(", "));
+  return decisions.map((d) => (d.kind === "group"
+    ? `- group (${d.group})'s row, ${n(d.records)} records in the group, covering ${n(d.covers_lines)} lines: ${d.ground}`
+      + (d.floors_not_covered.length ? `; the floors it does not cover: ${listed(d.floors_not_covered)}` : "")
+    : `- ${d.mark ?? d.record}${d.owner ? ` — ${d.owner}` : ""} (${d.record}): set aside${d.on ? ` on its ${d.on}` : ""}: ${d.ground}`));
+}
+
+/**
+ * The standing decisions, written where the reading step and the writer declare them as an input, so a change to a
+ * decision alone (a reason, a group's membership) makes a reader that already ran stale, and the delivery loop repeats
+ * it, as it does when the placements change. No clock: the file changes only when a decision does. Returns the
+ * decisions written. IMPURE (writes `_driver/placement-decisions.json`).
+ */
+export function writePlacementDecisions(P) {   // @internal — driven by its test with a run's own files
+  const decisions = standingPlacementDecisions(P);
+  mkdirSync(dirname(P.placementDecisions), { recursive: true });
+  writeFileSync(P.placementDecisions, JSON.stringify({ schema_version: 1, decisions }, null, 2) + "\n");
+  return decisions;
+}
+
+/**
+ * PLACEMENT'S DECISIONS IN THE DELIVERED AUDIT TRAIL (ruled 2026-10-18): one row per set-aside that stands on the shape
+ * now on disk, in the Audit Trail's own fields, carrying the decision's reference, its ground and, for a group's row,
+ * its count. A set-aside the shape no longer supports is not delivered. [] when there is none or nothing can be read.
+ * IMPURE (reads the run).
+ */
+export function placementAuditRows(P) {   // @internal — driven by its test with a run's own files
+  try {
+    const form = readPlacementForm(P.runDir);
+    if (!form.set_aside?.length) return [];
+    const input = readPlacementFormInput(P.runDir);
+    const index = buildSelectionIndex(input);
+    return standingSetAside(form.set_aside, input, { placedUris: placedUriRows(P).map((r) => r.uri), rows: form.rows }).flatMap((e) => {
+      if (!e?.ground) return [];
+      if (isSetAsideGroupRow(e)) return [{ source_layer: "Register", step: "placement", query: `group (${groupName(e.set_aside_group)})`,
+        rationale: e.ground, result_summary: `${Number(e.count ?? 0).toLocaleString("en-US")} records` }];
+      const c = index.resolve(e.set_aside);
+      return [{ source_layer: "Register", step: "placement",
+        query: `${c?.mark ?? e.set_aside}${c?.owner ? ` — ${c.owner}` : ""} (${e.set_aside})`, rationale: e.ground }];
+    });
+  } catch { return []; }
+}
+
+/**
+ * The records placement set aside, as recall reconciliation accepts them now that the audit delivers them: by name,
+ * an individual ending for any position; under a group's row, the members that row validly covers, which end only a
+ * residual position, as a ruled crowd does. Lower-cased uris. Empty when nothing stands. IMPURE (reads the run).
+ */
+export function placementRecallEndings(P, uris) {   // @internal — driven by its test with a run's own files
+  const byName = new Set(), byGroup = new Set();
+  try {
+    const groundOf = placementSetAsideGrounds(P);
+    for (const u of uris ?? []) {
+      const g = u ? groundOf(u) : null;
+      if (!g?.ground) continue;
+      (g.by === "group" ? byGroup : byName).add(String(u).toLowerCase());
+    }
+  } catch { /* nothing stands */ }
+  return { byName, byGroup };
+}

package/driver/placement-form.mjs

@@ -264,15 +264,31 @@ export function setAsideKeysOf(positions) {
  * {set_aside, owner, ground, by} or null. Resolved through the same selection index a `select` resolves
  * through, so the owner is read one way at both ends. A ground by name wins over the owner's group row;
  * `groups` is the band shape's, which says which group each owner sits in. PURE; never throws.
+ *
+ * A GROUP'S ROW GIVES A RECORD ONLY THE GROUND IT GIVES THE RECORD'S LINE. The row covers the lines of its group
+ * the step neither placed nor named, and a line holding a floor only in a crowd of a thousand or more in (b): the
+ * form says back exactly that (`covers_lines`, `floors_not_covered`) and the fate count counts it. Read record by
+ * record, the row also gave its ground to the other records of a floor's line, which had no fate, and to the other
+ * positions of a line the step placed through one of them, so the record trace showed grounds nobody gave. Every
+ * record of a line holding a floor the row cannot answer now leaves with none; so does every record of a placed
+ * line other than a floor, given `placedUris`, the records the form placed. A floor there keeps the answer it had,
+ * because the floor duty counts floors one by one and the delivery floor is read from it.
  */
-export function setAsideGrounds(entries, index, groups = null, floors = null) {
+export function setAsideGrounds(entries, index, groups = null, floors = null, { placedUris = null } = {}) {
   const byKey = new Map(), byGroup = new Map();
   for (const e of Array.isArray(entries) ? entries : []) {
     if (isSetAsideGroupRow(e)) { const g = groupName(e.set_aside_group); if (g && e?.ground) byGroup.set(g, e); }
     else if (e?.key && e?.ground) byKey.set(e.key, e);
   }
   const groupOf = byGroup.size ? groupOfKeys(groups) : new Map();
-  const floorUris = new Set((Array.isArray(floors) ? floors : []).map((f) => normalizeRecordUri(f?.record_id) || String(f?.record_id ?? "")).filter(Boolean));
+  const uriKey = (u) => normalizeRecordUri(u) || String(u ?? "");
+  const floorUris = new Set((Array.isArray(floors) ? floors : []).map((f) => uriKey(f?.record_id)).filter(Boolean));
+  // The lines holding a floor, as the union reads them: any floor record's line, or a shape line counting one.
+  const floorLines = new Set(byGroup.size ? [
+    ...[...floorUris].map((u) => lineKey(index?.resolve?.(u))).filter(Boolean),
+    ...["a", "b", "c", "d", "no_goods"].flatMap((g) => (Array.isArray(groups?.[g]?.list) ? groups[g].list : []).filter((l) => l?.floors > 0).map((l) => l.key)),
+  ] : []);
+  const placedLines = new Set(byGroup.size ? [...(placedUris ?? [])].map((u) => lineKey(index?.resolve?.(u))).filter(Boolean) : []);
   return (uri) => {
     if ((!byKey.size && !byGroup.size) || !index?.resolve) return null;
     const canonical = index.resolve(uri);
@@ -281,8 +297,11 @@ export function setAsideGrounds(entries, index, groups = null, floors = null) {
     const named = line ? byKey.get(line) : null;
     if (named) return { ...named, by: "name" };
     const group = line ? groupOf.get(line) : null, row = group ? byGroup.get(group) : null;
-    if (row && floorUris.has(normalizeRecordUri(uri) || String(uri ?? "")) && !groupRowCoversFloors(groups, group)) return null;
-    return row ? { set_aside: null, key: line, owner: null, ground: row.ground, by: "group", group } : null;
+    if (!row) return null;
+    const isFloor = floorUris.has(uriKey(uri));
+    if ((isFloor || floorLines.has(line)) && !groupRowCoversFloors(groups, group)) return null;
+    if (!isFloor && placedLines.has(line)) return null;
+    return { set_aside: null, key: line, owner: null, ground: row.ground, by: "group", group };
   };
 }
 
@@ -290,9 +309,11 @@ export function setAsideGrounds(entries, index, groups = null, floors = null) {
  * EVERY LINE'S FATE AT PLACEMENT, counted by the list the shape put it in: placed (a record of its mark is
  * in a placement), set aside by name, covered by its group's row, or no fate. A line is one mark of one
  * owner; an owner counts as fated when every one of its lines is. The lines with no goods on file are their
- * own list, which no group row covers. Counts, plus the keys left with no fate. PURE.
+ * own list, which no group row covers. Counts, plus the keys left with no fate. Given `served`, the line keys
+ * placement was served, a group row's lines never served are counted as `by_group_unread`; given `lineEvidence`,
+ * line → what its goods rest on (goods-evidence.mjs), a group row's lines are counted by it. PURE.
  */
-export function ownerFates({ groups, entries = [], index, placedUris = [] } = {}) {
+export function ownerFates({ groups, entries = [], index, placedUris = [], served = null, lineEvidence = null } = {}) {
   if (!groups || typeof groups !== "object" || !index?.resolve) return null;
   const placed = new Set([...placedUris].map((u) => lineKey(index.resolve(u))).filter(Boolean));
   const named = new Set(), grouped = new Set();
@@ -306,6 +327,7 @@ export function ownerFates({ groups, entries = [], index, placedUris = [] } = {}
   lists.no_goods = Array.isArray(groups.no_goods?.list) ? groups.no_goods.list : [];
   const zero = () => ({ lines: 0, placed: 0, by_name: 0, by_group: 0, unfated: 0 });
   const totals = zero(), by_list = {}, unfated_lines = [], ownerFated = new Map();
+  let unreadTotal = 0;
   for (const [list, lines] of Object.entries(lists)) {
     const c = zero();
     for (const l of lines) {
@@ -315,14 +337,26 @@ export function ownerFates({ groups, entries = [], index, placedUris = [] } = {}
       const fate = placed.has(l.key) ? "placed" : byName ? "by_name" : rowMay ? "by_group" : "unfated";
       c.lines++; c[fate]++; totals.lines++; totals[fate]++;
       if (fate === "unfated") unfated_lines.push({ list, key: l.key });
+      if (fate === "by_group") {
+        // AN UNREAD CROWD IS NOT A CLEAN NEGATIVE (ruled 2026-10-18). A crowd's row stands on its first page read and the
+        // count, so it covers lines placement never read; given what placement was served, those are counted apart. They
+        // stay covered by the group: the ruled method accepts the row, and the count records what it rested on.
+        if (served && !served.has(l.key)) { c.by_group_unread = (c.by_group_unread ?? 0) + 1; unreadTotal++; }
+        const state = typeof lineEvidence === "function" ? lineEvidence(l) : null;
+        if (state) { c.by_group_goods ??= {}; c.by_group_goods[state] = (c.by_group_goods[state] ?? 0) + 1; }
+      }
       ownerFated.set(l.owner_key, (ownerFated.get(l.owner_key) ?? true) && fate !== "unfated");
     }
-    by_list[list] = c;
+    by_list[list] = { ...c, ...(served ? { by_group_unread: c.by_group_unread ?? 0 } : {}), reconciles: sumsToLines(c) };
   }
-  return { unit: "line", ...totals, owners: ownerFated.size, owners_fated: [...ownerFated.values()].filter(Boolean).length,
+  // THE SUM IS STATED, as the floor duty states its own: one fate per line, so the four add up to the lines, and a
+  // count that does not is a defect here that a reader should not have to find by adding.
+  return { unit: "line", ...totals, ...(served ? { by_group_unread: unreadTotal } : {}), reconciles: sumsToLines(totals), owners: ownerFated.size, owners_fated: [...ownerFated.values()].filter(Boolean).length,
     by_list, unfated_lines };
 }
 
+const sumsToLines = (c) => c.placed + c.by_name + c.by_group + c.unfated === c.lines;
+
 const PROVENANCE = "driver-written form. You SELECT and you JUDGE; the driver COPIES. For each "
   + "register candidate you are placing, add a row naming one of its record ids in `select` plus your "
   + "`tier` and `reason` (and `borderline` if the call is close) — the driver resolves the id against the "

package/driver/placement-union.mjs

@@ -91,9 +91,11 @@ function indexRows(rows, { bySelection = true, uriLeg = true } = {}) {
  * @returns {{form, total, settled, outstanding, carried, seat_rows}}
  *   carried — settled rows this attempt's own submission would NOT have carried on its own: exactly the
  *             work a killed or cold re-dispatch used to destroy.
+ *   covered_lines — with `{ covered: true }` only: each set-aside group's covered line keys, sorted. Kept off
+ *             the form, so the step is never said back a list of the lines its row covers.
  * PURE; never throws.
  */
-export function unionPlacementForm(prior, submitted, input) {
+export function unionPlacementForm(prior, submitted, input, { covered = false } = {}) {
   const index = buildSelectionIndex(input);
   const priorRows = Array.isArray(prior) ? prior : (Array.isArray(prior?.rows) ? prior.rows : []);
   const submittedRows = Array.isArray(submitted) ? submitted : (Array.isArray(submitted?.rows) ? submitted.rows : null);
@@ -314,12 +316,15 @@ export function unionPlacementForm(prior, submitted, input) {
   const placedLines = new Set(form.rows.filter((row) => row.kind === "register" && rowIsSettled(row, row)).map((row) => lineKey(row)).filter(Boolean));
   const groupOf = groupOfKeys(groups);
   const lineOf = (g, key) => (Array.isArray(groups?.[g]?.list) ? groups[g].list : []).find((l) => l.key === key) ?? null;
-  const covers = new Map(), floorsLeft = new Map();
+  const covers = new Map(), floorsLeft = new Map(), coveredKeys = new Map();
   for (const [key, g] of groupOf) {
     if (!setAsideGroups.has(g) || placedLines.has(key) || setAside.has(key)) continue;
     const line = lineOf(g, key);
     if ((line?.floors ?? 0) > 0 && !groupRowCoversFloors(groups, g)) floorsLeft.set(g, [...(floorsLeft.get(g) ?? []), line.record_id ?? key]);
-    else covers.set(g, (covers.get(g) ?? 0) + 1);
+    else {
+      covers.set(g, (covers.get(g) ?? 0) + 1);
+      if (covered) { if (!coveredKeys.has(g)) coveredKeys.set(g, []); coveredKeys.get(g).push(key); }
+    }
   }
   for (const [g, e] of setAsideGroups) {
     e.covers_lines = covers.get(g) ?? 0;
@@ -331,9 +336,11 @@ export function unionPlacementForm(prior, submitted, input) {
   // or more, stands on its row and its count. Said back once the step has answered, on this turn or an earlier one:
   // the form written before any answer would list every floor of the band, and a turn whose form will not parse
   // leaves the earlier answer standing, its floors still owed.
-  const groundOf = setAsideGrounds([...setAside.values(), ...setAsideGroups.values()], index, groups, input?.floors);
+  const rendered = renderPlacementsJson(form.rows).placements;
+  const groundOf = setAsideGrounds([...setAside.values(), ...setAsideGroups.values()], index, groups, input?.floors,
+    { placedUris: rendered.flatMap((p) => (Array.isArray(p?.records) ? p.records : [])) });
   const duty = reconcileFloorDuty({ floors: Array.isArray(input?.floors) ? input.floors : [],
-    placements: renderPlacementsJson(form.rows).placements, setAsideGroundOf: groundOf });
+    placements: rendered, setAsideGroundOf: groundOf });
   const unfated = new Map();
   for (const r of duty.rows) {
     if (r.disposition !== "unanswered" && r.disposition !== "named-without-ground") continue;
@@ -349,7 +356,8 @@ export function unionPlacementForm(prior, submitted, input) {
   if (answered && unfated.size) form.floors_without_fate = [...unfated.values()];
   return { form, total: form.rows.length, settled, outstanding: form.rows.length - settled,
     carried, seat_rows: carriedSeat.length, unresolved: unresolved.length, set_aside: setAside.size, set_aside_groups: setAsideGroups.size,
-    floors_without_fate: [...unfated.values()].reduce((n, e) => n + e.floors.length, 0) };
+    floors_without_fate: [...unfated.values()].reduce((n, e) => n + e.floors.length, 0),
+    ...(covered ? { covered_lines: Object.fromEntries([...coveredKeys].map(([g, keys]) => [g, [...keys].sort()])) } : {}) };
 }
 
 /** How many rows of an already-unioned form the render would still omit. PURE. */

package/driver/provider-usage.mjs

@@ -241,14 +241,17 @@ export function tallyRegisterCalls(ledgerPath = DEFAULT_LEDGER_PATH, runPrefix)
 }
 
 /**
- * The SET of record_fetch target URIs for the run identified by `runPrefix`. Backs the Fix-1b acceptance
- * gate (the screen-gate predicate cross-checks each in-scope-live goods/field drop against this set). Reuses
- * the same gateway-namespace stripping + run-prefix matching as tallyRegisterCalls; read-only and defensive
- * (missing/unreadable ledger or a torn last line ⇒ skips that line, never throws). A cache_hit record_fetch
- * still counts — the URI WAS fetched this run, which is exactly what the gate asks.
+ * The SET of record_fetch target URIs this run fetched SUCCESSFULLY, for the run identified by `runPrefix`.
+ * Backs the Fix-1b acceptance gate (the screen-gate predicate cross-checks each in-scope-live goods/field drop
+ * against this set). Reuses the same gateway-namespace stripping + run-prefix matching as tallyRegisterCalls;
+ * read-only and defensive (missing/unreadable ledger or a torn last line ⇒ skips that line, never throws). A
+ * cache_hit record_fetch that succeeded still counts — the record WAS retrieved this run, which is what the
+ * gate asks. A fetch the register refused or that failed in transport (`ok: false`) does not: an attempt is
+ * not a retrieval, and the gate's own recovery fetch, then its disclosure, is what such a drop is owed (ruled
+ * 2026-10-18). One success among the target's rows is enough, whatever came before or after it.
  * @param {string} ledgerPath  path to the JSONL ledger
  * @param {string} runPrefix   e.g. `clearance-acme-bluejay-` (note the trailing hyphen)
- * @returns {Set<string>} the set of fetched record URIs
+ * @returns {Set<string>} the set of record URIs this run fetched successfully
  */
 export function fetchedRecordUris(ledgerPath = DEFAULT_LEDGER_PATH, runPrefix) {
   const out = new Set();
@@ -262,7 +265,7 @@ export function fetchedRecordUris(ledgerPath = DEFAULT_LEDGER_PATH, runPrefix) {
     let row;
     try { row = JSON.parse(line); } catch { continue; } // tolerate a torn concurrent-append line
     if (!rowMatchesRun(row, runPrefix)) continue;
-    if (row.tool === "record_fetch" && typeof row.target === "string" && row.target) out.add(row.target);
+    if (row.tool === "record_fetch" && row.ok === true && typeof row.target === "string" && row.target) out.add(row.target);
   }
   return out;
 }

package/driver/publish/audit-from-spine.mjs

@@ -245,7 +245,7 @@ export function recordsNeverDelivered(readingLog) {
     .sort((a, b) => b.misses - a.misses || a.record_id.localeCompare(b.record_id));
 }
 
-export function buildAuditMd(registerMd, commonLawMd, { findings: runFindings = null, doubts = null, asks = null, readingLog = null, commonLawGrid = null, doubtTruncations = null, registerPresence = null } = {}) {
+export function buildAuditMd(registerMd, commonLawMd, { findings: runFindings = null, doubts = null, asks = null, readingLog = null, commonLawGrid = null, doubtTruncations = null, registerPresence = null, placementRows = null } = {}) {
   const reg = parseTables(registerMd);
   const cl = parseTables(commonLawMd);
 
@@ -301,7 +301,10 @@ export function buildAuditMd(registerMd, commonLawMd, { findings: runFindings =
       result_summary: get(r, "Result Summary", "Result", "Summary"),
       tool_call: get(r, "Tool Call #", "Tool Call", "Call"),
       finding_ref: get(r, "Finding Reference", "Finding Ref", "Ref"),
-    })));
+    })))
+    // Placement's decisions, in the same fields: the reference, the ground and a group row's count, as the run
+    // recorded them (pipeline.mjs placementAuditRows), so a set-aside is traceable in the delivered audit.
+    .concat(Array.isArray(placementRows) ? placementRows : []);
 
   // One resolution per claim, GENERALIZED (2026-07-22, doubt-stitch): a block that joins a findings.json
   // finding of ANY disposition gets the run's own recorded resolution stamped onto it. The withdrawn

package/driver/publish/index.mjs

@@ -14,7 +14,7 @@ import { parseReport, parseAudit, parseSections, parseBlocks, stripInternal, par
 import { renderHtml, parseActionBuckets, actYouConditions } from './render.mjs';
 import { buildAudit } from './xlsx.mjs'; import { readDegradedPartRows, degradedPartRows, degradedAtPublish, storeStates, readDeliveredStores, mergeDegradedRows } from '../degraded-parts.mjs'; import { readDeclinations } from '../declination-tool.mjs'; import { frameSetAsideRows } from '../web-grid.mjs';   // — what synthesis set aside, with its grounds; and the stores the matter frame set aside, with its reason
 import { parseFindingsJson, parseFindingsJsonLenient, deriveDisplayVerdict, joinFindingToBlock, CLIENT_TIER_BY_COMPOSITE, projectCoverageJudgment } from '../findings-model.mjs';
-import { readStore, requiredAbsent, nonClosingAbsences } from './publish-inputs.mjs'; import { coverageFormStamp, readCoverageForm } from '../coverage-form-io.mjs'; import { readReleasedFamilies } from '../withheld-families.mjs'; import { unitLabel } from '../coverage-form.mjs'; import { coverageUnitLabel } from '../coverage-ledger.mjs'; import { recallReceiptForOwnCompany } from '../recall-receipt.mjs';   // — and why an absence did not close; whose recall checks an audit lists
+import { readStore, requiredAbsent, nonClosingAbsences } from './publish-inputs.mjs'; import { coverageFormStamp, readCoverageForm } from '../coverage-form-io.mjs'; import { readReleasedFamilies, readWithheldFamilies } from '../withheld-families.mjs'; import { unitLabel } from '../coverage-form.mjs'; import { coverageUnitLabel } from '../coverage-ledger.mjs'; import { recallReceiptForOwnCompany } from '../recall-receipt.mjs';   // — and why an absence did not close; whose recall checks an audit lists
 import { clearanceReportData } from './report-data.mjs';
 import { searchDepthRecord, planTerritoriesOf, caseLawPassRecord } from './search-depth.mjs'; import { bandRecords } from '../named-band.mjs'; import { CASELAW_BRIDGES } from '../engine/mcp/gather-config.mjs';   // how much was read to reach the answer, as counts and tokens; and the case-law sources whose calls the court state reads
 import { parseFrameworkManifest } from '../framework.mjs'; import { readFrozenMethod, FROZEN_METHOD_FILE } from '../framework-method.mjs';
@@ -1868,12 +1868,27 @@ function officeLinksFor(findings, recordsByUri, runOrigins) {
   return links;
 }
 
-/** The coverage form's family rows judged withheld, as audit-workbook coverage rows. Never throws. */
+/**
+ * The coverage form's family rows judged withheld, as audit-workbook coverage rows. Never throws.
+ *
+ * A family judged withheld is a recorded judgment and not open work: it takes the shipped `Note` presentation a
+ * released family's row has. Its reason is the reading turn's, read from the turn's own record, never the words a
+ * later digest gave the form's row; a family the turn left unrecorded, which the form itself settled, keeps the
+ * form's reason. That is the same set the register coverage line and the reviewer's table count as withheld
+ * (waitingFamilyStates), so the workbook never calls open work what the class line has already left out of it.
+ * A family the turn released after the form settled it ran: its own row, from the release record, says so, and
+ * the form's stale withheld row is not shown beside it.
+ */
 export function withheldFamilyRows(runDir) {
   try {
     const { rows } = readCoverageForm(runDir, coverageFormStamp(runDir).formName);
-    return (rows ?? []).filter((r) => r?.kind === 'family' && r.status === 'withheld-by-judgment' && r.reason)
-      .map((r) => ({ area: coverageUnitLabel(r.unit), state: 'not-searched', note: String(r.reason), done: '', left: String(r.reason) }));
+    const judged = readWithheldFamilies(runDir);
+    const released = readReleasedFamilies(runDir);
+    return (rows ?? []).filter((r) => r?.kind === 'family' && r.status === 'withheld-by-judgment' && r.reason && !Object.hasOwn(released, String(r.qid ?? '')))
+      .map((r) => {
+        const reason = String(judged[String(r.qid ?? '')]?.reason ?? r.reason).trim();
+        return { area: coverageUnitLabel(r.unit), state: 'note', note: reason, done: reason, left: '' };
+      });
   } catch { return []; }
 }
 

package/driver/publish/xlsx.mjs

@@ -141,22 +141,22 @@ const treatmentCell = f => f?.disposition === 'withdrawn'
 // Record retrieved? — the plain-English state of the register-record fetch for a finding, from the per-URI
 // fetch-state map ({retrieved | failed | not-attempted}). A common-law finding (no registrations) is
 // "n/a — live listing"; a failed fetch is VISIBLY unverified, never presented as confirmed.
-function retrievedCell(f, fetchState) {
+export function retrievedCell(f, fetchState) {   // @internal — driven by its test
   const regs = f?.owner?.registrations || [];
   if (!regs.length) return 'n/a — live listing';
   const st = uri => (fetchState && fetchState[String(uri || '').toLowerCase()]) || 'not-attempted';
   const states = regs.map(r => st(r.uri));
-  if (states.every(s => s === 'retrieved')) return 'Read from the register record';
+  if (states.every(s => s === 'retrieved')) return 'Retrieved from the register';
   const anyRead = states.some(s => s === 'retrieved');
   const anyFailed = states.some(s => s === 'failed');
   // no leg read: a fetch that FAILED (a 404) makes the registry values unverified — say so visibly; a leg
   // simply never pulled (off-field context) is the softer "not individually retrieved".
   if (!anyRead) return anyFailed ? 'Not retrieved — details unverified' : 'Not individually retrieved';
-  // mixed — spell out which country legs read and which did not ("CA read; US/AU not retrieved").
+  // mixed — spell out which country legs were retrieved and which were not ("CA retrieved; US/AU not retrieved").
   const read = regs.filter(r => st(r.uri) === 'retrieved').map(r => uriCountry(r.uri)).filter(Boolean);
   const missing = regs.filter(r => st(r.uri) !== 'retrieved').map(r => uriCountry(r.uri)).filter(Boolean);
   const parts = [];
-  if (read.length) parts.push(`${read.join('/')} read`);
+  if (read.length) parts.push(`${read.join('/')} retrieved`);
   if (missing.length) parts.push(`${missing.join('/')} not retrieved`);
   return parts.join('; ') || 'Not individually retrieved';
 }
@@ -442,7 +442,7 @@ function coverageOpen({ coverage = [], coverageJudgment = null, verdict = null,
   return openState || judgeUnsure || verdictCoverage;
 }
 
-function summaryRows(findings, coverage, fm, { mark, coverageJudgment, verdict, jurisdiction, registerOnly = false, commonLawUnlogged = false, clientGate = null, lintFailures = [], productName = null, degradedParts = [] } = {}) {
+export function summaryRows(findings, coverage, fm, { mark, coverageJudgment, verdict, jurisdiction, registerOnly = false, commonLawUnlogged = false, clientGate = null, lintFailures = [], productName = null, degradedParts = [] } = {}) {
   const disp = d => findings.filter(f => f.disposition === d && !f.isContextNote).length;
   const rated = findings.filter(f => !f.isContextNote);
   // A part that failed and still shipped is open too, so the count and the caveat never read complete
@@ -540,7 +540,7 @@ function summaryRows(findings, coverage, fm, { mark, coverageJudgment, verdict,
         : 'every search we ran — register and common-law — so you can see we looked everywhere.' },
     { Field: '   Coverage & gaps', Value: 'what is fully cleared and what is still open — read this first if you have a doubt.' },
     { Field: '   Evidence tags', Value: '“from source” = checked against the actual register record or live listing · “our read” = our own assessment.' },
-    { Field: '   Record retrieved?', Value: 'whether the register entry itself was pulled and read; where a record could not be retrieved, its details are shown unverified.' },
+    { Field: '   Record retrieved?', Value: 'whether the register entry itself was retrieved; where a record could not be retrieved, its details are shown unverified.' },
   ];
   return rows;
 }

package/driver/recall-reconciliation.mjs

@@ -209,24 +209,30 @@ export function groupByPosition(rankedCandidates, positions = []) {
  *
  * Deterministic; returns the machine artifact (no timestamps — the caller stamps `ts`).
  */
-export function reconcileRecall({ candidates = [], endings, crowdRulings = [], topSlice = RECALL_TOP_SLICE, positions = [], dominantElement = null, inScopeClasses = [] } = {}) {
+export function reconcileRecall({ candidates = [], endings, crowdRulings = [], topSlice = RECALL_TOP_SLICE, positions = [], dominantElement = null, inScopeClasses = [], placement = null } = {}) {
   const carried = endings?.carried ?? new Set();
   const dropRows = endings?.dropRows ?? new Set();
+  // PLACEMENT'S DECISIONS END A POSITION TOO, now that the delivered audit carries them (ruled 2026-10-18): a
+  // set-aside by name is an individual ending, for any position; a group's row ends only a residual position,
+  // for the members it validly covers, as a ruled crowd does, never a top-slice one that must end individually.
+  const byName = placement?.byName ?? new Set(), byGroup = placement?.byGroup ?? new Set();
   const ranked = rankCandidates(candidates);
   const groups = groupByPosition(ranked, positions);
   // ANY constituent URI ends the position — drop row first so an explicit negative is reported as
   // the reason even when the same position is also mentioned elsewhere.
   // match on the lowercased key, REPORT the URI in the band's own casing (see groupByPosition)
-  const endingOf = (g) => {
+  const endingOf = (g, tier) => {
     for (let i = 0; i < g.members.length; i++) if (dropRows.has(g.members[i])) return { ending: "drop-row", ended_by: g.member_display[i] };
     for (let i = 0; i < g.members.length; i++) if (carried.has(g.members[i])) return { ending: "finding", ended_by: g.member_display[i] };
+    for (let i = 0; i < g.members.length; i++) if (byName.has(g.members[i])) return { ending: "placement-set-aside", ended_by: g.member_display[i] };
+    if (tier === "residual") for (let i = 0; i < g.members.length; i++) if (byGroup.has(g.members[i])) return { ending: "placement-group", ended_by: g.member_display[i] };
     return { ending: null, ended_by: null };
   };
   const top = groups.slice(0, Math.max(0, topSlice));
   const rest = groups.slice(Math.max(0, topSlice));
   const row = (g, tier) => {
     const c = g.candidates[0];                      // the position's strongest constituent candidate
-    const { ending, ended_by } = endingOf(g);
+    const { ending, ended_by } = endingOf(g, tier);
     return {
       record_id: c.record_id, mark_text: c.mark_text, basis: c.basis, classes: c.classes,
       status: c.status, registry: c.registry, application_date: c.application_date ?? null,
@@ -261,6 +267,9 @@ export function reconcileRecall({ candidates = [], endings, crowdRulings = [], t
     in_scope_classes: inScopeClasses,
     top_slice: topRows,
     crowd: { rulings: crowdRulings, declared, residual: residualUnended.length, covers: crowdCovers },
+    // The records the gate weighed, by id: the population its count is out of, so a sentence stated with another
+    // gate's records can count each record once.
+    candidate_ids: [...new Set(ranked.map((c) => lc(normalizeRecordUri(c.record_id) || c.record_id || "")).filter(Boolean))],
     totals: {
       candidates: ranked.length,
       positions: groups.length,
@@ -268,6 +277,7 @@ export function reconcileRecall({ candidates = [], endings, crowdRulings = [], t
       ended_finding: [...topRows, ...restRows].filter((r) => r.ending === "finding").length,
       ended_drop_row: [...topRows, ...restRows].filter((r) => r.ending === "drop-row").length,
       ended_crowd: restRows.filter((r) => r.ending === "crowd").length,
+      ended_placement: [...topRows, ...restRows].filter((r) => r.ending === "placement-set-aside" || r.ending === "placement-group").length,
       unended: unended.length,
     },
     unended,
@@ -282,7 +292,7 @@ export function reconcileRecall({ candidates = [], endings, crowdRulings = [], t
  * Every field below is written on every row; absence is expressed as an explicit null. PURE.
  */
 export const RECALL_EVENT_FIELDS = ["candidates", "positions", "top_slice", "ended_finding",
-  "ended_drop_row", "ended_crowd", "unended", "crowd_declared", "crowd_residual"];
+  "ended_drop_row", "ended_crowd", "ended_placement", "unended", "crowd_declared", "crowd_residual"];
 
 export function recallReconciliationEvent({ trigger = null, artifact = null, reason = null } = {}) {
   const computable = artifact?.computable === true;
@@ -367,7 +377,7 @@ export function buildReconcileFollowup(artifact, { registerFindingsPath, hasCove
       : "";
   };
   const lines = [
-    `You are RESUMING your own register-digest session. The driver's retrieved-to-judgment RECONCILIATION found ${un.length} screened-live dominant-element POSITION(s) that end NOWHERE a reader can see — retrieved, screened in an instructed class, then silent. A report never ships losing screened candidates silently. The unit is the POSITION (the exact-identity collapse in the shape's "## Positions" section): one row ends the whole position, and citing ANY ONE constituent URI is enough. End each one now:`,
+    `This is a fresh session: your earlier register-digest work is not in your context. Your prior digest is ${registerFindingsPath}. The driver's retrieved-to-judgment RECONCILIATION found ${un.length} screened-live dominant-element POSITION(s) that end NOWHERE a reader can see — retrieved, screened in an instructed class, then silent. A report never ships losing screened candidates silently. The unit is the POSITION (the exact-identity collapse in the shape's "## Positions" section): one row ends the whole position, and citing ANY ONE constituent URI is enough. End each one now:`,
   ];
   if (topUn.length) {
     lines.push(