@clien-ai/mcp 0.10.8 → 0.11.0

package/dist/tools/report-digest.js

@@ -46,8 +46,9 @@
  * moves agent-authored text below that separator breaks the digest's own authority
  * rule, which a reader applies positionally.
  */
-import { collapseWhitespace, safeInline, safeId, clipReceiptQuote, RECEIPT_QUOTE_MAX, } from './render-safety.js';
+import { collapseWhitespace, safeInline, safeId, clipReceiptQuote, containsSpan, hasVisibleContent, RECEIPT_QUOTE_MAX, } from './render-safety.js';
 import { canonicalContentType, contentTypeDeviationLine, contentTypeProvenanceLine, } from './content-type-display.js';
+import { resolveSourceReceipt } from './receipt-children.js';
 import { resolveSupportedMarketSizing } from './market-sizing-proof.js';
 /**
  * Max claims rendered per spine. Above this the digest states how many were
@@ -184,6 +185,32 @@ const UNSOURCED_LABEL = 'unsourced';
 const HYPOTHESIS_LABEL = 'hypothesis';
 const SCOPE_CAVEAT_LABEL = '⚠️ scope caveat — persona support from OUTSIDE its credibility domain; directional, NOT grounded';
 const EVIDENCE_READING_LABEL = 'rests on';
+/**
+ * The marker on a receipt-CHILD line, and the pool sentence that explains it (FUL-685 / T8).
+ *
+ * ⚠️ IT HAS TO BE VISUALLY SUBORDINATE, for the same reason the pool prints one row per source
+ * parent: a child line that opened with `- ` would read as another cached discussion, which is
+ * exactly the breadth inflation D13 refuses. `↳` under an existing row reads as "inside this
+ * one" and nothing else.
+ *
+ * ⚠️ AND THE WORD IS `excerpt`, NOT `quote`. T1b (FUL-697) measured the provider transforming
+ * the text it returns — deleting a paragraph break, replacing an author's hyperlink with the
+ * literal token `URL` — on the rail these children come from. Calling this a speaker's exact
+ * words would be a false claim on the one surface whose entire purpose is that the product does
+ * not make those. The sentence renders only when a row actually has a child, so a report with
+ * no multi-excerpt source is byte-identical to what it rendered before.
+ */
+const RECEIPT_CHILD_MARKER = '↳';
+/**
+ * The spine's half of the same fact. One discussion can legitimately yield several excerpts, so
+ * a claim that addresses one carries BOTH ids — `sourceId` for the discussion, `receiptId` for
+ * the excerpt inside it — and the pool row's matching `↳` line is the text it was checked
+ * against. An unresolvable pair is never softened into the parent: it loses the receipt.
+ */
+const RECEIPT_CHILD_SPINE_NOTE = 'A claim carrying a second id after `·` addresses ONE excerpt inside that discussion — match it ' +
+    'to the `↳` line of the same id in the receipt pool below, not to the row\'s first excerpt.';
+const RECEIPT_CHILD_POOL_NOTE = 'A `↳` line is the bounded EXCERPT one claim\'s `receiptId` addresses inside that discussion — ' +
+    'an excerpt, not a speaker\'s exact words, and the claim line above names the id it points at';
 // ---------------------------------------------------------------------------
 // Defensive accessors — every one of these answers "or nothing" rather than throwing
 // ---------------------------------------------------------------------------
