@clien-ai/mcp 0.3.0 → 0.5.0

package/dist/tools/report-digest.js

@@ -0,0 +1,640 @@
+/**
+ * The `get_report` TRUST DIGEST (FUL-243) — renders the report's machine-checked
+ * trust spine into the tool result's TEXT.
+ *
+ * WHY THIS EXISTS. Every trust field this module renders was already returned by
+ * `get_report` — in `_meta.report_data`. But `_meta` is an OPTIONAL host channel:
+ * a host is not obliged to surface it to the model, and Claude Code does not. A
+ * wire capture against published `@clien-ai/mcp@0.3.0` showed the JSON-RPC
+ * `result` carrying both `_meta` and `content`, and the calling agent receiving
+ * only `content` — so in the ~58KB of markdown an agent actually reads, `RCP-`
+ * appeared 0 times, `RRCP-` 0 times, `identityPriors` 0 times, `qaFlagged` 0
+ * times. We had typed the whole Trust Engine and then delivered it down a channel
+ * the reader never sees.
+ *
+ * So the rule this module implements: ANY FACT AN AGENT MUST ACT ON HAS TO APPEAR
+ * IN THE RENDERED TEXT. Text works on every host, today, with no capability
+ * negotiation. `structuredContent` (the sanctioned machine-readable channel, added
+ * alongside this in the same change) is the richer path where supported, and
+ * `_meta` stays as-is for back-compat — but neither is allowed to be the ONLY
+ * place a trust signal lives.
+ *
+ * DEGRADATION PROPERTY (copied deliberately from `list_competitors`). Every line
+ * here is written so that a missing, absent, or unrecognised value makes an agent
+ * UNDER-trust the report rather than over-trust it:
+ *   - No trust data at all → an explicit "treat every figure above as unverified"
+ *     banner, not silence. Silence reads as "nothing to worry about".
+ *   - A spine that is absent → said out loud ("not present on this run"), because
+ *     an absent claim registry is NOT the same as a clean one.
+ *   - A `state` we do not recognise → rendered verbatim and counted as
+ *     un-grounded, never coerced into GROUNDED.
+ *   - A capped list → the cap is STATED with the dropped count (no silent
+ *     truncation, which reads as "that was all of them").
+ *
+ * READS DEFENSIVELY, ON PURPOSE. `getReport` passes the RAW payload through when
+ * `ResearchReportDataSchema` rejects it (never drop report data on backend drift),
+ * so this module is the one consumer guaranteed to sometimes meet a shape Zod
+ * refused. Hence the local `asArray` / `asRecord` / `str` / `num` accessors rather
+ * than typed field access: a reshaped field must degrade to "not shown", never
+ * throw and lose the whole digest.
+ */
+import { collapseWhitespace, safeInline, clipReceiptQuote, RECEIPT_QUOTE_MAX, } from './research.js';
+/**
+ * Max claims rendered per spine. Above this the digest states how many were
+ * dropped and where the full list lives — never a silent cut. Sized so a typical
+ * run (~40 persona claims, ~15 report claims) renders COMPLETE; the cap is a
+ * runaway backstop, not a routine trim.
+ */
+const CLAIM_RENDER_CAP = 40;
+/** Max chars of claim text per line. Keeps a 40-claim spine to roughly 5KB. */
+const CLAIM_TEXT_MAX = 140;
+/** Max personas / hypotheses / disagreements listed before capping. */
+const LIST_RENDER_CAP = 25;
+// ---------------------------------------------------------------------------
+// Defensive accessors — every one of these answers "or nothing" rather than throwing
+// ---------------------------------------------------------------------------
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function str(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function num(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+/**
+ * TRI-STATE boolean read: `true`, `false`, or `null` for "absent or unreadable".
+ *
+ * A plain `value === true` collapses the third case into `false`, and every flag
+ * this module reads is a WARNING flag — so a schema-drifted `qaFlagged: "true"`
+ * would render as "none QA-flagged" and a drifted `flipped: "true"` as "no
+ * verdict flipped". That is the exact inversion this module exists to prevent:
+ * unreadable must never present as clean. Callers distinguish the three cases and
+ * say "unknown" for `null`.
+ */
+function tribool(value) {
+    return typeof value === 'boolean' ? value : null;
+}
+/** True only for a real `true`. Use where a `null` is handled separately. */
+function bool(value) {
+    return tribool(value) === true;
+}
+/** True when a flag was present but not a boolean, or absent where required. */
+function unreadable(value) {
+    return value !== undefined && typeof value !== 'boolean';
+}
+/** `count` + a correctly pluralised noun, e.g. `3 claims` / `1 claim`. */
+function plural(count, noun, pluralNoun) {
+    return `${count} ${count === 1 ? noun : (pluralNoun ?? `${noun}s`)}`;
+}
+/**
+ * "(showing N of M — …)" tail, or '' when everything rendered.
+ *
+ * Always names WHERE the rest is, because a capped list with no pointer is
+ * indistinguishable from a complete one to a reader who cannot see the source.
+ */
+function capNote(shown, total, channel, path) {
+    if (shown >= total)
+        return '';
+    return `\n_(showing ${shown} of ${total} — the remaining ${total - shown} are in \`${channel}.${path}\`)_`;
+}
+function tallyStates(claims) {
+    const tally = { grounded: 0, speculation: 0, noReceipt: 0, other: 0 };
+    for (const raw of claims) {
+        const state = str(asRecord(raw)?.state);
+        if (state === 'GROUNDED')
+            tally.grounded += 1;
+        else if (state === 'SPECULATION')
+            tally.speculation += 1;
+        else if (state === 'NO_RECEIPT')
+            tally.noReceipt += 1;
+        // An unrecognised (or missing) state counts as OTHER — deliberately not
+        // folded into any of the three known buckets, and never into `grounded`.
+        else
+            tally.other += 1;
+    }
+    return tally;
+}
+function tallyLine(tally, total) {
+    const parts = [
+        `${tally.grounded} GROUNDED`,
+        `${tally.speculation} SPECULATION`,
+        `${tally.noReceipt} NO_RECEIPT`,
+    ];
+    if (tally.other > 0) {
+        parts.push(`${tally.other} with an unrecognised state (treat as UNGROUNDED)`);
+    }
+    return `${plural(total, 'claim')}: ${parts.join(' · ')}`;
+}
+/**
+ * One persona-spine claim line: `[STATE] id ← RCP-… — "text"`.
+ *
+ * The receipt id is rendered INLINE rather than described, because the marker
+ * itself is what an agent pattern-matches on — a digest that says "this claim has
+ * a receipt" without printing `RCP-p0-s2` leaves the agent unable to follow it.
+ */
+function renderPersonaClaim(raw) {
+    const claim = asRecord(raw);
+    if (!claim)
+        return '- (unreadable claim entry)';
+    // FUL-253: the spine is the sharpest row in this file. Every line is a `- `
+    // entry whose leading `[STATE]` is what an agent keys on, so a newline in
+    // `text` — the one field here that is model-written prose over scraped input —
+    // forges a SIBLING CLAIM carrying `[GROUNDED] … ← RCP-p0-s0`: a receipt minted
+    // for a claim no check ever ran on, which is the exact invariant this digest
+    // exists to hold. `truncate` never stopped it; it bounds length, and a forged
+    // line needs one `\n` well inside the cap. Guarded on every field, not just
+    // `text`: they share the line, so any of them can end it early.
+    //
+    // The GROUNDED gates keep reading the RAW `str()` value: flattening trims, so
+    // gating on the flattened one would newly admit `" GROUNDED "` as grounded and
+    // put the row's badge at odds with `tallyStates`, which reads raw. Flattening
+    // is for the RENDER; it must not widen what counts as a receipt.
+    const rawState = str(claim.state);
+    const state = safeInline(claim.state, 40) ?? 'UNKNOWN_STATE';
+    const id = safeInline(claim.id, 60) ?? '(no id)';
+    const personaId = safeInline(claim.personaId, 60);
+    const sourceId = safeInline(claim.sourceId, 60);
+    const text = safeInline(claim.text, CLAIM_TEXT_MAX);
+    // Gated on `state`, not on `sourceId` presence — see `renderReportClaim` for
+    // why a pointer on a non-GROUNDED claim must never render as a receipt.
+    let receipt = '';
+    if (rawState === 'GROUNDED') {
+        receipt = sourceId ? ` ← ${sourceId}` : ' · GROUNDED but no receipt id — unresolvable';
+    }
+    else if (sourceId) {
+        receipt = ` (carries ${sourceId}, which does NOT grant grounding — state is ${state})`;
+    }
+    const who = personaId ? ` (${personaId})` : '';
+    const body = text ? ` — "${text}"` : '';
+    return `- [${state}] ${id}${who}${receipt}${body}`;
+}
+/**
+ * One report-spine claim line. Differs from the persona one in two ways that
+ * matter to a reader: it carries a `section` (market/competitor) instead of a
+ * persona, and a NO_RECEIPT claim has TWO distinct provenance readings that must
+ * be told apart — model-attested (a page was read and independently vouched, no
+ * exact span pinned) versus plain model knowledge (recalled, unverified).
+ *
+ * Neither reading is grounding. The attestation's `sourceId` is printed under an
+ * explicit `model-attested →` label rather than the bare `←` used for real
+ * receipts, so the two can never be skim-read as the same thing.
+ */
+function renderReportClaim(raw) {
+    const claim = asRecord(raw);
+    if (!claim)
+        return '- (unreadable claim entry)';
+    // FUL-253: same guard and same raw-gate split as `renderPersonaClaim` — this
+    // spine's rows are the ones a forged `[GROUNDED] … ← RRCP-s0` would hide in.
+    const rawState = str(claim.state);
+    const state = safeInline(claim.state, 40) ?? 'UNKNOWN_STATE';
+    const id = safeInline(claim.id, 60) ?? '(no id)';
+    const section = safeInline(claim.section, 40);
+    const sourceId = safeInline(claim.sourceId, 60);
+    const text = safeInline(claim.text, CLAIM_TEXT_MAX);
+    const attestation = asRecord(claim.attestation);
+    const attestedSourceId = safeInline(attestation?.sourceId, 60);
+    // The bare `←` arrow means RECEIPT, so it is gated on `state`, NOT on the mere
+    // presence of a `sourceId`. Keying on presence would render an explicitly
+    // unsupported claim with the same marker a span-verified one gets: the schema
+    // types `state` and `sourceId` independently and `.passthrough()`s unknown
+    // shapes, and `getReport` hands the RAW payload through when Zod rejects it, so
+    // `{ state: 'NO_RECEIPT', sourceId: 'RRCP-s0' }` genuinely reaches this code.
+    // An agent following that arrow would treat a NO_RECEIPT figure as source-checked.
+    let provenance = '';
+    if (rawState === 'GROUNDED') {
+        provenance = sourceId ? ` ← ${sourceId}` : ' · GROUNDED but no receipt id — unresolvable';
+    }
+    else if (rawState === 'NO_RECEIPT' && attestedSourceId) {
+        provenance = ` · model-attested → ${attestedSourceId} (NOT a receipt)`;
+    }
+    else if (rawState === 'NO_RECEIPT') {
+        provenance = ' · 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.
+    if (rawState !== 'GROUNDED' && sourceId) {
+        provenance += ` (carries ${sourceId}, which does NOT grant grounding — state is ${state})`;
+    }
+    const where = section ? ` (${section})` : '';
+    const body = text ? ` — "${text}"` : '';
+    return `- [${state}] ${id}${where}${provenance}${body}`;
+}
+function renderPersonaSpine(reportData, channel) {
+    const claims = asArray(reportData.claims);
+    if (claims.length === 0) {
+        return ('### Persona claim spine — NOT PRESENT on this run\n' +
+            'No persona claim registry was produced, so NOTHING in the persona/interview prose above ' +
+            'has been machine-checked. Absent is not clean: treat those statements as unverified.');
+    }
+    const tally = tallyStates(claims);
+    const shown = claims.slice(0, CLAIM_RENDER_CAP);
+    const lines = shown.map(renderPersonaClaim);
+    return (`### Persona claim spine — ${tallyLine(tally, claims.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. 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' +
+        `${lines.join('\n')}` +
+        capNote(shown.length, claims.length, channel, 'report_data.claims'));
+}
+function renderReportSpine(reportData, channel) {
+    const claims = asArray(reportData.reportClaims);
+    if (claims.length === 0) {
+        return ('### Market/competitor claim spine — NOT PRESENT on this run\n' +
+            'No market/competitor claim registry was produced, so no sizing figure, trend, or competitor ' +
+            'fact in the prose above has been machine-checked. Treat every such figure as unverified.');
+    }
+    const tally = tallyStates(claims);
+    const attested = claims.filter((raw) => {
+        const claim = asRecord(raw);
+        return str(claim?.state) === 'NO_RECEIPT' && str(asRecord(claim?.attestation)?.sourceId) !== null;
+    }).length;
+    const attestedNote = attested > 0 ? ` (of which ${attested} model-attested)` : '';
+    const shown = claims.slice(0, CLAIM_RENDER_CAP);
+    const lines = shown.map(renderReportClaim);
+    return (`### Market/competitor claim spine — ${tallyLine(tally, claims.length)}${attestedNote}\n` +
+        'A SEPARATE pool from the persona spine — the two never cross. A GROUNDED claim\'s `RRCP-s{n}` ' +
+        'indexes `reportEvidence[n]`. A NO_RECEIPT claim marked `model-attested` means Claude read a ' +
+        'supporting page an independent check vouched for, but no exact span was pinned — stronger than ' +
+        'recall, still NOT a receipt. Unmarked NO_RECEIPT is recalled model knowledge, unverified. ' +
+        'Key on the state, never on whether a source id is present.\n' +
+        `${lines.join('\n')}` +
+        capNote(shown.length, claims.length, channel, 'report_data.reportClaims'));
+}
+/**
+ * The verified spans each persona receipt has to be able to SHOW, keyed by the
+ * receipt id its claims point at (FUL-252).
+ *
+ * Gated on `state === 'GROUNDED'`, matching `renderPersonaClaim`'s own gate and for
+ * the same reason: only a GROUNDED claim's span earned a badge, so only a GROUNDED
+ * claim's span is what the excerpt owes the reader. Keying on the mere presence of
+ * `quoteSpan` would let a SPECULATION claim steer the window — pushing the excerpt
+ * away from the sentence a real receipt was verified against, in favour of one no
+ * check ever ran on. `getReport` hands the RAW payload through when Zod rejects it,
+ * so `{ state: 'SPECULATION', quoteSpan: … }` genuinely reaches this code.
+ *
+ * Read from the SHOWN slice, not from every claim: past `CLAIM_RENDER_CAP` a claim
+ * 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.
+ */
+function collectVerifiedSpans(reportData) {
+    const spans = new Map();
+    for (const raw of asArray(reportData.claims).slice(0, CLAIM_RENDER_CAP)) {
+        const claim = asRecord(raw);
+        if (!claim || str(claim.state) !== 'GROUNDED')
+            continue;
+        const sourceId = str(claim.sourceId);
+        const span = str(claim.quoteSpan);
+        if (!sourceId || !span)
+            continue;
+        const existing = spans.get(sourceId);
+        if (existing)
+            existing.push(span);
+        else
+            spans.set(sourceId, [span]);
+    }
+    return spans;
+}
+/**
+ * The two receipt POOLS, so an agent that reads `← RCP-p0-s2` in a claim line can
+ * resolve the pointer without the structured channel.
+ *
+ * FUL-247: persona receipts now carry the VERBATIM QUOTE, truncated to
+ * `RECEIPT_QUOTE_MAX`. This comment used to say "the verbatim quotes stay in the
+ * structured payload", and that was the whole problem: `renderPersonaClaim` prints
+ * `claim.text`, which is a PARAPHRASE, and the pool printed only platform + url —
+ * so an agent could see that a GROUNDED claim had a receipt and where it pointed,
+ * but no agent-visible channel anywhere carried the sentence the claim was
+ * grounded ON. `structuredContent` is not a fallback for this: `_meta` is dropped
+ * by Claude Code outright, and a reader checking a claim against its evidence
+ * should not have to leave the text to do it.
+ *
+ * FUL-252: the quote is now WINDOWED around the spans of the claims pointing at it,
+ * within the same budget. Rendering the head was not merely a smaller view of the
+ * evidence — when the verified span sat past the cutoff it was a view that excluded
+ * the evidence, under a `[GROUNDED]` badge.
+ *
+ * Evidence receipts (`RRCP-`) are NOT given the same treatment: they point at web
+ * 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).
+ */
+function renderReceiptPools(reportData, channel) {
+    const personas = asArray(reportData.personas);
+    const reportEvidence = asArray(reportData.reportEvidence);
+    const spansByReceipt = collectVerifiedSpans(reportData);
+    const personaReceipts = [];
+    personas.forEach((rawPersona, i) => {
+        const sources = asArray(asRecord(rawPersona)?.sources);
+        sources.forEach((rawSource, j) => {
+            const source = asRecord(rawSource);
+            // 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
+            // receipt row the comment below says a forged quote would.
+            const platform = safeInline(source?.platform, 40) ?? 'unknown platform';
+            const url = safeInline(source?.url, 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.
+            //
+            // `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".
+            //
+            // 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.
+            const receiptId = `RCP-p${i}-s${j}`;
+            const quote = collapseWhitespace(str(source?.quote) ?? '');
+            const clipped = clipReceiptQuote(quote, spansByReceipt.get(receiptId) ?? [], RECEIPT_QUOTE_MAX);
+            const quoteLine = quote ? `\n    "${clipped}"` : '';
+            personaReceipts.push(`- ${receiptId} — ${platform} — ${url}${quoteLine}`);
+        });
+    });
+    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
+        // what an `RRCP-s{n}` pointer resolves TO — a forged one answers a real
+        // 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-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.
+        const published = safeInline(source?.publishedDate, 40) ?? 'publish date unknown';
+        return `- RRCP-s${n} (${section}) — ${platform} — ${published} — ${url}`;
+    });
+    if (personaReceipts.length === 0 && evidenceReceipts.length === 0) {
+        return ('### Receipt pools — EMPTY\n' +
+            'No cached sources were attached to this run, so no claim above can be followed to a source. ' +
+            'Any receipt id referenced in the prose is unresolvable.');
+    }
+    const sections = ['### Receipt pools'];
+    if (personaReceipts.length > 0) {
+        const shown = personaReceipts.slice(0, CLAIM_RENDER_CAP);
+        sections.push(`**Persona receipts** (${plural(personaReceipts.length, 'cached forum post')}) — the target of an \`RCP-\` pointer:\n` +
+            shown.join('\n') +
+            capNote(shown.length, personaReceipts.length, channel, 'report_data.personas[].sources'));
+    }
+    if (evidenceReceipts.length > 0) {
+        const shown = evidenceReceipts.slice(0, CLAIM_RENDER_CAP);
+        sections.push(`**Market/competitor evidence** (${plural(evidenceReceipts.length, 'cached page')}) — the target of an \`RRCP-\` pointer:\n` +
+            shown.join('\n') +
+            capNote(shown.length, evidenceReceipts.length, channel, 'report_data.reportEvidence'));
+    }
+    return sections.join('\n\n');
+}
+/**
+ * Per-persona QA + identity grounding.
+ *
+ * `qaFlagged` is rendered as a LOUD leading warning rather than a trailing field:
+ * a flagged persona either failed a quality check or could not be checked at all
+ * (FUL-132 fail-safe), and an agent about to interview or quote it needs that
+ * before it reads the persona's name, not after.
+ *
+ * `identityPriors` and `identityProvenance` are labelled as NOT receipts, because
+ * they sit next to real receipts and the failure mode is an agent citing
+ * "calibrated against N real ICP profiles" as if it were a source.
+ */
+function renderPersonas(reportData, channel) {
+    const personas = asArray(reportData.personas);
+    if (personas.length === 0) {
+        return '### Personas — none carried on this run';
+    }
+    const shown = personas.slice(0, LIST_RENDER_CAP);
+    const lines = shown.map((raw, i) => {
+        const persona = asRecord(raw);
+        // FUL-253: `str()` answers "is this a string", not "is this safe on a line".
+        // These rows are `- ` entries carrying a QA-FLAGGED warning, so a newline in a
+        // persona name forges a SIBLING PERSONA that renders without the warning —
+        // the one field on this line an agent reads to decide whether to trust the
+        // rest of it. Applied to every free-text field on the row, not just the name:
+        // they share one line, so any of them can end it early.
+        const name = safeInline(persona?.name, 100) ?? `persona-${i}`;
+        const role = safeInline(persona?.role, 100);
+        const sources = asArray(persona?.sources);
+        const flagged = bool(persona?.qaFlagged);
+        const reasons = asArray(persona?.qaFlagReasons)
+            .map((r) => safeInline(r, 120))
+            .filter((r) => r !== null);
+        const insufficient = bool(persona?.insufficientEvidence);
+        const sourcesFound = num(persona?.sourcesFound);
+        const priors = asRecord(persona?.identityPriors);
+        const seniority = safeInline(priors?.seniority, 80);
+        const careerPath = safeInline(priors?.careerPath, 80);
+        const provenance = safeInline(persona?.identityProvenance, 200);
+        const bits = [];
+        bits.push(`${plural(sources.length, 'receipt')}`);
+        if (insufficient) {
+            bits.push(`⚠️ insufficientEvidence${sourcesFound !== null ? ` (only ${sourcesFound} real posts found)` : ''}`);
+        }
+        else if (sourcesFound !== null) {
+            bits.push(`sourcesFound: ${sourcesFound}`);
+        }
+        // identityPriors are TYPED ENRICHMENT, not evidence — the label says so on
+        // the same line so the two can't be conflated at a glance.
+        if (seniority)
+            bits.push(`identityPriors.seniority: ${seniority}`);
+        if (careerPath)
+            bits.push(`identityPriors.careerPath: ${careerPath}`);
+        // A flag we cannot READ is reported as unknown, never as "not flagged" — an
+        // unreadable quality signal is a reason for less confidence, not more.
+        const flag = flagged
+            ? `⚠️ QA-FLAGGED${reasons.length > 0 ? ` (${reasons.join('; ')})` : ' (no reason recorded)'} — do not rely on this persona's claims. `
+            : unreadable(persona?.qaFlagged)
+                ? '⚠️ qaFlagged UNREADABLE (malformed value) — treat this persona as unchecked. '
+                : '';
+        const provenanceLine = provenance
+            ? `\n  identityProvenance: "${provenance}" — aggregate calibration, NEVER a receipt; do not cite it as a source.`
+            : '';
+        return `- **${name}**${role ? ` (${role})` : ''} — ${flag}${bits.join(' · ')}${provenanceLine}`;
+    });
+    const flaggedCount = personas.filter((p) => bool(asRecord(p)?.qaFlagged)).length;
+    // "none QA-flagged" is a CLEAN BILL, so it is only claimed when every persona's
+    // flag was actually readable. One malformed value makes the aggregate unknown —
+    // otherwise drifted data would render as a passed quality check.
+    const unreadableCount = personas.filter((p) => unreadable(asRecord(p)?.qaFlagged)).length;
+    const header = flaggedCount > 0
+        ? `### Personas — ${personas.length}, ⚠️ ${flaggedCount} QA-FLAGGED`
+        : unreadableCount > 0
+            ? `### Personas — ${personas.length}, ⚠️ QA status UNREADABLE for ${unreadableCount} (not a clean result)`
+            : `### Personas — ${personas.length}, none QA-flagged`;
+    return (`${header}\n${lines.join('\n')}` +
+        capNote(shown.length, personas.length, channel, 'report_data.personas'));
+}
+/**
+ * The anti-sycophancy readout — deterministically computed from the interviews,
+ * not model-opined, which is exactly why it belongs in the text: it is the one
+ * signal that says whether the personas actually pushed back or just agreed.
+ */
+function renderSycophancy(reportData, channel) {
+    const signals = asRecord(reportData.sycophancySignals);
+    if (!signals) {
+        return ('### Anti-sycophancy — NOT COMPUTED on this run\n' +
+            'No broken-persona / rejection readout was produced. You cannot tell from this report whether ' +
+            'the personas genuinely disagreed with the idea or simply agreed with everything.');
+    }
+    const totalRejections = num(signals.totalRejections);
+    const lowDiscriminationCount = num(signals.lowDiscriminationCount) ?? 0;
+    const personaSignals = asArray(signals.personaSignals);
+    const disagreements = asArray(signals.disagreements);
+    const lines = [];
+    // A healthy run has ≥1 explicit rejection; zero is itself the warning.
+    if (totalRejections !== null) {
+        lines.push(totalRejections === 0
+            ? '⚠️ 0 explicit rejections across all personas — nobody said no to anything. A run with no ' +
+                'rejections is the classic sycophancy signature; discount the supportive findings above.'
+            : `${plural(totalRejections, 'explicit rejection')} across all personas.`);
+    }
+    if (lowDiscriminationCount > 0) {
+        const names = personaSignals
+            .filter((raw) => bool(asRecord(raw)?.lowDiscrimination))
+            // FUL-253: joined into one warning line, so a newline in a name would end
+            // the warning early and leave the rest of the flagged personas rendering
+            // as ordinary text below it.
+            .map((raw) => safeInline(asRecord(raw)?.personaName, 100) ?? '(unnamed)');
+        lines.push(`⚠️ ${lowDiscriminationCount} persona(s) flagged \`lowDiscrimination\` (uniformly supportive AND ` +
+            `rejected nothing — their answers carry little signal): ${names.join(', ')}`);
+    }
+    if (disagreements.length > 0) {
+        const shown = disagreements.slice(0, LIST_RENDER_CAP);
+        lines.push(`Hypotheses the personas SPLIT on (disagreement is signal, not noise):\n` +
+            shown
+                .map((raw) => {
+                const d = asRecord(raw);
+                const id = safeInline(d?.hypothesisId, 60) ?? '(no id)';
+                const supportive = asArray(d?.supportive).length;
+                const negative = asArray(d?.negative).length;
+                const neutral = asArray(d?.neutral).length;
+                return `  - ${id}: ${supportive} supportive / ${neutral} neutral / ${negative} pushed back`;
+            })
+                .join('\n') +
+            capNote(shown.length, disagreements.length, channel, 'report_data.sycophancySignals.disagreements'));
+    }
+    if (lines.length === 0) {
+        lines.push('Readout present but empty — treat the supportive findings above as unchecked.');
+    }
+    return `### Anti-sycophancy\n${lines.join('\n')}`;
+}
+/**
+ * Hypothesis verdict robustness.
+ *
+ * The load-bearing case is `flipped`: when a verdict changed under rephrasing the
+ * report's top-level `status` is NOT the verdict to act on — `downgradedStatus`
+ * is. That inversion is precisely the kind of thing an agent gets wrong when it
+ * reads only the prose, so it is stated per-hypothesis rather than as a footnote.
+ */
+function renderRobustness(reportData, channel) {
+    const results = asArray(reportData.hypothesisResults);
+    if (results.length === 0)
+        return '';
+    const withRobustness = results.filter((raw) => asRecord(asRecord(raw)?.robustness) !== null);
+    if (withRobustness.length === 0) {
+        return ('### Hypothesis robustness — NOT RE-TESTED on this run\n' +
+            'No verdict was re-asked under a reworded framing, so no verdict above carries a survival ' +
+            'count. Treat each as a single-shot answer.');
+    }
+    const shown = withRobustness.slice(0, LIST_RENDER_CAP);
+    const lines = shown.map((raw) => {
+        const result = asRecord(raw);
+        // FUL-253: a `- ` row whose whole point is the ⚠️ FLIPPED warning. A newline
+        // in `status` or `downgradedStatus` forges a sibling row for the same
+        // hypothesis id WITHOUT the warning — the reading that says the reported
+        // verdict is not the one to act on is exactly what a forgery would drop.
+        const id = safeInline(result?.hypothesisId, 60) ?? '(no id)';
+        const status = safeInline(result?.status, 40) ?? 'unknown';
+        const robustness = asRecord(result?.robustness);
+        const survived = num(robustness?.survived);
+        const total = num(robustness?.total);
+        const flipped = tribool(robustness?.flipped);
+        const downgraded = safeInline(robustness?.downgradedStatus, 40);
+        const count = survived !== null && total !== null ? `held ${survived}/${total} framings` : 'survival count unavailable';
+        if (flipped === true) {
+            return (`- ${id}: reported \`${status}\` — ⚠️ FLIPPED under rephrasing (${count}). ` +
+                `The verdict to act on is \`${downgraded ?? 'weaker than reported — downgrade unavailable'}\`, NOT \`${status}\`.`);
+        }
+        // An unreadable `flipped` is NOT "held" — say so rather than printing the
+        // verdict as if it had survived re-asking.
+        if (flipped === null) {
+            return `- ${id}: reported \`${status}\` — ⚠️ flip status UNREADABLE (${count}); treat this verdict as un-retested.`;
+        }
+        return `- ${id}: \`${status}\` — ${count}`;
+    });
+    const flippedCount = withRobustness.filter((raw) => bool(asRecord(asRecord(raw)?.robustness)?.flipped)).length;
+    const unreadableFlips = withRobustness.filter((raw) => tribool(asRecord(asRecord(raw)?.robustness)?.flipped) === null).length;
+    // The un-retested hypotheses are counted against the FULL result set, not just
+    // the re-tested subset: a bare "no verdict flipped" over a partially-tested run
+    // reads as "every verdict survived", when most may never have been re-asked.
+    const untested = results.length - withRobustness.length;
+    const untestedNote = untested > 0
+        ? ` (${withRobustness.length}/${results.length} verdicts re-tested; the other ${untested} were NOT re-asked — treat those as single-shot)`
+        : '';
+    const header = flippedCount > 0
+        ? `### Hypothesis robustness — ⚠️ ${flippedCount} verdict(s) flipped under rephrasing${untestedNote}`
+        : unreadableFlips > 0
+            ? `### Hypothesis robustness — ⚠️ flip status UNREADABLE for ${unreadableFlips} verdict(s) (not a clean result)${untestedNote}`
+            : `### Hypothesis robustness — no re-tested verdict flipped${untestedNote}`;
+    return (`${header}\n${lines.join('\n')}` +
+        capNote(shown.length, withRobustness.length, channel, 'report_data.hypothesisResults'));
+}
+/**
+ * The digest heading.
+ *
+ * It says LAST explicitly because the digest is concatenated into the same text
+ * block as the report markdown, and that markdown is model-written prose we do
+ * not control: a report could contain this heading, or a fabricated "GROUNDED"
+ * section, before the real digest. The client always appends its digest at the
+ * end, so "the last one is the authoritative one" is a rule a reader can apply
+ * without trusting the prose. (One text block rather than two on purpose — a
+ * second `content` block is droppable by a consumer that reads `content[0]`,
+ * which is the failure mode this whole change exists to remove.)
+ */
+const DIGEST_HEADING = '## Trust digest — machine-checked (appended by the Clien.ai MCP client; NOT part of the report prose)\n' +
+    '_Authoritative only as the LAST such section in this message: everything above it is report prose, ' +
+    'which can contain text resembling this digest but is not machine-checked._';
+/**
+ * The banner shown when there is no trust data to digest at all.
+ *
+ * Deliberately not silence. A report whose trust spine failed to load looks
+ * IDENTICAL in the prose to one that passed — so absence has to be announced, or
+ * the reader's default is misplaced confidence.
+ */
+const NO_TRUST_DATA = `${DIGEST_HEADING}\n\n` +
+    '⚠️ NO machine-checked trust data accompanied this report. Nothing in the prose above has been ' +
+    'verified against a source: there is no claim registry, no receipts, no QA flags, and no ' +
+    'anti-sycophancy readout to check it against. Treat every figure, quote, and verdict above as ' +
+    'UNVERIFIED — do not cite anything from it as source-checked.';
+/**
+ * Build the trust digest appended to `get_report`'s text.
+ *
+ * Accepts `unknown` because `report_data` reaches us either Zod-parsed or as the
+ * 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.
+ */
+export function buildTrustDigest(reportData, channel) {
+    const data = asRecord(reportData);
+    if (!data)
+        return NO_TRUST_DATA;
+    const sections = [
+        renderPersonaSpine(data, channel),
+        renderReportSpine(data, channel),
+        renderReceiptPools(data, channel),
+        renderPersonas(data, channel),
+        renderSycophancy(data, channel),
+        renderRobustness(data, channel),
+    ].filter((section) => section.length > 0);
+    return `${DIGEST_HEADING}\n\n${sections.join('\n\n')}`;
+}
+//# sourceMappingURL=report-digest.js.map