@polycode-projects/the-mechanical-code-talker 6.0.18 → 6.0.19

package/src/domain/news-feed.mjs

@@ -527,9 +527,13 @@ export function hubSeedTerms(hub) {
  *  `seedTerms` starts the walk from more than the hub itself (hubSeedTerms).
  *  Everything downstream that asks "is this the hub" — the report sentences,
  *  the sources, the neighbourhood — still reads the hub term alone, so a seed
- *  widens only what the card can draw background from. */
+ *  widens only what the card can draw background from.
+ *
+ *  `excludeIds` drops rows before the cap rather than after it, so a card that
+ *  gives a report away to another card (storyCoverage) spends the freed budget
+ *  on rows it will actually show. */
 export function subgraphAround(rows, hub, {
-  hops = NEWS_HUB_HOPS, cap = 60, adjacency = null, priorityIds = null, seedTerms = null,
+  hops = NEWS_HUB_HOPS, cap = 60, adjacency = null, priorityIds = null, seedTerms = null, excludeIds = null,
 } = {}) {
   const adj = adjacency ?? buildTermAdjacency(rows);
   const hubTerm = normFactTerm(hub);
@@ -538,11 +542,13 @@ export function subgraphAround(rows, hub, {
   let frontier = [...new Set(seeds)].sort();
   const collected = new Map();
   const hopOf = new Map();
+  const isExcluded = excludeIds instanceof Set ? (id) => excludeIds.has(id) : () => false;
   for (let hop = 0; hop < hops; hop += 1) {
     const nextFrontier = new Set();
     for (const term of [...frontier].sort()) {
       for (const idx of adj.byTerm.get(term) ?? []) {
         const row = rows[idx];
+        if (isExcluded(row.id)) continue;
         collected.set(row.id, row);
         if (!hopOf.has(row.id)) hopOf.set(row.id, hop);
         const [s, o] = adj.terms[idx];
@@ -561,6 +567,32 @@ export function subgraphAround(rows, hub, {
     .slice(0, cap);
 }
 
+// How far the walk goes from an entity the ARTICLE names rather than a fact,
+// and how many rows it may bring back. One hop: what the graph says about that
+// entity itself, never what it says about everything that entity touches. The
+// hub's own two-hop walk is unchanged; this one runs beside it.
+const ARTICLE_ENTITY_HOPS = 1;
+const ARTICLE_ENTITY_ROW_CAP = 24;
+
+/** The rows sitting one hop from an entity the card's article names. Seeded
+ *  from `terms` rather than the hub, so a definition the graph holds about a
+ *  name inside the headline reaches the card even when no fact of the card's
+ *  own touches that name — "amigados is a disk operating system" beside a
+ *  report whose only fact is that a site discussed the headline.
+ *
+ *  `excludeIds` carries the card's reported rows as well as the ones another
+ *  card claimed, so this walk returns background and nothing else: what a
+ *  source reported is the hub walk's business. */
+export function articleEntityRows(rows, terms, {
+  adjacency = null, excludeIds = null, cap = ARTICLE_ENTITY_ROW_CAP,
+} = {}) {
+  const seedTerms = (terms || []).map((term) => normFactTerm(term)).filter(Boolean);
+  if (!seedTerms.length) return [];
+  return subgraphAround(rows, seedTerms[0], {
+    hops: ARTICLE_ENTITY_HOPS, cap, adjacency, seedTerms, excludeIds,
+  });
+}
+
 /** The strongest prior kind among `rows`, for the item's trust chip — read
  *  off each row's own `trust` (a number) and `sourceTypes` (the kind array
  *  readFactRows already computes), never a re-derivation of SOURCE_PRIOR. */
@@ -768,40 +800,58 @@ function identityFans(subgraphRows) {
   return { senseFan, sourcedSenseFan, categoryFan };
 }
 
-/** What this card is ABOUT: its hub, the region of a hub the source spelled
- *  "settlement, region", and the other terms its own report sentences name —
- *  minus any of those that reads across senses. A quake card's report
+// Where a background row's anchor term came from, and so which rows the
+// disclosure names first: the card's own hub, then a term its report names,
+// then an entity its article names that no fact of the card's own touches.
+const ANCHOR_RANK_HUB = 0;
+const ANCHOR_RANK_REPORT = 1;
+const ANCHOR_RANK_ARTICLE = 2;
+
+/** What this card is ABOUT, each term mapped to its anchor rank: its hub, the
+ *  region of a hub the source spelled "settlement, region", the other terms its
+ *  own report sentences name, and the entities its article names (`articleTerms`)
+ *  — minus any of those that reads across senses. A quake card's report
  *  names "earthquake" and a place; the class term is where the graph's
  *  knowledge is thinnest and its senses widest, so background drawn through it
  *  is background about earthquakes in general, never about this quake. The hub
- *  itself is always in, whatever its sense count — the card is about it. */
-function cardSubjectTerms(hub, subgraphRows, { reportedIds = null, senseFan }) {
+ *  itself is always in, whatever its sense count — the card is about it.
+ *
+ *  An article entity earns the same reading a report term gets, one rank
+ *  behind it: the story's own words name it, but no fact the card reports
+ *  does. */
+function cardSubjectTerms(hub, subgraphRows, { reportedIds = null, senseFan, articleTerms = [] }) {
   const hubTerm = normFactTerm(hub);
   const isReported = idMembership(reportedIds);
-  const terms = new Set(hubSeedTerms(hubTerm));
+  const terms = new Map();
+  for (const seed of hubSeedTerms(hubTerm)) terms.set(seed, ANCHOR_RANK_HUB);
+  const admit = (raw, rank) => {
+    const term = normFactTerm(raw);
+    if (!term || terms.has(term) || STOP_SET.has(term)) return;
+    if ((senseFan.get(term) || 0) > IDENTITY_MAX_CLASSES) return;
+    terms.set(term, rank);
+  };
   for (const row of hubReportRows(hubTerm, subgraphRows, { reportedIds })) {
     if (!isReported(row.id)) continue;
-    for (const raw of [row.subject, row.object]) {
-      const term = normFactTerm(raw);
-      if (!term || terms.has(term) || STOP_SET.has(term)) continue;
-      if ((senseFan.get(term) || 0) > IDENTITY_MAX_CLASSES) continue;
-      terms.add(term);
-    }
+    for (const raw of [row.subject, row.object]) admit(raw, ANCHOR_RANK_REPORT);
   }
+  for (const raw of articleTerms) admit(raw, ANCHOR_RANK_ARTICLE);
   return terms;
 }
 
 /** The background rows worth telling a reader about, ranked: a row touching
  *  one of this card's own subject terms, whose other side is not a category
  *  node, and — for an identity row — whose subject is not read across senses.
- *  Ranks the hub's own rows first, then by how specific the other side is,
- *  then by content-addressed id, so the same fact set always yields the same
- *  lines in the same order. */
-export function knownFactRows(hub, subgraphRows, { reportedIds = null, limit = KNOWN_FACT_ROW_LIMIT } = {}) {
+ *  Ranks the hub's own rows first, then the ones its report names, then the
+ *  ones an entity in its article names, then by how specific the other side
+ *  is, then by content-addressed id, so the same fact set always yields the
+ *  same lines in the same order. */
+export function knownFactRows(hub, subgraphRows, {
+  reportedIds = null, limit = KNOWN_FACT_ROW_LIMIT, articleTerms = [],
+} = {}) {
   const hubTerm = normFactTerm(hub);
   const isReported = idMembership(reportedIds);
   const { senseFan, sourcedSenseFan, categoryFan } = identityFans(subgraphRows);
-  const subjects = cardSubjectTerms(hub, subgraphRows, { reportedIds, senseFan });
+  const subjects = cardSubjectTerms(hub, subgraphRows, { reportedIds, senseFan, articleTerms });
   const neighbourIds = new Set(neighbourRows(hub, subgraphRows, { reportedIds }).map((r) => r.id));
 
   const scored = [];
@@ -822,14 +872,14 @@ export function knownFactRows(hub, subgraphRows, { reportedIds = null, limit = K
     if ((categoryFan.get(other) || 0) > CATEGORY_FAN_MAX) continue;
     scored.push({
       row,
-      anchorIsHub: anchor === hubTerm,
+      anchorRank: subjects.get(anchor),
       otherCategoryFan: categoryFan.get(other) || 0,
       otherSenseFan: senseFan.get(other) || 0,
     });
   }
 
   return scored
-    .sort((a, b) => (Number(b.anchorIsHub) - Number(a.anchorIsHub))
+    .sort((a, b) => (a.anchorRank - b.anchorRank)
       || (a.otherCategoryFan - b.otherCategoryFan)
       || (a.otherSenseFan - b.otherSenseFan)
       || byId(a.row, b.row))
@@ -856,30 +906,49 @@ function predicatesInRenderOrder(rows) {
 
 /** One sentence per (subject, predicate) group over `rows`, in the order the
  *  rows arrive — the same shape the hub's own relation sentences take, so a
- *  background line reads like the rest of the paragraph rather than a dump. */
-function groupedFactSentences(rows) {
+ *  background line reads like the rest of the paragraph rather than a dump.
+ *  Each entry carries the group's own rows alongside its text, so a caller
+ *  that needs to know which facts a sentence came from (the bench's noisy-
+ *  line scoring) reads them off the same grouping the sentence itself used,
+ *  never a second derivation of it. */
+function groupedFactSentenceEntries(rows) {
   const groups = new Map();
   for (const row of rows) {
     const key = `${row.subject}${row.predicate}`;
     let group = groups.get(key);
-    if (!group) groups.set(key, (group = { subject: row.subject, predicate: row.predicate, objects: [] }));
+    if (!group) groups.set(key, (group = { subject: row.subject, predicate: row.predicate, objects: [], rows: [] }));
     group.objects.push(row.object);
+    group.rows.push(row);
   }
-  return [...groups.values()].map(({ subject, predicate, objects }) => {
+  return [...groups.values()].map(({ subject, predicate, objects, rows: groupRows }) => {
     const sorted = [...objects].sort();
-    const rendered = IDENTITY_PREDICATES.has(predicate)
-      ? sorted.map((object) => `${articleFor(object)} ${object}`)
-      : sorted;
-    return `${subject} ${predicatePhrase(predicate, subject)} ${joinObjects(rendered)}`;
+    // "rdf:type" reads "is a" from the curated phrase table, which is the wrong
+    // article before a vowel and a second one in front of an object articleFor
+    // has already spelled. The identity clause the paragraph opens with says a
+    // bare "is" and lets articleFor choose; a background line says it the same
+    // way. Every other predicate, "is a kind of" included, carries whatever
+    // article it needs inside its own phrase and takes the object bare.
+    const text = predicate === "rdf:type"
+      ? `${subject} is ${joinObjects(sorted.map((object) => `${articleFor(object)} ${object}`))}`
+      : `${subject} ${predicatePhrase(predicate, subject)} ${joinObjects(sorted)}`;
+    return { text, rows: groupRows };
   });
 }
 
+function groupedFactSentences(rows) {
+  return groupedFactSentenceEntries(rows).map((entry) => entry.text);
+}
+
 /** The sentences a card's paragraph is made of, as four ordered blocks: the
  *  report (what a source said inside the window), the identity clause, the
- *  related facts the graph already held, and the neighbourhood. Callers that
- *  render only one block — the "what the graph already knew" disclosure —
- *  read the block they want instead of re-deriving it. */
-function paragraphBlocks(hub, subgraphRows, { reportedIds = null } = {}) {
+ *  related facts the graph already held, and the neighbourhood. Each entry is
+ *  `{ text, rows }` — the rendered sentence and the fact row(s) it came from
+ *  — so a caller that needs to know which facts actually reached the printed
+ *  text (the bench's noisy-line scoring) reads them off the same blocks
+ *  `renderNewsParagraph` itself slices, never a second derivation of it.
+ *  Callers that render only one block — the "what the graph already knew"
+ *  disclosure — read the block they want instead of re-deriving it. */
+function paragraphBlocks(hub, subgraphRows, { reportedIds = null, articleTerms = [] } = {}) {
   const hubTerm = normFactTerm(hub);
   const isReported = idMembership(reportedIds);
   const hubRows = subgraphRows.filter((r) => normFactTerm(r.subject) === hubTerm);
@@ -887,12 +956,10 @@ function paragraphBlocks(hub, subgraphRows, { reportedIds = null } = {}) {
   const report = [];
   for (const predicate of predicatesInRenderOrder(reportedHubRows)) {
     if (IDENTITY_PREDICATES.has(predicate) || report.length >= REPORT_SENTENCE_CAP) continue;
-    const objects = reportedHubRows
-      .filter((r) => r.predicate === predicate)
-      .map((r) => r.object)
-      .sort();
+    const groupRows = reportedHubRows.filter((r) => r.predicate === predicate);
+    const objects = groupRows.map((r) => r.object).sort();
     if (!objects.length) continue;
-    report.push(`${hub} ${predicatePhrase(predicate, hub)} ${joinObjects(objects)}`);
+    report.push({ text: `${hub} ${predicatePhrase(predicate, hub)} ${joinObjects(objects)}`, rows: groupRows });
   }
 
   // A hub that only ever appears as an OBJECT — the place a quake struck, the
@@ -900,12 +967,13 @@ function paragraphBlocks(hub, subgraphRows, { reportedIds = null } = {}) {
   // and its card came out blank. What was reported about it still says
   // something, so those rows render whole, subject and all.
   if (!report.length) {
-    const aboutHub = subgraphRows
+    const aboutHubRows = subgraphRows
       .filter((r) => normFactTerm(r.object) === hubTerm && normFactTerm(r.subject) !== hubTerm && isReported(r.id))
       .sort(byId)
-      .slice(0, OBJECTS_PER_SENTENCE)
-      .map((r) => factSentence(r));
-    if (aboutHub.length) report.push(aboutHub.join("; "));
+      .slice(0, OBJECTS_PER_SENTENCE);
+    if (aboutHubRows.length) {
+      report.push({ text: aboutHubRows.map((r) => factSentence(r)).join("; "), rows: aboutHubRows });
+    }
   }
 
   // The identity clause follows the news, never leads it, and only when
@@ -913,23 +981,41 @@ function paragraphBlocks(hub, subgraphRows, { reportedIds = null } = {}) {
   // closure names thirteen classes for "france" — a list nobody asked for,
   // most of it the wrong sense — so it opens no card.
   const identity = [];
-  const identityObjects = hubRows
-    .filter((r) => IDENTITY_PREDICATES.has(r.predicate) && !isDerivedRow(r))
-    .map((r) => r.object)
-    .sort();
+  const identityRows = hubRows.filter((r) => IDENTITY_PREDICATES.has(r.predicate) && !isDerivedRow(r));
+  const identityObjects = identityRows.map((r) => r.object).sort();
   const identityIsSingleSense = identityObjects.length > 0 && identityObjects.length <= IDENTITY_MAX_CLASSES;
   if (identityIsSingleSense) {
-    identity.push(`${hub} is ${joinObjects(identityObjects.map((object) => `${articleFor(object)} ${object}`))}`);
+    identity.push({
+      text: `${hub} is ${joinObjects(identityObjects.map((object) => `${articleFor(object)} ${object}`))}`,
+      rows: identityRows,
+    });
   }
 
-  const known = groupedFactSentences(knownFactRows(hub, subgraphRows, { reportedIds }));
+  const known = groupedFactSentenceEntries(knownFactRows(hub, subgraphRows, { reportedIds, articleTerms }));
 
   const neighbours = neighbourRows(hub, subgraphRows, { reportedIds });
-  const around = neighbours.length ? [`Around it: ${neighbours.map((r) => factSentence(r)).join("; ")}`] : [];
+  const around = neighbours.length
+    ? [{ text: `Around it: ${neighbours.map((r) => factSentence(r)).join("; ")}`, rows: neighbours }]
+    : [];
 
   return { report, identity, known, around };
 }
 
+/** The paragraph's own sentence entries (`{ text, rows }`), in print order and
+ *  sliced to exactly what `renderNewsParagraph` shows — the per-block caps
+ *  (identity, known) and the paragraph-wide `SENTENCE_CAP` both applied.
+ *  Shared by `renderNewsParagraph` and `printedParagraphRows` so the two can
+ *  never drift: one reads `.text`, the other reads `.rows`. */
+function paragraphSentenceEntries(hub, subgraphRows, { reportedIds = null, articleTerms = [] } = {}) {
+  const { report, identity, known, around } = paragraphBlocks(hub, subgraphRows, { reportedIds, articleTerms });
+  return [
+    ...report,
+    ...identity.slice(0, IDENTITY_SENTENCE_CAP),
+    ...known.slice(0, KNOWN_FACT_SENTENCE_CAP),
+    ...around,
+  ].slice(0, SENTENCE_CAP);
+}
+
 /** A card's paragraph: what a source reported, then what the thing is, then
  *  the related facts the graph already held about it, then its own
  *  neighbourhood (neighbourRows). Every sentence shown is a grounded fact,
@@ -940,27 +1026,307 @@ function paragraphBlocks(hub, subgraphRows, { reportedIds = null } = {}) {
  *  into what was reported (the lead sentences) and what the graph already held
  *  (the background ones). Defaults to null, meaning every row counts as
  *  reported. */
-export function renderNewsParagraph(hub, subgraphRows, { reportedIds = null } = {}) {
-  const { report, identity, known, around } = paragraphBlocks(hub, subgraphRows, { reportedIds });
-  const sentences = [
-    ...report,
-    ...identity.slice(0, IDENTITY_SENTENCE_CAP),
-    ...known.slice(0, KNOWN_FACT_SENTENCE_CAP),
-    ...around,
-  ].slice(0, SENTENCE_CAP);
+export function renderNewsParagraph(hub, subgraphRows, { reportedIds = null, articleTerms = [] } = {}) {
+  const sentences = paragraphSentenceEntries(hub, subgraphRows, { reportedIds, articleTerms }).map((entry) => entry.text);
   return sentences.length ? `${sentences.join(". ")}.` : "";
 }
 
+/** Every fact row that survives into the card's rendered main paragraph —
+ *  the same rows `renderNewsParagraph` drew its sentences from, after every
+ *  cap it applies (per-block and the paragraph-wide `SENTENCE_CAP`). A row
+ *  computed but sliced away before render (an "Around it" clause cut by the
+ *  overall cap, an identity class beyond `IDENTITY_MAX_CLASSES`) never
+ *  appears here, because it never appears on the card either. */
+export function printedParagraphRows(hub, subgraphRows, { reportedIds = null, articleTerms = [] } = {}) {
+  return paragraphSentenceEntries(hub, subgraphRows, { reportedIds, articleTerms }).flatMap((entry) => entry.rows);
+}
+
 /** The "what the graph already knew" disclosure: the same related facts the
  *  paragraph leads with, at the disclosure's own fuller depth, and nothing the
  *  card already reported. Empty when the graph held nothing about this card's
  *  own subjects — a card with no background says so rather than filling the
  *  space with whatever the two-hop walk happened to reach. */
-export function renderKnownFactsParagraph(hub, subgraphRows, { reportedIds = null } = {}) {
-  const sentences = groupedFactSentences(knownFactRows(hub, subgraphRows, { reportedIds }));
+export function renderKnownFactsParagraph(hub, subgraphRows, { reportedIds = null, articleTerms = [] } = {}) {
+  const sentences = groupedFactSentences(knownFactRows(hub, subgraphRows, { reportedIds, articleTerms }));
   return sentences.length ? `${sentences.join(". ")}.` : "";
 }
 
+// ---------------------------------------------------------------------------
+// Which story a card tells, and what it is called.
+// ---------------------------------------------------------------------------
+
+// The item tag a news row carries, at whatever depth the ingest wrapper
+// nested it ("news:<sourceId>@<itemId>", "optimistic-extract:news:…"), plus
+// the fixture replay's own twin. Every sentence a card prints comes from a
+// row, so which story a card is telling is readable from the fact set alone —
+// no source map, no arrival order, no clock.
+const NEWS_STORY_TAG_RE = /(?:^|:)news(?:-fixture)?:([^\s|]+)/;
+
+/** The newsworthy item one row reported, or "" when its provenance names
+ *  none. Pure. */
+export function newsStoryKey(row) {
+  return NEWS_STORY_TAG_RE.exec(String(row?.provenance || ""))?.[1] || "";
+}
+
+/** Every reported row touching each term, subject side or object side. Built
+ *  once per feed assembly and shared, for the same reason buildTermAdjacency
+ *  is. */
+function reportedRowsByTerm(reported) {
+  const byTerm = new Map();
+  for (const row of reported) {
+    for (const term of new Set([normFactTerm(row.subject), normFactTerm(row.object)])) {
+      if (!term) continue;
+      let rowsFor = byTerm.get(term);
+      if (!rowsFor) byTerm.set(term, (rowsFor = []));
+      rowsFor.push(row);
+    }
+  }
+  return byTerm;
+}
+
+// How many stories a term's own reports must span before it stops being one
+// story's subject. Two is enough: a term the day's second story also names is
+// a publication, a wire desk or a class every item shares, and a card headed
+// by one repeats whatever the per-story cards already said.
+const PUBLICATION_STORY_MIN = 2;
+
+/** How many distinct newsworthy items each term's own reports came from. */
+function storyCountsByTerm(rowsByTerm) {
+  const counts = new Map();
+  for (const [term, rowsFor] of rowsByTerm) {
+    const keys = new Set();
+    for (const row of rowsFor) {
+      const key = newsStoryKey(row);
+      if (key) keys.add(key);
+    }
+    counts.set(term, keys.size);
+  }
+  return counts;
+}
+
+// The classes the graph's own identity rows use to say a thing is a place or
+// a person. The same closed set the bench's entity-preservation metric reads
+// off the seed, duplicated here (not imported) because the domain layer never
+// imports a script.
+const PLACE_OR_PERSON_CLASS_TERMS = new Set([
+  "place", "person", "city", "country", "location", "nation", "continent",
+  "capital", "state", "province", "town", "region",
+]);
+
+/** Every term the graph itself types as a place or a person, whoever stated
+ *  the identity. A card prefers one of these for its own title: it is the
+ *  thing the story is about, where a clause the same report threw off is only
+ *  something that happened to it. Pure over `rows`. */
+export function placeAndPersonTerms(rows) {
+  const grounded = new Set();
+  for (const row of rows) {
+    if (row.predicate !== "rdf:type" && row.predicate !== "rdfs:subClassOf") continue;
+    if (!PLACE_OR_PERSON_CLASS_TERMS.has(normFactTerm(row.object))) continue;
+    const subject = normFactTerm(row.subject);
+    if (subject) grounded.add(subject);
+  }
+  return grounded;
+}
+
+// A predicate minted from a source's own verb, lemma only: "mgx:hit",
+// "mgx:discuss". The curated table's entries carry a capital ("mgx:partOf")
+// and a folded preposition carries a hyphen ("mgx:strike-near"), and neither
+// can be a single word inside a term, so neither belongs in the verb set.
+const MINTED_VERB_PREDICATE_RE = /^mgx:([a-z]+)$/;
+
+/** The verbs this window's own reports minted a predicate from. A term
+ *  carrying one of them is a clause the extraction cut in half, and the graph
+ *  says so itself rather than a hand-written verb list saying it. */
+export function reportedVerbWords(reported) {
+  const verbs = new Set();
+  for (const row of reported) {
+    const lemma = MINTED_VERB_PREDICATE_RE.exec(String(row.predicate || ""))?.[1];
+    if (lemma) verbs.add(lemma);
+  }
+  return verbs;
+}
+
+// How many words a name runs to before it reads as a sentence about a thing
+// rather than the thing's name. "south sandwich islands region" is a place;
+// "boats hit by mystery attackers" is what happened to some.
+const CLAUSE_TITLE_MAX_WORDS = 4;
+const CLAUSE_WORD_EDGE_RE = /^[^a-z0-9]+|[^a-z0-9]+$/g;
+
+/** Does `term` read as a clause rather than a name — longer than a name runs,
+ *  or carrying one of the verbs the window's own reports minted? A clause
+ *  never takes a card's title from a grounded entity term. */
+export function readsAsClauseTerm(term, verbWords) {
+  const words = String(term ?? "").trim().toLowerCase().split(/\s+/).filter(Boolean);
+  if (!words.length) return false;
+  if (words.length > CLAUSE_TITLE_MAX_WORDS) return true;
+  const verbs = verbWords instanceof Set ? verbWords : new Set(verbWords || []);
+  return words.some((word) => verbs.has(word.replace(CLAUSE_WORD_EDGE_RE, "")));
+}
+
+/** The term a card is titled and keyed by, given the hub the gate chose and
+ *  the reported rows that hub sits in. In order:
+ *
+ *  1. the hub itself, when the graph already types it as a place or a person;
+ *  2. a place/person term the hub's own reports name — "bali" over "sacred
+ *     glow", "clacton" over "election";
+ *  3. the subject those reports share, but only when the hub reads as a clause
+ *     and only when that subject tells one story of its own — the publication
+ *     every headline hangs off is never a card's name;
+ *  4. the hub, unchanged.
+ *
+ *  Ties inside a step go to the term the reports name most, then alphabetical,
+ *  so the same fact set always titles a card the same way. Nothing here invents
+ *  a term: every candidate is already on one of the card's own rows. */
+export function hubTitleTerm(hubTerm, hubRows, { placeOrPerson, verbWords, storyCountByTerm }) {
+  if (placeOrPerson.has(hubTerm)) return hubTerm;
+
+  const namesAThing = (term) => Boolean(term) && term !== hubTerm && !STOP_SET.has(term)
+    && !isQuantityTerm(term) && looksLikeEntityTerm(term) && !readsAsClauseTerm(term, verbWords);
+
+  const groundedCounts = new Map();
+  const subjectCounts = new Map();
+  for (const row of hubRows) {
+    const subject = normFactTerm(row.subject);
+    const object = normFactTerm(row.object);
+    for (const term of new Set([subject, object])) {
+      if (namesAThing(term) && placeOrPerson.has(term)) groundedCounts.set(term, (groundedCounts.get(term) || 0) + 1);
+    }
+    if (object !== hubTerm || !namesAThing(subject)) continue;
+    if ((storyCountByTerm.get(subject) || 0) >= PUBLICATION_STORY_MIN) continue;
+    subjectCounts.set(subject, (subjectCounts.get(subject) || 0) + 1);
+  }
+
+  const mostNamed = (counts) => [...counts.entries()]
+    .sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))[0]?.[0] || "";
+
+  return mostNamed(groundedCounts)
+    || (readsAsClauseTerm(hubTerm, verbWords) ? mostNamed(subjectCounts) : "")
+    || hubTerm;
+}
+
+/** True when a source spelled this term as a settlement and its region at once
+ *  — "wana, pakistan", "mina, nevada". The source has already said which of a
+ *  report's terms is the thing that happened somewhere, so the term reads as a
+ *  place even where no identity row types it as one. hubSeedTerms holds the
+ *  same reading for the walk. */
+const namesASettlementAndRegion = (term) => hubSeedTerms(term).length > 1;
+
+/** The gate's hubs retitled by hubTitleTerm, with two hubs that answer to the
+ *  same name merged into one. Each keeps the two readings storyCoverage ranks
+ *  cards by, taken on the title the card will actually wear. Keeps the gate's
+ *  own sort — changed count desc, then term asc. */
+function titledHubs(hubs, rows, reported, rowsByTerm) {
+  const placeOrPerson = placeAndPersonTerms(rows);
+  const verbWords = reportedVerbWords(reported);
+  const storyCountByTerm = storyCountsByTerm(rowsByTerm);
+  const changedByTitle = new Map();
+  for (const { term, changed } of hubs) {
+    const title = hubTitleTerm(term, rowsByTerm.get(term) || [], { placeOrPerson, verbWords, storyCountByTerm });
+    const held = changedByTitle.get(title);
+    if (held === undefined || changed > held) changedByTitle.set(title, changed);
+  }
+  return [...changedByTitle.entries()]
+    .map(([term, changed]) => ({
+      term,
+      changed,
+      namesAnEntity: placeOrPerson.has(term) || namesASettlementAndRegion(term),
+      clauseShaped: readsAsClauseTerm(term, verbWords),
+      reportSubject: (rowsByTerm.get(term) || []).some((row) => normFactTerm(row.subject) === term),
+    }))
+    .sort((a, b) => b.changed - a.changed || (a.term < b.term ? -1 : a.term > b.term ? 1 : 0));
+}
+
+/** How a story picks between the cards that want to tell it. In order: the
+ *  hub whose own reports span fewest stories, since a card about one story
+ *  beats a publication's roundup of it; then the hub that names a place or a
+ *  person, since that is what the story is about; then the hub that
+ *  reads as a name rather than a clause; then the one the report puts on the
+ *  subject side, the story's actor where the object is what happened to it;
+ *  then the gate's own changed count; then the term itself, so the answer never
+ *  comes down to arrival order. */
+function byCardClaim(a, b) {
+  return a.storyCount - b.storyCount
+    || (Number(b.namesAnEntity) - Number(a.namesAnEntity))
+    || (Number(a.clauseShaped) - Number(b.clauseShaped))
+    || (Number(b.reportSubject) - Number(a.reportSubject))
+    || (b.changed - a.changed)
+    || (a.term < b.term ? -1 : a.term > b.term ? 1 : 0);
+}
+
+/** Which stories each hub gets to tell, and which of its reports belong to
+ *  another card. One story mints one card: the hubs bid for it in byCardClaim
+ *  order and the first takes it, so a report that threw off both a subject hub
+ *  and an object hub ("ukraine" beside "air war", "london" beside "glass")
+ *  stops minting a card each. A hub left with no story of its own does not
+ *  mint, and one that keeps some carries only those — the "hackernews" card
+ *  that repeated both of the day's Hacker News cards wholesale is gone, and one
+ *  that repeated three of four carries the fourth alone.
+ *
+ *  A row whose provenance names no story is never claimed and never dropped, so
+ *  a hub built only from those still mints.
+ *
+ *  Returns hub term -> `{ mints, coveredRowIds }`. */
+export function storyCoverage(hubs, rowsByTerm) {
+  const rowIdsByStory = new Map();
+  for (const { term } of hubs) {
+    const byStory = new Map();
+    for (const row of rowsByTerm.get(term) || []) {
+      const key = newsStoryKey(row);
+      if (!key) continue;
+      let ids = byStory.get(key);
+      if (!ids) byStory.set(key, (ids = []));
+      ids.push(row.id);
+    }
+    rowIdsByStory.set(term, byStory);
+  }
+
+  const bidders = hubs
+    .map((hub) => ({ ...hub, storyCount: rowIdsByStory.get(hub.term).size }))
+    .sort(byCardClaim);
+
+  const claimed = new Set();
+  const coverage = new Map();
+  for (const { term, storyCount } of bidders) {
+    const stories = rowIdsByStory.get(term);
+    const coveredRowIds = new Set();
+    let ownStories = 0;
+    for (const key of [...stories.keys()].sort()) {
+      if (claimed.has(key)) {
+        for (const id of stories.get(key)) coveredRowIds.add(id);
+        continue;
+      }
+      claimed.add(key);
+      ownStories += 1;
+    }
+    coverage.set(term, { mints: storyCount === 0 || ownStories > 0, coveredRowIds });
+  }
+  return coverage;
+}
+
+/** The entities this card's own article names, as terms the graph could hold
+ *  facts about. `articleEntityNames` reads them out of the text the card
+ *  already shows — each source's headline and the description beneath it — and
+ *  the same discipline the hub gate applies then filters them: no stop word, no
+ *  quantity, no class the graph's own identity rows name, nothing that reads as
+ *  a clause rather than a name. Sorted, so a card's background never depends on
+ *  the order the names came back in. */
+function cardArticleTerms(sources, articleEntityNames, { concepts, readsAsEntityTerm }) {
+  const texts = [];
+  for (const source of sources) {
+    if (source.title) texts.push(source.title);
+    if (source.summary) texts.push(source.summary);
+  }
+  if (!texts.length) return [];
+  const terms = new Set();
+  for (const name of articleEntityNames(texts) || []) {
+    const term = normFactTerm(name);
+    if (!term || STOP_SET.has(term) || isQuantityTerm(term) || concepts.has(term)) continue;
+    if (!readsAsEntityTerm(term)) continue;
+    terms.add(term);
+  }
+  return [...terms].sort();
+}
+
 /** newsworthyHubs -> one item per hub (PLAN_NEWS_FEED.md section 6.6),
  *  paragraph included, sorted builtAt desc then id asc. `sourcesByFactId`
  *  maps fact ids to snapshot source links ({ title, url, name, publishedAt?
@@ -977,19 +1343,57 @@ export function renderKnownFactsParagraph(hub, subgraphRows, { reportedIds = nul
  *  nothing else. The two-hop walk reaches every row a shared class node
  *  touches, so attributing the whole sub-graph gave one quake's card all 44 of
  *  the day's quake headlines. An "Around it" neighbour is context the card
- *  borrows, and it carries its own citation on its own card. */
-export function buildNewsItems(rows, { now, windowMs, limit = 6, sourcesByFactId = new Map(), readsAsEntityTerm } = {}) {
+ *  borrows, and it carries its own citation on its own card.
+ *
+ *  Between the gate and the render sit two more reads over the same reported
+ *  rows: `titledHubs` names each card after the entity its own report grounds
+ *  rather than a clause the report threw off, and `storyCoverage` leaves a
+ *  publication with only the stories no other card tells. Both are pure over
+ *  the fact set, so a feed built from the same rows in two orders still comes
+ *  back byte for byte.
+ *
+ *  `articleEntityNames`, when the caller supplies one, reads the entity names
+ *  out of the text of the sources a card shows (news.mjs wires the services
+ *  layer's own capture, the same one the enrichment ledger admits terms by).
+ *  Those entities widen the card's background: what the graph holds about a
+ *  name inside the headline now reaches the card, where before only the
+ *  endpoints of its own facts did. They never widen its report — the walk they
+ *  seed excludes every reported row — so what a card claims a source said is
+ *  untouched. */
+export function buildNewsItems(rows, {
+  now, windowMs, limit = 6, sourcesByFactId = new Map(), readsAsEntityTerm, articleEntityNames = null,
+} = {}) {
   const reported = reportedRows(rows, { now, windowMs });
   const reportedIds = new Set(reported.map((r) => r.id));
   const adjacency = buildTermAdjacency(rows);
   const prior = priorTerms(rows);
   const hubOptions = { now, windowMs, limit, adjacency, prior };
   if (readsAsEntityTerm) hubOptions.readsAsEntityTerm = readsAsEntityTerm;
-  const hubs = newsworthyHubs(rows, reported, hubOptions);
-  const items = hubs.map(({ term, changed }) => {
-    const subgraphRows = subgraphAround(rows, term, {
-      adjacency, priorityIds: reportedIds, seedTerms: hubSeedTerms(term),
+  const rowsByTerm = reportedRowsByTerm(reported);
+  const hubs = titledHubs(newsworthyHubs(rows, reported, hubOptions), rows, reported, rowsByTerm);
+  const coverage = storyCoverage(hubs, rowsByTerm);
+  const concepts = conceptTerms(rows);
+  const namesEntities = readsAsEntityTerm || looksLikeEntityTerm;
+  const items = hubs.filter(({ term }) => coverage.get(term).mints).map(({ term, changed }) => {
+    const coveredRowIds = coverage.get(term).coveredRowIds;
+    const hubRows = subgraphAround(rows, term, {
+      adjacency,
+      priorityIds: reportedIds,
+      seedTerms: hubSeedTerms(term),
+      excludeIds: coveredRowIds,
     });
+    const sources = collectSources(hubReportRows(term, hubRows, { reportedIds }), sourcesByFactId);
+    const articleTerms = articleEntityNames
+      ? cardArticleTerms(sources, articleEntityNames, { concepts, readsAsEntityTerm: namesEntities })
+      : [];
+    const heldIds = new Set(hubRows.map((r) => r.id));
+    const articleRows = articleTerms.length
+      ? articleEntityRows(rows, articleTerms, {
+        adjacency,
+        excludeIds: new Set([...coveredRowIds, ...reportedIds]),
+      }).filter((r) => !heldIds.has(r.id))
+      : [];
+    const subgraphRows = articleRows.length ? [...hubRows, ...articleRows] : hubRows;
     const factIds = subgraphRows.map((r) => r.id).sort();
     const { background } = splitCardRows(subgraphRows, reportedIds);
     return {
@@ -998,11 +1402,11 @@ export function buildNewsItems(rows, { now, windowMs, limit = 6, sourcesByFactId
       factIds,
       changedCount: changed,
       builtAt: now,
-      paragraph: renderNewsParagraph(term, subgraphRows, { reportedIds }),
+      paragraph: renderNewsParagraph(term, subgraphRows, { reportedIds, articleTerms }),
       tier: tierOf(subgraphRows),
-      sources: collectSources(hubReportRows(term, subgraphRows, { reportedIds }), sourcesByFactId),
+      sources,
       background: background.map((r) => r.id).sort(),
-      backgroundParagraph: renderKnownFactsParagraph(term, subgraphRows, { reportedIds }),
+      backgroundParagraph: renderKnownFactsParagraph(term, subgraphRows, { reportedIds, articleTerms }),
     };
   });
   return items.sort((a, b) => (toMs(b.builtAt) - toMs(a.builtAt)) || byId(a, b));