@@ -221,6 +248,25 @@ function renderId(raw, absent = '(no id)') {
 function num(value) {
     return typeof value === 'number' && Number.isFinite(value) ? value : null;
 }
+/**
+ * Acceptance is a count, not merely a finite number (FUL-740).
+ *
+ * Classify before interpreting so an invalid counter can never reach a comparison that reads it
+ * as evidence or absence. `Number.isInteger` rejects non-numbers, NaN, Infinity and fractions;
+ * the remaining check rejects negative integers. `null` is treated like an omitted field because
+ * both mean the producer supplied no usable counter; either way, only `valid` carries a number
+ * downstream.
+ */
+function readAcceptanceCounter(value) {
+    if (value === undefined || value === null)
+        return { kind: 'absent' };
+    if (!Number.isInteger(value))
+        return { kind: 'invalid' };
+    const integer = value;
+    if (integer < 0)
+        return { kind: 'invalid' };
+    return { kind: 'valid', value: integer };
+}
 /**
  * TRI-STATE boolean read: `true`, `false`, or `null` for "absent or unreadable".
  *
@@ -272,7 +318,27 @@ function safeReceiptUrl(raw) {
         return null;
     }
 }
-/** Resolve the single, persona-owned presentation grant behind a GROUNDED claim. */
+/**
+ * Resolve the single, persona-owned presentation grant behind a GROUNDED claim.
+ *
+ * ⚠️ FUL-711 — TWO REFERENCES, AND THEY MUST AGREE. `sourceId` locates the source parent
+ * positionally; an optional `receiptId` locates the exact excerpt CHILD inside it. The three
+ * outcomes are deliberately not two:
+ *
+ *   - **no `receiptId` key (or raw `undefined`)** — the legacy path. Resolve the parent, render
+ *     its single cached excerpt, exactly as before this function learned about children.
+ *   - **`receiptId` resolves AND the child carries the claim's `quoteSpan`** — the claim
+ *     addresses that child, and the child's own text is what `clipReceiptQuote` gets as its
+ *     haystack. Both halves, or neither: FUL-728 added the span check because resolving to a
+ *     child that does not contain the span is FUL-711's defect with a content-addressed id on
+ *     it (see the call site).
+ *   - **`receiptId` present but unresolvable** — `null`, malformed, dangling, cross-source,
+ *     duplicate, or a parent with no children at all: **return `null` and fail closed.** Our
+ *     producer omits this optional key, so an explicit `null` has unknown provenance and cannot
+ *     claim the legacy parent's quote as grounded evidence. Falling back would print a 200-char
+ *     clip of excerpt 1 under a GROUNDED badge for a claim grounded on excerpt 2 — precisely the
+ *     defect this resolution exists to remove, restored as an error path.
+ */
 function resolvePersonaReceipt(rawClaim, personas) {
     const claim = asRecord(rawClaim);
     if (str(claim?.state) !== 'GROUNDED')
@@ -288,11 +354,71 @@ function resolvePersonaReceipt(rawClaim, personas) {
     const href = safeReceiptUrl(source?.url);
     if (!source || !href)
         return null;
+    // Branch on the RAW value, not on the resolved one: only `undefined` is "legacy claim, nothing
+    // to resolve" and every present value — including `null` — is a promise this parent must keep.
+    const claimedReceiptId = claim?.receiptId;
+    let child = null;
+    if (claimedReceiptId !== undefined) {
+        child = resolveSourceReceipt(source.receipts, claimedReceiptId) ?? null;
+        if (!child)
+            return null;
+        // ⚠️ RESOLVING THE ID IS NOT CHECKING THE SPAN, AND FUL-711'S DEFECT SURVIVES THE GAP
+        // (FUL-728). A `receiptId` that is well-formed, lives under the RIGHT parent, and is unique
+        // there resolves cleanly — while the claim's `quoteSpan` sits in a DIFFERENT child of that
+        // same parent. Nothing above notices: the id was never asked to agree with the span, only to
+        // exist. `clipReceiptQuote` then finds no span in the child it was handed, takes the head
+        // clip, and the digest prints `[GROUNDED]` beside an excerpt that does not contain the
+        // sentence which earned the badge — FUL-711 resolved to the wrong child instead of
+        // positionally, which is the same lie with a content-addressed id on it. D12 asks the
+        // selected receipt to CONTAIN the exact span, so ask it here.
+        //
+        // ⚠️ THIS IS A DIFFERENT AXIS FROM THE `> 1` BOUND BELOW, and neither substitutes for the
+        // other. That one asks whether a claim named a child at all; this one asks whether the child
+        // it named is the right one. Widening that bound would break the single-child byte-identity
+        // guarantee it exists to hold; this check cannot, because it lives entirely inside the branch
+        // a `receiptId` opens — a legacy claim carries none and never reaches it.
+        //
+        // ⚠️ NO `quoteSpan` STILL GRANTS. There is no span to contradict the child, and refusing on
+        // absence would be a different rule — "a Reddit claim must carry a span" — which belongs to
+        // the producer and to T5's schema, not to a renderer inferring it. `containsSpan` uses the
+        // renderer's OWN lookup, so a span this package could not locate can never earn a badge here
+        // and then quietly render as an unwindowed head clip.
+        //
+        // ⚠️ BRANCH ON THE RAW VALUE, exactly as `receiptId` does two lines up (#1059 review). `str()`
+        // answers `null` for a NUMBER, an OBJECT and `''` alike, so reading through it would file a
+        // present-but-malformed span under "legacy claim, nothing to check" and grant. Those are
+        // different facts: absence is a claim that never promised a span, while a present one is a
+        // promise this child has to keep, and a producer that emitted `42` or `''` there has told us
+        // nothing about which sentence earned the badge. Fail closed on the promise it cannot keep.
+        const rawSpan = claim?.quoteSpan;
+        if (rawSpan !== undefined && rawSpan !== null) {
+            const span = str(rawSpan);
+            if (span === null || !containsSpan(child.excerpt, span))
+                return null;
+        }
+    }
+    else if (asArray(source.receipts).length > 1) {
+        // ⚠️ ABSENT `receiptId` ON A parent carrying SEVERAL children is not a legacy claim — it is a
+        // producer that failed to name one, and it is the only case that reaches the fallback this
+        // function's docblock forbids. `quote` holds excerpt 1 (D13: one staging row per permalink),
+        // so returning the parent prints a clip of excerpt 1 under a GROUNDED badge for a claim whose
+        // span may live in excerpt 2 — FUL-711's exact defect, restored as an error path that fires
+        // only on malformed input nobody is watching.
+        //
+        // ⚠️ THE BOUND IS `> 1`, NOT `> 0`, AND THAT IS D15's LINE — "multi-receipt evidence" needs an
+        // addressed child; "legacy single-receipt" keeps positional behaviour. With exactly ONE child
+        // the parent row and that child carry the same text BY CONSTRUCTION, so resolving positionally
+        // cannot show a span-free excerpt and the legacy byte-identity guarantee holds. Widening this
+        // to `> 0` breaks that guarantee for one-child sources, which is a real regression: an
+        // additive field would start changing what a legacy reader sees.
+        return null;
+    }
     return {
         sourceId: `RCP-p${personaIndex}-s${sourceIndex}`,
         href,
         quote: collapseWhitespace(str(source.quote) ?? ''),
         source,
+        child,
     };
 }
 function resolvePersonaRows(reportData) {
@@ -369,7 +495,13 @@ function renderPersonaClaim(raw, resolvedReceipt) {
     // why a pointer on a non-GROUNDED claim must never render as a receipt.
     let provenance = '';
     if (resolvedReceipt) {
-        provenance = ` ← ${resolvedReceipt.sourceId}`;
+        // FUL-685: when the claim addressed a receipt CHILD, the arrow carries both halves of the
+        // pair. Without the child id a reader looking at two claims on one `RCP-p0-s0` row cannot
+        // tell which `↳` excerpt grounds which claim — the same "wrong excerpt under a GROUNDED
+        // badge" confusion this change removes, relocated one line down. `safeId` because it is an
+        // identifier: exact or nothing.
+        const childId = resolvedReceipt.child ? safeId(resolvedReceipt.child.receiptId) : null;
+        provenance = ` ← ${resolvedReceipt.sourceId}${childId ? ` · ${childId}` : ''}`;
     }
     else if (rawState === 'GROUNDED') {
         provenance = ' · Stored grade: GROUNDED — receipt unavailable; do not cite';
@@ -387,7 +519,8 @@ function renderPersonaClaim(raw, resolvedReceipt) {
  * A stored GROUNDED grade and a model-attestation marker are both untrusted report JSON, not proof
  * by themselves. Either earns its presentation only when its canonical pointer indexes the exact
  * `reportEvidence` pool and the target has a non-credentialed HTTP(S) destination. An attestation
- * additionally needs its nonblank captured window. Keeping this as one resolver lets the row,
+ * additionally needs a captured window with something VISIBLE in it — not merely a nonblank
+ * string, which U+200B and the C0 controls satisfy. Keeping this as one resolver lets the row,
  * tally, pointer and window consume the same answer instead of minting orphan citations.
  */
 function resolveReportReceipt(rawClaim, reportEvidence) {
@@ -405,7 +538,13 @@ function resolveReportReceipt(rawClaim, reportEvidence) {
         const attestation = asRecord(claim?.attestation);
         sourceId = typeof attestation?.sourceId === 'string' ? attestation.sourceId.trim() : '';
         quote = typeof attestation?.quote === 'string' ? collapseWhitespace(attestation.quote) : '';
-        if (!quote)
+        // ⚠️ NONBLANK IS NOT THE SAME TEST AS "HAS A WINDOW" (#1059 review, same defect as FUL-728
+        // item 3). `collapseWhitespace` only collapses `\s`, which covers none of U+200B, U+2060,
+        // U+00AD or the C0 controls — so an attestation window built from those survives this as a
+        // non-empty string, clears the guard, and the claim earns `cited → RRCP-s0` plus an
+        // `Attested window: ""` line. A citation marker over a window nobody can read is the
+        // presentation this resolver exists to withhold.
+        if (!hasVisibleContent(quote))
             return null;
     }
     else {
@@ -523,9 +662,14 @@ function renderPersonaSpine(reportData, channel) {
     const tally = tallyPersonaStates(rows);
     const shown = rows.slice(0, CLAIM_RENDER_CAP);
     const lines = shown.map(({ claim, receipt }) => renderPersonaClaim(claim, receipt));
+    // FUL-685: only say the pair exists when a rendered claim actually carries one. A report with
+    // no multi-excerpt source renders this header byte-identically to before.
+    const anyChild = shown.some(({ receipt }) => receipt?.child);
     return (`### Persona claim spine — ${tallyLine(tally, rows.length)}\n` +
         'A GROUNDED claim\'s receipt id (`RCP-p{i}-s{j}`) indexes `personas[i].sources[j]` — the cached ' +
-        'forum post its quote span was code-verified against. A stored GROUNDED grade whose canonical, ' +
+        'forum post its quote span was code-verified against. ' +
+        (anyChild ? `${RECEIPT_CHILD_SPINE_NOTE} ` : '') +
+        'A stored GROUNDED grade whose canonical, ' +
         'persona-owned safe receipt is unavailable is rendered and counted NO_RECEIPT. NO_RECEIPT can mean a bad claim OR merely ' +
         'sparse evidence: check that persona\'s `insufficientEvidence` / `sourcesFound` below before ' +
         'discounting it. Anything not GROUNDED is unverified.\n' +
@@ -582,6 +726,25 @@ function renderReportSpine(reportData, channel) {
  * has no visible badge, so windowing a quote to support it would spend the excerpt
  * on a claim the agent cannot see, at the cost of one it can.
  */
+/**
+ * The bucket a claim's verified span belongs to.
+ *
+ * ⚠️ FUL-711 — KEYED BY THE HAYSTACK, NOT BY THE SOURCE. Before receipt children there was one
+ * text per source and `sourceId` was both. Now a source can carry several excerpts, and a span
+ * verified inside excerpt 2 is not findable in excerpt 1 — so windowing the parent by it would
+ * locate nothing and silently fall back to the head clip. One bucket per (parent, child), with
+ * the childless bucket keyed by the empty string, keeps every span pointed at the text it is
+ * actually in. A NUL (`U+0000`) cannot appear in either id, so the two halves cannot alias.
+ *
+ * ⚠️ THE SEPARATOR IS WRITTEN `\u0000`, NEVER AS THE RAW BYTE. A literal NUL anywhere in a
+ * `.ts` file makes `file` classify it as `data` and makes grep and ripgrep skip it with a bare
+ * `Binary file matches` — which, on the digest, silently removes the repo's most trust-critical
+ * renderer from every search an agent runs here. The escape is the same byte at runtime.
+ * Enforced by `__tests__/integration/workflows/source-files-stay-greppable.test.ts`.
+ */
+function receiptBucketKey(sourceId, receiptId) {
+    return `${sourceId}\u0000${receiptId ?? ''}`;
+}
 function collectVerifiedSpans(rows) {
     const spans = new Map();
     for (const { claim: raw, receipt } of rows.slice(0, CLAIM_RENDER_CAP)) {
@@ -591,11 +754,12 @@ function collectVerifiedSpans(rows) {
         const span = str(claim.quoteSpan);
         if (!span)
             continue;
-        const existing = spans.get(receipt.sourceId);
+        const key = receiptBucketKey(receipt.sourceId, receipt.child?.receiptId ?? null);
+        const existing = spans.get(key);
         if (existing)
             existing.push(span);
         else
-            spans.set(receipt.sourceId, [span]);
+            spans.set(key, [span]);
     }
     return spans;
 }
@@ -622,18 +786,36 @@ function collectVerifiedSpans(rows) {
  * pages, whose "quote" would be a page excerpt chosen at fetch time rather than a
  * human's own words, and the pool already carries the one thing a reader needs
  * from them — `publishedDate`, the figure's actual recency (FUL-148).
+ *
+ * FUL-685 (T8 / D13/D15), spec in FUL-711: a source whose ONE url yielded several bounded
+ * excerpts gets ONE row here, still — receipt count must never inflate source or discussion
+ * breadth — with an indented `↳` line per excerpt a rendered claim actually ADDRESSES. Not per
+ * stored excerpt: printing the whole child set under a row would make one discussion look like
+ * several, which is the inflation D13 exists to prevent, and would spend the digest budget on
+ * text no claim points at.
  */
 function renderReceiptPools(reportData, channel) {
     const reportEvidence = asArray(reportData.reportEvidence);
     const personaRows = resolvePersonaRows(reportData).slice(0, CLAIM_RENDER_CAP);
     const spansByReceipt = collectVerifiedSpans(personaRows);
+    /**
+     * One entry per source PARENT, carrying the receipt children the rendered claims addressed.
+     * A `Map` keyed by child id so two claims on the same excerpt collapse to one `↳` line.
+     */
     const personaReceiptById = new Map();
     for (const { receipt } of personaRows) {
-        if (receipt)
-            personaReceiptById.set(receipt.sourceId, receipt);
+        if (!receipt)
+            continue;
+        let row = personaReceiptById.get(receipt.sourceId);
+        if (!row) {
+            row = { receipt, children: new Map() };
+            personaReceiptById.set(receipt.sourceId, row);
+        }
+        if (receipt.child)
+            row.children.set(receipt.child.receiptId, receipt.child);
     }
     const personaReceipts = [];
-    for (const [receiptId, receipt] of personaReceiptById) {
+    for (const [receiptId, { receipt, children }] of personaReceiptById) {
         const source = receipt.source;
         // FUL-253: the quote below was already flattened — these two were not, and
         // they sit on the SAME `- RCP-…` line, so a newline in either forges the
@@ -647,17 +829,59 @@ function renderReceiptPools(reportData, channel) {
         // `collapseWhitespace` is a FORGERY GUARD, not formatting: this pool is a
         // list of `- RCP-i-j — …` lines, and a quote containing a newline plus a
         // convincing `- RCP-` prefix would add an entry pointing at a source nobody
-        // retrieved. A whitespace-only quote also collapses to '' here and correctly
-        // renders as a bare pointer rather than as `""` — "the source said nothing".
+        // retrieved.
+        //
+        // ⚠️ WHETHER TO PRINT THE LINE AT ALL IS A DIFFERENT QUESTION, AND `hasVisibleContent` IS THE
+        // ONE THAT ANSWERS IT (#1059 review, same defect as FUL-728 item 3). A whitespace-only quote
+        // collapses to '' and correctly renders as a bare pointer — "the source said nothing" — but
+        // a quote of U+200B or U+0000 survives the collapse non-empty, and this line then prints `""`
+        // under a receipt GROUNDED claims point at. The forgery guard stays on the flattening; the
+        // emptiness question is asked of the visible characters.
         //
         // FUL-252: WHICH `RECEIPT_QUOTE_MAX` characters is chosen by the spans of the
         // GROUNDED claims pointing at THIS receipt, not by the quote's head. Passing
         // the receipt's own id is the whole wiring — `RCP-p{i}-s{j}` is the pointer
         // `renderPersonaClaim` prints, so the two sides of the arrow are built from
         // the same expression and cannot drift into windowing the wrong receipt.
+        //
+        // ⚠️ FUL-685: the parent bucket is now the CHILDLESS one. A span verified inside excerpt 2
+        // is not findable in excerpt 1, so windowing this line by it would locate nothing and fall
+        // back to the head clip while looking like a window. Legacy claims carry no `receiptId`, so
+        // for every pre-existing report every span is still in this bucket and this line is
+        // byte-identical to what it rendered before.
         const quote = receipt.quote;
-        const clipped = clipReceiptQuote(quote, spansByReceipt.get(receiptId) ?? [], RECEIPT_QUOTE_MAX);
-        const quoteLine = quote ? `\n    "${clipped}"` : '';
+        const clipped = clipReceiptQuote(quote, spansByReceipt.get(receiptBucketKey(receiptId, null)) ?? [], RECEIPT_QUOTE_MAX);
+        const topic = safeInline(source?.topic, 40);
+        const topicLine = topic ? `\n    On ${topic}` : '';
+        const quoteLine = hasVisibleContent(quote) ? `\n    "${clipped}"` : '';
+        // The addressed receipt CHILDREN, one line each, sorted by receipt id.
+        //
+        // ⚠️ THE PARENT LINE STAYS, EVEN WHEN A CHILD REPEATS IT. The parent's `quote` IS the first
+        // excerpt (that is what `admitRedditPersonaSources` writes), so a claim addressing child 1
+        // prints the same sentence twice. That redundancy is deliberate and cheaper than the
+        // alternatives: suppressing the parent line whenever every claim addressed a child means a
+        // row can render with no excerpt at all on any path that miscounts, and suppressing a `↳`
+        // line that merely duplicates the parent breaks the header's own instruction — a claim's id
+        // would have no line to match, which is the mapping this change exists to establish.
+        //
+        // ⚠️ SORTED BY ID, NOT BY CLAIM ORDER. The id is content-addressed — `deriveReceiptId`
+        // hashes (normalized url, exact excerpt) — so sorting on it is stable across retry, merge,
+        // reopen and promotion, and matches the order the producer emits children in. Ordering by
+        // first-claim-seen would instead make the pool's shape a function of how the synthesiser
+        // happened to sequence its claims.
+        //
+        // `safeId` rather than `safeInline`: this is an IDENTIFIER, and a repaired id is a wrong id
+        // that still reads as one. It cannot fail in practice — nothing reaches here without
+        // matching `rr{n}:{16 hex}` — but exact-or-nothing is the rule for every id in this package
+        // and a silently clipped one would be a pointer to a child that does not exist.
+        const childLines = [...children.values()]
+            .sort((a, b) => (a.receiptId < b.receiptId ? -1 : a.receiptId > b.receiptId ? 1 : 0))
+            .map((child) => {
+            const childId = safeId(child.receiptId) ?? '(unrenderable receipt id)';
+            const clippedChild = clipReceiptQuote(child.excerpt, spansByReceipt.get(receiptBucketKey(receiptId, child.receiptId)) ?? [], RECEIPT_QUOTE_MAX);
+            return `\n    ${RECEIPT_CHILD_MARKER} ${childId} — "${clippedChild}"`;
+        })
+            .join('');
         // FUL-560: the source type, stated ONCE for the pool (in the header below) and inline only
         // on a row that breaks the stated rule. This pool is the one place in the package where the
         // type is a near-constant: `stampEvidenceMetadata` (agent-side) prunes every non-`user_voice`
@@ -671,8 +895,9 @@ function renderReceiptPools(reportData, channel) {
         // would be exactly the "silence reads as reassurance" fail-open this change exists to close.
         const personaType = canonicalContentType(source?.contentType);
         const deviationLine = personaType === 'user_voice' ? '' : contentTypeDeviationLine(source?.contentType);
-        personaReceipts.push(`- ${receiptId} — ${platform} — ${url}${quoteLine}${deviationLine}`);
+        personaReceipts.push(`- ${receiptId} — ${platform} — ${url}${topicLine}${quoteLine}${childLines}${deviationLine}`);
     }
+    const anyReceiptChildren = [...personaReceiptById.values()].some((row) => row.children.size > 0);
     const evidenceReceipts = reportEvidence.map((raw, n) => {
         const source = asRecord(raw);
         // FUL-253: every field on this row is scraped-page metadata, and the row is
@@ -711,7 +936,9 @@ function renderReceiptPools(reportData, channel) {
     if (personaReceipts.length > 0) {
         const shown = personaReceipts.slice(0, CLAIM_RENDER_CAP);
         sections.push(`**Persona receipts** (${plural(personaReceipts.length, 'cached forum post')}) — safe targets of the visible \`RCP-\` pointers above. ` +
-            'Every receipt here is a first-hand `user_voice` post unless its own row says otherwise:\n' +
+            'Every receipt here is a first-hand `user_voice` post unless its own row says otherwise' +
+            (anyReceiptChildren ? `. ${RECEIPT_CHILD_POOL_NOTE}` : '') +
+            ':\n' +
             shown.join('\n') +
             capNote(shown.length, personaReceipts.length, channel, 'report_data.personas[].sources'));
     }
@@ -1469,7 +1696,7 @@ function renderMarketSizing(reportData) {
             return `- ${labels[scope]}: — (Not established)`;
         }
         const validInputs = inputs.filter((input) => input !== null);
-        const sameBoundary = validInputs.every((input) => input.period === entry.period && input.geography === entry.geography && input.audience === entry.audience);
+        const sameBoundary = validInputs.every((input) => input.kind === 'ratio_assumption' || (input.period === entry.period && input.geography === entry.geography && input.audience === entry.audience));
         const inputValues = validInputs.map((input) => num(input.value));
         const oneCurrency = validInputs.filter((input) => input.kind === 'currency' && input.currency === currency).length === 1;
         const product = inputValues.every((input) => input !== null)
@@ -1483,6 +1710,204 @@ function renderMarketSizing(reportData) {
     });
     return `### TAM / SAM / SOM — typed sizing\n${lines.join('\n')}`;
 }
+/**
+ * The Reddit community-evidence rail's typed outcome (FUL-685 / T8, D6).
+ *
+ * ⚠️ SILENCE IS A STATE, AND SO IS SAYING NOTHING — they are different, and this function is
+ * where the difference is kept. TWO cases render NOTHING at all:
+ *
+ *   - the note is **absent or unreadable** → UNRECORDED. Every report written before the field
+ *     existed omits it, as does one served by an app deploy that predates it. Printing "Reddit
+ *     was not searched" off that silence would be inventing a fact about the run.
+ *   - the note says **`not_run`** → the rail did not dispatch, so there is no coverage claim to
+ *     make in either direction. The plan's placement table is explicit: no Reddit-specific copy
+ *     and no claim that Reddit ran; this is operator telemetry, and it lives in the ledger.
+ *
+ * The other four each get their own sentence, and `failed` may NEVER be relabelled
+ * `completed_empty` (F7): a provider outage dressed up as an honest empty search is a false claim
+ * about coverage, which is the one thing this whole digest exists not to make.
+ *
+ * ⚠️ COUNTS ARE TWO NUMBERS, NOT ONE. `acceptedSourceCount` is discussions and
+ * `acceptedExcerptCount` is excerpts, because one thread legitimately yields several — collapsing
+ * them would let receipt multiplicity inflate the breadth figure, which D12/D13 forbid.
+ *
+ * ⚠️ NO COST, NO LATENCY, NO REASON CODE ON A HEALTHY RUN. `costUsd`, `latencyMs`,
+ * `requestsIssued`, `toolRequests` and the three intent counters are operator telemetry; they
+ * change nothing an agent should do about a claim, and a digest an agent skims past is a digest it
+ * does not read. The reason code renders only where it explains a limitation the reader has to act
+ * on.
+ *
+ * ⚠️ ONE PRODUCER WRITES THIS TODAY, AND IT IS NOT THE HERO. `redditReportMethodology`
+ * (`agent/src/scoped-research.ts`, FUL-686 / T9) stamps the summary on every scoped run whose rail
+ * was ARMED; the hero orchestrator still DELETES the key at its enrich chokepoint, and T10
+ * (FUL-687) owns replacing that delete with the real backfill plus the matching terminal event. So
+ * a report reaching this renderer with no note is either a hero run or a pre-feature one — which
+ * is exactly why UNRECORDED, and not "Reddit was not searched", is the only honest reading of
+ * absence.
+ */
+function renderRedditRetrieval(reportData) {
+    const note = asRecord(asRecord(reportData.methodology)?.redditRetrieval);
+    if (!note)
+        return '';
+    const outcome = str(note.outcome);
+    if (!outcome || outcome === 'not_run')
+        return '';
+    const reason = safeInline(note.reason, 60);
+    const because = reason ? ` (reason code: \`${reason}\`)` : '';
+    const sourceCounter = readAcceptanceCounter(note.acceptedSourceCount);
+    const excerptCounter = readAcceptanceCounter(note.acceptedExcerptCount);
+    const sources = sourceCounter.kind === 'valid' ? sourceCounter.value : null;
+    const excerpts = excerptCounter.kind === 'valid' ? excerptCounter.value : null;
+    const validCounters = sourceCounter.kind === 'valid' && excerptCounter.kind === 'valid'
+        ? { sources: sourceCounter.value, excerpts: excerptCounter.value }
+        : null;
+    // ⚠️ THE TWO COUNTERS ARE POSITIVE TOGETHER OR ZERO TOGETHER, AND A PAIR THAT DISAGREES IS A
+    // CORRUPT NOTE (FUL-732). Both derive from the same accepted-source array and every accepted
+    // source carries at least one excerpt, so `acceptedSourceCount: 0` beside `acceptedExcerptCount:
+    // 7` is not a measurement this rail can produce — it is the note telling you it drifted. Reading
+    // acceptance off whichever number happens to be positive trusts a record that has already proved
+    // it cannot be trusted, which is what the OR below used to do.
+    const countersContradict = validCounters !== null && validCounters.sources > 0 !== validCounters.excerpts > 0;
+    // Counts are stated only when BOTH are readable AND they agree. "3 discussions · unknown
+    // excerpts" reads as a measurement rather than as a gap in the record, and the outcome sentence
+    // already carries the fact that matters; "0 accepted discussions · 7 bounded excerpts" reads as
+    // a measurement of something impossible, which is worse. Gating it here rather than per-arm is
+    // what stops the impossible pair reaching any outcome's wording — including the ones below that
+    // never ask about acceptance at all.
+    const counts = validCounters && !countersContradict
+        ? ` ${plural(validCounters.sources, 'accepted discussion')} · ` +
+            `${plural(validCounters.excerpts, 'bounded excerpt')}.`
+        : '';
+    // ⚠️ THIS QUESTION IS THREE-WAY, AND THE ORCHESTRATOR HAS COLLAPSED IT TO TWO IN BOTH
+    // DIRECTIONS ALREADY (FUL-732). Read the history before touching these three lines:
+    //
+    //   1. FUL-728 keyed the unknown wording on `acceptedSourceCount` ALONE, so a note carrying
+    //      seven excerpts was reported as a pass that "may have accepted none" — a FALSE NEGATIVE.
+    //   2. The correction made acceptance an OR over the two counters, so a note reporting `0`
+    //      sources beside `7` excerpts rendered "0 accepted discussions · 7 bounded excerpts.
+    //      Accepted evidence is real." plus the pool pointer — a line that contradicts itself,
+    //      reached by trusting whichever number was positive.
+    //
+    // Both are the same mistake: a two-valued test over a question with three answers. The rule that
+    // holds is the table below, and neither arm may be folded into another.
+    //
+    //   two valid counters agree and prove acceptance → accepted evidence is real
+    //   two valid counters agree on zero              → accepted none
+    //   counters contradict, or either is absent/invalid → UNKNOWN wording, and NO pool pointer
+    //
+    // FUL-740 closes the repeated edge left by interpreting first and guarding second. A count is
+    // valid only when it is a finite non-negative integer; one counter never validates its partner.
+    // That makes the invalid state unrepresentable in either assertion below instead of relying on
+    // every comparison to remember negatives, fractions and non-finite values separately.
+    const acceptedProven = validCounters !== null &&
+        !countersContradict &&
+        validCounters.sources > 0 &&
+        validCounters.excerpts > 0;
+    const acceptedNoneProven = validCounters !== null &&
+        !countersContradict &&
+        validCounters.sources === 0 &&
+        validCounters.excerpts === 0;
+    // ⚠️ THE POOL POINTER BELONGS ONLY TO THE OUTCOMES THAT HAVE EVIDENCE. Appending it to all
+    // four sent a `failed` reader looking for accepted excerpts in a pool the very next section
+    // often declares EMPTY — a pointer to nothing, in the paragraph that just said the pass did not
+    // complete. And even on a good run it is a POINTER, not a promise: the pool renders the sources
+    // a GROUNDED claim resolved, so an accepted excerpt no claim cites is not there. The wording
+    // says "any excerpt a claim cites", which is what the pool actually holds.
+    const poolPointer = ' Any accepted excerpt a claim cites appears in the persona receipt pool below like any other ' +
+        'cached source; they are excerpts from a discussion, not a speaker\'s exact words.';
+    // ⚠️ `completed` MEANS AT LEAST ONE SOURCE WAS ACCEPTED — that is the runtime contract, not a
+    // convention — so `completed` beside a zero acceptance count is INCONSISTENT INPUT, not a state.
+    // Rendering the coverage sentence for it announces a successful pass and points the reader at a
+    // pool the very next section may declare EMPTY: the same defect the `completed_partial` branch
+    // below already refuses, one outcome over. The honest answer to a note that contradicts itself
+    // is the one an unrecognised outcome gets — coverage UNKNOWN.
+    //
+    // ⚠️ EITHER COUNTER READING ZERO IS THAT CONTRADICTION, NOT JUST `acceptedSourceCount`
+    // (#1063 review). This branch keyed on the source count alone, on the argument that `completed`
+    // independently asserts a source was accepted so the outcome sentence survives an
+    // `acceptedExcerptCount: 0`. That argument uses one side of the contradiction to validate
+    // itself: by the same invariant the contradictory pair rests on, every accepted source carries
+    // at least one excerpt, so `excerpts === 0` PROVES `sources === 0` — the exact shape this
+    // branch already refuses to render as a completed pass. Keeping the outcome sentence there and
+    // dropping only the figures announced coverage from a note already known corrupt, and pointed
+    // at the pool while doing it. On `completed` an impossible PAIR (7 / 0) is not a separate case,
+    // because whichever valid counter reads exactly zero already contradicts the outcome.
+    //
+    // A `null` is UNREADABLE, not zero, and keeps the completed wording: the note omitted or
+    // corrupted a telemetry counter, which is not the note claiming something impossible.
+    const completedWithNoAcceptance = outcome === 'completed' &&
+        (sources === 0 || excerpts === 0);
+    const body = completedWithNoAcceptance
+        ? `The Reddit pass reported \`completed\` beside a ZERO acceptance count${because}, which the ` +
+            "rail's own contract does not allow — a completed pass accepted at least one source, and " +
+            'every accepted source carries at least one excerpt, so neither counter can read zero. The ' +
+            'note contradicts itself, so treat Reddit coverage as UNKNOWN and make no claim in either ' +
+            'direction.'
+        : outcome === 'completed'
+            ? `The Reddit pass completed.${counts}${poolPointer}`
+            : outcome === 'completed_empty'
+                ? 'No Reddit evidence cleared this run\'s bounded search and source checks. This does NOT ' +
+                    'mean no relevant Reddit discussion exists, and it is not a finding about the market.'
+                : outcome === 'completed_partial'
+                    ? // ⚠️ A PARTIAL RUN MAY HAVE ACCEPTED NOTHING, and the three cases must not read alike.
+                        // `completed_partial` means "a cap, deadline or failure stopped the pass", which is
+                        // compatible with ZERO accepted sources — so asserting "accepted evidence is real"
+                        // unconditionally makes a claim about evidence that may not exist, and appends a
+                        // pointer to a pool the next section renders EMPTY. That is the same defect the
+                        // pool-pointer comment above describes for `failed`, one outcome over.
+                        //
+                        // ⚠️ AND AN UNPROVABLE COUNT IS ITS OWN CASE (FUL-728). This used to take the
+                        // evidence wording whenever the counter was unreadable, on the argument that a run
+                        // cut short having accepted an unknown amount is likelier to have accepted something
+                        // than nothing. That argues from likelihood, and this digest does not assert from
+                        // likelihood: the whole outcome vocabulary exists so a reader is never handed a
+                        // probable fact wearing a stated one's clothes. `completed_partial` PERMITS zero —
+                        // that is the difference from `completed` above, whose own runtime contract
+                        // guarantees at least one accepted source and so keeps its wording when the counter
+                        // is unreadable. Here nothing guarantees it.
+                        //
+                        // ⚠️ BOTH COUNTERS MUST BE VALID BEFORE EITHER CLAIM IS AVAILABLE (FUL-740). Earlier
+                        // versions let one readable counter settle the question, which repeatedly made a
+                        // malformed partner acquire meaning through `> 0` or `<= 0`. Classification now
+                        // admits only finite non-negative integers, and the pair is interpreted only after
+                        // both pass. Missing, wrong-typed, negative, fractional, NaN and Infinity therefore
+                        // share the UNKNOWN arm and can manufacture neither a figure nor a claim.
+                        //
+                        // ⚠️ AND A CONTRADICTORY PAIR IS THE FOURTH SPELLING, NOT A FOURTH RULE (FUL-732). It
+                        // lands in the SAME row of the table as the unreadable case — UNKNOWN, no counts, no
+                        // pool pointer — but it gets its own sentence, because "not recorded readably" is
+                        // false of two numbers that are both perfectly readable and simply cannot both be
+                        // true. Naming the real defect is what tells an operator to go look at the producer
+                        // instead of at a dropped telemetry field.
+                        countersContradict
+                            ? `The Reddit pass was cut short${because}, so its coverage is PARTIAL. Its two ` +
+                                'acceptance counters CONTRADICT each other, which no real pass produces, so this ' +
+                                'note is corrupt on the question of what it accepted — treat Reddit as PARTIALLY ' +
+                                'SEARCHED, and make no claim about what it found.'
+                            : acceptedNoneProven
+                                ? `The Reddit pass was cut short${because}, so its coverage is PARTIAL.${counts} ` +
+                                    'It accepted no evidence before stopping — treat Reddit as PARTIALLY SEARCHED, ' +
+                                    'not as searched and empty.'
+                                : !acceptedProven
+                                    ? `The Reddit pass was cut short${because}, so its coverage is PARTIAL. How much ` +
+                                        'evidence it accepted before stopping was not recorded readably, and a partial ' +
+                                        'pass may have accepted none — treat Reddit as PARTIALLY SEARCHED, and make no ' +
+                                        'claim about what it found.'
+                                    : `The Reddit pass was cut short${because}, so its coverage is PARTIAL.${counts} ` +
+                                        'Accepted evidence is real; the absence of more is not evidence of absence.' +
+                                        poolPointer
+                    : outcome === 'failed'
+                        ? `The Reddit pass did NOT complete${because}. This run makes no claim about Reddit ` +
+                            'coverage — treat it as unsearched, NOT as searched and empty.'
+                        : // ⚠️ A LIVE BRANCH, NOT A FORMALITY — see `RedditRetrievalNoteSchema`'s `outcome`,
+                            // which is deliberately lenient so a client older than the app that answered it
+                            // reports UNKNOWN rather than falling silent. Failing closed here is the whole
+                            // reason the schema does not reject the token itself.
+                            `The Reddit pass reported an outcome this client does not recognise ` +
+                                `(\`${safeInline(outcome, 40) ?? 'unreadable'}\`)${because}. Treat Reddit coverage ` +
+                                'as UNKNOWN, and upgrade `@clien-ai/mcp` — the app is newer than this client.';
+    return `### Reddit community evidence\n${body}`;
+}
 /**
  * Build the trust digest appended to `get_report`'s text.
  *
@@ -1500,6 +1925,9 @@ export function buildTrustDigest(reportData, channel) {
         renderReportSpine(data, channel),
         renderMarketSizing(data),
         renderCompetitorSourceQuality(data),
+        // FUL-685: immediately above the pool the accepted rows land in, so a reader meets the
+        // coverage caveat before the evidence rather than after it.
+        renderRedditRetrieval(data),
         renderReceiptPools(data, channel),
         renderPersonas(data, channel),
         renderSycophancy(data, channel),