@clien-ai/mcp 0.14.0 → 0.15.1

package/dist/tools/report-digest.js

@@ -52,7 +52,7 @@ import { readFinalHypothesisState } from './hypothesis-final.js';
 import { finalClauseCoverageMatchesIntegrity, readRobustnessCounts, reportClaimNeedsIndependentMarketAuthority, sourceAuthenticatesMarketEconomics, } from '../hypothesis-semantics.js';
 import { parseReceiptId, resolveSourceReceipt } from './receipt-children.js';
 import { resolveMarketSignals } from './market-signals.js';
-import { MCP_OVERVIEW_REF_CAP, MCP_OVERVIEW_SPAN_CAP, REPORT_PORTRAIT_PATHS, sanitizeMcpMarkdownTitle, sanitizeMcpReportTitle, } from '../types/report.js';
+import { MCP_OVERVIEW_REF_CAP, MCP_OVERVIEW_SPAN_CAP, REPORT_PORTRAIT_PATHS, isModelAttestedReportClaim, parseUnverifiedSourceId, receiptRowHasSafeDestination, safeSourceUrl, sanitizeMcpMarkdownTitle, sanitizeMcpReportTitle, } from '../types/report.js';
 import { readSemanticTheme } from '../types/semantic-theme.js';
 import { isDisplaySuitableExcerpt } from '../lib/excerpt-suitability.js';
 /**
@@ -165,6 +165,28 @@ const ATTESTED_WINDOW_LABEL = 'cited window (NOT a verified span)';
  * carries the meaning the shared word no longer can.
  */
 const UNSOURCED_LABEL = 'unsourced';
+/**
+ * FUL-1219: the words on an unverified-source line (Alex D1), keyed by the stored label. An unknown
+ * label has no entry and renders nothing: a guessed word would be a claim about the page.
+ *
+ * ⚠️ THE LINE SHAPE IS THE GUARD, as with `ATTESTED_WINDOW_LABEL`. A receipt is `← RRCP-s{n}` on
+ * the row or an indented `"…"` excerpt in a pool; this line has neither, names itself
+ * `unverified source` and ends `(NOT a receipt)`, so no reader keying on the receipt shapes can
+ * take it for one. Pinned by `unverified-sources.test.ts`.
+ */
+const UNVERIFIED_SOURCE_WORDS = {
+    paid_market_report: 'paid market report',
+    company_own_page: 'company\'s own page',
+    related_source: 'related source',
+};
+const UNVERIFIED_SOURCE_LABEL = 'unverified source';
+/** Plan D8: at most three lines per claim; the rest become one "+N more" line. */
+const UNVERIFIED_SOURCE_CAP = 3;
+/**
+ * Replaces `from model knowledge, unverified` on an unsourced row that shows an unverified source:
+ * the page listed beneath contradicts "model knowledge", but it is still no receipt.
+ */
+const NO_VERIFIED_RECEIPT = 'no verified receipt';
 /**
  * The three labels on a robustness row's continuation lines (FUL-614).
  *
@@ -316,20 +338,18 @@ function overviewCapNote(truncated, cap, noun) {
         return '';
     return `\n_(showing at most ${cap} stored ${noun} — additional entries were omitted before public allowlisting)_`;
 }
-/** Return the normalized URL only when it is a safe, non-credentialed web receipt. */
-function safeReceiptUrl(raw) {
-    if (typeof raw !== 'string' || !/^https?:\/\//i.test(raw))
-        return null;
-    try {
-        const url = new URL(raw);
-        if ((url.protocol !== 'http:' && url.protocol !== 'https:') || url.username || url.password) {
-            return null;
-        }
-        return url.href;
-    }
-    catch {
-        return null;
-    }
+/** FUL-1225: printed where a receipt's link would be when its stored URL is unsafe to show. */
+const URL_WITHHELD = '(url withheld)';
+/**
+ * FUL-1225: a receipt row's link, split into the two questions it answers. `reachable` is FUL-534's
+ * grant condition (a safe destination, shown or withheld by the projection) and decides state and
+ * tally. `href` is what may be printed: only a URL `safeSourceUrl` accepts, else null. Keeping them
+ * apart is what lets an unprintable URL go unlinked without the claim going unsourced.
+ */
+function receiptLink(source) {
+    if (!source)
+        return { reachable: false, href: null };
+    return { reachable: receiptRowHasSafeDestination(source), href: safeSourceUrl(source.url) };
 }
 const OVERVIEW_ASSERTION_MAX = 320;
 function overviewReceiptSupportsClaim(claim, receipt) {
@@ -351,14 +371,14 @@ function resolveOverviewRef(ref, claimSpan, reportEvidence, forumThreads) {
         if (!match)
             return null;
         const source = asRecord(reportEvidence[Number(match[1])]);
-        const href = safeReceiptUrl(source?.url);
+        const link = receiptLink(source);
         const quote = str(source?.quote);
-        if (!source || !href || !quote || !isDisplaySuitableExcerpt(quote) || !overviewReceiptSupportsClaim(claimSpan, quote))
+        if (!source || !link.reachable || !quote || !isDisplaySuitableExcerpt(quote) || !overviewReceiptSupportsClaim(claimSpan, quote))
             return null;
         if (reportClaimNeedsIndependentMarketAuthority('summary', claimSpan) &&
             !sourceAuthenticatesMarketEconomics(source))
             return null;
-        return `${sourceId} -> ${href}`;
+        return `${sourceId} -> ${link.href ?? URL_WITHHELD}`;
     }
     if (kind === 'forum_receipt') {
         const receiptId = safeId(record?.receiptId);
@@ -375,7 +395,7 @@ function resolveOverviewRef(ref, claimSpan, reportEvidence, forumThreads) {
                     !isDisplaySuitableExcerpt(excerpt) ||
                     !overviewReceiptSupportsClaim(claimSpan, excerpt))
                     return [];
-                const href = safeReceiptUrl(thread?.url);
+                const href = safeSourceUrl(thread?.url);
                 return [`${receiptId}${href
                         ? ` -> ${href}`
                         : ` -> cached excerpt: "${safeInline(excerpt, OVERVIEW_ASSERTION_MAX) ?? '[unavailable]'}"`}`];
@@ -474,9 +494,10 @@ function resolvePersonaReceipt(rawClaim, personas) {
     if (sourceIndex < 0)
         return null;
     const source = asRecord(sources[sourceIndex]);
-    const href = safeReceiptUrl(source?.url);
-    if (!source || !href)
+    const link = receiptLink(source);
+    if (!source || !link.reachable)
         return null;
+    const href = link.href;
     // 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;
@@ -690,7 +711,7 @@ function resolveReportReceipt(rawClaim, reportEvidence) {
         return null;
     const source = asRecord(reportEvidence[sourceIndex]);
     if (!source ||
-        !safeReceiptUrl(source.url) ||
+        !receiptRowHasSafeDestination(source) ||
         (kind === 'grounded' && !isDisplaySuitableExcerpt(source.quote)))
         return null;
     if (reportClaimNeedsIndependentMarketAuthority(claim?.section, claim?.text) &&
@@ -737,7 +758,62 @@ function digestSpanOnRow(quote, span) {
     const normalizedSpan = normalize(span);
     return normalizedSpan.length > 0 && normalize(quote).includes(normalizedSpan);
 }
-function renderReportClaim(raw, receipt, corroborating = []) {
+/**
+ * FUL-1219: the unverified-source lines under one claim, or '' when there are none.
+ *
+ * Only a stored, non-attested `NO_RECEIPT` claim shows them: on a GROUNDED claim they would sit
+ * beside a receipt, on a model-attested one beside "cited", and a SPECULATION claim never expected
+ * evidence. `getReport` hands the RAW payload through after schema drift, so every check the
+ * projection makes is repeated here: the id resolves only through the anchored `RUVS-` parser (a
+ * receipt id never reaches the unverified pool), the pool row must be of the claim's section and
+ * have a plain, printable-ASCII http(s) URL not already listed under the claim, and the label must
+ * be one this client knows. Only the host is printed; the full URL stays in the structured channel.
+ */
+function unverifiedSourceLines(rawClaim, unverifiedEvidence) {
+    const claim = asRecord(rawClaim);
+    if (str(claim?.state) !== 'NO_RECEIPT')
+        return '';
+    // A model-attested claim renders `cited → RRCP-s{n}`; an unverified line beside "cited" would read
+    // as support (plan stop condition (d)). Same marker test as the projection and the app.
+    if (isModelAttestedReportClaim(claim))
+        return '';
+    const lines = [];
+    const seen = new Set();
+    let resolved = 0;
+    for (const raw of asArray(claim?.unverifiedSources)) {
+        const entry = asRecord(raw);
+        const index = parseUnverifiedSourceId(entry?.sourceId);
+        const word = typeof entry?.label === 'string' && Object.hasOwn(UNVERIFIED_SOURCE_WORDS, entry.label)
+            ? UNVERIFIED_SOURCE_WORDS[entry.label]
+            : null;
+        const row = index === null ? null : asRecord(unverifiedEvidence[index]);
+        // Parity with the app: a pool row of another section is not this claim's page, and a URL
+        // already listed under this claim is not listed twice.
+        if (!row || row.section !== claim?.section)
+            continue;
+        const url = safeSourceUrl(row.url);
+        if (!word || !url || seen.has(url))
+            continue;
+        const host = safeInline(new URL(url).hostname.replace(/^www\./, ''), 120);
+        if (!host)
+            continue;
+        seen.add(url);
+        resolved += 1;
+        if (lines.length < UNVERIFIED_SOURCE_CAP) {
+            lines.push(`\n    · ${UNVERIFIED_SOURCE_LABEL} RUVS-s${index} (${word}): ${host} (NOT a receipt)`);
+        }
+    }
+    if (lines.length === 0)
+        return '';
+    const stored = claim?.unverifiedSourcesOmitted;
+    const omitted = (Number.isSafeInteger(stored) && stored > 0 ? stored : 0) +
+        (resolved - lines.length);
+    if (omitted > 0) {
+        lines.push(`\n    · +${omitted} more ${omitted === 1 ? UNVERIFIED_SOURCE_LABEL : `${UNVERIFIED_SOURCE_LABEL}s`} found`);
+    }
+    return lines.join('');
+}
+function renderReportClaim(raw, receipt, corroborating = [], unverified = '') {
     const claim = asRecord(raw);
     if (!claim)
         return '- (unreadable claim entry)';
@@ -771,7 +847,7 @@ function renderReportClaim(raw, receipt, corroborating = []) {
         provenance = ` · ${ATTESTED_LABEL} → ${receipt.sourceId} (NOT a receipt)`;
     }
     else if (rawState === 'NO_RECEIPT') {
-        provenance = ` · ${UNSOURCED_LABEL} — from model knowledge, unverified`;
+        provenance = ` · ${UNSOURCED_LABEL} — ${unverified ? NO_VERIFIED_RECEIPT : 'from model knowledge, unverified'}`;
     }
     // A pointer on a non-grounded claim is shown but explicitly disarmed, so it is
     // neither hidden from the reader nor readable as grounding.
@@ -780,7 +856,7 @@ function renderReportClaim(raw, receipt, corroborating = []) {
     }
     const where = section ? ` (${section})` : '';
     const body = text ? ` — "${text}"` : '';
-    return `- [${state}] ${id}${where}${provenance}${body}${attestedWindow(receipt)}`;
+    return `- [${state}] ${id}${where}${provenance}${body}${attestedWindow(receipt)}${unverified}`;
 }
 /**
  * The attested claim's window: the captured snapshot text an independent judge read
@@ -862,6 +938,7 @@ function renderReportSpine(reportData, channel) {
             'figure as unverified.');
     }
     const reportEvidence = asArray(reportData.reportEvidence);
+    const unverifiedEvidence = asArray(reportData.unverifiedEvidence);
     const rows = claims.map((claim) => ({
         claim,
         receipt: resolveReportReceipt(claim, reportEvidence),
@@ -870,7 +947,21 @@ function renderReportSpine(reportData, channel) {
     const attested = rows.filter(({ receipt }) => receipt?.kind === 'attested').length;
     const attestedNote = attested > 0 ? ` (of which ${attested} ${ATTESTED_LABEL})` : '';
     const shown = rows.slice(0, CLAIM_RENDER_CAP);
-    const lines = shown.map(({ claim, receipt }) => renderReportClaim(claim, receipt, corroboratingReceiptIds(claim, receipt, reportEvidence)));
+    let anyUnverified = false;
+    const lines = shown.map(({ claim, receipt }) => {
+        const unverified = unverifiedSourceLines(claim, unverifiedEvidence);
+        if (unverified)
+            anyUnverified = true;
+        return renderReportClaim(claim, receipt, corroboratingReceiptIds(claim, receipt, reportEvidence), unverified);
+    });
+    // FUL-1219: said only when a row carries such a line, so a report without them renders
+    // byte-identically to before.
+    const unverifiedNote = anyUnverified
+        ? `An indented \`· ${UNVERIFIED_SOURCE_LABEL} RUVS-s{n} (…)\` line under a NO_RECEIPT row is a page ` +
+            'the research found for that claim that did NOT verify, labelled with why (a paid market report, ' +
+            `the company's own page, or a related source); its full URL is \`${channel}.report_data.unverifiedEvidence[n]\`. It is NOT a ` +
+            'receipt: it changes no state and counts toward no tally above. '
+        : '';
     // FUL-358 — SAY WHICH POPULATION THE HEADLINE COUNTED.
     //
     // The prose below has always explained that a `summary` claim usually restates a `market` or
@@ -902,6 +993,7 @@ function renderReportSpine(reportData, channel) {
         'text as we captured it: read it as the context the judge weighed, never as a span checked against ' +
         'the claim. Unmarked NO_RECEIPT is recalled model knowledge, unverified. A stored GROUNDED grade ' +
         'whose receipt is unavailable is shown as neutral audit context and counted NO_RECEIPT. ' +
+        unverifiedNote +
         'Key on the rendered state and receipt arrow, never on stored state or source-id presence alone.\n' +
         `${lines.join('\n')}` +
         capNote(shown.length, claims.length, channel, 'report_data.reportClaims'));
@@ -1017,7 +1109,7 @@ function renderReceiptPools(reportData, channel) {
         // they sit on the SAME `- RCP-…` line, so a newline in either forges the
         // receipt row the comment below says a forged quote would.
         const platform = safeInline(source?.platform, 40) ?? 'unknown platform';
-        const url = safeInline(receipt.href, 200) ?? '(no url)';
+        const url = receipt.href === null ? URL_WITHHELD : safeInline(receipt.href, 200) ?? '(no url)';
         // Indented under its own receipt line so the pool still scans as a list of
         // pointers; a receipt with no cached quote simply has no second line, which
         // is itself worth seeing — it is a pointer that grounds nothing until fetched.
@@ -1101,7 +1193,10 @@ function renderReceiptPools(reportData, channel) {
         // claim's arrow with a source nobody fetched.
         const section = safeInline(source?.section, 40) ?? 'unknown section';
         const platform = safeInline(source?.platform, 40) ?? 'unknown platform';
-        const url = safeInline(source?.url, 200) ?? '(no url)';
+        // FUL-1225: the stored string is printed only when the display check accepts it; a withheld
+        // or unsafe one never reaches the text channel.
+        const link = receiptLink(source);
+        const url = link.href ? safeInline(source?.url, 200) ?? '(no url)' : link.reachable ? URL_WITHHELD : '(no url)';
         // FUL-148: `publishedDate` is the figure's recency; `retrievedAt` is only when
         // WE fetched it. Rendering retrievedAt as recency would be a lie, so an absent
         // publication date is shown honestly as unknown rather than substituted.
@@ -1252,7 +1347,7 @@ function renderCommunityPatterns(reportData, channel) {
         const sentiment = safeInline(thread?.sentimentSummary, MODEL_FRAMING_TEXT_MAX);
         const title = safeInline(thread?.title, MODEL_FRAMING_TEXT_MAX) ?? 'Untitled discussion';
         const theme = readSemanticTheme(thread?.theme, title);
-        const href = safeReceiptUrl(thread?.url);
+        const href = safeSourceUrl(thread?.url);
         return [
             `- Theme: ${theme ?? 'not recorded'}`,
             `  Sentiment: ${sentiment ?? 'not recorded'}`,
@@ -1812,9 +1907,9 @@ function renderInsightCrossReferences(reportData) {
             const source = Number.isSafeInteger(index) ? asRecord(evidence[index]) : null;
             const authorityEligible = !reportClaimNeedsIndependentMarketAuthority('summary', statement) ||
                 sourceAuthenticatesMarketEconomics(source);
-            const href = source && authorityEligible ? safeReceiptUrl(source.url) : null;
-            return sourceId && href
-                ? `${label} → ${sourceId} — ${href}`
+            const link = authorityEligible ? receiptLink(source) : { reachable: false, href: null };
+            return sourceId && link.reachable
+                ? `${label} → ${sourceId} — ${link.href ?? URL_WITHHELD}`
                 : `${label} (no resolvable receipt)`;
         })
             .filter((source) => Boolean(source));
@@ -1836,16 +1931,16 @@ function resolveCrossCuttingEvidence(reportData, ref, claim) {
             !sourceAuthenticatesMarketEconomics(source))
             return null;
         const label = safeInline(source.platform, MODEL_FRAMING_TEXT_MAX) || 'Web source';
-        const href = safeReceiptUrl(source.url);
+        const link = receiptLink(source);
         const hasQuote = Object.prototype.hasOwnProperty.call(source, 'quote');
         if (hasQuote && !isDisplaySuitableExcerpt(source.quote))
             return null;
         const quote = hasQuote
             ? safeInline(source.quote, RECEIPT_QUOTE_MAX)
             : null;
-        if (!href)
+        if (!link.reachable)
             return null;
-        return `${label}${href ? ` — ${href}` : ''}${quote ? `\n    > ${quote}` : ''}`;
+        return `${label} — ${link.href ?? URL_WITHHELD}${quote ? `\n    > ${quote}` : ''}`;
     }
     if (ref.kind === 'forum_receipt') {
         const receiptId = safeId(ref.receiptId);
@@ -1862,7 +1957,7 @@ function resolveCrossCuttingEvidence(reportData, ref, claim) {
             return null;
         const match = matches[0];
         const label = safeInline(match.thread?.platform, MODEL_FRAMING_TEXT_MAX) || 'Community source';
-        const href = safeReceiptUrl(match.thread?.url);
+        const href = safeSourceUrl(match.thread?.url);
         const quote = isDisplaySuitableExcerpt(match.receipt?.excerpt)
             ? safeInline(match.receipt?.excerpt, RECEIPT_QUOTE_MAX)
             : null;
@@ -1960,12 +2055,12 @@ function renderProjectedSourceBearingOutput(reportData, channel) {
     else {
         const evidenceRows = asArray(reportData.reportEvidence).slice(0, LIST_RENDER_CAP).flatMap((raw, index) => {
             const source = asRecord(raw);
-            const href = safeReceiptUrl(source?.url);
-            if (!source || !href)
+            const link = receiptLink(source);
+            if (!source || !link.reachable)
                 return [];
             const section = safeInline(source.section, 40);
             const platform = safeInline(source.platform, 40) ?? 'Source';
-            return [`- RRCP-s${index}${section ? ` (${section})` : ''} — ${platform} — ${href}`];
+            return [`- RRCP-s${index}${section ? ` (${section})` : ''} — ${platform} — ${link.href ?? URL_WITHHELD}`];
         });
         if (evidenceRows.length > 0)
             sections.push(`## Report Sources\n\n${evidenceRows.join('\n')}`);
@@ -2145,7 +2240,7 @@ function renderMarketSizing(reportData) {
     const lines = signals.map((signal) => {
         const context = safeInline(signal.context, 360) ?? 'Context unavailable';
         const sources = (signal.sources ?? (signal.source ? [signal.source] : []))
-            .map((source) => safeInline(source.url, 240))
+            .map((source) => safeSourceUrl(source.url) ? safeInline(source.url, 240) : URL_WITHHELD)
             .filter((url) => Boolean(url));
         const citations = sources.length > 0 ? ` ← ${sources.join(', ')}` : '';
         if (signal.kind !== 'size')
@@ -2363,6 +2458,10 @@ function renderRedditRetrieval(reportData) {
  * raw passthrough payload (see the module header). Returns the full digest, or
  * the explicit "no trust data" banner — never an empty string, because an empty
  * digest and a clean one must not look the same.
+ *
+ * ⚠️ FUL-1225: callers pass the output of exactly ONE `projectReportDataForMcp` (via
+ * `prepareReportDataForMcp`). The projection strips stored `urlWithheld` / `urlWithheldHost` markers
+ * before setting its own; on unprojected JSON a forged marker would be trusted as a reachable receipt.
  */
 export function buildTrustDigest(reportData, channel) {
     const rawData = asRecord(reportData);